refactor!: overhaul endpoint resolver types (#361)

Author: aajtodd

aws-runtime/aws-config/common/src/aws/sdk/kotlin/runtime/config/imds/ImdsClient.kt

@@ -6,19 +6,17 @@
 package aws.sdk.kotlin.runtime.config.imds
 
 import aws.sdk.kotlin.runtime.AwsServiceException
-import aws.sdk.kotlin.runtime.ConfigurationException
 import aws.sdk.kotlin.runtime.client.AwsClientOption
-import aws.sdk.kotlin.runtime.endpoint.Endpoint
 import aws.sdk.kotlin.runtime.http.ApiMetadata
 import aws.sdk.kotlin.runtime.http.AwsUserAgentMetadata
 import aws.sdk.kotlin.runtime.http.engine.crt.CrtHttpEngine
-import aws.sdk.kotlin.runtime.http.middleware.ServiceEndpointResolver
 import aws.sdk.kotlin.runtime.http.middleware.UserAgent
 import aws.smithy.kotlin.runtime.client.ExecutionContext
 import aws.smithy.kotlin.runtime.client.SdkClientOption
 import aws.smithy.kotlin.runtime.client.SdkLogMode
 import aws.smithy.kotlin.runtime.http.*
 import aws.smithy.kotlin.runtime.http.engine.HttpClientEngine
+import aws.smithy.kotlin.runtime.http.middleware.ResolveEndpoint
 import aws.smithy.kotlin.runtime.http.operation.*
 import aws.smithy.kotlin.runtime.http.response.HttpResponse
 import aws.smithy.kotlin.runtime.io.Closeable
@@ -78,22 +76,11 @@ public class ImdsClient private constructor(builder: Builder) : InstanceMetadata
         }
 
         httpClient = sdkHttpClient(engine)
