Conjure User-Agents supports arbitrary comment data

packages/conjure-client/changelog/@unreleased/pr-186.v2.yml

@@ -0,0 +1,5 @@
+type: feature
+feature:
+  description: Conjure User-Agents supports arbitrary comment data
+  links:
+  - https://github.com/palantir/conjure-typescript-runtime/pull/186

packages/conjure-client/src/__integTest__/tests.ts

@@ -44,6 +44,7 @@ const bridge = new FetchBridge({
     userAgent: {
         productName: "conjure-typescript-runtime",
         productVersion: "0.0.0",
+        comments: ["some-comment"],
     },
 });
 

packages/conjure-client/src/fetchBridge/__tests__/fetchBridgeServerTests.ts

@@ -36,7 +36,7 @@ describe("FetchBridgeImplServer", () => {
         const host = "localhost";
         const port = 9000;
         const baseUrl = `http://${host}:${port}`;
-        const userAgent: IUserAgent = { productName: "foo", productVersion: "1.2.3" };
+        const userAgent: IUserAgent = { productName: "foo", productVersion: "1.2.3", comments: ["some-comment"] };
         bridge = new FetchBridge({ baseUrl, token, fetch: nodeFetchStreamAdapter(nodeFetch), userAgent });
 
         app = express();

packages/conjure-client/src/fetchBridge/__tests__/fetchBridgeTests.ts

@@ -563,6 +563,32 @@ describe("FetchBridgeImpl", () => {
             verifyFetchUserAgent(`foo/1.2.3 bar/1.2.3 baz/1.2.3 conjure-typescript-runtime/${IMPLEMENTATION_VERSION}`);
         });
 
+        it("for a user agent with comments", async () => {
+            const fetchBridge = new FetchBridge({
+                baseUrl,
+                token,
+                fetch: undefined,
+                userAgent: { productName: "foo", productVersion: "1.2.3", comments: ["comment1", "comment2"] },
+            });
+
+            await fetchBridge.callEndpoint(request);
+
+            verifyFetchUserAgent(`foo/1.2.3 (comment1; comment2) conjure-typescript-runtime/${IMPLEMENTATION_VERSION}`);
+        });
+
+        it("for a user agent with empty coments", async () => {
+            const fetchBridge = new FetchBridge({
+                baseUrl,
+                token,
+                fetch: undefined,
+                userAgent: { productName: "foo", productVersion: "1.2.3", comments: [] },
+            });
+
+            await fetchBridge.callEndpoint(request);
+
+            verifyFetchUserAgent(`foo/1.2.3 conjure-typescript-runtime/${IMPLEMENTATION_VERSION}`);
+        });
+
         it("for changing user agent", async () => {
             const userAgentSupplier = jest
                 .fn()

packages/conjure-client/src/userAgent.ts

@@ -18,6 +18,18 @@
 export interface IUserAgent {
     productName: string;
     productVersion: string;
+    /**
+     * [rfc7231 section-5.5.3](https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3) comment
+     * metadata (as described by
+     * [rfc7230 section-3.2.6](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6"))
+     * for additional diagnostic information.
+     *
+     * Note that this library provides a much stricter set of allowed
+     * characters within comments than the linked RFCs to reduce complexity.
+     *
+     * Allowed characters: "a-zA-Z0-9.-:_/ "
+     */
+    comments?: string[];
 }
 
 /**
@@ -40,6 +52,10 @@ export class UserAgent {
 }
 
 function formatUserAgent(userAgent: IUserAgent): string {
-    const { productName, productVersion } = userAgent;
-    return `${productName}/${productVersion}`;
+    const { productName, productVersion, comments } = userAgent;
+    let formattedUserAgent = `${productName}/${productVersion}`;
+    if (comments != null && comments.length > 0) {
+        formattedUserAgent += " (" + comments.join("; ") + ")";
+    }
+    return formattedUserAgent;
 }