0
# AWS HTTP JVM
1

2
AWS HTTP JVM provides HTTP core functionality for AWS service clients in the AWS SDK for Kotlin. It implements essential HTTP operations including user agent management, retry policies, request/response middleware, business metrics collection, and HTTP authentication integration for AWS services.
3

4
## Package Information
5

6
- **Package Name**: aws-http-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin (multiplatform)
9
- **Group ID**: aws.sdk.kotlin
10
- **Artifact ID**: aws-http-jvm
11
- **Installation**: Add to your `build.gradle.kts`:
12

13
```kotlin
14
implementation("aws.sdk.kotlin:aws-http-jvm:1.5.33")
15
```
16

17
## Core Imports
18

19
```kotlin
20
import aws.sdk.kotlin.runtime.http.*
21
import aws.sdk.kotlin.runtime.http.middleware.*
22
import aws.sdk.kotlin.runtime.http.interceptors.*
23
import aws.sdk.kotlin.runtime.http.retries.*
24
```
25

26
## Basic Usage
27

28
```kotlin
29
import aws.sdk.kotlin.runtime.http.AwsUserAgentMetadata
30
import aws.sdk.kotlin.runtime.http.ApiMetadata
31
import aws.sdk.kotlin.runtime.http.retries.AwsRetryPolicy
32
import aws.sdk.kotlin.runtime.http.middleware.UserAgent
33

34
// Create user agent metadata
35
val apiMetadata = ApiMetadata(serviceId = "S3", version = "2023-01-01")
36
val userAgentMetadata = AwsUserAgentMetadata.fromEnvironment(apiMetadata)
37

38
// Create user agent middleware
39
val userAgentMiddleware = UserAgent(userAgentMetadata)
40

41
// Use AWS retry policy
42
val retryPolicy = AwsRetryPolicy.Default
43
```
44

45
## Architecture
46

47
AWS HTTP JVM is built around several key components:
48

49
- **User Agent Management**: Comprehensive metadata collection and formatting for AWS service identification
50
- **Retry Policies**: AWS-specific retry logic with exponential backoff and exception handling
51
- **HTTP Middleware**: Request/response processing pipeline components for cross-cutting concerns
52
- **HTTP Interceptors**: Fine-grained request/response modification for tracing, metrics, and authentication
53
- **Business Metrics**: Telemetry collection for AWS service usage patterns and client behavior
54
- **Platform Support**: Multiplatform Kotlin with JVM, native, and common implementations
55

56
## Capabilities
57

58
### Retry Policies
59

60
AWS-specific retry policies that implement exponential backoff, jitter, and AWS service-specific exception handling patterns.
61

62
```kotlin { .api }
63
open class AwsRetryPolicy : StandardRetryPolicy() {
64
    companion object {
65
        val Default: AwsRetryPolicy
66
    }
67
    
68
    protected override fun evaluateSpecificExceptions(ex: Throwable): RetryDirective?
69
}
70
```
71

72
[Retry Policies](./retry-policies.md)
73

74
### User Agent Management
75

76
Comprehensive user agent metadata collection and formatting that provides detailed client identification for AWS services, including SDK version, platform information, and custom metadata.
77

78
```kotlin { .api }
79
data class AwsUserAgentMetadata(
80
    val sdkMetadata: SdkMetadata,
81
    val apiMetadata: ApiMetadata,
82
    val osMetadata: OsMetadata,
83
    val languageMetadata: LanguageMetadata,
84
    val execEnvMetadata: ExecutionEnvMetadata? = null,
85
    val frameworkMetadata: FrameworkMetadata? = null,
86
    val appId: String? = null,
87
    val customMetadata: CustomUserAgentMetadata? = null
88
) {
89
    val xAmzUserAgent: String
90
    val userAgent: String
91
    
92
    companion object {
93
        fun fromEnvironment(apiMeta: ApiMetadata, appId: String? = null): AwsUserAgentMetadata
94
    }
95
}
96
```
97

98
[User Agent Management](./user-agent.md)
99

100
### HTTP Middleware
101

102
Request and response processing middleware components that handle cross-cutting concerns like user agent injection, retry headers, and recursion detection.
103

104
```kotlin { .api }
105
class UserAgent(private val staticMetadata: AwsUserAgentMetadata) : ModifyRequestMiddleware {
106
    override fun install(op: SdkHttpOperation<*, *>)
107
    override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
108
}
109

110
class RecursionDetection(env: EnvironmentProvider = PlatformProvider.System) : ModifyRequestMiddleware {
111
    override fun install(op: SdkHttpOperation<*, *>)
112
    override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
113
}
114

115
class AwsRetryHeaderMiddleware : MutateMiddleware {
116
    suspend fun handle(req: OperationRequest, handler: Handler<OperationRequest, OperationResponse>): OperationResponse
117
    override fun install(op: SdkHttpOperation<*, *>)
118
}
119
```
120

121
[HTTP Middleware](./middleware.md)
122

123
### HTTP Interceptors
124

