tessl/maven-aws-sdk-kotlin--aws-http-jvm
HTTP core functionality for AWS service clients in the AWS SDK for Kotlin, providing user agent management, retry policies, and HTTP middleware.
—
Pending
middleware.mddocs/
HTTP Middleware
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.
Capabilities
UserAgent Middleware
Middleware that sets User-Agent and x-amz-user-agent headers on outgoing requests.
/**
* HTTP middleware that sets User-Agent and x-amz-user-agent headers
*/
class UserAgent(private val staticMetadata: AwsUserAgentMetadata) : ModifyRequestMiddleware {
/**
* Install the middleware on an HTTP operation
* @param op The HTTP operation to install middleware on
*/
override fun install(op: SdkHttpOperation<*, *>)
/**
* Modify the request to add user agent headers
* @param req The HTTP request to modify
* @return Modified request with user agent headers
*/
override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
}Usage Examples:
import aws.sdk.kotlin.runtime.http.middleware.UserAgent
import aws.sdk.kotlin.runtime.http.AwsUserAgentMetadata
import aws.sdk.kotlin.runtime.http.ApiMetadata
// Create user agent metadata
val apiMetadata = ApiMetadata(serviceId = "DynamoDB", version = "2020-01-01")
val userAgentMetadata = AwsUserAgentMetadata.fromEnvironment(apiMetadata)
// Create and install middleware
val userAgentMiddleware = UserAgent(userAgentMetadata)
userAgentMiddleware.install(httpOperation)
// The middleware will automatically add headers:
// User-Agent: aws-sdk-kotlin/1.5.33 Linux/5.15.0 Kotlin/1.9.0 md/DynamoDB-2020-01-01
// x-amz-user-agent: aws-sdk-kotlin/1.5.33 api/DynamoDB-2020-01-01 os/linux lang/kotlin#1.9.0AwsRetryHeaderMiddleware
Middleware that adds AWS-specific retry headers to requests for tracking retry attempts.
/**
* Middleware that adds AWS-specific retry headers to requests
*/
class AwsRetryHeaderMiddleware : MutateMiddleware {
/**
* Install the middleware on an HTTP operation
* @param op The HTTP operation to install middleware on
*/
override fun install(op: SdkHttpOperation<*, *>)
/**
* Handle the operation request and add retry headers
* @param request The operation request to process
* @param handler The next handler in the chain
* @return The operation response
*/
suspend fun handle(
request: OperationRequest,
handler: Handler<OperationRequest, OperationResponse>
): OperationResponse
}Usage Examples:
import aws.sdk.kotlin.runtime.http.middleware.AwsRetryHeaderMiddleware
// Create and install retry header middleware
val retryHeaderMiddleware = AwsRetryHeaderMiddleware()
retryHeaderMiddleware.install(httpOperation)
// The middleware will add headers like:
// amz-sdk-invocation-id: unique-request-id
// amz-sdk-request: attempt=1; max=3RecursionDetection Middleware
Middleware that adds recursion detection headers to prevent infinite loops in AWS service calls.
/**
* HTTP middleware to add recursion detection header where required
*/
class RecursionDetection(env: EnvironmentProvider = PlatformProvider.System) : ModifyRequestMiddleware {
/**
* Install the middleware on an HTTP operation
* @param op The HTTP operation to install middleware on
*/
override fun install(op: SdkHttpOperation<*, *>)
/**
* Modify the request to add recursion detection header
* @param req The HTTP request to modify
* @return Modified request with trace header
*/
override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
}Usage Examples:
import aws.sdk.kotlin.runtime.http.middleware.RecursionDetection
import aws.smithy.kotlin.runtime.util.PlatformProvider
// Create with default environment provider
val recursionDetection = RecursionDetection()
// Create with custom environment provider
val customEnvProvider = // ... your environment provider
val customRecursionDetection = RecursionDetection(customEnvProvider)
// Modify request to add trace header
val modifiedRequest = recursionDetection.modifyRequest(originalRequest)
// The middleware adds header:
// X-Amzn-Trace-Id: Root=1-trace-id-from-environmentMiddleware Pipeline
Middleware components work together in a processing pipeline:
- Request Phase: Middleware modifies outgoing requests
- Transport Phase: HTTP client sends the request
- Response Phase: Middleware processes incoming responses
- Error Handling: Middleware handles failures and retries
import aws.smithy.kotlin.runtime.http.operation.SdkHttpOperation
// Typical middleware installation order
val operation: SdkHttpOperation<Request, Response> = // ... create operation
// Install middleware in order
RecursionDetection().install(operation)
UserAgent(userAgentMetadata).install(operation)
AwsRetryHeaderMiddleware().install(operation)
// Execute operation with all middleware applied
val response = operation.execute(request)Environment Integration
Middleware components integrate with the environment and platform:
- Environment Variables: Read configuration from AWS_* environment variables
- System Properties: Use JVM system properties where applicable
- Platform Detection: Automatic platform-specific behavior
- Context Propagation: Pass metadata through execution context
Error Handling
Middleware handles various error scenarios:
- Network Failures: Connection timeouts and network errors
- Service Errors: AWS service-specific error responses
- Configuration Errors: Invalid or missing configuration
- Platform Errors: Platform-specific failures
Security Considerations
Middleware components ensure secure handling of:
- Sensitive Headers: Proper handling of authentication headers
- Request Metadata: Safe serialization of request information
- Error Information: Appropriate error message sanitization
- Trace Information: Secure trace ID generation and propagation
Install with Tessl CLI
npx tessl i tessl/maven-aws-sdk-kotlin--aws-http-jvm