@webpieces/core-util 0.3.285 → 0.3.287

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.3.285",
+  "version": "0.3.287",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/ContextKey.d.ts

@@ -1,21 +1,39 @@
-import { Header } from './Header';
 /**
- * ContextKey - Typed key for non-HTTP context values stored in RequestContext.
+ * ContextKey - a single key that travels in the request's "magic context"
+ * (RequestContext on the server, MutableContextStore in the browser).
  *
- * Similar to PlatformHeader but for context-only values that don't correspond
- * to HTTP headers (e.g., METHOD_META, REQUEST_PATH).
+ * This ONE class replaces the old split of `Header` (interface) + `PlatformHeader`
+ * (class) + `ContextKey` (class). Every context value — whether it rides over HTTP
+ * (request-id, tenant, authorization) or stays in-process (method-meta, the
+ * TestCaseRecorder) — is a `ContextKey`.
  *
- * Customers can define their own ContextKey instances for app-specific values.
+ * The fields are named for what they DO (flipped from the old model):
+ * - `name`       ALWAYS set. The context storage key, the log/MDC key, and the
+ *                recorder name. e.g. 'requestId', 'tenantId', 'authorization'.
+ * - `httpHeader` OPTIONAL. When set, this key is transferred over the wire under
+ *                this HTTP header name (inbound request -> context, and context ->
+ *                outbound request). e.g. 'x-request-id'. When UNSET, the key is
+ *                context-only and never leaves the process (method-meta, recorder).
+ * - `isSecured`  When true, the value is masked (partially) in logs.
+ * - `isLogged`   Defaults to true. When false, the value is NEVER logged (used for
+ *                object-valued/internal keys like the recorder or method-meta that
+ *                must not be serialized into log lines).
  *
- * Usage:
- * ```typescript
- * const MY_KEY = new ContextKey('my-app-key');
- * RequestContext.putHeader(MY_KEY, someValue);
- * const value = RequestContext.getHeader(MY_KEY);
- * ```
+ * Per CLAUDE.md: data-only structures are classes, not interfaces.
  */
