feat: make HTTP engines copyable/reconfigurable in service client config (#851)

Author: ianbotsf

.changes/b35b5256-bb67-415b-84af-49be743aed14.json

@@ -0,0 +1,5 @@
+{
+    "id": "b35b5256-bb67-415b-84af-49be743aed14",
+    "type": "feature",
+    "description": "**Breaking**: Make HTTP engines configurable in client config during initialization and during `withCopy`. See [this discussion post](https://github.com/awslabs/aws-sdk-kotlin/discussions/new?category=announcements) for more information."
+}

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/core/RuntimeTypes.kt

@@ -72,6 +72,7 @@ object RuntimeTypes {
 
         object Config : RuntimeTypePackage(KotlinDependency.HTTP, "config") {
             val HttpClientConfig = symbol("HttpClientConfig")
+            val HttpEngineConfig = symbol("HttpEngineConfig")
         }
 
         object Engine : RuntimeTypePackage(KotlinDependency.HTTP, "engine") {
@@ -335,6 +336,7 @@ object RuntimeTypes {
     object HttpClientEngines {
         object Default : RuntimeTypePackage(KotlinDependency.DEFAULT_HTTP_ENGINE) {
             val DefaultHttpEngine = symbol("DefaultHttpEngine")
+            val HttpEngineConfigImpl = symbol("HttpEngineConfigImpl")
         }
     }
 

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/ServiceClientConfigGenerator.kt

@@ -44,7 +44,7 @@ class ServiceClientConfigGenerator(
         add(RuntimeConfigProperty.ClientName)
         add(RuntimeConfigProperty.LogMode)
         if (context.protocolGenerator?.applicationProtocol?.isHttpProtocol == true) {
-            add(RuntimeConfigProperty.HttpClientEngine)
+            add(RuntimeConfigProperty.HttpClient)
             add(RuntimeConfigProperty.HttpInterceptors)
             add(RuntimeConfigProperty.HttpAuthSchemes)
         }

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/protocol/HttpProtocolClientGenerator.kt

@@ -81,7 +81,7 @@ abstract class HttpProtocolClientGenerator(
      */
     protected open fun renderProperties(writer: KotlinWriter) {
         writer.write("private val managedResources = #T()", RuntimeTypes.Core.IO.SdkManagedGroup)
-        writer.write("private val client = #T(config.httpClientEngine)", RuntimeTypes.HttpClient.SdkHttpClient)
+        writer.write("private val client = #T(config.httpClient)", RuntimeTypes.HttpClient.SdkHttpClient)
 
         // render auth resolver related properties
         writer.write("private val identityProviderConfig = #T(config)", IdentityProviderConfigGenerator.getSymbol(ctx.settings))
@@ -133,7 +133,7 @@ abstract class HttpProtocolClientGenerator(
      */
     protected open fun renderInit(writer: KotlinWriter) {
         writer.withBlock("init {", "}") {
-            write("managedResources.#T(config.httpClientEngine)", RuntimeTypes.Core.IO.addIfManaged)
+            write("managedResources.#T(config.httpClient)", RuntimeTypes.Core.IO.addIfManaged)
         }
     }
 

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/protocol/HttpProtocolUnitTestRequestGenerator.kt

@@ -115,7 +115,7 @@ open class HttpProtocolUnitTestRequestGenerator protected constructor(builder: B
      * configures a mock HttpClientEngine and an idempotency token generator appropriate for protocol tests.
      */
     open fun renderConfigureServiceClient(test: HttpRequestTestCase) {
-        writer.write("httpClientEngine = mockEngine")
+        writer.write("httpClient = mockEngine")
         if (idempotentFieldsInModel) {
             writer.write("idempotencyTokenProvider = #T { \"00000000-0000-4000-8000-000000000000\" }", RuntimeTypes.SmithyClient.IdempotencyTokenProvider)
         }

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/protocol/HttpProtocolUnitTestResponseGenerator.kt

@@ -108,7 +108,7 @@ open class HttpProtocolUnitTestResponseGenerator protected constructor(builder:
      * configures a mock HttpClientEngine and an idempotency token generator appropriate for protocol tests.
      */
     open fun renderConfigureServiceClient(test: HttpResponseTestCase) {
-        writer.write("httpClientEngine = mockEngine")
+        writer.write("httpClient = mockEngine")
         if (idempotentFieldsInModel) {
             // see: https://awslabs.github.io/smithy/1.0/spec/http-protocol-compliance-tests.html#parameter-format
             writer.write("idempotencyTokenProvider = #T { \"00000000-0000-4000-8000-000000000000\" }", RuntimeTypes.SmithyClient.IdempotencyTokenProvider)

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/util/AbstractConfigGenerator.kt

@@ -5,6 +5,7 @@
 
 package software.amazon.smithy.kotlin.codegen.rendering.util
 
+import software.amazon.smithy.codegen.core.Symbol
 import software.amazon.smithy.codegen.core.SymbolReference
 import software.amazon.smithy.kotlin.codegen.core.CodegenContext
 import software.amazon.smithy.kotlin.codegen.core.KotlinWriter
@@ -49,7 +50,7 @@ abstract class AbstractConfigGenerator {
         addPropertyImports(props, writer)
 
         val sortedProps = props.sortedWith(compareBy({ it.order }, { it.propertyName }))
-        val formattedBaseClasses = props.formattedBaseClasses { it.baseClass?.name }
+        val formattedBaseClasses = props.formattedBaseClasses { it.baseClass to it.baseClassDelegate }
 
         writer.withBlock(
             "$visibility class #configClass.name:L private constructor(builder: Builder)$formattedBaseClasses {",
@@ -75,14 +76,12 @@ abstract class AbstractConfigGenerator {
      */
     private fun addPropertyImports(props: Collection<ConfigProperty>, writer: KotlinWriter) {
         props.forEach {
-            it.baseClass?.let { baseClass ->
-                writer.addImport(baseClass)
-            }
+            it.baseClass?.let(writer::addImport)
+            it.baseClassDelegate?.symbol?.let(writer::addImport)
+            it.builderBaseClassDelegate?.symbol?.let(writer::addImport)
             writer.addImport(it.symbol)
             writer.addImportReferences(it.symbol, SymbolReference.ContextOption.USE)
-            it.additionalImports.forEach { symbol ->
-                writer.addImport(symbol)
-            }
+            it.additionalImports.forEach(writer::addImport)
         }
     }
 
@@ -130,7 +129,7 @@ abstract class AbstractConfigGenerator {
     }
 
     protected open fun renderBuilder(props: Collection<ConfigProperty>, writer: KotlinWriter) {
-        val formattedBaseClasses = props.formattedBaseClasses { it.builderBaseClass?.name }
+        val formattedBaseClasses = props.formattedBaseClasses { it.builderBaseClass to it.builderBaseClassDelegate }
 
         writer.write("")
             .withBlock("$visibility class Builder$formattedBaseClasses {", "}") {
@@ -159,8 +158,11 @@ abstract class AbstractConfigGenerator {
      * Return the formatted base classes for the config property
      * @param transform the selector from config property that maps the property to a base class name
      */
-    private inline fun Collection<ConfigProperty>.formattedBaseClasses(transform: (ConfigProperty) -> String?): String {
-        val baseClasses = mapNotNull(transform)
+    private inline fun Collection<ConfigProperty>.formattedBaseClasses(
+        transform: (ConfigProperty) -> Pair<Symbol?, Delegate?>,
+    ): String {
+        val baseClasses = map(transform)
+            .mapNotNull { (symbol, delegate) -> symbol?.format(delegate) }
             .sorted()
             .toSet()
             .joinToString(", ")
@@ -178,3 +180,6 @@ abstract class AbstractConfigGenerator {
         }
     }
 }
+
+private fun Symbol.format(delegate: Delegate?): String =
+    name + (delegate?.let { " by ${it.delegationExpression}" } ?: "")

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/util/ConfigProperty.kt

@@ -78,13 +78,33 @@ class ConfigProperty private constructor(builder: Builder) {
      */
     val baseClass: Symbol? = builder.baseClass
 
+    /**
+     * A delegate the config object should use as the backing implementation of this property's base class. This enables
+     * class specifications such as:
+     *
+     * ```kotlin
+     * class Config : BaseClass by BaseClassDelegate(...)
+     * ```
+     */
+    val baseClassDelegate: Delegate? = builder.baseClassDelegate
+
     /**
      * Additional base classes the config builder should inherit from
      *
      * NOTE: Adding 1 or more base classes will implicitly render the property with an `override` modifier
      */
     val builderBaseClass: Symbol? = builder.builderBaseClass
 
+    /**
+     * A delegate the config builder object should use as the backing implementation of this property's builder base
+     * class. This enables class specifications such as:
+     *
+     * ```kotlin
+     * class Builder : BuilderBaseClass by BuilderBaseClassDelegate(...)
+     * ```
+     */
+    val builderBaseClassDelegate: Delegate? = builder.builderBaseClassDelegate
+
     /**
      * The configuration property type. This controls how the property is constructed and rendered
      */
@@ -193,7 +213,9 @@ class ConfigProperty private constructor(builder: Builder) {
         var documentation: String? = null
 
         var baseClass: Symbol? = null
+        var baseClassDelegate: Delegate? = null
         var builderBaseClass: Symbol? = null
+        var builderBaseClassDelegate: Delegate? = null
 
         var propertyType: ConfigPropertyType = ConfigPropertyType.SymbolDefault
 
@@ -231,6 +253,14 @@ class ConfigProperty private constructor(builder: Builder) {
     }
 }
 
+/**
+ * Represents a type which may be used for [inheritance delegation](https://kotlinlang.org/docs/delegation.html).
+ * @param symbol The symbol for the delegate target. Codegenerators should import this symbol where appropriate so that
+ * the [delegationExpression] has the correct symbol in scope.
+ * @param delegationExpression The code expression for how to delegate
+ */
+data class Delegate(val symbol: Symbol?, val delegationExpression: String)
+
 private fun builtInSymbol(symbolName: String, defaultValue: String?): Symbol {
     val builder = Symbol.builder()
         .name(symbolName)

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/util/RuntimeConfigProperty.kt

@@ -42,28 +42,25 @@ object RuntimeConfigProperty {
         order = -100
     }
 
-    val HttpClientEngine = ConfigProperty {
+    val HttpClient = ConfigProperty {
+        name = "httpClient"
         symbol = RuntimeTypes.HttpClient.Engine.HttpClientEngine
-        baseClass = RuntimeTypes.HttpClient.Config.HttpClientConfig
-        useNestedBuilderBaseClass()
-        documentation = """
-        Override the default HTTP client engine used to make SDK requests (e.g. configure proxy behavior, timeouts, concurrency, etc).
-        NOTE: The caller is responsible for managing the lifetime of the engine when set. The SDK
-        client will not close it when the client is closed.
-        """.trimIndent()
-        order = -100
 
-        propertyType = ConfigPropertyType.Custom(
-            render = { prop, writer ->
-                writer.write(
-                    "override val #1L: #2T = builder.#1L ?: #3T().#4T()",
-                    prop.propertyName,
-                    prop.symbol,
-                    RuntimeTypes.HttpClientEngines.Default.DefaultHttpEngine,
-                    RuntimeTypes.HttpClient.Engine.manage,
-                )
-            },
+        baseClass = RuntimeTypes.HttpClient.Config.HttpEngineConfig
+        baseClassDelegate = Delegate(null, "builder.buildHttpEngineConfig()")
+
+        builderBaseClass = RuntimeTypes.HttpClient.Config.HttpEngineConfig.let {
+            buildSymbol {
+                name = "${it.name}.Builder"
+                namespace = it.namespace
+            }
+        }
+        builderBaseClassDelegate = Delegate(
+            RuntimeTypes.HttpClientEngines.Default.HttpEngineConfigImpl,
+            "HttpEngineConfigImpl.BuilderImpl()",
         )
+
+        propertyType = ConfigPropertyType.Custom({ _, _ -> }, { _, _ -> })
     }
 
     val IdempotencyTokenProvider = ConfigProperty {

codegen/smithy-kotlin-codegen/src/test/kotlin/software/amazon/smithy/kotlin/codegen/rendering/ServiceClientConfigGeneratorTest.kt

@@ -42,13 +42,12 @@ class ServiceClientConfigGeneratorTest {
         contents.assertBalancedBracesAndParens()
 
         val expectedCtor = """
-public class Config private constructor(builder: Builder) : HttpAuthConfig, HttpClientConfig, IdempotencyTokenConfig, SdkClientConfig, TracingClientConfig {
+public class Config private constructor(builder: Builder) : HttpAuthConfig, HttpClientConfig, HttpEngineConfig by builder.buildHttpEngineConfig(), IdempotencyTokenConfig, SdkClientConfig, TracingClientConfig {
 """
         contents.shouldContainWithDiff(expectedCtor)
 
         val expectedProps = """
     override val clientName: String = builder.clientName
-    override val httpClientEngine: HttpClientEngine = builder.httpClientEngine ?: DefaultHttpEngine().manage()
     override val authSchemes: kotlin.collections.List<aws.smithy.kotlin.runtime.http.auth.HttpAuthScheme> = builder.authSchemes
     public val endpointProvider: EndpointProvider = requireNotNull(builder.endpointProvider) { "endpointProvider is a required configuration property" }
     override val idempotencyTokenProvider: IdempotencyTokenProvider = builder.idempotencyTokenProvider ?: IdempotencyTokenProvider.Default
@@ -61,19 +60,12 @@ public class Config private constructor(builder: Builder) : HttpAuthConfig, Http
         contents.shouldContainWithDiff(expectedProps)
 
         val expectedBuilder = """
-    public class Builder : HttpAuthConfig.Builder, HttpClientConfig.Builder, IdempotencyTokenConfig.Builder, SdkClientConfig.Builder<Config>, TracingClientConfig.Builder {
+    public class Builder : HttpAuthConfig.Builder, HttpClientConfig.Builder, HttpEngineConfig.Builder by HttpEngineConfigImpl.BuilderImpl(), IdempotencyTokenConfig.Builder, SdkClientConfig.Builder<Config>, TracingClientConfig.Builder {
         /**
          * A reader-friendly name for the client.
          */
         override var clientName: String = "Test"
 
-        /**
-         * Override the default HTTP client engine used to make SDK requests (e.g. configure proxy behavior, timeouts, concurrency, etc).
-         * NOTE: The caller is responsible for managing the lifetime of the engine when set. The SDK
-         * client will not close it when the client is closed.
-         */
-        override var httpClientEngine: HttpClientEngine? = null
-
         /**
          * Register new or override default [HttpAuthScheme]s configured for this client. By default, the set
          * of auth schemes configured comes from the service model. An auth scheme configured explicitly takes
@@ -256,7 +248,6 @@ public class Config private constructor(builder: Builder) {
         // Expect logMode config value to override default to LogMode.Request
         val expectedConfigValues = """
     override val clientName: String = builder.clientName
-    override val httpClientEngine: HttpClientEngine = builder.httpClientEngine ?: DefaultHttpEngine().manage()
     override val authSchemes: kotlin.collections.List<aws.smithy.kotlin.runtime.http.auth.HttpAuthScheme> = builder.authSchemes
     public val customProp: Int? = builder.customProp
     public val endpointProvider: EndpointProvider = requireNotNull(builder.endpointProvider) { "endpointProvider is a required configuration property" }