0
# HTTP Middleware
1

2
Request and response processing middleware components that handle cross-cutting concerns like user agent injection, retry headers, and recursion detection in the AWS SDK HTTP pipeline.
3

4
## Capabilities
5

6
### UserAgent Middleware
7

8
Middleware that sets User-Agent and x-amz-user-agent headers on outgoing requests.
9

10
```kotlin { .api }
11
/**
12
 * HTTP middleware that sets User-Agent and x-amz-user-agent headers
13
 */
14
class UserAgent(private val staticMetadata: AwsUserAgentMetadata) : ModifyRequestMiddleware {
15
    /**
16
     * Install the middleware on an HTTP operation
17
     * @param op The HTTP operation to install middleware on
18
     */
19
    override fun install(op: SdkHttpOperation<*, *>)
20
    
21
    /**
22
     * Modify the request to add user agent headers
23
     * @param req The HTTP request to modify
24
     * @return Modified request with user agent headers
25
     */
26
    override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
27
}
28
```
29

30
**Usage Examples:**
31

32
```kotlin
33
import aws.sdk.kotlin.runtime.http.middleware.UserAgent
34
import aws.sdk.kotlin.runtime.http.AwsUserAgentMetadata
35
import aws.sdk.kotlin.runtime.http.ApiMetadata
36

37
// Create user agent metadata
38
val apiMetadata = ApiMetadata(serviceId = "DynamoDB", version = "2020-01-01")
39
val userAgentMetadata = AwsUserAgentMetadata.fromEnvironment(apiMetadata)
40

41
// Create and install middleware
42
val userAgentMiddleware = UserAgent(userAgentMetadata)
43
userAgentMiddleware.install(httpOperation)
44

45
// The middleware will automatically add headers:
46
// User-Agent: aws-sdk-kotlin/1.5.33 Linux/5.15.0 Kotlin/1.9.0 md/DynamoDB-2020-01-01
47
// x-amz-user-agent: aws-sdk-kotlin/1.5.33 api/DynamoDB-2020-01-01 os/linux lang/kotlin#1.9.0
48
```
49

50
### AwsRetryHeaderMiddleware
51

52
Middleware that adds AWS-specific retry headers to requests for tracking retry attempts.
53

54
```kotlin { .api }
55
/**
56
 * Middleware that adds AWS-specific retry headers to requests
57
 */
58
class AwsRetryHeaderMiddleware : MutateMiddleware {
59
    /**
60
     * Install the middleware on an HTTP operation
61
     * @param op The HTTP operation to install middleware on
62
     */
63
    override fun install(op: SdkHttpOperation<*, *>)
64
    
65
    /**
66
     * Handle the operation request and add retry headers
67
     * @param request The operation request to process
68
     * @param handler The next handler in the chain
69
     * @return The operation response
70
     */
71
    suspend fun handle(
72
        request: OperationRequest,
73
        handler: Handler<OperationRequest, OperationResponse>
74
    ): OperationResponse
75
}
76
```
77

78
**Usage Examples:**
79

80
```kotlin
81
import aws.sdk.kotlin.runtime.http.middleware.AwsRetryHeaderMiddleware
82

83
// Create and install retry header middleware
84
val retryHeaderMiddleware = AwsRetryHeaderMiddleware()
85
retryHeaderMiddleware.install(httpOperation)
86

87
// The middleware will add headers like:
88
// amz-sdk-invocation-id: unique-request-id
89
// amz-sdk-request: attempt=1; max=3
90
```
91

92
### RecursionDetection Middleware
93

94
Middleware that adds recursion detection headers to prevent infinite loops in AWS service calls.
95

96
```kotlin { .api }
97
/**
98
 * HTTP middleware to add recursion detection header where required
99
 */
100
class RecursionDetection(env: EnvironmentProvider = PlatformProvider.System) : ModifyRequestMiddleware {
101
    /**
102
     * Install the middleware on an HTTP operation
103
     * @param op The HTTP operation to install middleware on
104
     */
105
    override fun install(op: SdkHttpOperation<*, *>)
106
    
107
    /**
108
     * Modify the request to add recursion detection header
109
     * @param req The HTTP request to modify
110
     * @return Modified request with trace header
111
     */
112
    override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
113
}
114
```
115

116
**Usage Examples:**
117

118
```kotlin
119
import aws.sdk.kotlin.runtime.http.middleware.RecursionDetection
120
import aws.smithy.kotlin.runtime.util.PlatformProvider
121

122
// Create with default environment provider
123
val recursionDetection = RecursionDetection()
124

125
// Create with custom environment provider
126
val customEnvProvider = // ... your environment provider
127
val customRecursionDetection = RecursionDetection(customEnvProvider)
128

129
// Modify request to add trace header
130
val modifiedRequest = recursionDetection.modifyRequest(originalRequest)
131

132
// The middleware adds header:
133
// X-Amzn-Trace-Id: Root=1-trace-id-from-environment
134
```
135

136
## Middleware Pipeline
137

138
Middleware components work together in a processing pipeline:
139

140
1. **Request Phase**: Middleware modifies outgoing requests
141
2. **Transport Phase**: HTTP client sends the request
142
3. **Response Phase**: Middleware processes incoming responses
143
4. **Error Handling**: Middleware handles failures and retries
144

145
```kotlin
146
import aws.smithy.kotlin.runtime.http.operation.SdkHttpOperation
147

148
// Typical middleware installation order
149
val operation: SdkHttpOperation<Request, Response> = // ... create operation
150

151
// Install middleware in order
152
RecursionDetection().install(operation)
153
UserAgent(userAgentMetadata).install(operation)
154
AwsRetryHeaderMiddleware().install(operation)
155

156
// Execute operation with all middleware applied
157
val response = operation.execute(request)
158
```
159

160
## Environment Integration
161

162
Middleware components integrate with the environment and platform:
163

164
- **Environment Variables**: Read configuration from AWS_* environment variables
165
- **System Properties**: Use JVM system properties where applicable
166
- **Platform Detection**: Automatic platform-specific behavior
167
- **Context Propagation**: Pass metadata through execution context
168

169
## Error Handling
170

171
Middleware handles various error scenarios:
172

173
- **Network Failures**: Connection timeouts and network errors
174
- **Service Errors**: AWS service-specific error responses
175
- **Configuration Errors**: Invalid or missing configuration
176
- **Platform Errors**: Platform-specific failures
177

178
## Security Considerations
179

180
Middleware components ensure secure handling of:
181

182
- **Sensitive Headers**: Proper handling of authentication headers
183
- **Request Metadata**: Safe serialization of request information
184
- **Error Information**: Appropriate error message sanitization
185
- **Trace Information**: Secure trace ID generation and propagation