0
# HTTP Interceptors
1

2
Fine-grained request and response interceptors for advanced processing including span attributes for tracing, user agent metadata injection, and flexible checksum handling in the AWS SDK HTTP pipeline.
3

4
## Capabilities
5

6
### AwsSpanInterceptor
7

8
HTTP interceptor that sets AWS-specific span attributes for distributed tracing and observability.
9

10
```kotlin { .api }
11
/**
12
 * HTTP interceptor that sets AWS-specific span attributes for tracing
13
 */
14
object AwsSpanInterceptor : Interceptor {
15
    /**
16
     * Modify context before attempt completion to add span attributes
17
     * @param context Response interceptor context with request/response information
18
     * @return Result containing the modified response or error
19
     */
20
    suspend fun modifyBeforeAttemptCompletion(
21
        context: ResponseInterceptorContext<Any, Any>
22
    ): Result<Any>
23
    
24
    /**
25
     * Modify context before final completion to add span attributes
26
     * @param context Response interceptor context with final request/response
27
     * @return Result containing the modified response or error
28
     */
29
    suspend fun modifyBeforeCompletion(
30
        context: ResponseInterceptorContext<Any, Any>
31
    ): Result<Any>
32
}
33
```
34

35
**Usage Examples:**
36

37
```kotlin
38
import aws.sdk.kotlin.runtime.http.interceptors.AwsSpanInterceptor
39
import aws.smithy.kotlin.runtime.http.interceptors.ResponseInterceptorContext
40

41
// The interceptor is typically registered automatically by the SDK
42
// It adds AWS-specific span attributes like:
43
// - aws.service.name
44
// - aws.operation.name  
45
// - aws.region
46
// - http.status_code
47
// - error information (if applicable)
48

49
// Manual usage (typically not needed)
50
val context: ResponseInterceptorContext<Any, Any> = // ... from SDK
51
val result = AwsSpanInterceptor.modifyBeforeAttemptCompletion(context)
52
```
53

54
### AddUserAgentMetadataInterceptor
55

56
Interceptor that adds custom metadata to the user agent sent in requests.
57

58
```kotlin { .api }
59
/**
60
 * Adds custom metadata to the user agent sent in requests
61
 */
62
class AddUserAgentMetadataInterceptor(metadata: Map<String, String>) : Interceptor {
63
    /**
64
     * Add metadata to the execution context before request execution
65
     * @param context Request interceptor context
66
     */
67
    fun readBeforeExecution(context: RequestInterceptorContext<Any>)
68
}
69
```
70

71
**Usage Examples:**
72

73
```kotlin
74
import aws.sdk.kotlin.runtime.http.interceptors.AddUserAgentMetadataInterceptor
75

76
// Create interceptor with custom metadata
77
val customMetadata = mapOf(
78
    "feature" to "s3-transfer-acceleration",
79
    "version" to "2.1.0",
80
    "framework" to "spring-boot"
81
)
82

83
val interceptor = AddUserAgentMetadataInterceptor(customMetadata)
84

85
// Register with HTTP client (SDK handles this automatically)
86
// The metadata will be included in User-Agent headers as:
87
// md/feature-s3-transfer-acceleration md/version-2.1.0 md/framework-spring-boot
88
```
89

90
### IgnoreCompositeFlexibleChecksumResponseInterceptor
91

92
Specialized interceptor for flexible checksum handling that ignores composite checksums during response validation.
93

94
```kotlin { .api }
95
/**
96
 * Variant of FlexibleChecksumsResponseInterceptor where composite checksums are not validated
97
 */
98
class IgnoreCompositeFlexibleChecksumResponseInterceptor(
99
    ignoreSha256HeaderErrorResponseHeaders: Boolean,
100
    responseHttpChecksumConfig: ResponseHttpChecksumConfig
101
) : FlexibleChecksumsResponseInterceptor {
102
    /**
103
     * Determine whether to ignore a specific checksum type
104
     * @param algorithmName The checksum algorithm name to evaluate
105
     * @param context Protocol response interceptor context
106
     * @return true if the checksum should be ignored, false to validate
107
     */
108
    override fun ignoreChecksum(
109
        algorithmName: String,
110
        context: ProtocolResponseInterceptorContext<Any, HttpResponse>
111
    ): Boolean
112
}
113
```
114

