feat(middleware-user-agent): add client config for userAgentAppId

codegen/smithy-aws-typescript-codegen/src/main/java/software/amazon/smithy/aws/typescript/codegen/AddUserAgentDependency.java

@@ -34,7 +34,7 @@
 import software.amazon.smithy.utils.SmithyInternalApi;
 
 /**
- * Add client plubins and configs to support injecting user agent.
+ * Add client plugins and configs to support injecting user agent.
  */
 @SmithyInternalApi
 public class AddUserAgentDependency implements TypeScriptIntegration {
@@ -57,6 +57,9 @@ public void addConfigInterfaceFields(
         writer.writeDocs("The provider populating default tracking information to be sent with `user-agent`, "
                 + "`x-amz-user-agent` header\n@internal");
         writer.write("defaultUserAgentProvider?: Provider<__UserAgent>;\n");
+        writer.writeDocs("The application ID used to identify the application.");
+        writer.write("userAgentAppId?: string | "
+        + "__Provider<string>;\n");
     }
 
     @Override
@@ -76,6 +79,15 @@ public Map<String, Consumer<TypeScriptWriter>> getRuntimeConfigWriters(
                             writer.addIgnoredDefaultImport("packageInfo", "./package.json",
                                     "package.json will be imported from dist folders");
                             writeDefaultUserAgentProvider(writer, settings, model);
+                        },
+                        "userAgentAppId", writer -> {
+                            writer.addDependency(TypeScriptDependency.NODE_CONFIG_PROVIDER);
+                            writer.addImport("loadConfig", "loadNodeConfig",
+                                TypeScriptDependency.NODE_CONFIG_PROVIDER);
+                            writer.addDependency(AwsDependency.AWS_SDK_UTIL_USER_AGENT_NODE);
+                            writer.addImport("NODE_APP_ID_CONFIG_OPTIONS", "NODE_APP_ID_CONFIG_OPTIONS",
+                                AwsDependency.AWS_SDK_UTIL_USER_AGENT_NODE);
+                            writer.write("loadNodeConfig(NODE_APP_ID_CONFIG_OPTIONS)");
                         }
                 );
             case BROWSER:

packages/middleware-user-agent/package.json

@@ -24,6 +24,7 @@
   "dependencies": {
     "@aws-sdk/types": "*",
     "@aws-sdk/util-endpoints": "*",
+    "@smithy/core": "*",
     "@smithy/protocol-http": "^4.1.3",
     "@smithy/types": "^3.4.2",
     "tslib": "^2.6.2"

packages/middleware-user-agent/src/configurations.ts

@@ -1,4 +1,11 @@
-import { Provider, UserAgent } from "@smithy/types";
+import { Logger, Provider, UserAgent } from "@smithy/types";
+import { normalizeProvider } from "@smithy/core";
+
+/**
+ * @internal
+ */
+export const DEFAULT_UA_APP_ID = undefined;
+
 /**
  * @public
  */
@@ -7,11 +14,18 @@ export interface UserAgentInputConfig {
    * The custom user agent header that would be appended to default one
    */
   customUserAgent?: string | UserAgent;
+  /**
+   * The application ID used to identify the SDK client.
+   */
+  userAgentAppId?: string | undefined | Provider<string | undefined>;
 }
+
 interface PreviouslyResolved {
   defaultUserAgentProvider: Provider<UserAgent>;
   runtime: string;
+  logger?: Logger;
 }
+
 export interface UserAgentResolvedConfig {
   /**
    * The provider populating default tracking information to be sent with `user-agent`, `x-amz-user-agent` header.
@@ -26,12 +40,37 @@ export interface UserAgentResolvedConfig {
    * The runtime environment
    */
   runtime: string;
+  /**
+   * Resolved value for input config {config.userAgentAppId}
+   */
+  userAgentAppId: Provider<string | undefined>;
 }
+
+function isValidUserAgentAppId(appId: unknown): boolean {
+  if (appId === undefined) {
+    return true;
+  }
+  return typeof appId === "string" && appId.length <= 50;
+}
+
 export function resolveUserAgentConfig<T>(
   input: T & PreviouslyResolved & UserAgentInputConfig
 ): T & UserAgentResolvedConfig {
+  const normalizedAppIdProvider = normalizeProvider(input.userAgentAppId ?? DEFAULT_UA_APP_ID);
   return {
     ...input,
     customUserAgent: typeof input.customUserAgent === "string" ? [[input.customUserAgent]] : input.customUserAgent,
+    userAgentAppId: async () => {
+      const appId = await normalizedAppIdProvider();
+      if (!isValidUserAgentAppId(appId)) {
+        const logger = input.logger?.constructor?.name === 'NoOpLogger' ? console : input.logger;
+        if (typeof appId !== "string") {
+          logger?.warn("userAgentAppId must be a string or undefined.");
+        } else if (appId.length > 50) {
+          logger?.warn("The provided userAgentAppId exceeds the maximum length of 50 characters.");
+        }
+      }
+      return appId;
+    },
   };
-}
+}

