feat: extend user agent metadata with framework, feature, and config (#372)

Author: aajtodd

aws-runtime/aws-config/common/src/aws/sdk/kotlin/runtime/config/imds/ImdsClient.kt

@@ -97,7 +97,7 @@ public class ImdsClient private constructor(builder: Builder) : InstanceMetadata
             resolver = ImdsEndpointResolver(platformProvider, endpointConfiguration)
         },
         UserAgent.create {
-            metadata = AwsUserAgentMetadata.fromEnvironment(ApiMetadata(SERVICE, "unknown"))
+            staticMetadata = AwsUserAgentMetadata.fromEnvironment(ApiMetadata(SERVICE, "unknown"))
         },
         TokenMiddleware.create {
             httpClient = this@ImdsClient.httpClient

aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/AwsUserAgentMetadata.kt

@@ -5,10 +5,20 @@
 
 package aws.sdk.kotlin.runtime.http
 
-import aws.smithy.kotlin.runtime.util.OsFamily
-import aws.smithy.kotlin.runtime.util.Platform
+import aws.sdk.kotlin.runtime.InternalSdkApi
+import aws.sdk.kotlin.runtime.http.operation.ConfigMetadata
+import aws.sdk.kotlin.runtime.http.operation.CustomUserAgentMetadata
+import aws.sdk.kotlin.runtime.http.operation.FeatureMetadata
+import aws.smithy.kotlin.runtime.util.*
+import kotlin.jvm.JvmInline
 
-private const val AWS_EXECUTION_ENV: String = "AWS_EXECUTION_ENV"
+internal const val AWS_EXECUTION_ENV = "AWS_EXECUTION_ENV"
+internal const val AWS_APP_ID_ENV = "AWS_SDK_UA_APP_ID"
+
+// non-standard environment variables/properties
+internal const val AWS_APP_ID_PROP = "aws.userAgentAppId"
+internal const val FRAMEWORK_METADATA_ENV = "AWS_FRAMEWORK_METADATA"
+internal const val FRAMEWORK_METADATA_PROP = "aws.frameworkMetadata"
 
 /**
  * Metadata used to populate the `User-Agent` and `x-amz-user-agent` headers
@@ -18,62 +28,115 @@ public data class AwsUserAgentMetadata(
     val apiMetadata: ApiMetadata,
     val osMetadata: OsMetadata,
     val languageMetadata: LanguageMetadata,
-    val execEnvMetadata: ExecutionEnvMetadata? = null
+    val execEnvMetadata: ExecutionEnvMetadata? = null,
+    val frameworkMetadata: FrameworkMetadata? = null,
+    val appId: String? = null,
+    val customMetadata: CustomUserAgentMetadata? = null
 ) {
 
     public companion object {
         /**
          * Load user agent configuration data from the current environment
          */
-        public fun fromEnvironment(apiMeta: ApiMetadata): AwsUserAgentMetadata {
-            val sdkMeta = SdkMetadata("kotlin", apiMeta.version)
-            val osInfo = Platform.osInfo()
-            val osMetadata = OsMetadata(osInfo.family, osInfo.version)
-            val langMeta = platformLanguageMetadata()
-            return AwsUserAgentMetadata(sdkMeta, apiMeta, osMetadata, langMeta, detectExecEnv())
-        }
+        public fun fromEnvironment(
+            apiMeta: ApiMetadata,
+        ): AwsUserAgentMetadata = loadAwsUserAgentMetadataFromEnvironment(Platform, apiMeta)
     }
 
     /**
      * New-style user agent header value for `x-amz-user-agent`
      */