-
-        // validate the override at construction time
-        if (endpointConfiguration is EndpointConfiguration.Custom) {
-            val url = endpointConfiguration.endpoint.toUrl()
-            try {
-                Url.parse(url.toString())
-            } catch (ex: Exception) {
-                throw ConfigurationException("Invalid endpoint configuration: `$url` is not a valid URI", ex)
-            }
-        }
     }
 
     // cached middleware instances
     private val middleware: List<Feature> = listOf(
-        ServiceEndpointResolver.create {
-            serviceId = SERVICE
+        ResolveEndpoint.create {
             resolver = ImdsEndpointResolver(platformProvider, endpointConfiguration)
         },
         UserAgent.create {
@@ -220,13 +207,13 @@ public enum class EndpointMode(internal val defaultEndpoint: Endpoint) {
      * IPv4 mode. This is the default unless otherwise specified
      * e.g. `http://169.254.169.254'
      */
-    IPv4(Endpoint("169.254.169.254", "http")),
+    IPv4(Endpoint("http://169.254.169.254")),
 
     /**
      * IPv6 mode
      * e.g. `http://[fd00:ec2::254]`
      */
-    IPv6(Endpoint("[fd00:ec2::254]", "http"));
+    IPv6(Endpoint("http://[fd00:ec2::254]"));
 
     public companion object {
         public fun fromValue(value: String): EndpointMode = when (value.lowercase()) {
@@ -244,13 +231,3 @@ public enum class EndpointMode(internal val defaultEndpoint: Endpoint) {
  * @param message The error message
  */
 public class EC2MetadataError(public val statusCode: Int, message: String) : AwsServiceException(message)
-
-private fun Endpoint.toUrl(): Url {
-    val endpoint = this
-    val protocol = Protocol.parse(endpoint.protocol)
-    return Url(
-        scheme = protocol,
-        host = endpoint.hostname,
-        port = endpoint.port ?: protocol.defaultPort,
-    )
-}

aws-runtime/aws-config/common/src/aws/sdk/kotlin/runtime/config/imds/ImdsEndpointResolver.kt

@@ -8,9 +8,8 @@ package aws.sdk.kotlin.runtime.config.imds
 import aws.sdk.kotlin.runtime.config.AwsSdkSetting
 import aws.sdk.kotlin.runtime.config.profile.loadActiveAwsProfile
 import aws.sdk.kotlin.runtime.config.resolve
-import aws.sdk.kotlin.runtime.endpoint.Endpoint
-import aws.sdk.kotlin.runtime.endpoint.EndpointResolver
-import aws.smithy.kotlin.runtime.http.Url
+import aws.smithy.kotlin.runtime.http.operation.Endpoint
+import aws.smithy.kotlin.runtime.http.operation.EndpointResolver
 import aws.smithy.kotlin.runtime.util.PlatformProvider
 import aws.smithy.kotlin.runtime.util.asyncLazy
 
@@ -25,7 +24,7 @@ internal class ImdsEndpointResolver(
     private val resolvedEndpoint = asyncLazy(::doResolveEndpoint)
     private val activeProfile = asyncLazy { loadActiveAwsProfile(platformProvider) }
 
-    override suspend fun resolve(service: String, region: String): Endpoint = resolvedEndpoint.get()
+    override suspend fun resolve(): Endpoint = resolvedEndpoint.get()
 
     private suspend fun doResolveEndpoint(): Endpoint = when (endpointConfiguration) {
         is EndpointConfiguration.Custom -> endpointConfiguration.endpoint
@@ -63,7 +62,4 @@ internal class ImdsEndpointResolver(
 }
 
 // Parse a string as a URL and convert to an endpoint
-internal fun String.toEndpoint(): Endpoint {
-    val url = Url.parse(this)
-    return Endpoint(url.host, url.scheme.protocolName, url.port)
-}
+internal fun String.toEndpoint(): Endpoint = Endpoint(this)

aws-runtime/aws-config/common/test/aws/sdk/kotlin/runtime/config/imds/ImdsClientTest.kt

@@ -5,12 +5,9 @@
 
 package aws.sdk.kotlin.runtime.config.imds
 
-import aws.sdk.kotlin.runtime.ConfigurationException
-import aws.sdk.kotlin.runtime.endpoint.Endpoint
 import aws.sdk.kotlin.runtime.testing.TestPlatformProvider
 import aws.sdk.kotlin.runtime.testing.runSuspendTest
-import aws.smithy.kotlin.runtime.http.*
-import aws.smithy.kotlin.runtime.httptest.TestConnection
+import aws.smithy.kotlin.runtime.http.operation.Endpoint
 import aws.smithy.kotlin.runtime.httptest.buildTestConnection
 import aws.smithy.kotlin.runtime.time.Instant
 import aws.smithy.kotlin.runtime.time.ManualClock
@@ -25,19 +22,6 @@ import kotlin.time.ExperimentalTime
 @OptIn(ExperimentalTime::class)
 class ImdsClientTest {
 
-    @Test
-    fun testInvalidEndpointOverrideFailsCreation() {
-        val connection = TestConnection()
-        assertFailsWith<ConfigurationException> {
-            ImdsClient {
-                engine = connection
-                endpointConfiguration = EndpointConfiguration.Custom(
-                    Endpoint("[foo::254]", protocol = "http")
-                )
-            }
-        }
-    }
-
     @Test
     fun testTokensAreCached() = runSuspendTest {
         val connection = buildTestConnection {
@@ -252,8 +236,7 @@ class ImdsClientTest {
         val client = ImdsClient {
             engine = connection
             test.endpointOverride?.let { endpointOverride ->
-                val endpoint = Url.parse(endpointOverride).let { Endpoint(it.host, it.scheme.protocolName) }
-
+                val endpoint = Endpoint(endpointOverride)
                 endpointConfiguration = EndpointConfiguration.Custom(endpoint)
             }
             test.modeOverride?.let {

aws-runtime/aws-endpoint/build.gradle.kts

@@ -8,13 +8,14 @@ extra["displayName"] = "AWS :: SDK :: Kotlin :: Endpoint"
 extra["moduleName"] = "aws.sdk.kotlin.runtime.endpoint"
 
 val smithyKotlinVersion: String by project
-val kotestVersion: String by project
 
 kotlin {
     sourceSets {
         commonMain{
             dependencies {
                 implementation(project(":aws-runtime:aws-core"))
+                // exposes Endpoint
+                api("aws.smithy.kotlin:http:$smithyKotlinVersion")
             }
         }
 

aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/AwsEndpoint.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+package aws.sdk.kotlin.runtime.endpoint
+
+import aws.smithy.kotlin.runtime.http.Url
+import aws.smithy.kotlin.runtime.http.operation.Endpoint
+
+/**
+ * Represents the endpoint a service client should make API operation calls to.
+ *
+ * The SDK will automatically resolve these endpoints per API client using an internal resolver.
+ *
+ * @property endpoint The endpoint clients will use to make API calls
+ * to e.g. "{service-id}.{region}.amazonaws.com"
+ * @property credentialScope Custom signing constraint overrides
+ */
+public data class AwsEndpoint(
+    public val endpoint: Endpoint,
+    public val credentialScope: CredentialScope? = null
+) {
+    public constructor(url: Url, credentialScope: CredentialScope? = null) : this(Endpoint(url), credentialScope)
+    public constructor(url: String, credentialScope: CredentialScope? = null) : this(Endpoint(Url.parse(url)), credentialScope)
+}

…lin/runtime/endpoint/EndpointResolver.kt …/runtime/endpoint/AwsEndpointResolver.ktaws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/EndpointResolver.kt renamed to aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/AwsEndpointResolver.kt aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/EndpointResolver.kt renamed to aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/AwsEndpointResolver.kt

@@ -8,13 +8,13 @@ package aws.sdk.kotlin.runtime.endpoint
 /**
  * Resolves endpoints for a given service and region
  */
-public interface EndpointResolver {
+public fun interface AwsEndpointResolver {
 
     /**
-     * Resolve the [Endpoint] for the given service and region
+     * Resolve the [AwsEndpoint] for the given service and region
      * @param service the service id associated with the desired endpoint
      * @param region the region associated with the desired endpoint
-     * @return an [Endpoint] that can be used to connect to the service
+     * @return an [AwsEndpoint] that can be used to connect to the service
      */
-    public suspend fun resolve(service: String, region: String): Endpoint
+    public suspend fun resolve(service: String, region: String): AwsEndpoint
 }

aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/CredentialScope.kt

@@ -0,0 +1,14 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+package aws.sdk.kotlin.runtime.endpoint
+
+/**
+ * A custom signing constraint for an endpoint
+ *
+ * @property region A custom sigv4 signing name
+ * @property service A custom sigv4 service name to use when signing a request
+ */
+public data class CredentialScope(val region: String? = null, val service: String? = null)

aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/Endpoint.kt

@@ -6,8 +6,8 @@
 package aws.sdk.kotlin.runtime.endpoint
 
 /**
- * An [EndpointResolver] that returns a static endpoint
+ * An [AwsEndpointResolver] that returns a static endpoint
  */
-public class StaticEndpointResolver(private val endpoint: Endpoint) : EndpointResolver {
-    override suspend fun resolve(service: String, region: String): Endpoint = endpoint
+public class StaticEndpointResolver(private val endpoint: AwsEndpoint) : AwsEndpointResolver {
+    override suspend fun resolve(service: String, region: String): AwsEndpoint = endpoint
 }

aws-runtime/aws-endpoint/common/src/aws/sdk/kotlin/runtime/endpoint/StaticEndpointResolver.kt

@@ -6,22 +6,17 @@
 package aws.sdk.kotlin.runtime.endpoint.internal
 
 import aws.sdk.kotlin.runtime.InternalSdkApi
-import aws.sdk.kotlin.runtime.endpoint.Endpoint
+import aws.sdk.kotlin.runtime.endpoint.AwsEndpoint
+import aws.sdk.kotlin.runtime.endpoint.CredentialScope
+import aws.smithy.kotlin.runtime.http.Protocol
+import aws.smithy.kotlin.runtime.http.Url
+import aws.smithy.kotlin.runtime.http.operation.Endpoint
 
 private const val defaultProtocol = "https"
 private const val defaultSigner = "v4"
 private val protocolPriority = listOf("https", "http")
 private val signerPriority = listOf("v4")
 
-/**
- * A custom signing constraint for an endpoint
- *
- * @property region A custom sigv4 signing name
- * @property service A custom sigv4 service name to use when signing a request
- */
-@InternalSdkApi
-public data class CredentialScope(val region: String? = null, val service: String? = null)
-
 /**
  * A description of a single service endpoint
  */
@@ -96,7 +91,7 @@ public data class Partition(
 internal fun Partition.canResolveEndpoint(region: String): Boolean =
     endpoints.containsKey(region) || regionRegex.matches(region)
 
-internal fun Partition.resolveEndpoint(region: String): Endpoint? {
+internal fun Partition.resolveEndpoint(region: String): AwsEndpoint {
     val resolvedRegion = if (region.isEmpty() && partitionEndpoint.isNotEmpty()) {
         partitionEndpoint
     } else {
@@ -119,7 +114,7 @@ private fun Partition.endpointDefinitionForRegion(region: String): EndpointDefin
     return match ?: EndpointDefinition()
 }
 
-internal fun EndpointDefinition.resolve(region: String, defaults: EndpointDefinition): Endpoint {
+internal fun EndpointDefinition.resolve(region: String, defaults: EndpointDefinition): AwsEndpoint {
     val merged = mergeDefinitions(this, defaults)
 
     // hostname must have been set either by default or on this endpoint
@@ -130,7 +125,9 @@ internal fun EndpointDefinition.resolve(region: String, defaults: EndpointDefini
     val signingName = merged.credentialScope?.service
     val signingRegion = merged.credentialScope?.region ?: region
 
-    return Endpoint(hostname, protocol, signingName = signingName, signingRegion = signingRegion)
+    val uri = Url(Protocol.parse(protocol), hostname)
+    val scope = CredentialScope(signingRegion, signingName)
+    return AwsEndpoint(Endpoint(uri), scope)
 }
 
 /**
@@ -164,7 +161,7 @@ private fun getByPriority(from: List<String>, priority: List<String>, default: S
  * Resolve an endpoint for a given region using the given partitions
  */
 @InternalSdkApi
-public fun resolveEndpoint(partitions: List<Partition>, region: String): Endpoint? {
+public fun resolveEndpoint(partitions: List<Partition>, region: String): AwsEndpoint? {
     if (partitions.isEmpty()) return null
 
     // fallback to first partition if no candidate found