feat(rt): http client engine config (#493)

Author: aajtodd

.github/ISSUE_TEMPLATE/feature_request.md

@@ -30,7 +30,7 @@ labels: enhancement, needs-triage
 <!--- Any alternative solutions or features you've considered -->
 
 ## Additional Context
-<!--- How has the lack of this feaure affected you? What are you trying to accomplish? -->
+<!--- How has the lack of this feature affected you? What are you trying to accomplish? -->
 <!--- Providing context helps us come up with a solution that is most useful in the real world -->
 
 

runtime/protocol/http-client-engines/http-client-engine-ktor/jvm/src/aws/smithy/kotlin/runtime/http/engine/ktor/KtorEngine.kt

@@ -6,10 +6,7 @@ package aws.smithy.kotlin.runtime.http.engine.ktor
 
 import aws.smithy.kotlin.runtime.http.Headers
 import aws.smithy.kotlin.runtime.http.HttpStatusCode
-import aws.smithy.kotlin.runtime.http.engine.HttpClientEngine
-import aws.smithy.kotlin.runtime.http.engine.HttpClientEngineBase
-import aws.smithy.kotlin.runtime.http.engine.HttpClientEngineConfig
-import aws.smithy.kotlin.runtime.http.engine.callContext
+import aws.smithy.kotlin.runtime.http.engine.*
 import aws.smithy.kotlin.runtime.http.request.HttpRequest
 import aws.smithy.kotlin.runtime.http.response.HttpCall
 import aws.smithy.kotlin.runtime.logging.*
@@ -24,15 +21,46 @@ import kotlinx.coroutines.channels.Channel
 import kotlinx.coroutines.channels.SendChannel
 import kotlinx.coroutines.job
 import kotlinx.coroutines.launch
+import okhttp3.ConnectionPool
+import okhttp3.Protocol
+import java.util.concurrent.TimeUnit
 import kotlin.coroutines.CoroutineContext
+import kotlin.time.ExperimentalTime
+import kotlin.time.toJavaDuration
 import aws.smithy.kotlin.runtime.http.response.HttpResponse as SdkHttpResponse
 
 /**
  * JVM [HttpClientEngine] backed by Ktor
  */
-class KtorEngine(val config: HttpClientEngineConfig) : HttpClientEngineBase("ktor") {
+class KtorEngine(
+    private val config: HttpClientEngineConfig = HttpClientEngineConfig.Default
+) : HttpClientEngineBase("ktor-okhttp") {
+    @OptIn(ExperimentalTime::class)
     val client: HttpClient = HttpClient(OkHttp) {
-        // TODO - propagate applicable client engine config to OkHttp engine
+        engine {
+            config {
+                connectTimeout(config.connectTimeout.toJavaDuration())
+                readTimeout(config.socketReadTimeout.toJavaDuration())
+                writeTimeout(config.socketWriteTimeout.toJavaDuration())
+                val pool = ConnectionPool(
+                    maxIdleConnections = config.maxConnections.toInt(),
+                    keepAliveDuration = config.connectionIdleTimeout.inWholeMilliseconds,
+                    TimeUnit.MILLISECONDS
+                )
+                connectionPool(pool)
+
+                if (config.alpn.isNotEmpty()) {
+                    val protocols = config.alpn.mapNotNull {
+                        when (it) {
+                            AlpnId.HTTP1_1 -> Protocol.HTTP_1_1
+                            AlpnId.HTTP2 -> Protocol.HTTP_2
+                            else -> null
+                        }
+                    }
+                    protocols(protocols)
+                }
+            }
+        }
 
         // do not throw exceptions if status code < 300, error handling is expected by generated clients
         expectSuccess = false

runtime/protocol/http/common/src/aws/smithy/kotlin/runtime/http/HttpClientConfig.kt

@@ -8,6 +8,7 @@ import aws.smithy.kotlin.runtime.http.engine.HttpClientEngine
 import aws.smithy.kotlin.runtime.http.engine.HttpClientEngineClosedException
 import aws.smithy.kotlin.runtime.http.engine.SdkRequestContextElement
 import aws.smithy.kotlin.runtime.http.engine.createCallContext
+import aws.smithy.kotlin.runtime.http.request.HttpRequest
 import aws.smithy.kotlin.runtime.http.request.HttpRequestBuilder
 import aws.smithy.kotlin.runtime.http.response.HttpCall
 import aws.smithy.kotlin.runtime.io.Handler
@@ -21,15 +22,10 @@ typealias HttpHandler = Handler<HttpRequestBuilder, HttpCall>
  * Create an [SdkHttpClient] with the given engine, and optionally configure it
  * This will **not** manage the engine lifetime, the caller is expected to close it.
  */
-@HttpClientDsl
 fun sdkHttpClient(
     engine: HttpClientEngine,
-    configure: HttpClientConfig.() -> Unit = {},
     manageEngine: Boolean = false,
-): SdkHttpClient {
-    val config = HttpClientConfig().apply(configure)
-    return SdkHttpClient(engine, config, manageEngine)
-}
+): SdkHttpClient = SdkHttpClient(engine, manageEngine)
 
 /**
  * An HTTP client capable of round tripping requests and responses
@@ -38,19 +34,20 @@ fun sdkHttpClient(
  */
 class SdkHttpClient(
     val engine: HttpClientEngine,
-    val config: HttpClientConfig,
     private val manageEngine: Boolean = false
 ) : HttpHandler {
     private val closed = atomic(false)
 
-    override suspend fun call(request: HttpRequestBuilder): HttpCall = executeWithCallContext(request)
+    suspend fun call(request: HttpRequest): HttpCall = executeWithCallContext(request)
+    override suspend fun call(request: HttpRequestBuilder): HttpCall = executeWithCallContext(request.build())
 
-    private suspend fun executeWithCallContext(request: HttpRequestBuilder): HttpCall {
+    // FIXME - can we relocate to engine?
+    private suspend fun executeWithCallContext(request: HttpRequest): HttpCall {
         if (!engine.coroutineContext.job.isActive) throw HttpClientEngineClosedException()
         val callContext = engine.createCallContext(coroutineContext)
         val context = callContext + SdkRequestContextElement(callContext)
         return withContext(context) {
-            engine.roundTrip(request.build())
+            engine.roundTrip(request)
         }
     }
 

runtime/protocol/http/common/src/aws/smithy/kotlin/runtime/http/SdkHttpClient.kt

@@ -6,6 +6,7 @@ package aws.smithy.kotlin.runtime.http.engine
 
 import aws.smithy.kotlin.runtime.ClientException
 import aws.smithy.kotlin.runtime.http.request.HttpRequest
+import aws.smithy.kotlin.runtime.http.request.HttpRequestBuilder
 import aws.smithy.kotlin.runtime.http.response.HttpCall
 import aws.smithy.kotlin.runtime.io.Closeable
 import aws.smithy.kotlin.runtime.util.InternalApi
@@ -23,6 +24,12 @@ interface HttpClientEngine : Closeable, CoroutineScope {
      */
     suspend fun roundTrip(request: HttpRequest): HttpCall
 
+    /**
+     * Execute a single HTTP request and return the response
+     * Consumers *MUST* call `HttpCall.complete()` when finished processing the response
+     */
+    suspend fun roundTrip(request: HttpRequestBuilder): HttpCall = roundTrip(request.build())
+
     /**
      * Shutdown and cleanup any resources
      */

runtime/protocol/http/common/src/aws/smithy/kotlin/runtime/http/engine/HttpClientEngine.kt

@@ -4,7 +4,123 @@
  */
 package aws.smithy.kotlin.runtime.http.engine
 
+import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
+
+// See https://github.com/aws/aws-sdk-java-v2/blob/master/http-client-spi/src/main/java/software/amazon/awssdk/http/SdkHttpConfigurationOption.java
+// for all the options the Java v2 SDK supports
+
 /**
  * Common configuration options to be interpreted by an underlying engine
+ *
+ * NOTE: Not all engines will support every option! Engines *SHOULD* log a warning when given a configuration
+ * option they don't understand/support
  */
-class HttpClientEngineConfig
+@OptIn(ExperimentalTime::class)
+open class HttpClientEngineConfig constructor(builder: Builder) {
+    constructor() : this(Builder())
+
+    companion object {
+        operator fun invoke(block: Builder.() -> Unit): HttpClientEngineConfig = HttpClientEngineConfig(Builder().apply(block))
+
+        /**
+         * Default client engine config
+         */
+        val Default: HttpClientEngineConfig = HttpClientEngineConfig(Builder())
+    }
+
+    /**
+     * Timeout for each read to an underlying socket
+     */
+    val socketReadTimeout: Duration = builder.socketReadTimeout
+
+    /**
+     * Timeout for each write to an underlying socket
+     */
+    val socketWriteTimeout: Duration = builder.socketWriteTimeout
+
+    /**
+     * Maximum number of open connections
+     */
+    val maxConnections: UInt = builder.maxConnections
+
+    /**
+     * The amount of time to wait for a connection to be established
+     */
+    val connectTimeout: Duration = builder.connectTimeout
+
+    /**
+     * The amount of time to wait for an already-established connection from a connection pool
+     */
+    val connectionAcquireTimeout: Duration = builder.connectionAcquireTimeout
+
+    /**
+     * The amount of time before an idle connection should be reaped from a connection pool. Zero indicates that
+     * idle connections should never be reaped.
+     */
+    val connectionIdleTimeout: Duration = builder.connectionIdleTimeout
+
+    /**
+     * Set the ALPN protocol list when a TLS connection starts
+     */
+    val alpn: List<AlpnId> = builder.alpn
+
+    open class Builder {
+        /**
+         * Timeout for each read to an underlying socket
+         */
+        var socketReadTimeout: Duration = Duration.seconds(30)
+
+        /**
+         * Timeout for each write to an underlying socket
+         */
+        var socketWriteTimeout: Duration = Duration.seconds(30)
+
+        /**
+         * Maximum number of open connections
+         */
+        var maxConnections: UInt = 16u
+
+        /**
+         * The amount of time to wait for a connection to be established
+         */
+        var connectTimeout: Duration = Duration.seconds(2)
+
+        /**
+         * The amount of time to wait for an already-established connection from a connection pool
+         */
+        var connectionAcquireTimeout: Duration = Duration.seconds(10)
+
+        /**
+         * The amount of time before an idle connection should be reaped from a connection pool. Zero indicates that
+         * idle connections should never be reaped.
+         */
+        var connectionIdleTimeout: Duration = Duration.seconds(60)
+
+        /**
+         * Set the ALPN protocol list when a TLS connection starts
+         */
+        var alpn: List<AlpnId> = emptyList()
+    }
+}
+
+/**
+ * Common ALPN identifiers
+ * See the [IANA registry](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids)
+ */
+enum class AlpnId(val protocolId: String) {
+    /**
+     * HTTP 1.1
+     */
+    HTTP1_1("http/1.1"),
+
+    /**
+     * HTTP 2 over TLS
+     */
+    HTTP2("h2"),
+
+    /**
+     * HTTP 3
+     */
+    HTTP3("h3")
+}

runtime/protocol/http/common/src/aws/smithy/kotlin/runtime/http/engine/HttpClientEngineConfig.kt

@@ -98,6 +98,10 @@ abstract class HttpProtocolClientGenerator(
     }
 
     //  defaults to Ktor since it's the only available engine in smithy-kotlin runtime
+    /**
+     * The client engine to default to when one is not given in config. This type *MUST* be default constructable
+     * or else you need to override [renderInit] and construct it manually
+     */
     protected open val defaultHttpClientEngineSymbol: Symbol = buildSymbol {
         name = "KtorEngine"
         namespace(KotlinDependency.HTTP_KTOR_ENGINE)
@@ -109,7 +113,7 @@ abstract class HttpProtocolClientGenerator(
     protected open fun renderInit(writer: KotlinWriter) {
         writer.addImport(defaultHttpClientEngineSymbol)
         writer.openBlock("init {", "}") {
-            writer.write("val httpClientEngine = config.httpClientEngine ?: #T(HttpClientEngineConfig())", defaultHttpClientEngineSymbol)
+            writer.write("val httpClientEngine = config.httpClientEngine ?: #T()", defaultHttpClientEngineSymbol)
             writer.write("client = sdkHttpClient(httpClientEngine, manageEngine = config.httpClientEngine == null)")
         }
     }

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

@@ -52,7 +52,7 @@ class HttpProtocolClientGeneratorTest {
         commonTestContents.shouldContainOnlyOnceWithDiff("val client: SdkHttpClient")
         val expected = """
     init {
-        val httpClientEngine = config.httpClientEngine ?: KtorEngine(HttpClientEngineConfig())
+        val httpClientEngine = config.httpClientEngine ?: KtorEngine()
         client = sdkHttpClient(httpClientEngine, manageEngine = config.httpClientEngine == null)
     }
 """