BREAKING: Updated endpoint resolution

[lucix-aws]

An upcoming release of the AWS SDK for Kotlin includes redesigned endpoint resolution, as well as support for a host of endpoint-related AWS features.

This release will break any code that currently references the EndpointResolver interface.

Release date

This feature will ship with the v0.18.0 release planned for 11/22/22.

What's changing?

Client implementations in the SDK are generated from service models written in smithy. A recent update to the smithy IDL included support for endpoint rules. Endpoint rules, in brief, define an intermediate language that dictates how endpoints are resolved within the context of a request.

The principal benefit of this feature is to allow service teams (S3, Lambda, etc.) to define the logic for how to resolve endpoints such that SDKs can generate implementations to do so.

The switch to using modeled endpoint providers comes with a host of AWS SDK features that in the past would have required hand-written customizations:

• FIPS/dualstack endpoints
• S3 Transfer Acceleration
• S3 Access Points
• S3 Object Lambda
• S3 PrivateLink
• S3 Outputs
• S3 Virtual Host Addressing

The EndpointResolver interface, which was previously a static type within the runtime:

fun interface EndpointResolver {
    suspend fun resolve(): Endpoint
}

has been refactored into a per-service type known as EndpointProvider:

package aws.sdk.kotlin.<service>.endpoints

fun interface EndpointProvider {
    suspend fun resolveEndpoint(params: EndpointParameters): Endpoint
}

The resolve method (now resolveEndpoint) now takes a set of service-specific parameters. The way in which the parameters are set is an implementation detail of the SDK and can vary per-request.

How to migrate

• If you're implementing your own EndpointResolver to use FIPS or dualstack endpoints, you can most likely remove this and instead set the client config fields useFips and useDualStack accordingly.
• If you're implementing your own EndpointResolver for any other reason, you will need to update your implementation according to the new per-service type.
  • The resolve method is invoked with the service-specific parameters, the values of which are bound internally as part of the request. If you wish to compose the default implementation of the endpoint provider with your own, you can do so by instantiating and calling the default implementation with the passed parameters, e.g.:

import aws.sdk.kotlin.s3.endpoints.DefaultEndpointProvider as DefaultS3EndpointProvider
import aws.sdk.kotlin.s3.endpoints.EndpointParameters as S3EndpointParameters
import aws.sdk.kotlin.s3.endpoints.EndpointProvider as S3EndpointProvider
// ...

public class S3CustomEndpointProvider(private val ctx: MyApplicationContext) : S3EndpointProvider {
    public override suspend fun resolveEndpoint(params: S3EndpointParameters): Endpoint {
        val baseEndpoint = DefaultS3EndpointProvider().resolveEndpoint(params)
        // ... perform logic based on resolved endpoint and your own application context
    }
}

• The S3 client config now contains various additional parameters to control some of the newly-available features released as part of this change. Please reference the API documentation for more information on specific settings.

Additional resources

• Endpoints "v2" design document
• Configuring endpoints guide

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you've encountered a bug with these changes, please file an issue.