Add UserAgentFeatureId and UserAgentDetails for UA2.1 Feature Tracking (#3707)

Author: muhammad-othman

sdk/src/Core/Amazon.Runtime/Internal/UserAgent/UserAgentDetails.cs

@@ -0,0 +1,59 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+using System.Collections.Generic;
+
+namespace Amazon.Runtime.Internal.UserAgent
+{
+    /// <summary>
+    /// Represents the User Agent details, including tracked features under User Agent 2.1 (UA2.1).
+    /// This class ensures that feature metrics are collected efficiently and the final
+    /// User-Agent string is generated only when needed.
+    /// </summary>
+    public class UserAgentDetails
+    {
+        private const int MaxSizeBytes = 1024; // 1 KB size limit
+        private readonly HashSet<string> _trackedFeatureIds = new HashSet<string>();
+
+        /// <summary>
+        /// Gets the list of tracked feature IDs.
+        /// </summary>
+        public IEnumerable<string> TrackedFeatureIds => _trackedFeatureIds;
+
+        /// <summary>
+        /// Adds a feature metric to be included in the User-Agent string.
+        /// Duplicate entries are ignored.
+        /// </summary>
+        /// <param name="featureId">The feature metric ID to track.</param>
+        public void AddFeature(UserAgentFeatureId featureId)
+        {
+            if (featureId == null) return;
+            _trackedFeatureIds.Add(featureId.Value);
+        }
+
+        /// <summary>
+        /// Generates the User-Agent metrics string.
+        /// Ensures the final string does not exceed 1024 bytes.
+        /// </summary>
+        /// <returns>The formatted User-Agent metrics string.</returns>
+#pragma warning disable CA1822 // Mark members as static
+        public string GenerateMetricsUserAgent()
+#pragma warning restore CA1822 // Mark members as static
+        {
+            // TODO
+            return "m/{metricsString}";
+        }
+    }
+}

sdk/src/Core/Amazon.Runtime/Internal/UserAgent/UserAgentFeatureId.cs

@@ -0,0 +1,306 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+namespace Amazon.Runtime.Internal.UserAgent
+{
+    /// <summary>
+    /// Represents the unique metric identifiers for SDK features tracked under User Agent 2.1 (UA2.1).
+    /// </summary>
+    public class UserAgentFeatureId : ConstantClass
+    {
+        /// <summary>
+        /// An operation called using a C2j Resource model.
+        /// </summary>
+        public static readonly UserAgentFeatureId RESOURCE_MODEL = new UserAgentFeatureId("A");
+
+        /// <summary>
+        /// An operation called using a waiter.
+        /// </summary>
+        public static readonly UserAgentFeatureId WAITER = new UserAgentFeatureId("B");
+
+        /// <summary>
+        /// An operation called using a paginator.
+        /// </summary>
+        public static readonly UserAgentFeatureId PAGINATOR = new UserAgentFeatureId("C");
+
+        /// <summary>
+        /// An operation called using the legacy retry mode.
+        /// </summary>
+        public static readonly UserAgentFeatureId RETRY_MODE_LEGACY = new UserAgentFeatureId("D");
+
+        /// <summary>
+        /// An operation called using the standard retry mode.
+        /// </summary>
+        public static readonly UserAgentFeatureId RETRY_MODE_STANDARD = new UserAgentFeatureId("E");
+
+        /// <summary>
+        /// An operation called using the adaptive retry mode.
+        /// </summary>
+        public static readonly UserAgentFeatureId RETRY_MODE_ADAPTIVE = new UserAgentFeatureId("F");
+
+        /// <summary>
+        /// An operation called using the S3 Transfer Manager.
+        /// </summary>
+        public static readonly UserAgentFeatureId S3_TRANSFER = new UserAgentFeatureId("G");
+
+        /// <summary>
+        /// An operation called using the S3 Encryption Client V1.
+        /// </summary>
+        public static readonly UserAgentFeatureId S3_CRYPTO_V1N = new UserAgentFeatureId("H");
+
+        /// <summary>
+        /// An operation called using the S3 Encryption Client V2.
+        /// </summary>
+        public static readonly UserAgentFeatureId S3_CRYPTO_V2 = new UserAgentFeatureId("I");
+
+        /// <summary>
+        /// An operation called using the S3 Express feature.
+        /// </summary>
+        public static readonly UserAgentFeatureId S3_EXPRESS_BUCKET = new UserAgentFeatureId("J");
+
+        /// <summary>
+        /// An operation called using the S3 Access Grants feature.
+        /// </summary>
+        public static readonly UserAgentFeatureId S3_ACCESS_GRANTS = new UserAgentFeatureId("K");
+
+        /// <summary>
+        /// An operation called using GZIP request compression.
+        /// </summary>
+        public static readonly UserAgentFeatureId GZIP_REQUEST_COMPRESSION = new UserAgentFeatureId("L");
+
+        /// <summary>
+        /// An operation called using the Smithy RPC v2 CBOR protocol.
+        /// </summary>
+        public static readonly UserAgentFeatureId PROTOCOL_RPC_V2_CBOR = new UserAgentFeatureId("M");
+
+        /// <summary>
+        /// An operation called using a user provided endpoint URL.
+        /// </summary>
+        public static readonly UserAgentFeatureId ENDPOINT_OVERRIDE = new UserAgentFeatureId("N");
+
+        /// <summary>
+        /// An operation called with account ID mode set to preferred.
+        /// </summary>
+        public static readonly UserAgentFeatureId ACCOUNT_ID_MODE_PREFERRED = new UserAgentFeatureId("P");
+
+        /// <summary>
+        /// An operation called with account ID mode set to disabled.
+        /// </summary>
+        public static readonly UserAgentFeatureId ACCOUNT_ID_MODE_DISABLED = new UserAgentFeatureId("Q");
+
+        /// <summary>
+        /// An operation called with account ID mode set to required.
+        /// </summary>
+        public static readonly UserAgentFeatureId ACCOUNT_ID_MODE_REQUIRED = new UserAgentFeatureId("R");
+
+        /// <summary>
+        /// An operation called using sigv4a signing.
+        /// </summary>
+        public static readonly UserAgentFeatureId SIGV4A_SIGNING = new UserAgentFeatureId("S");
+
+        /// <summary>
+        /// An operation where credential resolution resolved an account ID.
+        /// </summary>
+        public static readonly UserAgentFeatureId RESOLVED_ACCOUNT_ID = new UserAgentFeatureId("T");
+
+        /// <summary>
+        /// Operation included a CRC-32  checksum for request payload.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_CRC32 = new UserAgentFeatureId("U");
+
+        /// <summary>
+        /// Operation included a CRC-32C checksum for request payload.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_CRC32C = new UserAgentFeatureId("V");
+
+        /// <summary>
+        /// Operation included a CRC-64 checksum for request payload.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_CRC64 = new UserAgentFeatureId("W");
+
+        /// <summary>
+        /// Operation included a SHA-1 checksum for request payload.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_SHA1 = new UserAgentFeatureId("X");
+
+        /// <summary>
+        /// Operation included a SHA-256 checksum for request payload.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_SHA256 = new UserAgentFeatureId("Y");
+
+        /// <summary>
+        /// SDK resolved configuration <see cref="RequestChecksumCalculation.WHEN_SUPPORTED"/>.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_WHEN_SUPPORTED = new UserAgentFeatureId("Z");
+
+        /// <summary>
+        /// SDK resolved configuration <see cref="RequestChecksumCalculation.WHEN_REQUIRED"/>.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_REQ_WHEN_REQUIRED = new UserAgentFeatureId("a");
+
+        /// <summary>
+        /// SDK resolved configuration <see cref="ResponseChecksumValidation.WHEN_SUPPORTED"/>.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_RES_WHEN_SUPPORTED = new UserAgentFeatureId("b");
+
+        /// <summary>
+        /// SDK resolved configuration <see cref="ResponseChecksumValidation.WHEN_REQUIRED"/>.
+        /// </summary>
+        public static readonly UserAgentFeatureId FLEXIBLE_CHECKSUMS_RES_WHEN_REQUIRED = new UserAgentFeatureId("c");
+
+        /// <summary>
+        /// An operation called using a DynamoDB Mapper high level library.
+        /// </summary>
+        public static readonly UserAgentFeatureId DDB_MAPPER = new UserAgentFeatureId("d");
+
+        /// <summary>
+        /// An operation called using credentials resolved from code, cli parameters, session object, or client instance.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_CODE = new UserAgentFeatureId("e");
+
+        /// <summary>
+        /// An operation called using credentials resolved from JVM system properties.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_JVM_SYSTEM_PROPERTIES = new UserAgentFeatureId("f");
+
+        /// <summary>
+        /// An operation called using credentials resolved from environment variables.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_ENV_VARS = new UserAgentFeatureId("g");
+
+        /// <summary>
+        /// An operation called using credentials resolved from environment variables for assuming a role with STS using a web identity token.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_ENV_VARS_STS_WEB_ID_TOKEN = new UserAgentFeatureId("h");
+
+        /// <summary>
+        /// An operation called using credentials resolved from STS using assume role.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_STS_ASSUME_ROLE = new UserAgentFeatureId("i");
+
+        /// <summary>
+        /// An operation called using credentials resolved from STS using assume role with SAML.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_STS_ASSUME_ROLE_SAML = new UserAgentFeatureId("j");
+
+        /// <summary>
+        /// An operation called using credentials resolved from STS using assume role with web identity.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_STS_ASSUME_ROLE_WEB_ID = new UserAgentFeatureId("k");
+
+        /// <summary>
+        /// An operation called using credentials resolved from STS using a federation token.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_STS_FEDERATION_TOKEN = new UserAgentFeatureId("l");
+
+        /// <summary>
+        /// An operation called using credentials resolved from STS using a session token.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_STS_SESSION_TOKEN = new UserAgentFeatureId("m");
+
+        /// <summary>
+        /// An operation called using credentials resolved from a config file(s) profile with static credentials.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE = new UserAgentFeatureId("n");
+
+        /// <summary>
+        /// An operation called using credentials resolved from a source profile in a config file(s) profile.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE_SOURCE_PROFILE = new UserAgentFeatureId("o");
+
+        /// <summary>
+        /// An operation called using credentials resolved from a named provider in a config file(s) profile.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE_NAMED_PROVIDER = new UserAgentFeatureId("p");
+
+        /// <summary>
+        /// An operation called using credentials resolved from configuration for assuming a role with STS using web identity token in a config file(s) profile.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE_STS_WEB_ID_TOKEN = new UserAgentFeatureId("q");
+
+        /// <summary>
+        /// An operation called using credentials resolved from an SSO session in a config file(s) profile.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE_SSO = new UserAgentFeatureId("r");
+
+        /// <summary>
+        /// An operation called using credentials resolved from an SSO session.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_SSO = new UserAgentFeatureId("s");
+
+        /// <summary>
+        /// An operation called using credentials resolved from an SSO session in a config file(s) profile using legacy format.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE_SSO_LEGACY = new UserAgentFeatureId("t");
+
+        /// <summary>
+        /// An operation called using credentials resolved from an SSO session using legacy format.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_SSO_LEGACY = new UserAgentFeatureId("u");
+
+        /// <summary>
+        /// An operation called using credentials resolved from a process in a config file(s) profile.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROFILE_PROCESS = new UserAgentFeatureId("v");
+
+        /// <summary>
+        /// An operation called using credentials resolved from a process.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_PROCESS = new UserAgentFeatureId("w");
+
+        /// <summary>
+        /// An operation called using credentials resolved from the credentials section of a boto2 config file.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_BOTO2_CONFIG_FILE = new UserAgentFeatureId("x");
+
+        /// <summary>
+        /// An operation called using credentials resolved from a profile in an AWS SDK store.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_AWS_SDK_STORE = new UserAgentFeatureId("y");
+
+        /// <summary>
+        /// An operation called using credentials resolved from an HTTP endpoint.
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_HTTP = new UserAgentFeatureId("z");
+
+        /// <summary>
+        /// An operation called using credentials resolved from the instance metadata service (IMDS).
+        /// </summary>
+        public static readonly UserAgentFeatureId CREDENTIALS_IMDS = new UserAgentFeatureId("0");
+
+        /// <summary>
+        /// Calling an SSO-OIDC operation as part of the SSO login flow, when using the OAuth2.0 device code grant.
+        /// </summary>
+        public static readonly UserAgentFeatureId SSO_LOGIN_DEVICE = new UserAgentFeatureId("1");
+
+        /// <summary>
+        /// Calling an SSO-OIDC operation as part of the SSO login flow, when using the OAuth2.0 authorization code grant.
+        /// </summary>
+        public static readonly UserAgentFeatureId SSO_LOGIN_AUTH = new UserAgentFeatureId("2");
+
+        public UserAgentFeatureId(string value) : base(value) { }
+
+        public static UserAgentFeatureId FindValue(string value)
+        {
+            return FindValue<UserAgentFeatureId>(value);
+        }
+
+        public static implicit operator UserAgentFeatureId(string value)
+        {
+            return FindValue(value);
+        }
+    }
+
+}

sdk/src/Core/Amazon.Runtime/Pipeline/Contexts.cs

@@ -17,6 +17,7 @@
 using Amazon.Runtime.Internal;
 using Amazon.Runtime.Internal.Auth;
 using Amazon.Runtime.Internal.Transform;
+using Amazon.Runtime.Internal.UserAgent;
 using Amazon.Runtime.Internal.Util;
 using System;
 using System.Collections.Generic;
@@ -53,6 +54,7 @@ public interface IRequestContext
         IDictionary<string, object> ContextAttributes { get; }
 
         IHttpRequestStreamHandle RequestStreamHandle {get;set;}
+        UserAgentDetails UserAgentDetails { get; }
     }
 
     public interface IResponseContext
@@ -104,6 +106,7 @@ public RequestContext(bool enableMetrics, ISigner clientSigner)
             this.Metrics = new RequestMetrics();
             this.Metrics.IsEnabled = enableMetrics;
             this.InvocationId = Guid.NewGuid();
+            this.UserAgentDetails = new UserAgentDetails();
         }
 
         public IRequest Request { get; set; }
@@ -120,6 +123,7 @@ public RequestContext(bool enableMetrics, ISigner clientSigner)
         public InvokeOptionsBase Options { get; set; }        
         public ISigner Signer { get; set; }
         public BaseIdentity Identity { get; set; }
+        public UserAgentDetails UserAgentDetails { get; }
 
 #if AWS_ASYNC_API
         public System.Threading.CancellationToken CancellationToken { get; set; }