feat: w3c field

.github/workflows/dockerized-test.yml

@@ -0,0 +1,45 @@
+name: dockerized-test
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [nodejs24.x]
+  pull_request:
+    branches: ['*']
+  workflow_dispatch:
+
+jobs:
+  dockerized-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Build the RIC tarball
+        # Produces build-artifacts/aws-lambda-ric-<version>.tgz, which
+        # Dockerfile.test unpacks into /var/runtime in the test image.
+        run: npm run build:container
+
+      - name: Build the test image
+        run: |
+          docker build . \
+            -t local/test \
+            -f Dockerfile.test \
+            --build-arg BASE_IMAGE=public.ecr.aws/lambda/nodejs:24
+
+      - name: Run dockerized suites
+        uses: aws/containerized-test-runner-for-aws-lambda@76eacfb110903739d9c5f7fcdaafede6324a1473 # maxday/client-context
+        with:
+          suiteFileArray: '["./test/dockerized/suites/*.json"]'
+          dockerImageName: 'local/test'
+          taskFolder: './test/dockerized/tasks'

Dockerfile.js

@@ -23,11 +23,11 @@ RUN mkdir -p /build && \
     ls -R /build/deps
 
 # Copy bare config
-COPY package.json tsconfig.json eslint.config.js vitest.config.js vitest.setup.ts  /app/
+COPY package.json package-lock.json tsconfig.json eslint.config.js vitest.config.js vitest.setup.ts  /app/
 
 WORKDIR /app
 
-RUN npm install --ignore-scripts
+RUN npm ci --ignore-scripts
 
 COPY src /app/src
 COPY scripts/build.js /app/scripts/build.js

Dockerfile.test