packages/middleware-user-agent/src/user-agent-middleware.spec.ts

@@ -30,6 +30,7 @@ describe("userAgentMiddleware", () => {
           ],
           customUserAgent: [["custom_ua/abc"]],
           runtime,
+          userAgentAppId: async () => undefined,
         });
         const handler = middleware(mockNextHandler, { userAgent: [["cfg/retry-mode", "standard"]] });
         await handler({ input: {}, request: new HttpRequest({ headers: {} }) });
@@ -50,6 +51,44 @@ describe("userAgentMiddleware", () => {
     );
   });
 
+  it("should include appId in user agent when provided", async () => {
+    const middleware = userAgentMiddleware({
+      defaultUserAgentProvider: async () => [
+        ["default_agent", "1.0.0"],
+        ["aws-sdk-js", "1.0.0"],
+      ],
+      customUserAgent: [["custom_ua/abc"]],
+      runtime: "node",
+      userAgentAppId: async () => "test-app-id",
+    });
+    const handler = middleware(mockNextHandler, { userAgent: [["cfg/retry-mode", "standard"]] });
+    await handler({ input: {}, request: new HttpRequest({ headers: {} }) });
+    expect(mockNextHandler.mock.calls.length).toEqual(1);
+    const sdkUserAgent = mockNextHandler.mock.calls[0][0].request.headers[USER_AGENT];
+    expect(sdkUserAgent).toEqual(expect.stringContaining("app/test-app-id"));
+  });
+
+  it("should include long appId in user agent when provided", async () => {
+    const longAppId = "a".repeat(51); // 51 characters, exceeding the 50 character limit
+    const middleware = userAgentMiddleware({
+      defaultUserAgentProvider: async () => [
+        ["default_agent", "1.0.0"],
+        ["aws-sdk-js", "1.0.0"],
+      ],
+      customUserAgent: [["custom_ua/abc"]],
+      runtime: "node",
+      userAgentAppId: async () => longAppId,
+    });
+    const handler = middleware(mockNextHandler, {});
+    await handler({ input: {}, request: new HttpRequest({ headers: {} }) });
+
+    const sdkUserAgent = mockNextHandler.mock.calls[0][0].request.headers[USER_AGENT];
+    expect(sdkUserAgent).toEqual(expect.stringContaining(`app/${longAppId}`));
+    expect(sdkUserAgent).toEqual(expect.stringContaining("aws-sdk-js/1.0.0"));
+    expect(sdkUserAgent).toEqual(expect.stringContaining("default_agent/1.0.0"));
+    expect(sdkUserAgent).toEqual(expect.stringContaining("custom_ua/abc"));
+  });
+
   describe("should sanitize the SDK user agent string", () => {
     const cases: { ua: UserAgentPair; expected: string }[] = [
       { ua: ["/name", "1.0.0"], expected: "name/1.0.0" },
@@ -72,6 +111,7 @@ describe("userAgentMiddleware", () => {
             const middleware = userAgentMiddleware({
               defaultUserAgentProvider: async () => [ua],
               runtime,
+              userAgentAppId: async () => undefined,
             });
             const handler = middleware(mockNextHandler, {});
             await handler({ input: {}, request: new HttpRequest({ headers: {} }) });
@@ -84,6 +124,7 @@ describe("userAgentMiddleware", () => {
             const middleware = userAgentMiddleware({
               defaultUserAgentProvider: async () => [ua],
               runtime,
+              userAgentAppId: async () => undefined,
             });
 
             // internal variant

packages/middleware-user-agent/src/user-agent-middleware.ts

@@ -46,8 +46,12 @@ export const userAgentMiddleware =
     if (!HttpRequest.isInstance(request)) return next(args);
     const { headers } = request;
     const userAgent = context?.userAgent?.map(escapeUserAgent) || [];
-    const defaultUserAgent = (await options.defaultUserAgentProvider()).map(escapeUserAgent);
+    let defaultUserAgent = (await options.defaultUserAgentProvider()).map(escapeUserAgent);
     const customUserAgent = options?.customUserAgent?.map(escapeUserAgent) || [];
+    const appId = await options.userAgentAppId();
+    if (appId) {
+      defaultUserAgent.push(escapeUserAgent([`app/${appId}`]));
+    }
     const prefix = getUserAgentPrefix();
 
     // Set value to AWS-specific user agent header

packages/util-user-agent-browser/src/index.spec.ts

@@ -1,23 +1,50 @@
-import { defaultUserAgent } from ".";
+import { defaultUserAgent, PreviouslyResolved } from ".";
 
 const ua =
   "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.111 Safari/537.36";
 
-it("should populate metrics", async () => {
-  jest.spyOn(window.navigator, "userAgent", "get").mockReturnValue(ua);
-  const userAgent = await defaultUserAgent({ serviceId: "s3", clientVersion: "0.1.0" })();
-  expect(userAgent[0]).toEqual(["aws-sdk-js", "0.1.0"]);
-  expect(userAgent[1]).toEqual(["ua", "2.0"]);
-  expect(userAgent[2]).toEqual(["os/macOS", "10.15.7"]);
-  expect(userAgent[3]).toEqual(["lang/js"]);
-  expect(userAgent[4]).toEqual(["md/browser", "Chrome_86.0.4240.111"]);
-  expect(userAgent[5]).toEqual(["api/s3", "0.1.0"]);
-  jest.clearAllMocks();
-});
-
-it("should populate metrics when service id not available", async () => {
-  jest.spyOn(window.navigator, "userAgent", "get").mockReturnValue(ua);
-  const userAgent = await defaultUserAgent({ serviceId: undefined, clientVersion: "0.1.0" })();
-  expect(userAgent).not.toContainEqual(["api/s3", "0.1.0"]);
-  jest.clearAllMocks();
-});
+const mockConfig: PreviouslyResolved = {
+  userAgentAppId: jest.fn().mockResolvedValue(undefined),
+};
+
+describe("defaultUserAgent", () => {
+  beforeEach(() => {
+    jest.spyOn(window.navigator, "userAgent", "get").mockReturnValue(ua);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should populate metrics", async () => {
+    const userAgent = await defaultUserAgent({ serviceId: "s3", clientVersion: "0.1.0" })(mockConfig);
+    expect(userAgent[0]).toEqual(["aws-sdk-js", "0.1.0"]);
+    expect(userAgent[1]).toEqual(["ua", "2.0"]);
+    expect(userAgent[2]).toEqual(["os/macOS", "10.15.7"]);
+    expect(userAgent[3]).toEqual(["lang/js"]);
+    expect(userAgent[4]).toEqual(["md/browser", "Chrome_86.0.4240.111"]);
+    expect(userAgent[5]).toEqual(["api/s3", "0.1.0"]);
+    expect(userAgent.length).toBe(6);
+  });
+
+  it("should populate metrics when service id not available", async () => {
+    const userAgent = await defaultUserAgent({ serviceId: undefined, clientVersion: "0.1.0" })(mockConfig);
+    expect(userAgent).not.toContainEqual(["api/s3", "0.1.0"]);
+    expect(userAgent.length).toBe(5);
+  });
+
+  it("should include appId when provided", async () => {
+    const configWithAppId: PreviouslyResolved = {
+      userAgentAppId: jest.fn().mockResolvedValue("test-app-id"),
+    };
+    const userAgent = await defaultUserAgent({ serviceId: "s3", clientVersion: "0.1.0" })(configWithAppId);
+    expect(userAgent[6]).toEqual(["app/test-app-id"]);
+    expect(userAgent.length).toBe(7);
+  });
+
+  it("should not include appId when not provided", async () => {
+    const userAgent = await defaultUserAgent({ serviceId: "s3", clientVersion: "0.1.0" })(mockConfig);
+    expect(userAgent).not.toContainEqual(expect.arrayContaining(["app/"]));
+    expect(userAgent.length).toBe(6);
+  });
+});

packages/util-user-agent-browser/src/index.ts

@@ -3,15 +3,19 @@ import bowser from "bowser";
 
 import { DefaultUserAgentOptions } from "./configurations";
 
+export interface PreviouslyResolved {
+  userAgentAppId: Provider<string | undefined>;
+}
+
 /**
  * @internal
  *
  * Default provider to the user agent in browsers. It's a best effort to infer
  * the device information. It uses bowser library to detect the browser and version
  */
 export const defaultUserAgent =
-  ({ serviceId, clientVersion }: DefaultUserAgentOptions): Provider<UserAgent> =>
-  async () => {
+  ({ serviceId, clientVersion }: DefaultUserAgentOptions): ((config: PreviouslyResolved) => Promise<UserAgent>) =>
+  async (config?: PreviouslyResolved) => {
     const parsedUA =
       typeof window !== "undefined" && window?.navigator?.userAgent
         ? bowser.parse(window.navigator.userAgent)
@@ -36,5 +40,10 @@ export const defaultUserAgent =
       sections.push([`api/${serviceId}`, clientVersion]);
     }
 
+    const appId = await config?.userAgentAppId?.();
+    if (appId) {
+      sections.push([`app/${appId}`]);
+    }
+
     return sections;
   };

packages/util-user-agent-node/package.json

@@ -20,6 +20,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
+    "@aws-sdk/middleware-user-agent": "*",
     "@aws-sdk/types": "*",
     "@smithy/node-config-provider": "^3.1.7",
     "@smithy/types": "^3.4.2",