125
Fine-grained request and response interceptors for advanced processing including business metrics collection, span attributes, and checksum handling.
126

127
```kotlin { .api }
128
object AwsSpanInterceptor : Interceptor {
129
    suspend fun modifyBeforeAttemptCompletion(context: ResponseInterceptorContext<Any, Any>): Result<Any>
130
    suspend fun modifyBeforeCompletion(context: ResponseInterceptorContext<Any, Any>): Result<Any>
131
}
132

133
class AddUserAgentMetadataInterceptor(metadata: Map<String, String>) : Interceptor {
134
    fun readBeforeExecution(context: RequestInterceptorContext<Any>)
135
}
136

137
class IgnoreCompositeFlexibleChecksumResponseInterceptor(
138
    ignoreSha256HeaderErrorResponseHeaders: Boolean,
139
    responseHttpChecksumConfig: ResponseHttpChecksumConfig
140
) : FlexibleChecksumsResponseInterceptor {
141
    override fun ignoreChecksum(algorithmName: String, context: ProtocolResponseInterceptorContext<Any, HttpResponse>): Boolean
142
}
143
```
144

145
[HTTP Interceptors](./interceptors.md)
146

147
### Business Metrics
148

149
AWS telemetry and business metrics collection system that tracks SDK usage patterns, credential providers, and service-specific metrics for analytics and optimization.
150

151
```kotlin { .api }
152
class BusinessMetricsInterceptor : HttpInterceptor {
153
    override suspend fun modifyBeforeTransmit(context: ProtocolRequestInterceptorContext<Any, HttpRequest>): HttpRequest
154
}
155

156
enum class AwsBusinessMetric(override val identifier: String) : BusinessMetric {
157
    S3_EXPRESS_BUCKET("J"),
158
    DDB_MAPPER("d");
159
    
160
    enum class Credentials(override val identifier: String) : BusinessMetric {
161
        CREDENTIALS_CODE("e"),
162
        CREDENTIALS_JVM_SYSTEM_PROPERTIES("f"),
163
        CREDENTIALS_ENV_VARS("g"),
164
        CREDENTIALS_ENV_VARS_STS_WEB_ID_TOKEN("h"),
165
        CREDENTIALS_STS_ASSUME_ROLE("i"),
166
        CREDENTIALS_STS_ASSUME_ROLE_WEB_ID("k"),
167
        CREDENTIALS_PROFILE("n"),
168
        CREDENTIALS_PROFILE_SOURCE_PROFILE("o"),
169
        CREDENTIALS_PROFILE_NAMED_PROVIDER("p"),
170
        CREDENTIALS_PROFILE_STS_WEB_ID_TOKEN("q"),
171
        CREDENTIALS_PROFILE_SSO("r"),
172
        CREDENTIALS_SSO("s"),
173
        CREDENTIALS_PROFILE_SSO_LEGACY("t"),
174
        CREDENTIALS_SSO_LEGACY("u"),
175
        CREDENTIALS_PROFILE_PROCESS("v"),
176
        CREDENTIALS_PROCESS("w"),
177
        CREDENTIALS_HTTP("z"),
178
        CREDENTIALS_IMDS("0")
179
    }
180
}
181
```
182

183
[Business Metrics](./business-metrics.md)
184

185
## Constants
186

187
```kotlin { .api }
188
const val AWS_APP_ID_ENV: String = "AWS_SDK_UA_APP_ID"
189
const val AWS_APP_ID_PROP: String = "aws.userAgentAppId"
190
const val BUSINESS_METRICS_MAX_LENGTH: Int = 1024
191
```
192

193
## Core Types
194

195
```kotlin { .api }
196
data class SdkMetadata(val name: String, val version: String)
197

198
data class ApiMetadata(val serviceId: String, val version: String)
199

200
data class OsMetadata(val family: OsFamily, val version: String? = null)
201

202
data class LanguageMetadata(
203
    val version: String = KotlinVersion.CURRENT.toString(),
204
    val extras: Map<String, String> = emptyMap()
205
)
206

207
data class ExecutionEnvMetadata(val name: String)
208

209
data class FrameworkMetadata(val name: String, val version: String)
210

211
class CustomUserAgentMetadata(
212
    extras: Map<String, String> = mapOf(),
213
    typedExtras: List<TypedUserAgentMetadata> = listOf()
214
) {
215
    fun add(key: String, value: String)
216
    fun add(metadata: TypedUserAgentMetadata) 
217
    operator fun plus(other: CustomUserAgentMetadata): CustomUserAgentMetadata
218
    
219
    companion object {
220
        val ContextKey: AttributeKey<CustomUserAgentMetadata>
221
        internal fun fromEnvironment(provider: PlatformEnvironProvider): CustomUserAgentMetadata
222
    }
223
}
224

225
sealed interface TypedUserAgentMetadata
226

227
data class FeatureMetadata(val name: String, val version: String? = null) : TypedUserAgentMetadata
228

229
data class ConfigMetadata(val name: String, val value: String) : TypedUserAgentMetadata
230
```