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

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

AWS HTTP JVM

Name: tessl/maven-aws-sdk-kotlin--aws-http-jvm
Author: tessl

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.

Package Information

Package Name: aws-http-jvm
Package Type: maven
Language: Kotlin (multiplatform)
Group ID: aws.sdk.kotlin
Artifact ID: aws-http-jvm
Installation: Add to your build.gradle.kts:

implementation("aws.sdk.kotlin:aws-http-jvm:1.5.33")

Core Imports

import aws.sdk.kotlin.runtime.http.*
import aws.sdk.kotlin.runtime.http.middleware.*
import aws.sdk.kotlin.runtime.http.interceptors.*
import aws.sdk.kotlin.runtime.http.retries.*

Basic Usage

import aws.sdk.kotlin.runtime.http.AwsUserAgentMetadata
import aws.sdk.kotlin.runtime.http.ApiMetadata
import aws.sdk.kotlin.runtime.http.retries.AwsRetryPolicy
import aws.sdk.kotlin.runtime.http.middleware.UserAgent

// Create user agent metadata
val apiMetadata = ApiMetadata(serviceId = "S3", version = "2023-01-01")
val userAgentMetadata = AwsUserAgentMetadata.fromEnvironment(apiMetadata)

// Create user agent middleware
val userAgentMiddleware = UserAgent(userAgentMetadata)

// Use AWS retry policy
val retryPolicy = AwsRetryPolicy.Default

Architecture

AWS HTTP JVM is built around several key components:

User Agent Management: Comprehensive metadata collection and formatting for AWS service identification
Retry Policies: AWS-specific retry logic with exponential backoff and exception handling
HTTP Middleware: Request/response processing pipeline components for cross-cutting concerns
HTTP Interceptors: Fine-grained request/response modification for tracing, metrics, and authentication
Business Metrics: Telemetry collection for AWS service usage patterns and client behavior
Platform Support: Multiplatform Kotlin with JVM, native, and common implementations

Capabilities

Retry Policies

AWS-specific retry policies that implement exponential backoff, jitter, and AWS service-specific exception handling patterns.

open class AwsRetryPolicy : StandardRetryPolicy() {
    companion object {
        val Default: AwsRetryPolicy
    }
    
    protected override fun evaluateSpecificExceptions(ex: Throwable): RetryDirective?
}

Retry Policies

User Agent Management

Comprehensive user agent metadata collection and formatting that provides detailed client identification for AWS services, including SDK version, platform information, and custom metadata.

data class AwsUserAgentMetadata(
    val sdkMetadata: SdkMetadata,
    val apiMetadata: ApiMetadata,
    val osMetadata: OsMetadata,
    val languageMetadata: LanguageMetadata,
    val execEnvMetadata: ExecutionEnvMetadata? = null,
    val frameworkMetadata: FrameworkMetadata? = null,
    val appId: String? = null,
    val customMetadata: CustomUserAgentMetadata? = null
) {
    val xAmzUserAgent: String
    val userAgent: String
    
    companion object {
        fun fromEnvironment(apiMeta: ApiMetadata, appId: String? = null): AwsUserAgentMetadata
    }
}

User Agent Management

HTTP Middleware

Request and response processing middleware components that handle cross-cutting concerns like user agent injection, retry headers, and recursion detection.

class UserAgent(private val staticMetadata: AwsUserAgentMetadata) : ModifyRequestMiddleware {
    override fun install(op: SdkHttpOperation<*, *>)
    override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
}

class RecursionDetection(env: EnvironmentProvider = PlatformProvider.System) : ModifyRequestMiddleware {
    override fun install(op: SdkHttpOperation<*, *>)
    override suspend fun modifyRequest(req: SdkHttpRequest): SdkHttpRequest
}

class AwsRetryHeaderMiddleware : MutateMiddleware {
    suspend fun handle(req: OperationRequest, handler: Handler<OperationRequest, OperationResponse>): OperationResponse
    override fun install(op: SdkHttpOperation<*, *>)
}

HTTP Middleware

HTTP Interceptors

Fine-grained request and response interceptors for advanced processing including business metrics collection, span attributes, and checksum handling.

