CtrlK
BlogDocsLog inGet started
Tessl Logo

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
Overview
Eval results
Files

interceptors.mddocs/

HTTP Interceptors

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.

Capabilities

AwsSpanInterceptor

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

/**
 * HTTP interceptor that sets AWS-specific span attributes for tracing
 */
object AwsSpanInterceptor : Interceptor {
    /**
     * Modify context before attempt completion to add span attributes
     * @param context Response interceptor context with request/response information
     * @return Result containing the modified response or error
     */
    suspend fun modifyBeforeAttemptCompletion(
        context: ResponseInterceptorContext<Any, Any>
    ): Result<Any>
    
    /**
     * Modify context before final completion to add span attributes
     * @param context Response interceptor context with final request/response
     * @return Result containing the modified response or error
     */
    suspend fun modifyBeforeCompletion(
        context: ResponseInterceptorContext<Any, Any>
    ): Result<Any>
}

Usage Examples:

import aws.sdk.kotlin.runtime.http.interceptors.AwsSpanInterceptor
import aws.smithy.kotlin.runtime.http.interceptors.ResponseInterceptorContext

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

// Manual usage (typically not needed)
val context: ResponseInterceptorContext<Any, Any> = // ... from SDK
val result = AwsSpanInterceptor.modifyBeforeAttemptCompletion(context)

AddUserAgentMetadataInterceptor

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

/**
 * Adds custom metadata to the user agent sent in requests
 */
class AddUserAgentMetadataInterceptor(metadata: Map<String, String>) : Interceptor {
    /**
     * Add metadata to the execution context before request execution
     * @param context Request interceptor context
     */
    fun readBeforeExecution(context: RequestInterceptorContext<Any>)
}

Usage Examples:

import aws.sdk.kotlin.runtime.http.interceptors.AddUserAgentMetadataInterceptor

// Create interceptor with custom metadata
val customMetadata = mapOf(
    "feature" to "s3-transfer-acceleration",
    "version" to "2.1.0",
    "framework" to "spring-boot"
)

val interceptor = AddUserAgentMetadataInterceptor(customMetadata)

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

IgnoreCompositeFlexibleChecksumResponseInterceptor

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

/**
 * Variant of FlexibleChecksumsResponseInterceptor where composite checksums are not validated
 */
class IgnoreCompositeFlexibleChecksumResponseInterceptor(
    ignoreSha256HeaderErrorResponseHeaders: Boolean,
    responseHttpChecksumConfig: ResponseHttpChecksumConfig
) : FlexibleChecksumsResponseInterceptor {
    /**
     * Determine whether to ignore a specific checksum type
     * @param algorithmName The checksum algorithm name to evaluate
     * @param context Protocol response interceptor context
     * @return true if the checksum should be ignored, false to validate
     */
    override fun ignoreChecksum(
        algorithmName: String,
        context: ProtocolResponseInterceptorContext<Any, HttpResponse>
    ): Boolean
}

Usage Examples:

import aws.sdk.kotlin.runtime.http.interceptors.IgnoreCompositeFlexibleChecksumResponseInterceptor
import aws.smithy.kotlin.runtime.http.auth.ResponseHttpChecksumConfig

// Create with validation configuration
val checksumConfig = ResponseHttpChecksumConfig(
    responseAlgorithms = setOf("CRC32", "SHA256"),
    validationMode = ChecksumValidationMode.WHEN_SUPPORTED
)

val interceptor = IgnoreCompositeFlexibleChecksumResponseInterceptor(
    ignoreSha256HeaderErrorResponseHeaders = true,
    responseHttpChecksumConfig = checksumConfig
)

// The interceptor will ignore composite checksums like:
// - x-amz-checksum-crc32c-sha256 (composite)
// But will validate individual checksums like:
// - x-amz-checksum-crc32 (individual)
// - x-amz-checksum-sha256 (individual)

Interceptor Pipeline

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

Request Phase Interceptors

  • readBeforeExecution: Read and modify context before any processing
  • modifyBeforeCompletion: Final modifications before sending request
  • readBeforeAttempt: Process context before each retry attempt
  • modifyBeforeAttemptCompletion: Modify request before attempt completion

Response Phase Interceptors

  • readAfterExecution: Read response data after execution
  • modifyBeforeCompletion: Final response modifications
  • readAfterAttempt: Process response after each attempt
  • modifyBeforeAttemptCompletion: Modify response before attempt completion
// Interceptor registration (typically handled by SDK)
import aws.smithy.kotlin.runtime.http.interceptors.HttpInterceptor

val interceptors: List<HttpInterceptor> = listOf(
    AwsSpanInterceptor,
    AddUserAgentMetadataInterceptor(customMetadata),
    // ... other interceptors
)

// SDK automatically manages interceptor pipeline execution

Context and Metadata

Interceptors work with rich context objects that provide access to:

  • Request Information: HTTP method, URL, headers, body
  • Response Information: Status code, headers, response body
  • Execution Context: Custom attributes, configuration, metadata
  • Error Information: Exception details, retry information
  • Timing Information: Request start time, duration, attempt number
import aws.smithy.kotlin.runtime.http.interceptors.RequestInterceptorContext
import aws.smithy.kotlin.runtime.http.interceptors.ResponseInterceptorContext

// Access context information in interceptors
fun processRequestContext(context: RequestInterceptorContext<Any>) {
    val request = context.request
    val executionContext = context.executionContext
    val protocolRequest = context.protocolRequest
    
    // Add custom attributes
    executionContext[MyCustomAttribute] = "custom-value"
}

Error Handling

Interceptors handle errors gracefully:

  • Exception Wrapping: Convert and wrap exceptions appropriately
  • Context Preservation: Maintain context through error scenarios
  • Retry Compatibility: Work correctly with retry mechanisms
  • Logging Integration: Provide appropriate error logging

Performance Considerations

Interceptors are designed for high performance:

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

Integration with AWS Services

Interceptors integrate seamlessly with AWS services:

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

Install with Tessl CLI

npx tessl i tessl/maven-aws-sdk-kotlin--aws-http-jvm

docs

business-metrics.md

index.md

interceptors.md

middleware.md

retry-policies.md

user-agent.md

tile.json