-    val xAmzUserAgent: String = buildString {
-        /*
-           ABNF for the user agent:
-           ua-string =
-               sdk-metadata RWS
-               [api-metadata RWS]
-               os-metadata RWS
-               language-metadata RWS
-               [env-metadata RWS]
-               *(feat-metadata RWS)
-               *(config-metadata RWS)
-               *(framework-metadata RWS)
-               [appId]
-         */
-        append("$sdkMetadata ")
-        append("$apiMetadata ")
-        append("$osMetadata ")
-        append("$languageMetadata ")
-        execEnvMetadata?.let { append("$it") }
-
-        // TODO - feature metadata
-        // TODO - config metadata
-        // TODO - framework metadata (e.g. Amplify would be a good candidate for this data)
-        // TODO - appId
-    }.trimEnd()
+    val xAmzUserAgent: String
+        get() {
+            /*
+               ABNF for the user agent:
+               ua-string =
+                   [internal-metadata RWS]
+                   sdk-metadata RWS
+                   [api-metadata RWS]
+                   os-metadata RWS
+                   language-metadata RWS
+                   [env-metadata RWS]
+                   *(feat-metadata RWS)
+                   *(config-metadata RWS)
+                   *(framework-metadata RWS)
+                   [appId]
+             */
+            val ua = mutableListOf<String>()
+
+            val isInternal = customMetadata?.extras?.remove("internal")
+            if (isInternal != null) {
+                ua.add("md/internal")
+            }
+
+            ua.add("$sdkMetadata")
+            ua.add("$apiMetadata")
+            ua.add("$osMetadata")
+            ua.add("$languageMetadata")
+            execEnvMetadata?.let { ua.add("$it") }
+
+            val features = customMetadata?.typedExtras?.filterIsInstance<FeatureMetadata>()
+            features?.forEach { ua.add("$it") }
+
+            val config = customMetadata?.typedExtras?.filterIsInstance<ConfigMetadata>()
+            config?.forEach { ua.add("$it") }
+
+            frameworkMetadata?.let { ua.add("$it") }
+            appId?.let { ua.add("app/$it") }
+
+            customMetadata?.extras?.let {
+                val wrapper = AdditionalMetadata(it)
+                ua.add("$wrapper")
+            }
+
+            return ua.joinToString(separator = " ")
+        }
 
     /**
      * Legacy user agent header value for `UserAgent`
      */
-    val userAgent: String = "$sdkMetadata"
+    val userAgent: String
+        get() = "$sdkMetadata"
+}
+
+internal fun loadAwsUserAgentMetadataFromEnvironment(platform: PlatformProvider, apiMeta: ApiMetadata): AwsUserAgentMetadata {
+    val sdkMeta = SdkMetadata("kotlin", apiMeta.version)
+    val osInfo = platform.osInfo()
+    val osMetadata = OsMetadata(osInfo.family, osInfo.version)
+    val langMeta = platformLanguageMetadata()
+    val appId = platform.getProperty(AWS_APP_ID_PROP) ?: platform.getenv(AWS_APP_ID_ENV)
+
+    val frameworkMetadata = FrameworkMetadata.fromEnvironment(platform)
+    return AwsUserAgentMetadata(
+        sdkMeta,
+        apiMeta,
+        osMetadata,
+        langMeta,
+        detectExecEnv(platform),
+        frameworkMetadata = frameworkMetadata,
+        appId = appId,
+    )
+}
+
+/**
+ * Wrapper around additional metadata kv-pairs that handles formatting
+ */
+@JvmInline
+internal value class AdditionalMetadata(private val extras: Map<String, String>) {
+    override fun toString(): String = extras.entries.joinToString(separator = " ") { entry ->
+        when (entry.value.lowercase()) {
+            "true" -> "md/${entry.key}"
+            else -> "md/${entry.key.encodeUaToken()}/${entry.value.encodeUaToken()}"
+        }
+    }
 }
 
 /**
  * SDK metadata
  * @property name The SDK (language) name
  * @property version The SDK version
  */
+@InternalSdkApi
 public data class SdkMetadata(val name: String, val version: String) {
     override fun toString(): String = "aws-sdk-$name/$version"
 }