@@ -0,0 +1,11 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+ARG BASE_IMAGE=public.ecr.aws/lambda/nodejs:24
+FROM $BASE_IMAGE
+
+# Swap the RIC shipped in the base image for the one we just built.
+ADD build-artifacts/aws-lambda-ric-*.tgz /tmp/
+RUN mv /tmp/package/* /var/runtime/ && rm -rf /tmp/package
+
+COPY test/dockerized/tasks /var/task/

src/context/constants.ts

@@ -24,6 +24,14 @@ export const REQUIRED_ENV_VARS = [
   "AWS_LAMBDA_LOG_STREAM_NAME",
 ];
 
+export const W3C_ALLOWED_FIELDS = [
+  "traceparent",
+  "tracestate",
+  "baggage",
+] as const;
+
+export type W3CFieldName = (typeof W3C_ALLOWED_FIELDS)[number];
+
 // This RIC is used by Nodejs24 and above, it's used by NOdejs22 only for LMI and not OD
 export const CALLBACK_ERROR_NODEJS22 =
   "ERROR: AWS Lambda does not support callback-based function handlers when using Node.js 22 with Managed Instances. To use Managed Instances, modify this function to use a supported handler signature. For more information see https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html.";

src/context/context-builder.test.ts

@@ -60,6 +60,7 @@ describe("ContextBuilder", () => {
 
         // Methods
         getRemainingTimeInMillis: expect.any(Function),
+        w3c: expect.any(Function),
       });
     });
 
@@ -183,6 +184,272 @@ describe("ContextBuilder", () => {
     });
   });
 
+  describe("w3c", () => {
+    it("should return {} when no clientContext header is provided", () => {
+      // GIVEN
+      const headersWithoutClientContext: Record<string, string> = {
+        ...mockValidHeaders,
+      };
+      delete headersWithoutClientContext[HEADERS.CLIENT_CONTEXT];
+
+      // WHEN
+      const context = ContextBuilder.build(headersWithoutClientContext);
+
+      // THEN
+      expect(context.w3c()).toEqual({});
+    });
+
+    it("should return {} when clientContext has no w3c key", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({ custom: { value: "test" } }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({});
+      // clientContext is untouched when there was nothing to strip
+      expect(context.clientContext).toEqual({ custom: { value: "test" } });
+    });
+
+    it("should return {baggage:'abc'} when only baggage is set", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: { baggage: "abc" },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({ baggage: "abc" });
+    });
+
+    it("should return every w3c field carried on clientContext", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          custom: { value: "test" },
+          w3c: {
+            traceparent:
+              "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+            tracestate: "rojo=00f067aa0ba902b7",
+            baggage: "userId=alice",
+          },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({
+        traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+        tracestate: "rojo=00f067aa0ba902b7",
+        baggage: "userId=alice",
+      });
+    });
+
+    it("should remove the source clientContext.w3c (and nested fields) after construction", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          custom: { value: "test" },
+          w3c: {
+            traceparent:
+              "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+            baggage: "userId=alice",
+          },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.clientContext).toBeDefined();
+      expect(context.clientContext).not.toHaveProperty("w3c");
+      expect(
+        (context.clientContext as Record<string, unknown>)["w3c"],
+      ).toBeUndefined();
+      // Sibling clientContext fields are preserved
+      expect(context.clientContext).toEqual({ custom: { value: "test" } });
+    });
+
+    it("should ignore non-string w3c field values while still stripping the source", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: {
+            baggage: "abc",
+            traceparent: 42, // wrong type — must be dropped
+            tracestate: null, // wrong type — must be dropped
+          },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({ baggage: "abc" });
+      expect(context.clientContext).not.toHaveProperty("w3c");
+    });
+
+    it("should treat a non-object w3c value as empty and still strip the source", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: "not-an-object",
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({});
+      expect(context.clientContext).not.toHaveProperty("w3c");
+    });
+
+    it("should treat an array w3c value as empty and still strip the source", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: ["baggage=abc"],
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({});
+      expect(context.clientContext).not.toHaveProperty("w3c");
+    });
+
+    it("should return a fresh copy so callers cannot mutate the underlying map", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: { baggage: "abc" },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+      const first = context.w3c();
+      first["baggage"] = "tampered";
+      first["injected"] = "nope";
+
+      // THEN
+      expect(context.w3c()).toEqual({ baggage: "abc" });
+    });
+
+    it("should only surface the allowlisted fields (traceparent, tracestate, baggage)", () => {
+      // GIVEN — every allowlisted field set, plus a non-allowlisted one
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: {
+            traceparent:
+              "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+            tracestate: "rojo=00f067aa0ba902b7",
+            baggage: "userId=alice",
+          },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({
+        traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+        tracestate: "rojo=00f067aa0ba902b7",
+        baggage: "userId=alice",
+      });
+    });
+
+    it("should drop non-allowlisted w3c keys even when the value is a valid string", () => {
+      // GIVEN
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: {
+            baggage: "keep=me",
+            // Non-allowlisted keys — must NOT be surfaced by w3c()
+            unknownField: "should-not-appear",
+            "x-custom-trace": "should-not-appear",
+            __proto__: "should-not-appear",
+            constructor: "should-not-appear",
+            toString: "should-not-appear",
+          },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({ baggage: "keep=me" });
+      // Source is still stripped regardless
+      expect(context.clientContext).not.toHaveProperty("w3c");
+    });
+
+    it("should omit allowlisted keys when they are absent (no undefined leaks)", () => {
+      // GIVEN — only baggage present
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: { baggage: "abc" },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      const result = context.w3c();
+      expect(result).toEqual({ baggage: "abc" });
+      expect("traceparent" in result).toBe(false);
+      expect("tracestate" in result).toBe(false);
+    });
+
+    it("should drop allowlisted keys whose value is not a string", () => {
+      // GIVEN — every allowlisted key present, but with wrong types
+      const headers = {
+        ...mockValidHeaders,
+        [HEADERS.CLIENT_CONTEXT]: JSON.stringify({
+          w3c: {
+            traceparent: 42,
+            tracestate: null,
+            baggage: { nested: "no" },
+          },
+        }),
+      };
+
+      // WHEN
+      const context = ContextBuilder.build(headers);
+
+      // THEN
+      expect(context.w3c()).toEqual({});
+      expect(context.clientContext).not.toHaveProperty("w3c");
+    });
+  });
+
   describe("getRemainingTimeInMillis", () => {
     it("should calculate remaining time correctly", () => {
       // GIVEN