apcore-js 0.18.0 → 0.20.0

package/dist/trace-context.js

@@ -1,36 +1,71 @@
 /**
- * W3C Trace Context support: TraceParent parsing and TraceContext injection/extraction.
+ * W3C Trace Context support: TraceParent + tracestate parsing and TraceContext
+ * injection/extraction.
  */
 import { randomHex } from './utils/index.js';
 const TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const PARENT_ID_RE = /^[0-9a-f]{16}$/;
+const TRACESTATE_KEY_RE = /^[a-z0-9][a-z0-9_\-*/@]{0,255}$/;
+/** W3C tracestate hard cap (RFC: SHOULD discard beyond 32 entries). */
+const MAX_TRACESTATE_ENTRIES = 32;
+/** Well-known key under `context.data` carrying the inbound TraceParent (if any). */
+const INBOUND_KEY = '_apcore.trace.inbound';
 export class TraceContext {
     /**
-     * Build a traceparent header dict from an apcore Context.
+     * Build outbound trace headers from an apcore Context.
      *
-     * Uses `context.traceId` (already 32-hex format) directly in the
-     * W3C traceparent header. Uses the last span's `spanId` from the
-     * tracing stack if available, otherwise generates a random 16-hex parent id.
+     * Behavior:
+     * - Uses `context.traceId` (already 32-hex) as the traceparent trace_id.
+     * - When `parentId` is supplied it is used verbatim and MUST match `^[0-9a-f]{16}$`;
+     *   otherwise the last span on the tracing stack provides the id, falling back
+     *   to a fresh random 16-hex value.
+     * - When the Context carries an inbound TraceParent under
+     *   `data['_apcore.trace.inbound']`, its `traceFlags` and `tracestate` are
+     *   propagated; otherwise traceFlags defaults to `"01"` (sampled) for new roots.
+     *
+     * @param context apcore Context
+     * @param parentId optional 16-hex parent id override
+     * @throws {Error} if `parentId` is provided but malformed
      */
-    static inject(context) {
+    static inject(context, parentId) {
         const traceIdHex = context.traceId; // already 32-hex format
-        const spansStack = context.data['_apcore.mw.tracing.spans'];
-        let parentId;
-        if (spansStack && spansStack.length > 0) {
-            parentId = spansStack[spansStack.length - 1].spanId;
+        let chosenParent;
+        if (parentId !== undefined) {
+            if (!PARENT_ID_RE.test(parentId)) {
+                const err = new Error(`Malformed parentId override: ${JSON.stringify(parentId)}. Expected 16 lowercase hex chars matching /^[0-9a-f]{16}$/.`);
+                err.code = 'INVALID_PARENT_ID';
+                throw err;
+            }
+            chosenParent = parentId;
         }
         else {
-            parentId = randomHex(8);
+            const spansStack = context.data['_apcore.mw.tracing.spans'];
+            if (spansStack && spansStack.length > 0) {
+                chosenParent = spansStack[spansStack.length - 1].spanId;
+            }
+            else {
+                chosenParent = randomHex(8);
+            }
+        }
+        const inbound = context.data[INBOUND_KEY];
+        const flags = inbound?.traceFlags ?? '01';
+        const headers = {
+            traceparent: `00-${traceIdHex}-${chosenParent}-${flags}`,
+        };
+        const stateEntries = inbound?.tracestate ?? [];
+        if (stateEntries.length > 0) {
+            headers.tracestate = TraceContext.formatTracestate(stateEntries);
         }
-        const traceparent = `00-${traceIdHex}-${parentId}-01`;
-        return { traceparent };
+        return headers;
     }
     /**
-     * Parse the `traceparent` header from the given headers object.
+     * Parse the `traceparent` (and optional `tracestate`) header from a header
+     * container, performing case-insensitive header name lookup.
      *
-     * Returns `null` if the header is missing or malformed.
+     * Returns `null` if the traceparent header is missing or malformed.
      */
     static extract(headers) {
-        const raw = headers['traceparent'];
+        const raw = TraceContext.lookupHeaderCi(headers, 'traceparent');
         if (raw === undefined) {
             return null;
         }
@@ -47,11 +82,16 @@ export class TraceContext {
         if (traceId === '0'.repeat(32) || parentId === '0'.repeat(16)) {
             return null;
         }
+        const tracestateRaw = TraceContext.lookupHeaderCi(headers, 'tracestate');
+        const tracestate = tracestateRaw !== undefined
+            ? Object.freeze(TraceContext.parseTracestate(tracestateRaw).map((p) => Object.freeze(p)))
+            : Object.freeze([]);
         return Object.freeze({
             version,
             traceId,
             parentId,
             traceFlags: match[4],
+            tracestate,
         });
     }
     /**
@@ -79,7 +119,90 @@ export class TraceContext {
             traceId,
             parentId,
             traceFlags: match[4],
+            tracestate: Object.freeze([]),
         });
     }
+    /**
+     * Parse a W3C `tracestate` header value.
+     *
+     * Splits on commas, trims each member, and accepts only entries shaped as
+     * `key=value` (the value may contain `=`). Malformed members are dropped
+     * silently. The list is truncated to {@link MAX_TRACESTATE_ENTRIES} (32).
+     */
+    static parseTracestate(raw) {
+        if (raw.length === 0) {
+            return [];
+        }
+        const entries = [];
+        for (const member of raw.split(',')) {
+            const trimmed = member.trim();
+            if (trimmed.length === 0) {
+                continue;
+            }
+            const eq = trimmed.indexOf('=');
+            if (eq <= 0) {
+                // Missing key (eq === 0) or no '=' (eq === -1). Drop silently.
+                continue;
+            }
+            const key = trimmed.slice(0, eq).trim();
+            const value = trimmed.slice(eq + 1).trim();
+            if (key.length === 0 || value.length === 0) {
+                continue;
+            }
+            // RFC 9: be lenient. Tolerate keys that fail strict regex but at least
+            // require non-empty key/value. Strict validation may be opted into by
+            // upstream callers if needed.
+            if (!TRACESTATE_KEY_RE.test(key)) {
+                // Still drop blatantly malformed keys (e.g., contains '=' or whitespace).
+                if (/[\s=,]/.test(key)) {
+                    continue;
+                }
+            }
+            entries.push([key, value]);
+            if (entries.length >= MAX_TRACESTATE_ENTRIES) {
+                break;
+            }
+        }
+        return entries;
+    }
+    /**
+     * Format tracestate entries to a comma-separated header value.
+     */
+    static formatTracestate(entries) {
+        return entries.map(([k, v]) => `${k}=${v}`).join(',');
+    }
+    /**
+     * Case-insensitive header lookup across plain objects, `Headers`, and `Map`.
+     *
+     * @returns the header value (or `undefined` if not present).
+     */
+    static lookupHeaderCi(headers, name) {
+        const target = name.toLowerCase();
+        // Headers (fetch API): already case-insensitive.
+        if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+            const v = headers.get(name);
+            return v === null ? undefined : v;
+        }
+        // Map<string, string>
+        if (headers instanceof Map) {
+            for (const [k, v] of headers.entries()) {
+                if (typeof k === 'string' && k.toLowerCase() === target) {
+                    return typeof v === 'string' ? v : String(v);
+                }
+            }
+            return undefined;
+        }
+        // Plain object
+        for (const [k, v] of Object.entries(headers)) {
+            if (k.toLowerCase() === target) {
+                if (typeof v === 'string')
+                    return v;
+                if (v === undefined || v === null)
+                    return undefined;
+                return String(v);
+            }
+        }
+        return undefined;
+    }
 }
 //# sourceMappingURL=trace-context.js.map

package/dist/trace-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../src/trace-context.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAMxD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAErC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAYpD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAMxD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAErC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAapD"}

package/dist/utils/index.js

@@ -25,7 +25,8 @@ export function randomHex(byteLength) {
         c.getRandomValues(bytes);
     }
     else {
-        // Last-resort fallback (sufficient for trace/span IDs, not for security)
+        // Last-resort fallback for environments without crypto (e.g., legacy Node without webcrypto)
+        console.warn('[apcore:utils] crypto unavailable — falling back to Math.random for randomHex (not cryptographically secure)');
         for (let i = 0; i < bytes.length; i++) {
             bytes[i] = Math.floor(Math.random() * 256);
         }

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kFAAkF;AAClF,IAAI,WAAqD,CAAC;AAC1D,IAAI,CAAC;IAAC,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;AAAC,CAAC;AAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;AAEtF,MAAM,UAAU,QAAQ,CAAI,GAAM;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,IAAI,WAAW,EAAE,SAAS,CAAC;IACtD,IAAI,CAAC,EAAE,CAAC;QACN,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,yEAAyE;QACzE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kFAAkF;AAClF,IAAI,WAAqD,CAAC;AAC1D,IAAI,CAAC;IAAC,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;AAAC,CAAC;AAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;AAEtF,MAAM,UAAU,QAAQ,CAAI,GAAM;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,IAAI,WAAW,EAAE,SAAS,CAAC;IACtD,IAAI,CAAC,EAAE,CAAC;QACN,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,6FAA6F;QAC7F,OAAO,CAAC,IAAI,CAAC,8GAA8G,CAAC,CAAC;QAC7H,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "AI-Perceivable Core — schema-driven module standard",
   "type": "module",
   "main": "./dist/index.js",