@@ -84,6 +147,7 @@ public data class SdkMetadata(val name: String, val version: String) {
  * @property version The version of the client (note this may be the same as [SdkMetadata.version] for SDK's
  * that don't independently version clients from one another.
  */
+@InternalSdkApi
 public data class ApiMetadata(val serviceId: String, val version: String) {
     override fun toString(): String {
         val formattedServiceId = serviceId.replace(" ", "-").lowercase()
@@ -94,6 +158,7 @@ public data class ApiMetadata(val serviceId: String, val version: String) {
 /**
  * Operating system metadata
  */
+@InternalSdkApi
 public data class OsMetadata(val family: OsFamily, val version: String? = null) {
     override fun toString(): String {
         // os-family = windows / linux / macos / android / ios / other
@@ -110,15 +175,17 @@ public data class OsMetadata(val family: OsFamily, val version: String? = null)
  * @property version The kotlin version in use
  * @property extras Additional key value pairs appropriate for the language/runtime (e.g.`jvmVm=OpenJdk`, etc)
  */
+@InternalSdkApi
 public data class LanguageMetadata(
     val version: String = KotlinVersion.CURRENT.toString(),
     // additional metadata key/value pairs
     val extras: Map<String, String> = emptyMap()
 ) {
     override fun toString(): String = buildString {
         append("lang/kotlin/$version")
-        extras.entries.forEach { (key, value) ->
-            append(" md/$key/${value.encodeUaToken()}")
+        if (extras.isNotEmpty()) {
+            val wrapper = AdditionalMetadata(extras)
+            append(" $wrapper")
         }
     }
 }
@@ -130,12 +197,37 @@ internal expect fun platformLanguageMetadata(): LanguageMetadata
  * Execution environment metadata
  * @property name The execution environment name (e.g. "lambda")
  */
+@InternalSdkApi
 public data class ExecutionEnvMetadata(val name: String) {
     override fun toString(): String = "exec-env/${name.encodeUaToken()}"
 }
 
-private fun detectExecEnv(): ExecutionEnvMetadata? =
-    Platform.getenv(AWS_EXECUTION_ENV)?.let {
+/**
+ * Framework metadata (e.g. name = "amplify" version = "1.2.3")
+ * @property name The framework name
+ * @property version The framework version
+ */
+@InternalSdkApi
+public data class FrameworkMetadata(
+    val name: String,
+    val version: String,
+) {
+    internal companion object {
+        internal fun fromEnvironment(provider: PlatformEnvironProvider): FrameworkMetadata? {
+            val kvPair = provider.getProperty(FRAMEWORK_METADATA_PROP) ?: provider.getenv(FRAMEWORK_METADATA_ENV)
+            return kvPair?.let {
+                val kv = kvPair.split(':', limit = 2)
+                check(kv.size == 2) { "Invalid value for FRAMEWORK_METADATA: $kvPair; must be of the form `name:version`" }
+                FrameworkMetadata(kv[0], kv[1])
+            }
+        }
+    }
+
+    override fun toString(): String = "lib/$name/$version"
+}
+
+private fun detectExecEnv(platform: PlatformEnvironProvider): ExecutionEnvMetadata? =
+    platform.getenv(AWS_EXECUTION_ENV)?.let {
         ExecutionEnvMetadata(it)
     }
 

aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/middleware/UserAgent.kt

@@ -7,10 +7,12 @@ package aws.sdk.kotlin.runtime.http.middleware
 
 import aws.sdk.kotlin.runtime.InternalSdkApi
 import aws.sdk.kotlin.runtime.http.AwsUserAgentMetadata
+import aws.sdk.kotlin.runtime.http.operation.CustomUserAgentMetadata
 import aws.smithy.kotlin.runtime.http.Feature
 import aws.smithy.kotlin.runtime.http.FeatureKey
 import aws.smithy.kotlin.runtime.http.HttpClientFeatureFactory
 import aws.smithy.kotlin.runtime.http.operation.SdkHttpOperation
+import aws.smithy.kotlin.runtime.io.middleware.Phase
 
 internal const val X_AMZ_USER_AGENT: String = "x-amz-user-agent"
 internal const val USER_AGENT: String = "User-Agent"
@@ -19,10 +21,15 @@ internal const val USER_AGENT: String = "User-Agent"
  *  Http middleware that sets the User-Agent and x-amz-user-agent headers
  */
 @InternalSdkApi
-public class UserAgent(private val awsUserAgentMetadata: AwsUserAgentMetadata) : Feature {
+public class UserAgent(
+    private val staticMetadata: AwsUserAgentMetadata
+) : Feature {
 
     public class Config {
-        public var metadata: AwsUserAgentMetadata? = null
+        /**
+         * Metadata that doesn't change per/request (e.g. sdk and environment related metadata)
+         */
+        public var staticMetadata: AwsUserAgentMetadata? = null
     }
 
     public companion object Feature :
@@ -31,19 +38,26 @@ public class UserAgent(private val awsUserAgentMetadata: AwsUserAgentMetadata) :
 
         override fun create(block: Config.() -> Unit): UserAgent {
             val config = Config().apply(block)
-            val metadata = requireNotNull(config.metadata) { "metadata is required" }
+            val metadata = requireNotNull(config.staticMetadata) { "staticMetadata is required" }
             return UserAgent(metadata)
         }
     }
 
     override fun <I, O> install(operation: SdkHttpOperation<I, O>) {
-        operation.execution.mutate.intercept { req, next ->
+        operation.execution.mutate.intercept(Phase.Order.After) { req, next ->
+
+            // pull dynamic values out of the context
+            val customMetadata = req.context.getOrNull(CustomUserAgentMetadata.ContextKey)
+
+            // resolve the metadata for the request which is a combination of the static and per/operation metadata
+            val requestMetadata = staticMetadata.copy(customMetadata = customMetadata)
+
             // NOTE: Due to legacy issues with processing the user agent, the original content for
             // x-amz-user-agent and User-Agent is swapped here.  See top note in the
             // sdk-user-agent-header SEP and https://github.com/awslabs/smithy-kotlin/issues/373
             // for further details.
-            req.subject.headers[USER_AGENT] = awsUserAgentMetadata.xAmzUserAgent
-            req.subject.headers[X_AMZ_USER_AGENT] = awsUserAgentMetadata.userAgent
+            req.subject.headers[USER_AGENT] = requestMetadata.xAmzUserAgent
+            req.subject.headers[X_AMZ_USER_AGENT] = requestMetadata.userAgent
             next.call(req)
         }
     }

aws-runtime/aws-http/common/src/aws/sdk/kotlin/runtime/http/operation/CustomUserAgentMetadata.kt

@@ -0,0 +1,71 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+package aws.sdk.kotlin.runtime.http.operation
+
+import aws.sdk.kotlin.runtime.InternalSdkApi
+import aws.smithy.kotlin.runtime.client.ExecutionContext
+import aws.smithy.kotlin.runtime.util.AttributeKey
+
+/**
+ * Operation context element for adding additional metadata to the `User-Agent` header string.
+ *
+ * Access via extension property [ExecutionContext.customUserAgentMetadata]
+ */
+public class CustomUserAgentMetadata {
+    internal val extras: MutableMap<String, String> = mutableMapOf()
+    internal val typedExtras: MutableList<TypedUserAgentMetadata> = mutableListOf()
+
+    internal companion object {
+        public val ContextKey: AttributeKey<CustomUserAgentMetadata> = AttributeKey("CustomUserAgentMetadata")
+    }
+
+    /**
+     * Add additional key-value pairs of metadata to the request. These will show up as `md/key/value` when sent.
+     */
+    public fun add(key: String, value: String) {
+        extras[key] = value
+    }
+
+    @InternalSdkApi
+    public fun add(metadata: TypedUserAgentMetadata) {
+        typedExtras.add(metadata)
+    }
+}
+
+/**
+ * Get the [CustomUserAgentMetadata] instance to append additional context to the generated `User-Agent` string.
+ */
+public val ExecutionContext.customUserAgentMetadata: CustomUserAgentMetadata
+    get() = computeIfAbsent(CustomUserAgentMetadata.ContextKey) { CustomUserAgentMetadata() }
+
+/**
+ * Marker interface for addition of classified metadata types (e.g. [ConfigMetadata] or [FeatureMetadata]).
+ */
+@InternalSdkApi
+public sealed interface TypedUserAgentMetadata
+
+/**
+ * Feature metadata
+ * @property name The name of the feature
+ * @property version Optional version of the feature (if independently versioned)
+ */
+@InternalSdkApi
+public data class FeatureMetadata(val name: String, val version: String? = null) : TypedUserAgentMetadata {
+    override fun toString(): String = if (version != null) "ft/$name/$version" else "ft/$name"
+}
+
+/**
+ * Configuration metadata
+ * @property name The configuration property name (e.g. "retry-mode")
+ * @property value The property value (e.g. "standard")
+ */
+@InternalSdkApi
+public data class ConfigMetadata(val name: String, val value: String) : TypedUserAgentMetadata {
+    override fun toString(): String = when (value.lowercase()) {
+        "true" -> "cfg/$name"
+        else -> "cfg/$name/$value"
+    }
+}