S3: GetObjectRequest: Support for If-Range header

[berlix]

Describe the bug

This is somewhere between a bug report and a feature request, as it seems to be a strange omission.

It appears that S3 handles the If-Range header correctly when responding to GetObject requests. However, aws.sdk.kotlin.services.s3.model.GetObjectRequest does not support setting it (it does support setting Range and If-Match).

Background: If-Range is similar to If-Match, except that it in case the ETag does not match, the entire object is returned rather than status 412.

Regression Issue

• Select this option if this issue appears to be a regression.

Expected behavior

Ability to set If-Range header in aws.sdk.kotlin.services.s3.model.GetObjectRequest.

Current behavior

No such facility exists in aws.sdk.kotlin.services.s3.model.GetObjectRequest.

Steps to Reproduce

1. Search for the strings If-Range and ifRange in aws.sdk.kotlin.services.s3.model.GetObjectRequest.
2. Find none.

Possible Solution

No response

Context

I have a backend component that proxies some requests to S3. The clients of my backend component use If-Range for partial downloads. It would be convenient to be able to just forward those headers to S3.

My current workaround is to translate client requests with If-Range into multiple GetObjectRequests:

• One with If-Match and Range.
• In case that first request returns status 412, a second request without Range and If-Match.

AWS SDK for Kotlin version

1.4.119

Platform (JVM/JS/Native)

JVM

Operating system and version

Ubuntu 25.04

[ianbotsf]

Thank you for the submission, @berlix. It appears that S3 does not model the If-Range header nor describe it in their GetObject documentation despite supporting it in the backend. I'll raise this with the S3 team and see what they can do.

As a workaround, you can use an interceptor to set custom headers:

class IfRangeInterceptor(private val eTag: String) : HttpInterceptor {
    override suspend fun modifyBeforeRetryLoop(context: ProtocolRequestInterceptorContext<Any, HttpRequest>) =
        context
            .protocolRequest
            .toBuilder()
            .apply { headers["If-Range"] = "\"$eTag\"" }
            .build()
}

Because the eTag value will likely vary with each request, it's probably more convenient to wrap the functionality in a helper method:

suspend inline fun <T> S3Client.getObjectIfRange(
    bucket: String,
    key: String,
    eTag: String,
    range: String,
    crossinline block: suspend (GetObjectResponse) -> T,
): T = this
    .withConfig { interceptors += IfRangeInterceptor(eTag) }
    .use { s3 ->
        val req = GetObjectRequest {
            this.bucket = bucket
            this.key = key
            this.range = range
        }
        s3.getObject(req) { block(it) }
    }

I'll post an update here once I get a response from S3.

[berlix]

Thank you, @ianbotsf, for the workaround, for checking on my mistaken assumption that S3 supports If-Range (not sure where I got that from), and for raising this with the S3 team. Curious to hear what they say.