User Agent Management

/**
 * Metadata used to populate User-Agent and x-amz-user-agent headers for AWS service requests
 */
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
) {
    /**
     * New-style user agent header value for x-amz-user-agent
     */
    val xAmzUserAgent: String
    
    /**
     * Legacy user agent header value for User-Agent
     */
    val userAgent: String
    
    companion object {
        /**
         * Load user agent configuration from environment variables and system properties
         * @param apiMeta API metadata for the service being called
         * @param appId Optional application identifier
         * @return Configured AwsUserAgentMetadata instance
         */
        fun fromEnvironment(apiMeta: ApiMetadata, appId: String? = null): AwsUserAgentMetadata
    }
}

import aws.sdk.kotlin.runtime.http.*

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

// Access formatted headers
val xAmzUserAgent = userAgentMetadata.xAmzUserAgent
val userAgent = userAgentMetadata.userAgent

// Create metadata manually
val sdkMetadata = SdkMetadata(name = "aws-sdk-kotlin", version = "1.5.33")
val osMetadata = OsMetadata(family = OsFamily.LINUX, version = "5.15.0")
val languageMetadata = LanguageMetadata(
    version = "1.9.0",
    extras = mapOf("coroutines" to "1.7.3")
)

val customUserAgent = AwsUserAgentMetadata(
    sdkMetadata = sdkMetadata,
    apiMetadata = apiMetadata,
    osMetadata = osMetadata,
    languageMetadata = languageMetadata,
    appId = "my-app-v1.0"
)

/**
 * SDK identification metadata
 */
data class SdkMetadata(val name: String, val version: String)

/**
 * API service identification metadata
 */
data class ApiMetadata(val serviceId: String, val version: String)

/**
 * Operating system metadata
 */
data class OsMetadata(val family: OsFamily, val version: String? = null)

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

/**
 * Execution environment metadata (e.g., Lambda, EC2, ECS)
 */
data class ExecutionEnvMetadata(val name: String)

/**
 * Framework identification metadata (e.g., Spring Boot, Quarkus)
 */
data class FrameworkMetadata(val name: String, val version: String)

/**
 * Operation context element for adding custom metadata to User-Agent header
 */
class CustomUserAgentMetadata(
    extras: Map<String, String> = mapOf(),
    typedExtras: List<TypedUserAgentMetadata> = listOf()
) {
    /**
     * Add additional key-value pairs of metadata
     */
    fun add(key: String, value: String)
    
    /**
     * Add typed metadata for classified information
     */
    fun add(metadata: TypedUserAgentMetadata)
    
    /**
     * Combine with another CustomUserAgentMetadata instance
     */
    operator fun plus(other: CustomUserAgentMetadata): CustomUserAgentMetadata
    
    companion object {
        val ContextKey: AttributeKey<CustomUserAgentMetadata>
        internal fun fromEnvironment(provider: PlatformEnvironProvider): CustomUserAgentMetadata
    }
}

/**
 * Marker interface for classified metadata types
 */
sealed interface TypedUserAgentMetadata

/**
 * Feature metadata for user agent
 */
data class FeatureMetadata(val name: String, val version: String? = null) : TypedUserAgentMetadata

/**
 * Configuration metadata for user agent
 */
data class ConfigMetadata(val name: String, val value: String) : TypedUserAgentMetadata

/**
 * Get the CustomUserAgentMetadata instance from execution context
 */
val ExecutionContext.customUserAgentMetadata: CustomUserAgentMetadata

import aws.sdk.kotlin.runtime.http.operation.*
import aws.smithy.kotlin.runtime.operation.ExecutionContext

// Add custom metadata to a request
val customMetadata = CustomUserAgentMetadata()
customMetadata.add("feature", "s3-transfer-acceleration")
customMetadata.add(FeatureMetadata("encryption", "AES256"))
customMetadata.add(ConfigMetadata("retry-mode", "adaptive"))

// Access from execution context
val context: ExecutionContext = // ... obtained from operation
val metadata = context.customUserAgentMetadata

/**
 * Environment variable for application ID
 */
const val AWS_APP_ID_ENV: String = "AWS_SDK_UA_APP_ID"

/**
 * System property for application ID
 */
const val AWS_APP_ID_PROP: String = "aws.userAgentAppId"