feat: w3c, return a frozen W3CFields from w3c() instead of a per-call clone

Author: maxday

src/context/constants.ts

@@ -31,6 +31,7 @@ export const W3C_ALLOWED_FIELDS = [
 ] as const;
 
 export type W3CFieldName = (typeof W3C_ALLOWED_FIELDS)[number];
+export type W3CFields = Readonly<Partial<Record<W3CFieldName, string>>>;
 
 // This RIC is used by Nodejs24 and above, it's used by NOdejs22 only for LMI and not OD
 export const CALLBACK_ERROR_NODEJS22 =

src/context/context-builder.test.ts

@@ -339,7 +339,7 @@ describe("ContextBuilder", () => {
       expect(context.clientContext).not.toHaveProperty("w3c");
     });
 
-    it("should return a fresh copy so callers cannot mutate the underlying map", () => {
+    it("should expose a frozen object so callers cannot mutate the fields", () => {
       // GIVEN
       const headers = {
         ...mockValidHeaders,
@@ -350,11 +350,22 @@ describe("ContextBuilder", () => {
 
       // WHEN
       const context = ContextBuilder.build(headers);
-      const first = context.w3c();
-      first["baggage"] = "tampered";
-      first["injected"] = "nope";
 
-      // THEN
+      // THEN — the object is frozen
+      expect(Object.isFrozen(context.w3c())).toBe(true);
+
+      // AND — attempts to write silently no-op in sloppy mode and throw in
+      // strict mode. The test file is a strict ESM TypeScript module, so
+      // both overwriting an existing key and adding a new one throw.
+      const mutable = context.w3c() as Record<string, string>;
+      expect(() => {
+        mutable["baggage"] = "tampered";
+      }).toThrow(TypeError);
+      expect(() => {
+        mutable["injected"] = "nope";
+      }).toThrow(TypeError);
+
+      // AND — the value is unchanged.
       expect(context.w3c()).toEqual({ baggage: "abc" });
     });
 

src/context/context-builder.ts

@@ -4,6 +4,7 @@ import {
   REQUIRED_ENV_VARS,
   REQUIRED_INVOKE_HEADERS,
   W3C_ALLOWED_FIELDS,
+  W3CFields,
   W3CFieldName,
 } from "./constants.js";
 import { InvokeContext, InvokeHeaders } from "./types.js";
@@ -54,33 +55,33 @@ export class ContextBuilder {
       getRemainingTimeInMillis: function () {
         return deadline - Date.now();
       },
-      w3c: function (): Partial<Record<W3CFieldName, string>> {
-        return { ...w3cFields };
+      w3c: function (): W3CFields {
+        return w3cFields;
       },
     };
   }
 
   /**
-   * Pulls `w3c` out of the parsed `clientContext` and returns a normalized
-   * copy of the allowlisted string fields (see `W3C_ALLOWED_FIELDS`). The
-   * `w3c` key is removed from `clientContext` itself so callers cannot read
-   * the source through `context.clientContext`.
+   * Pulls `w3c` out of the parsed `clientContext` and returns a frozen,
+   * normalized copy of the allowlisted string fields (see
+   * `W3C_ALLOWED_FIELDS`). The `w3c` key is removed from `clientContext`
+   * itself so callers cannot read the source through `context.clientContext`.
    */
   private static extractAndStripW3c(
     clientContext: Record<string, unknown> | undefined,
-  ): Partial<Record<W3CFieldName, string>> {
+  ): W3CFields {
     if (!clientContext || typeof clientContext !== "object") {
-      return {};
+      return Object.freeze({});
     }
     if (!("w3c" in clientContext)) {
-      return {};
+      return Object.freeze({});
     }
 
     const rawW3c = clientContext.w3c;
     delete clientContext.w3c;
 
     if (!rawW3c || typeof rawW3c !== "object" || Array.isArray(rawW3c)) {
-      return {};
+      return Object.freeze({});
     }
 
     const source = rawW3c as Record<string, unknown>;
@@ -91,7 +92,7 @@ export class ContextBuilder {
         fields[key] = value;
       }
     }
-    return fields;
+    return Object.freeze(fields);
   }
 
   private static parseDeadline(invokeHeaders: InvokeHeaders) {

src/context/types.ts

@@ -2,7 +2,7 @@ import { WritableResponseStream } from "../stream/index.js";
 import {
   OPTIONAL_INVOKE_HEADERS,
   REQUIRED_INVOKE_HEADERS,
-  W3CFieldName,
+  W3CFields,
 } from "./constants.js";
 
 export interface InvokeHeaders {
@@ -41,7 +41,7 @@ export interface InvokeContext {
    * Returns the W3C trace context fields (traceparent, tracestate, baggage)
    * that were carried on `clientContext.w3c` at invoke time.
    */
-  w3c(): Partial<Record<W3CFieldName, string>>;
+  w3c(): W3CFields;
 }
 
 export interface StreamOptions {

test/dockerized/suites/w3c.json

@@ -1,11 +1,11 @@
 {
   "tests": [
     {
-      "name": "w3c_is_a_function_on_context",
-      "handler": "w3c.w3cIsFunction",
+      "name": "w3c_is_a_function_returning_a_frozen_object",
+      "handler": "w3c.w3cShape",
       "request": {},
       "assertions": [
-        { "response": { "isFunction": true } }
+        { "response": { "typeofW3c": "function", "typeofResult": "object", "isFrozen": true, "isObject": true } }
       ]
     },
 

test/dockerized/tasks/w3c.mjs

@@ -20,6 +20,12 @@ export const echoClientContext = async (_event, context) => {
   return context.clientContext ?? null;
 };
 
-export const w3cIsFunction = async (_event, context) => {
-  return { isFunction: typeof context.w3c === "function" };
+export const w3cShape = async (_event, context) => {
+  const value = context.w3c();
+  return {
+    typeofW3c: typeof context.w3c,
+    typeofResult: typeof value,
+    isFrozen: Object.isFrozen(value),
+    isObject: value !== null && typeof value === "object",
+  };
 };