115
**Usage Examples:**
116

117
```kotlin
118
import aws.sdk.kotlin.runtime.http.interceptors.IgnoreCompositeFlexibleChecksumResponseInterceptor
119
import aws.smithy.kotlin.runtime.http.auth.ResponseHttpChecksumConfig
120

121
// Create with validation configuration
122
val checksumConfig = ResponseHttpChecksumConfig(
123
    responseAlgorithms = setOf("CRC32", "SHA256"),
124
    validationMode = ChecksumValidationMode.WHEN_SUPPORTED
125
)
126

127
val interceptor = IgnoreCompositeFlexibleChecksumResponseInterceptor(
128
    ignoreSha256HeaderErrorResponseHeaders = true,
129
    responseHttpChecksumConfig = checksumConfig
130
)
131

132
// The interceptor will ignore composite checksums like:
133
// - x-amz-checksum-crc32c-sha256 (composite)
134
// But will validate individual checksums like:
135
// - x-amz-checksum-crc32 (individual)
136
// - x-amz-checksum-sha256 (individual)
137
```
138

139
## Interceptor Pipeline
140

141
Interceptors operate at different phases of the HTTP request/response lifecycle:
142

143
### Request Phase Interceptors
144

145
- **readBeforeExecution**: Read and modify context before any processing
146
- **modifyBeforeCompletion**: Final modifications before sending request
147
- **readBeforeAttempt**: Process context before each retry attempt
148
- **modifyBeforeAttemptCompletion**: Modify request before attempt completion
149

150
### Response Phase Interceptors
151

152
- **readAfterExecution**: Read response data after execution
153
- **modifyBeforeCompletion**: Final response modifications
154
- **readAfterAttempt**: Process response after each attempt
155
- **modifyBeforeAttemptCompletion**: Modify response before attempt completion
156

157
```kotlin
158
// Interceptor registration (typically handled by SDK)
159
import aws.smithy.kotlin.runtime.http.interceptors.HttpInterceptor
160

161
val interceptors: List<HttpInterceptor> = listOf(
162
    AwsSpanInterceptor,
163
    AddUserAgentMetadataInterceptor(customMetadata),
164
    // ... other interceptors
165
)
166

167
// SDK automatically manages interceptor pipeline execution
168
```
169

170
## Context and Metadata
171

172
Interceptors work with rich context objects that provide access to:
173

174
- **Request Information**: HTTP method, URL, headers, body
175
- **Response Information**: Status code, headers, response body
176
- **Execution Context**: Custom attributes, configuration, metadata
177
- **Error Information**: Exception details, retry information
178
- **Timing Information**: Request start time, duration, attempt number
179

180
```kotlin
181
import aws.smithy.kotlin.runtime.http.interceptors.RequestInterceptorContext
182
import aws.smithy.kotlin.runtime.http.interceptors.ResponseInterceptorContext
183

184
// Access context information in interceptors
185
fun processRequestContext(context: RequestInterceptorContext<Any>) {
186
    val request = context.request
187
    val executionContext = context.executionContext
188
    val protocolRequest = context.protocolRequest
189
    
190
    // Add custom attributes
191
    executionContext[MyCustomAttribute] = "custom-value"
192
}
193
```
194

195
## Error Handling
196

197
Interceptors handle errors gracefully:
198

199
- **Exception Wrapping**: Convert and wrap exceptions appropriately
200
- **Context Preservation**: Maintain context through error scenarios
201
- **Retry Compatibility**: Work correctly with retry mechanisms
202
- **Logging Integration**: Provide appropriate error logging
203

204
## Performance Considerations
205

206
Interceptors are designed for high performance:
207

208
- **Minimal Overhead**: Lightweight processing with minimal allocations
209
- **Async Compatible**: Work correctly with coroutines and async operations
210
- **Thread Safety**: Safe for concurrent access across multiple requests
211
- **Resource Management**: Proper cleanup of resources and connections
212

213
## Integration with AWS Services
214

215
Interceptors integrate seamlessly with AWS services:
216

217
- **Service-Specific Logic**: Handle AWS service-specific requirements
218
- **Authentication**: Work with AWS authentication mechanisms
219
- **Region Handling**: Process AWS region information correctly
220
- **Error Codes**: Handle AWS-specific error codes and retry logic