-export declare class ContextKey implements Header {
-    private readonly keyName;
-    constructor(keyName: string);
-    getHeaderName(): string;
+export declare class ContextKey {
+    /** Context storage key + log/MDC key + recorder name. Always set. */
+    readonly name: string;
+    /**
+     * HTTP header name when this key is transferred over the wire (e.g.
+     * 'x-request-id'). Undefined = context-only, never transferred.
+     */
+    readonly httpHeader?: string;
+    /** Mask this value (partially) in logs. */
+    readonly isSecured: boolean;
+    /** Whether this key is logged at all. Default true; false = never logged. */
+    readonly isLogged: boolean;
+    constructor(name: string, httpHeader?: string, isSecured?: boolean, isLogged?: boolean);
+    /** True when this key is transferred over HTTP (has an httpHeader). */
+    isTransferred(): boolean;
 }

package/src/ContextKey.js

@@ -2,27 +2,49 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextKey = void 0;
 /**
- * ContextKey - Typed key for non-HTTP context values stored in RequestContext.
+ * ContextKey - a single key that travels in the request's "magic context"
+ * (RequestContext on the server, MutableContextStore in the browser).
  *
- * Similar to PlatformHeader but for context-only values that don't correspond
- * to HTTP headers (e.g., METHOD_META, REQUEST_PATH).
+ * This ONE class replaces the old split of `Header` (interface) + `PlatformHeader`
+ * (class) + `ContextKey` (class). Every context value — whether it rides over HTTP
+ * (request-id, tenant, authorization) or stays in-process (method-meta, the
+ * TestCaseRecorder) — is a `ContextKey`.
  *
- * Customers can define their own ContextKey instances for app-specific values.
+ * The fields are named for what they DO (flipped from the old model):
+ * - `name`       ALWAYS set. The context storage key, the log/MDC key, and the
+ *                recorder name. e.g. 'requestId', 'tenantId', 'authorization'.
+ * - `httpHeader` OPTIONAL. When set, this key is transferred over the wire under
+ *                this HTTP header name (inbound request -> context, and context ->
+ *                outbound request). e.g. 'x-request-id'. When UNSET, the key is
+ *                context-only and never leaves the process (method-meta, recorder).
+ * - `isSecured`  When true, the value is masked (partially) in logs.
+ * - `isLogged`   Defaults to true. When false, the value is NEVER logged (used for
+ *                object-valued/internal keys like the recorder or method-meta that
+ *                must not be serialized into log lines).
  *
- * Usage:
- * ```typescript
- * const MY_KEY = new ContextKey('my-app-key');
- * RequestContext.putHeader(MY_KEY, someValue);
- * const value = RequestContext.getHeader(MY_KEY);
- * ```
+ * Per CLAUDE.md: data-only structures are classes, not interfaces.
  */
 class ContextKey {
-    keyName;
-    constructor(keyName) {
-        this.keyName = keyName;
+    /** Context storage key + log/MDC key + recorder name. Always set. */
+    name;
+    /**
+     * HTTP header name when this key is transferred over the wire (e.g.
+     * 'x-request-id'). Undefined = context-only, never transferred.
+     */
+    httpHeader;
+    /** Mask this value (partially) in logs. */
+    isSecured;
+    /** Whether this key is logged at all. Default true; false = never logged. */
+    isLogged;
+    constructor(name, httpHeader, isSecured = false, isLogged = true) {
+        this.name = name;
+        this.httpHeader = httpHeader;
+        this.isSecured = isSecured;
+        this.isLogged = isLogged;
     }
-    getHeaderName() {
-        return this.keyName;
+    /** True when this key is transferred over HTTP (has an httpHeader). */
+    isTransferred() {
+        return this.httpHeader !== undefined;
     }
 }
 exports.ContextKey = ContextKey;

package/src/ContextKey.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextKey.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextKey.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAa,UAAU;IACU;IAA7B,YAA6B,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEhD,aAAa;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ;AAND,gCAMC","sourcesContent":["import { Header } from './Header';\n\n/**\n * ContextKey - Typed key for non-HTTP context values stored in RequestContext.\n *\n * Similar to PlatformHeader but for context-only values that don't correspond\n * to HTTP headers (e.g., METHOD_META, REQUEST_PATH).\n *\n * Customers can define their own ContextKey instances for app-specific values.\n *\n * Usage:\n * ```typescript\n * const MY_KEY = new ContextKey('my-app-key');\n * RequestContext.putHeader(MY_KEY, someValue);\n * const value = RequestContext.getHeader(MY_KEY);\n * ```\n */\nexport class ContextKey implements Header {\n    constructor(private readonly keyName: string) {}\n\n    getHeaderName(): string {\n        return this.keyName;\n    }\n}\n"]}
+{"version":3,"file":"ContextKey.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/ContextKey.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,UAAU;IACnB,qEAAqE;IAC5D,IAAI,CAAS;IAEtB;;;OAGG;IACM,UAAU,CAAU;IAE7B,2CAA2C;IAClC,SAAS,CAAU;IAE5B,6EAA6E;IACpE,QAAQ,CAAU;IAE3B,YACI,IAAY,EACZ,UAAmB,EACnB,SAAS,GAAG,KAAK,EACjB,QAAQ,GAAG,IAAI;QAEf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC7B,CAAC;IAED,uEAAuE;IACvE,aAAa;QACT,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC;IACzC,CAAC;CACJ;AAhCD,gCAgCC","sourcesContent":["/**\n * ContextKey - a single key that travels in the request's \"magic context\"\n * (RequestContext on the server, MutableContextStore in the browser).\n *\n * This ONE class replaces the old split of `Header` (interface) + `PlatformHeader`\n * (class) + `ContextKey` (class). Every context value — whether it rides over HTTP\n * (request-id, tenant, authorization) or stays in-process (method-meta, the\n * TestCaseRecorder) — is a `ContextKey`.\n *\n * The fields are named for what they DO (flipped from the old model):\n * - `name`       ALWAYS set. The context storage key, the log/MDC key, and the\n *                recorder name. e.g. 'requestId', 'tenantId', 'authorization'.\n * - `httpHeader` OPTIONAL. When set, this key is transferred over the wire under\n *                this HTTP header name (inbound request -> context, and context ->\n *                outbound request). e.g. 'x-request-id'. When UNSET, the key is\n *                context-only and never leaves the process (method-meta, recorder).\n * - `isSecured`  When true, the value is masked (partially) in logs.\n * - `isLogged`   Defaults to true. When false, the value is NEVER logged (used for\n *                object-valued/internal keys like the recorder or method-meta that\n *                must not be serialized into log lines).\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\nexport class ContextKey {\n    /** Context storage key + log/MDC key + recorder name. Always set. */\n    readonly name: string;\n\n    /**\n     * HTTP header name when this key is transferred over the wire (e.g.\n     * 'x-request-id'). Undefined = context-only, never transferred.\n     */\n    readonly httpHeader?: string;\n\n    /** Mask this value (partially) in logs. */\n    readonly isSecured: boolean;\n\n    /** Whether this key is logged at all. Default true; false = never logged. */\n    readonly isLogged: boolean;\n\n    constructor(\n        name: string,\n        httpHeader?: string,\n        isSecured = false,\n        isLogged = true,\n    ) {\n        this.name = name;\n        this.httpHeader = httpHeader;\n        this.isSecured = isSecured;\n        this.isLogged = isLogged;\n    }\n\n    /** True when this key is transferred over HTTP (has an httpHeader). */\n    isTransferred(): boolean {\n        return this.httpHeader !== undefined;\n    }\n}\n"]}

package/src/http/ContextMgr.d.ts

@@ -1,31 +1,24 @@
 import { ContextReader } from './ContextReader';
 import { HeaderMethods } from './HeaderMethods';
-import { HeaderRegistry } from './HeaderRegistry';
 /**
- * ContextMgr - Manages context reader + header registry for HTTP clients.
+ * ContextMgr - propagates the magic context onto outbound HTTP requests.
  *
- * Passed to createApiClient() via ClientConfig.contextMgr to enable automatic
- * header propagation: every header in the registry with isWantTransferred=true
- * is read from the ContextReader and added to outbound requests.
+ * Passed to createApiClient() via ClientConfig.contextMgr: every transferred key
+ * (httpHeader set) in the GLOBAL {@link HeaderRegistry} is read from the ContextReader
+ * and added to outbound requests. The registry is a process global (configured once at
+ * startup, like LogManager), so ContextMgr no longer takes a registry argument.
  *
- * Browser-safe (no AsyncLocalStorage): the server-side reader
- * (RequestContextReader, in @webpieces/core-context) and the browser store
- * (MutableContextStore, in @webpieces/http-client) both implement ContextReader,
- * so ContextMgr itself lives here in browser+node core-util.
- *
- * BREAKING (migration from the PlatformHeader[] constructor):
- *   new ContextMgr(reader, headerArray)
- * becomes
- *   new ContextMgr(reader, new HeaderRegistry([new PlatformHeadersExtension(headerArray)]))
+ * Browser-safe (no AsyncLocalStorage): the server-side reader (RequestContextReader,
+ * in @webpieces/core-context) and the browser store (MutableContextStore, in
+ * @webpieces/http-client) both implement ContextReader.
  *
  * Example usage:
  * ```typescript
  * // Node.js server-side (reads the magic context from RequestContext):
- * const contextMgr = new ContextMgr(new RequestContextReader(), registry);
+ * const contextMgr = new ContextMgr(new RequestContextReader());
  *
  * // Browser client-side (app-managed store, no AsyncLocalStorage):
- * const store = new MutableContextStore();
- * const contextMgr = new ContextMgr(store, registry);
+ * const contextMgr = new ContextMgr(new MutableContextStore());
  *
  * // Both cases:
  * const config = new ClientConfig('http://api.example.com', contextMgr);
@@ -34,15 +27,10 @@ import { HeaderRegistry } from './HeaderRegistry';
  */
 export declare class ContextMgr {
     /**
-     * The context reader that provides header values.
+     * The context reader that provides context-key values.
      * Different implementations for Node.js vs browser.
      */
     readonly contextReader: ContextReader;
-    /**
-     * The single source of truth for which headers exist and how they behave
-     * (transferred/secured/MDC). Shared with the server-side filters.
-     */
-    readonly registry: HeaderRegistry;
     /**
      * When true (default), outbound calls send the current x-request-id as
      * x-previous-request-id (and drop x-request-id) so each hop in a
@@ -52,15 +40,10 @@ export declare class ContextMgr {
     private chainProcessor;
     constructor(
     /**
-     * The context reader that provides header values.
+     * The context reader that provides context-key values.
      * Different implementations for Node.js vs browser.
      */
     contextReader: ContextReader, 
-    /**
-     * The single source of truth for which headers exist and how they behave
-     * (transferred/secured/MDC). Shared with the server-side filters.
-     */
-    registry: HeaderRegistry, 
     /**
      * When true (default), outbound calls send the current x-request-id as
      * x-previous-request-id (and drop x-request-id) so each hop in a
@@ -68,16 +51,16 @@ export declare class ContextMgr {
      */
     chainRequestIds?: boolean);
     /**
-     * Build the headers to send on an outbound request: every transferred
-     * header (isWantTransferred=true) with a non-empty value in the context,
-     * then request-id chaining applied (unless opted out).
+     * Build the headers to send on an outbound request: every transferred key
+     * (httpHeader set) with a non-empty value in the context, emitted under its
+     * `httpHeader` wire name, then request-id chaining applied (unless opted out).
      *
      * Values are RAW (unmasked) - this map goes on the wire, not in logs.
      */
     buildOutboundHeaders(): Map<string, string>;
     /**
-     * Build the header map for LOGGING: secured header values are masked,
-     * and headers are keyed by loggerMdcKey when defined.
+     * Build the header map for LOGGING: secured values masked, keyed by each key's
+     * `name`, only for keys with isLogged=true.
      */
     buildHeadersForLogging(headerMethods: HeaderMethods): Map<string, string>;
 }

package/src/http/ContextMgr.js

@@ -1,32 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextMgr = void 0;
+const HeaderRegistry_1 = require("./HeaderRegistry");
 const RequestIdChainProcessor_1 = require("./RequestIdChainProcessor");
 /**
- * ContextMgr - Manages context reader + header registry for HTTP clients.
+ * ContextMgr - propagates the magic context onto outbound HTTP requests.
  *
- * Passed to createApiClient() via ClientConfig.contextMgr to enable automatic
- * header propagation: every header in the registry with isWantTransferred=true
- * is read from the ContextReader and added to outbound requests.
+ * Passed to createApiClient() via ClientConfig.contextMgr: every transferred key
+ * (httpHeader set) in the GLOBAL {@link HeaderRegistry} is read from the ContextReader
+ * and added to outbound requests. The registry is a process global (configured once at
+ * startup, like LogManager), so ContextMgr no longer takes a registry argument.
  *
- * Browser-safe (no AsyncLocalStorage): the server-side reader
- * (RequestContextReader, in @webpieces/core-context) and the browser store
- * (MutableContextStore, in @webpieces/http-client) both implement ContextReader,
- * so ContextMgr itself lives here in browser+node core-util.
- *
- * BREAKING (migration from the PlatformHeader[] constructor):
- *   new ContextMgr(reader, headerArray)
- * becomes
- *   new ContextMgr(reader, new HeaderRegistry([new PlatformHeadersExtension(headerArray)]))
+ * Browser-safe (no AsyncLocalStorage): the server-side reader (RequestContextReader,
+ * in @webpieces/core-context) and the browser store (MutableContextStore, in
+ * @webpieces/http-client) both implement ContextReader.
  *
  * Example usage:
  * ```typescript
  * // Node.js server-side (reads the magic context from RequestContext):
- * const contextMgr = new ContextMgr(new RequestContextReader(), registry);
+ * const contextMgr = new ContextMgr(new RequestContextReader());
  *
  * // Browser client-side (app-managed store, no AsyncLocalStorage):
- * const store = new MutableContextStore();
- * const contextMgr = new ContextMgr(store, registry);
+ * const contextMgr = new ContextMgr(new MutableContextStore());
  *
  * // Both cases:
  * const config = new ClientConfig('http://api.example.com', contextMgr);
@@ -35,20 +30,14 @@ const RequestIdChainProcessor_1 = require("./RequestIdChainProcessor");
  */
 class ContextMgr {
     contextReader;
-    registry;
     chainRequestIds;
     chainProcessor;
     constructor(
     /**
-     * The context reader that provides header values.
+     * The context reader that provides context-key values.
      * Different implementations for Node.js vs browser.
      */
     contextReader, 
-    /**
-     * The single source of truth for which headers exist and how they behave
-     * (transferred/secured/MDC). Shared with the server-side filters.
-     */
-    registry, 
     /**
      * When true (default), outbound calls send the current x-request-id as
      * x-previous-request-id (and drop x-request-id) so each hop in a
@@ -56,23 +45,22 @@ class ContextMgr {
      */
     chainRequestIds = true) {
         this.contextReader = contextReader;
-        this.registry = registry;
         this.chainRequestIds = chainRequestIds;
         this.chainProcessor = new RequestIdChainProcessor_1.RequestIdChainProcessor();
     }
     /**
-     * Build the headers to send on an outbound request: every transferred
-     * header (isWantTransferred=true) with a non-empty value in the context,
-     * then request-id chaining applied (unless opted out).
+     * Build the headers to send on an outbound request: every transferred key
+     * (httpHeader set) with a non-empty value in the context, emitted under its
+     * `httpHeader` wire name, then request-id chaining applied (unless opted out).
      *
      * Values are RAW (unmasked) - this map goes on the wire, not in logs.
      */
     buildOutboundHeaders() {
         const outbound = new Map();
-        for (const header of this.registry.getTransferredHeaders()) {
-            const value = this.contextReader.read(header);
+        for (const key of HeaderRegistry_1.HeaderRegistry.get().getTransferredKeys()) {
+            const value = this.contextReader.read(key);
             if (value !== undefined && value !== null && value !== '') {
-                outbound.set(header.headerName, value);
+                outbound.set(key.httpHeader, value);
             }
         }
         if (this.chainRequestIds) {
@@ -81,11 +69,11 @@ class ContextMgr {
         return outbound;
     }
     /**
-     * Build the header map for LOGGING: secured header values are masked,
-     * and headers are keyed by loggerMdcKey when defined.
+     * Build the header map for LOGGING: secured values masked, keyed by each key's
+     * `name`, only for keys with isLogged=true.
      */
     buildHeadersForLogging(headerMethods) {
-        return headerMethods.buildSecureMapForLogs(this.registry.getHeaders(), this.contextReader);
+        return headerMethods.buildSecureMapForLogs(HeaderRegistry_1.HeaderRegistry.get().getLoggedKeys(), this.contextReader);
     }
 }
 exports.ContextMgr = ContextMgr;

package/src/http/ContextMgr.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextMgr.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextMgr.ts"],"names":[],"mappings":";;;AAGA,uEAAoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,UAAU;IAQC;IAMA;IAOA;IApBZ,cAAc,CAA0B;IAEhD;IACI;;;OAGG;IACa,aAA4B;IAE5C;;;OAGG;IACa,QAAwB;IAExC;;;;OAIG;IACa,kBAA2B,IAAI;QAb/B,kBAAa,GAAb,aAAa,CAAe;QAM5B,aAAQ,GAAR,QAAQ,CAAgB;QAOxB,oBAAe,GAAf,eAAe,CAAgB;QAE/C,IAAI,CAAC,cAAc,GAAG,IAAI,iDAAuB,EAAE,CAAC;IACxD,CAAC;IAED;;;;;;OAMG;IACH,oBAAoB;QAChB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE3C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,qBAAqB,EAAE,EAAE,CAAC;YACzD,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBACxD,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YAC3C,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,sBAAsB,CAAC,aAA4B;QAC/C,OAAO,aAAa,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IAC/F,CAAC;CACJ;AAzDD,gCAyDC","sourcesContent":["import { ContextReader } from './ContextReader';\nimport { HeaderMethods } from './HeaderMethods';\nimport { HeaderRegistry } from './HeaderRegistry';\nimport { RequestIdChainProcessor } from './RequestIdChainProcessor';\n\n/**\n * ContextMgr - Manages context reader + header registry for HTTP clients.\n *\n * Passed to createApiClient() via ClientConfig.contextMgr to enable automatic\n * header propagation: every header in the registry with isWantTransferred=true\n * is read from the ContextReader and added to outbound requests.\n *\n * Browser-safe (no AsyncLocalStorage): the server-side reader\n * (RequestContextReader, in @webpieces/core-context) and the browser store\n * (MutableContextStore, in @webpieces/http-client) both implement ContextReader,\n * so ContextMgr itself lives here in browser+node core-util.\n *\n * BREAKING (migration from the PlatformHeader[] constructor):\n *   new ContextMgr(reader, headerArray)\n * becomes\n *   new ContextMgr(reader, new HeaderRegistry([new PlatformHeadersExtension(headerArray)]))\n *\n * Example usage:\n * ```typescript\n * // Node.js server-side (reads the magic context from RequestContext):\n * const contextMgr = new ContextMgr(new RequestContextReader(), registry);\n *\n * // Browser client-side (app-managed store, no AsyncLocalStorage):\n * const store = new MutableContextStore();\n * const contextMgr = new ContextMgr(store, registry);\n *\n * // Both cases:\n * const config = new ClientConfig('http://api.example.com', contextMgr);\n * const client = createApiClient(SaveApi, config);\n * ```\n */\nexport class ContextMgr {\n    private chainProcessor: RequestIdChainProcessor;\n\n    constructor(\n        /**\n         * The context reader that provides header values.\n         * Different implementations for Node.js vs browser.\n         */\n        public readonly contextReader: ContextReader,\n\n        /**\n         * The single source of truth for which headers exist and how they behave\n         * (transferred/secured/MDC). Shared with the server-side filters.\n         */\n        public readonly registry: HeaderRegistry,\n\n        /**\n         * When true (default), outbound calls send the current x-request-id as\n         * x-previous-request-id (and drop x-request-id) so each hop in a\n         * distributed trace gets its own id chained to its caller's.\n         */\n        public readonly chainRequestIds: boolean = true,\n    ) {\n        this.chainProcessor = new RequestIdChainProcessor();\n    }\n\n    /**\n     * Build the headers to send on an outbound request: every transferred\n     * header (isWantTransferred=true) with a non-empty value in the context,\n     * then request-id chaining applied (unless opted out).\n     *\n     * Values are RAW (unmasked) - this map goes on the wire, not in logs.\n     */\n    buildOutboundHeaders(): Map<string, string> {\n        const outbound = new Map<string, string>();\n\n        for (const header of this.registry.getTransferredHeaders()) {\n            const value = this.contextReader.read(header);\n            if (value !== undefined && value !== null && value !== '') {\n                outbound.set(header.headerName, value);\n            }\n        }\n\n        if (this.chainRequestIds) {\n            this.chainProcessor.process(outbound);\n        }\n\n        return outbound;\n    }\n\n    /**\n     * Build the header map for LOGGING: secured header values are masked,\n     * and headers are keyed by loggerMdcKey when defined.\n     */\n    buildHeadersForLogging(headerMethods: HeaderMethods): Map<string, string> {\n        return headerMethods.buildSecureMapForLogs(this.registry.getHeaders(), this.contextReader);\n    }\n}\n"]}
+{"version":3,"file":"ContextMgr.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextMgr.ts"],"names":[],"mappings":";;;AAEA,qDAAkD;AAClD,uEAAoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAa,UAAU;IAQC;IAOA;IAdZ,cAAc,CAA0B;IAEhD;IACI;;;OAGG;IACa,aAA4B;IAE5C;;;;OAIG;IACa,kBAA2B,IAAI;QAP/B,kBAAa,GAAb,aAAa,CAAe;QAO5B,oBAAe,GAAf,eAAe,CAAgB;QAE/C,IAAI,CAAC,cAAc,GAAG,IAAI,iDAAuB,EAAE,CAAC;IACxD,CAAC;IAED;;;;;;OAMG;IACH,oBAAoB;QAChB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;QAE3C,KAAK,MAAM,GAAG,IAAI,+BAAc,CAAC,GAAG,EAAE,CAAC,kBAAkB,EAAE,EAAE,CAAC;YAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBACxD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,UAAW,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACvB,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,sBAAsB,CAAC,aAA4B;QAC/C,OAAO,aAAa,CAAC,qBAAqB,CAAC,+BAAc,CAAC,GAAG,EAAE,CAAC,aAAa,EAAE,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IACzG,CAAC;CACJ;AAnDD,gCAmDC","sourcesContent":["import { ContextReader } from './ContextReader';\nimport { HeaderMethods } from './HeaderMethods';\nimport { HeaderRegistry } from './HeaderRegistry';\nimport { RequestIdChainProcessor } from './RequestIdChainProcessor';\n\n/**\n * ContextMgr - propagates the magic context onto outbound HTTP requests.\n *\n * Passed to createApiClient() via ClientConfig.contextMgr: every transferred key\n * (httpHeader set) in the GLOBAL {@link HeaderRegistry} is read from the ContextReader\n * and added to outbound requests. The registry is a process global (configured once at\n * startup, like LogManager), so ContextMgr no longer takes a registry argument.\n *\n * Browser-safe (no AsyncLocalStorage): the server-side reader (RequestContextReader,\n * in @webpieces/core-context) and the browser store (MutableContextStore, in\n * @webpieces/http-client) both implement ContextReader.\n *\n * Example usage:\n * ```typescript\n * // Node.js server-side (reads the magic context from RequestContext):\n * const contextMgr = new ContextMgr(new RequestContextReader());\n *\n * // Browser client-side (app-managed store, no AsyncLocalStorage):\n * const contextMgr = new ContextMgr(new MutableContextStore());\n *\n * // Both cases:\n * const config = new ClientConfig('http://api.example.com', contextMgr);\n * const client = createApiClient(SaveApi, config);\n * ```\n */\nexport class ContextMgr {\n    private chainProcessor: RequestIdChainProcessor;\n\n    constructor(\n        /**\n         * The context reader that provides context-key values.\n         * Different implementations for Node.js vs browser.\n         */\n        public readonly contextReader: ContextReader,\n\n        /**\n         * When true (default), outbound calls send the current x-request-id as\n         * x-previous-request-id (and drop x-request-id) so each hop in a\n         * distributed trace gets its own id chained to its caller's.\n         */\n        public readonly chainRequestIds: boolean = true,\n    ) {\n        this.chainProcessor = new RequestIdChainProcessor();\n    }\n\n    /**\n     * Build the headers to send on an outbound request: every transferred key\n     * (httpHeader set) with a non-empty value in the context, emitted under its\n     * `httpHeader` wire name, then request-id chaining applied (unless opted out).\n     *\n     * Values are RAW (unmasked) - this map goes on the wire, not in logs.\n     */\n    buildOutboundHeaders(): Map<string, string> {\n        const outbound = new Map<string, string>();\n\n        for (const key of HeaderRegistry.get().getTransferredKeys()) {\n            const value = this.contextReader.read(key);\n            if (value !== undefined && value !== null && value !== '') {\n                outbound.set(key.httpHeader!, value);\n            }\n        }\n\n        if (this.chainRequestIds) {\n            this.chainProcessor.process(outbound);\n        }\n\n        return outbound;\n    }\n\n    /**\n     * Build the header map for LOGGING: secured values masked, keyed by each key's\n     * `name`, only for keys with isLogged=true.\n     */\n    buildHeadersForLogging(headerMethods: HeaderMethods): Map<string, string> {\n        return headerMethods.buildSecureMapForLogs(HeaderRegistry.get().getLoggedKeys(), this.contextReader);\n    }\n}\n"]}

package/src/http/ContextReader.d.ts

@@ -1,37 +1,28 @@
 import { ContextKey } from '../ContextKey';
-import { PlatformHeader } from './PlatformHeader';
 /**
- * ContextReader - Interface for reading header values from context.
+ * ContextReader - reads context-key values from the ambient magic context.
  *
- * Different implementations for different environments:
- * - RequestContextReader: Node.js with AsyncLocalStorage (in @webpieces/http-routing, server-side only)
- * - MutableContextStore / StaticContextReader: Browser or testing with manual header
- *   management (in @webpieces/http-client)
- * - CompositeContextReader: Combines multiple readers with priority (in @webpieces/http-client)
+ * There are exactly TWO implementations, one per environment:
+ * - Node/server: `RequestContextReader` (in @webpieces/core-context) — reads the
+ *   AsyncLocalStorage-backed RequestContext.
+ * - Browser: `MutableContextStore` (in @webpieces/http-client) — a mutable in-memory
+ *   store the app sets as values become known (login token, tenant, ...).
  *
- * This interface is defined in @webpieces/http-api so both http-routing and http-client
- * can use it without creating circular dependencies. It is DI-independent so it works in
- * both server (Inversify) and client (Angular/React, browser) environments.
+ * Defined in core-util (browser + Node safe, DI-independent) so both sides can use it
+ * without a circular dependency.
  *
  * This is a business-logic interface (per CLAUDE.md: behavior = interface).
  */
 export interface ContextReader {
     /**
-     * Read the value of a platform header.
-     * Returns undefined if header not available.
-     *
-     * @param header - The platform header to read
-     * @returns The header value, or undefined if not present
+     * Read the string value of a context key. Returns undefined if not present.
      */
-    read(header: PlatformHeader): string | undefined;
+    read(key: ContextKey): string | undefined;
     /**
-     * OPTIONAL: read a non-header context value (e.g. the active
-     * TestCaseRecorder under RecorderKeys.RECORDER).
-     *
-     * Server-side readers (RequestContextReader) implement this over the
-     * RequestContext; browser readers may omit it (no server-side recording
-     * in browsers - same as Java). This keeps http-client free of any
-     * Node-only imports while still letting it find the recorder.
+     * OPTIONAL: read a non-string context value (e.g. the active TestCaseRecorder
+     * under RecorderKeys.RECORDER). Server-side readers implement this over the
+     * RequestContext; browser readers may omit it (no server-side recording in
+     * browsers — same as Java).
      */
     readValue?(key: ContextKey): unknown;
 }

package/src/http/ContextReader.js.map

@@ -1 +1 @@
-{"version":3,"file":"ContextReader.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextReader.ts"],"names":[],"mappings":"","sourcesContent":["import { ContextKey } from '../ContextKey';\nimport { PlatformHeader } from './PlatformHeader';\n\n/**\n * ContextReader - Interface for reading header values from context.\n *\n * Different implementations for different environments:\n * - RequestContextReader: Node.js with AsyncLocalStorage (in @webpieces/http-routing, server-side only)\n * - MutableContextStore / StaticContextReader: Browser or testing with manual header\n *   management (in @webpieces/http-client)\n * - CompositeContextReader: Combines multiple readers with priority (in @webpieces/http-client)\n *\n * This interface is defined in @webpieces/http-api so both http-routing and http-client\n * can use it without creating circular dependencies. It is DI-independent so it works in\n * both server (Inversify) and client (Angular/React, browser) environments.\n *\n * This is a business-logic interface (per CLAUDE.md: behavior = interface).\n */\nexport interface ContextReader {\n    /**\n     * Read the value of a platform header.\n     * Returns undefined if header not available.\n     *\n     * @param header - The platform header to read\n     * @returns The header value, or undefined if not present\n     */\n    read(header: PlatformHeader): string | undefined;\n\n    /**\n     * OPTIONAL: read a non-header context value (e.g. the active\n     * TestCaseRecorder under RecorderKeys.RECORDER).\n     *\n     * Server-side readers (RequestContextReader) implement this over the\n     * RequestContext; browser readers may omit it (no server-side recording\n     * in browsers - same as Java). This keeps http-client free of any\n     * Node-only imports while still letting it find the recorder.\n     */\n    // webpieces-disable no-any-unknown -- context values are heterogeneous (recorder, meta objects)\n    readValue?(key: ContextKey): unknown;\n}\n"]}
+{"version":3,"file":"ContextReader.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ContextReader.ts"],"names":[],"mappings":"","sourcesContent":["import { ContextKey } from '../ContextKey';\n\n/**\n * ContextReader - reads context-key values from the ambient magic context.\n *\n * There are exactly TWO implementations, one per environment:\n * - Node/server: `RequestContextReader` (in @webpieces/core-context) — reads the\n *   AsyncLocalStorage-backed RequestContext.\n * - Browser: `MutableContextStore` (in @webpieces/http-client) — a mutable in-memory\n *   store the app sets as values become known (login token, tenant, ...).\n *\n * Defined in core-util (browser + Node safe, DI-independent) so both sides can use it\n * without a circular dependency.\n *\n * This is a business-logic interface (per CLAUDE.md: behavior = interface).\n */\nexport interface ContextReader {\n    /**\n     * Read the string value of a context key. Returns undefined if not present.\n     */\n    read(key: ContextKey): string | undefined;\n\n    /**\n     * OPTIONAL: read a non-string context value (e.g. the active TestCaseRecorder\n     * under RecorderKeys.RECORDER). Server-side readers implement this over the\n     * RequestContext; browser readers may omit it (no server-side recording in\n     * browsers — same as Java).\n     */\n    // webpieces-disable no-any-unknown -- context values are heterogeneous (recorder, meta objects)\n    readValue?(key: ContextKey): unknown;\n}\n"]}

package/src/http/HeaderMethods.d.ts

@@ -1,71 +1,27 @@
-import { PlatformHeader } from './PlatformHeader';
+import { ContextKey } from '../ContextKey';
 import { ContextReader } from './ContextReader';
 /**
- * HeaderMethods - Utility class for working with platform headers.
+ * HeaderMethods - stateless utility for turning context keys + a ContextReader into
+ * the maps the framework needs (outbound transfer, masked log map).
  *
- * This class can be injected in both server (Node.js) and client (Angular/browser) environments.
- * It provides common operations for filtering and processing headers.
- *
- * Pattern: Stateless utility class (pure functions, can be instantiated or injected)
- * - Server: Can inject empty instance, use static-like methods
- * - Client: new HeaderMethods() (no DI needed)
- *
- * Usage:
- * ```typescript
- * // Server-side (ContextFilter)
- * constructor(@inject() headerMethods: HeaderMethods) {
- *     const allHeaders = [... flatten from extensions ...];
- *     this.transferHeaders = headerMethods.findTransferHeaders(allHeaders);
- * }
- *
- * // Client-side (ClientFactory)
- * const headerMethods = new HeaderMethods();
- * const loggableHeaders = headerMethods.findLoggableHeaders(allHeaders, requestHeaders);
- * ```
+ * Works in both server (Node) and browser environments; a plain `new HeaderMethods()`
+ * (no DI). The set of keys is supplied by the caller (from HeaderRegistry).
  */
 export declare class HeaderMethods {
+    /** Keys that transfer over the wire (httpHeader set). */
+    findTransferKeys(keys: ContextKey[]): ContextKey[];
+    /** Keys whose values are masked in logs (isSecured=true). */
+    securedKeys(keys: ContextKey[]): ContextKey[];
     /**
-     * Filter headers to only those that should be transferred (isWantTransferred=true).
-     *
-     * @param headers - Array of PlatformHeader definitions
-     * @returns Filtered array of headers with isWantTransferred=true
-     */
-    findTransferHeaders(headers: PlatformHeader[]): PlatformHeader[];
-    /**
-     * Split headers into secure and public categories.
-     *
-     * @param headers - Array of PlatformHeader definitions
-     * @returns SplitHeaders with secureHeaders (isSecured=true) and publicHeaders (isSecured=false)
-     */
-    secureHeaders(headers: PlatformHeader[]): PlatformHeader[];
-    /**
-     * Get all headers that should be logged.
-     * All headers are loggable - secure headers will be masked by formatHeadersForLogging.
-     *
-     * @param headers - Array of PlatformHeader definitions
-     * @returns All headers (they're all loggable, just some are masked)
-     */
-    findLoggableHeaders(headers: PlatformHeader[]): PlatformHeader[];
-    buildSecureMapForLogs(platformHeaders: PlatformHeader[], contextReader: ContextReader): Map<string, any>;
-    /**
-     * Format headers for logging with secure masking.
-     * Takes filtered PlatformHeaders and actual header values from request.
-     *
-     * Masking rules for secure headers (isSecured=true):
-     * - Length > 15: Show first 3 and last 3 characters with "..." between
-     * - Length 8-15: Show first 2 characters with "..."
-     * - Length < 8: Show "<secure key too short to log>"
-     *
-     * @param loggableHeaders - Filtered PlatformHeaders to log
-     * @param headerMap - Map of header name (lowercase) -> array of values from request
-     * @returns Record of header name -> masked or full value for logging
+     * Build the map for LOGGING from the given keys: each logged key (isLogged=true)
+     * with a value present is added under its `name`, masked when isSecured.
      */
-    formatHeadersForLogging(loggableHeaders: PlatformHeader[], headerMap: Map<string, string[]>): Record<string, string>;
+    buildSecureMapForLogs(keys: ContextKey[], contextReader: ContextReader): Map<string, string>;
     /**
-     * Mask a secure header value based on its length.
-     *
-     * @param value - The secure header value to mask
-     * @returns Masked value
+     * Mask a secure value based on its length.
+     * - Length > 15: first 3 + "..." + last 3
+     * - Length 8-15: first 2 + "..."
+     * - Length < 8: "<secure key too short to log>"
      */
     private maskSecureValue;
 }