object AwsSpanInterceptor : Interceptor {
    suspend fun modifyBeforeAttemptCompletion(context: ResponseInterceptorContext<Any, Any>): Result<Any>
    suspend fun modifyBeforeCompletion(context: ResponseInterceptorContext<Any, Any>): Result<Any>
}

class AddUserAgentMetadataInterceptor(metadata: Map<String, String>) : Interceptor {
    fun readBeforeExecution(context: RequestInterceptorContext<Any>)
}

class IgnoreCompositeFlexibleChecksumResponseInterceptor(
    ignoreSha256HeaderErrorResponseHeaders: Boolean,
    responseHttpChecksumConfig: ResponseHttpChecksumConfig
) : FlexibleChecksumsResponseInterceptor {
    override fun ignoreChecksum(algorithmName: String, context: ProtocolResponseInterceptorContext<Any, HttpResponse>): Boolean
}

HTTP Interceptors

Business Metrics

AWS telemetry and business metrics collection system that tracks SDK usage patterns, credential providers, and service-specific metrics for analytics and optimization.

class BusinessMetricsInterceptor : HttpInterceptor {
    override suspend fun modifyBeforeTransmit(context: ProtocolRequestInterceptorContext<Any, HttpRequest>): HttpRequest
}

enum class AwsBusinessMetric(override val identifier: String) : BusinessMetric {
    S3_EXPRESS_BUCKET("J"),
    DDB_MAPPER("d");
    
    enum class Credentials(override val identifier: String) : BusinessMetric {
        CREDENTIALS_CODE("e"),
        CREDENTIALS_JVM_SYSTEM_PROPERTIES("f"),
        CREDENTIALS_ENV_VARS("g"),
        CREDENTIALS_ENV_VARS_STS_WEB_ID_TOKEN("h"),
        CREDENTIALS_STS_ASSUME_ROLE("i"),
        CREDENTIALS_STS_ASSUME_ROLE_WEB_ID("k"),
        CREDENTIALS_PROFILE("n"),
        CREDENTIALS_PROFILE_SOURCE_PROFILE("o"),
        CREDENTIALS_PROFILE_NAMED_PROVIDER("p"),
        CREDENTIALS_PROFILE_STS_WEB_ID_TOKEN("q"),
        CREDENTIALS_PROFILE_SSO("r"),
        CREDENTIALS_SSO("s"),
        CREDENTIALS_PROFILE_SSO_LEGACY("t"),
        CREDENTIALS_SSO_LEGACY("u"),
        CREDENTIALS_PROFILE_PROCESS("v"),
        CREDENTIALS_PROCESS("w"),
        CREDENTIALS_HTTP("z"),
        CREDENTIALS_IMDS("0")
    }
}

Business Metrics

Constants

const val AWS_APP_ID_ENV: String = "AWS_SDK_UA_APP_ID"
const val AWS_APP_ID_PROP: String = "aws.userAgentAppId"
const val BUSINESS_METRICS_MAX_LENGTH: Int = 1024

Core Types

data class SdkMetadata(val name: String, val version: String)

data class ApiMetadata(val serviceId: String, val version: String)

data class OsMetadata(val family: OsFamily, val version: String? = null)

data class LanguageMetadata(
    val version: String = KotlinVersion.CURRENT.toString(),
    val extras: Map<String, String> = emptyMap()
)

data class ExecutionEnvMetadata(val name: String)

data class FrameworkMetadata(val name: String, val version: String)

class CustomUserAgentMetadata(
    extras: Map<String, String> = mapOf(),
    typedExtras: List<TypedUserAgentMetadata> = listOf()
) {
    fun add(key: String, value: String)
    fun add(metadata: TypedUserAgentMetadata) 
    operator fun plus(other: CustomUserAgentMetadata): CustomUserAgentMetadata
    
    companion object {
        val ContextKey: AttributeKey<CustomUserAgentMetadata>
        internal fun fromEnvironment(provider: PlatformEnvironProvider): CustomUserAgentMetadata
    }
}

sealed interface TypedUserAgentMetadata

data class FeatureMetadata(val name: String, val version: String? = null) : TypedUserAgentMetadata

data class ConfigMetadata(val name: String, val value: String) : TypedUserAgentMetadata