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
```