@webpieces/core-util 0.3.263 → 0.3.265

package/package.json

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

package/src/http/ContextReader.d.ts

@@ -0,0 +1,37 @@
+import { ContextKey } from '../ContextKey';
+import { PlatformHeader } from './PlatformHeader';
+/**
+ * ContextReader - Interface for reading header values from 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)
+ *
+ * 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.
+ *
+ * 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(header: PlatformHeader): 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.
+     */
+    readValue?(key: ContextKey): unknown;
+}

package/src/http/ContextReader.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ContextReader.js.map

package/src/http/ContextReader.js.map

@@ -0,0 +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"]}

package/src/http/HeaderMethods.d.ts

@@ -0,0 +1,71 @@
+import { PlatformHeader } from './PlatformHeader';
+import { ContextReader } from './ContextReader';
+/**
+ * HeaderMethods - Utility class for working with platform headers.
+ *
+ * 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);
+ * ```
+ */
+export declare class HeaderMethods {
+    /**
+     * 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
+     */
+    formatHeadersForLogging(loggableHeaders: PlatformHeader[], headerMap: Map<string, string[]>): Record<string, string>;
+    /**
+     * Mask a secure header value based on its length.
+     *
+     * @param value - The secure header value to mask
+     * @returns Masked value
+     */
+    private maskSecureValue;
+}

package/src/http/HeaderMethods.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeaderMethods = void 0;
+/**
+ * HeaderMethods - Utility class for working with platform headers.
+ *
+ * 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);
+ * ```
+ */
+class HeaderMethods {
+    /**
+     * 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) {
+        return headers.filter(h => h.isWantTransferred);
+    }
+    /**
+     * 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) {
+        return headers.filter(h => h.isSecured);
+    }
+    /**
+     * 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) {
+        return headers; // All headers are loggable, secure ones will be masked
+    }
+    buildSecureMapForLogs(platformHeaders, contextReader) {
+        const headers = new Map();
+        for (const header of platformHeaders) {
+            const value = contextReader.read(header);
+            if (value) {
+                // MDC-style key when defined (Java getLoggerMDCKey), else the raw header name
+                const logKey = header.loggerMdcKey ?? header.headerName;
+                if (!header.isSecured)
+                    headers.set(logKey, value);
+                else
+                    headers.set(logKey, this.maskSecureValue(value));
+            }
+        }
+        return headers;
+    }
+    /**
+     * 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
+     */
+    formatHeadersForLogging(loggableHeaders, headerMap) {
+        const result = {};
+        for (const platformHeader of loggableHeaders) {
+            // Look for header in the map (case-insensitive)
+            const values = headerMap.get(platformHeader.headerName.toLowerCase());
+            if (!values || values.length === 0) {
+                continue;
+            }
+            const value = values[0]; // Take first value
+            if (platformHeader.isSecured) {
+                result[platformHeader.headerName] = this.maskSecureValue(value);
+            }
+            else {
+                result[platformHeader.headerName] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Mask a secure header value based on its length.
+     *
+     * @param value - The secure header value to mask
+     * @returns Masked value
+     */
+    maskSecureValue(value) {
+        const len = value.length;
+        if (len < 8) {
+            return '<secure key too short to log>';
+        }
+        else if (len <= 15) {
+            // 8-15 characters: show first 2 + "..."
+            return `${value.substring(0, 2)}...`;
+        }
+        else {
+            // > 15 characters: show first 3 + "..." + last 3
+            return `${value.substring(0, 3)}...${value.substring(len - 3)}`;
+        }
+    }
+}
+exports.HeaderMethods = HeaderMethods;
+//# sourceMappingURL=HeaderMethods.js.map

package/src/http/HeaderMethods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeaderMethods.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HeaderMethods.ts"],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,aAAa;IACtB;;;;;OAKG;IACH,mBAAmB,CAAC,OAAyB;QACzC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,OAAyB;QACnC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;OAMG;IACH,mBAAmB,CAAC,OAAyB;QACzC,OAAO,OAAO,CAAC,CAAC,uDAAuD;IAC3E,CAAC;IAED,qBAAqB,CAAC,eAAiC,EAAE,aAA4B;QACjF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAe,CAAC;QAEvC,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzC,IAAG,KAAK,EAAE,CAAC;gBACP,8EAA8E;gBAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,UAAU,CAAC;gBACxD,IAAG,CAAC,MAAM,CAAC,SAAS;oBAChB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;;oBAE3B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;YACzD,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACnB,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,uBAAuB,CAAC,eAAiC,EAAE,SAAgC;QACvF,MAAM,MAAM,GAA2B,EAAE,CAAC;QAE1C,KAAK,MAAM,cAAc,IAAI,eAAe,EAAE,CAAC;YAC3C,gDAAgD;YAChD,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;YACtE,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACjC,SAAS;YACb,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB;YAE5C,IAAI,cAAc,CAAC,SAAS,EAAE,CAAC;gBAC3B,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;YACpE,CAAC;iBAAM,CAAC;gBACJ,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;YAC9C,CAAC;QACL,CAAC;QAED,OAAO,MAAM,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACK,eAAe,CAAC,KAAa;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;QAEzB,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACV,OAAO,+BAA+B,CAAC;QAC3C,CAAC;aAAM,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC;YACnB,wCAAwC;YACxC,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC;QACzC,CAAC;aAAM,CAAC;YACJ,iDAAiD;YACjD,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACpE,CAAC;IACL,CAAC;CACJ;AAxGD,sCAwGC","sourcesContent":["import { PlatformHeader } from './PlatformHeader';\n// Single source of truth for the ContextReader interface (was duplicated here)\nimport { ContextReader } from './ContextReader';\n\n/**\n * HeaderMethods - Utility class for working with platform headers.\n *\n * This class can be injected in both server (Node.js) and client (Angular/browser) environments.\n * It provides common operations for filtering and processing headers.\n *\n * Pattern: Stateless utility class (pure functions, can be instantiated or injected)\n * - Server: Can inject empty instance, use static-like methods\n * - Client: new HeaderMethods() (no DI needed)\n *\n * Usage:\n * ```typescript\n * // Server-side (ContextFilter)\n * constructor(@inject() headerMethods: HeaderMethods) {\n *     const allHeaders = [... flatten from extensions ...];\n *     this.transferHeaders = headerMethods.findTransferHeaders(allHeaders);\n * }\n *\n * // Client-side (ClientFactory)\n * const headerMethods = new HeaderMethods();\n * const loggableHeaders = headerMethods.findLoggableHeaders(allHeaders, requestHeaders);\n * ```\n */\nexport class HeaderMethods {\n    /**\n     * Filter headers to only those that should be transferred (isWantTransferred=true).\n     *\n     * @param headers - Array of PlatformHeader definitions\n     * @returns Filtered array of headers with isWantTransferred=true\n     */\n    findTransferHeaders(headers: PlatformHeader[]): PlatformHeader[] {\n        return headers.filter(h => h.isWantTransferred);\n    }\n\n    /**\n     * Split headers into secure and public categories.\n     *\n     * @param headers - Array of PlatformHeader definitions\n     * @returns SplitHeaders with secureHeaders (isSecured=true) and publicHeaders (isSecured=false)\n     */\n    secureHeaders(headers: PlatformHeader[]): PlatformHeader[] {\n        return headers.filter(h => h.isSecured);\n    }\n\n    /**\n     * Get all headers that should be logged.\n     * All headers are loggable - secure headers will be masked by formatHeadersForLogging.\n     *\n     * @param headers - Array of PlatformHeader definitions\n     * @returns All headers (they're all loggable, just some are masked)\n     */\n    findLoggableHeaders(headers: PlatformHeader[]): PlatformHeader[] {\n        return headers; // All headers are loggable, secure ones will be masked\n    }\n\n    buildSecureMapForLogs(platformHeaders: PlatformHeader[], contextReader: ContextReader): Map<string, any> {\n        const headers = new Map<string, any>();\n\n        for (const header of platformHeaders) {\n            const value = contextReader.read(header);\n            if(value) {\n                // MDC-style key when defined (Java getLoggerMDCKey), else the raw header name\n                const logKey = header.loggerMdcKey ?? header.headerName;\n                if(!header.isSecured)\n                    headers.set(logKey, value);\n                else\n                    headers.set(logKey, this.maskSecureValue(value));\n            }\n        }\n\n        return headers;\n    }\n\n    /**\n     * Format headers for logging with secure masking.\n     * Takes filtered PlatformHeaders and actual header values from request.\n     *\n     * Masking rules for secure headers (isSecured=true):\n     * - Length > 15: Show first 3 and last 3 characters with \"...\" between\n     * - Length 8-15: Show first 2 characters with \"...\"\n     * - Length < 8: Show \"<secure key too short to log>\"\n     *\n     * @param loggableHeaders - Filtered PlatformHeaders to log\n     * @param headerMap - Map of header name (lowercase) -> array of values from request\n     * @returns Record of header name -> masked or full value for logging\n     */\n    formatHeadersForLogging(loggableHeaders: PlatformHeader[], headerMap: Map<string, string[]>): Record<string, string> {\n        const result: Record<string, string> = {};\n\n        for (const platformHeader of loggableHeaders) {\n            // Look for header in the map (case-insensitive)\n            const values = headerMap.get(platformHeader.headerName.toLowerCase());\n            if (!values || values.length === 0) {\n                continue;\n            }\n\n            const value = values[0]; // Take first value\n\n            if (platformHeader.isSecured) {\n                result[platformHeader.headerName] = this.maskSecureValue(value);\n            } else {\n                result[platformHeader.headerName] = value;\n            }\n        }\n\n        return result;\n    }\n\n    /**\n     * Mask a secure header value based on its length.\n     *\n     * @param value - The secure header value to mask\n     * @returns Masked value\n     */\n    private maskSecureValue(value: string): string {\n        const len = value.length;\n\n        if (len < 8) {\n            return '<secure key too short to log>';\n        } else if (len <= 15) {\n            // 8-15 characters: show first 2 + \"...\"\n            return `${value.substring(0, 2)}...`;\n        } else {\n            // > 15 characters: show first 3 + \"...\" + last 3\n            return `${value.substring(0, 3)}...${value.substring(len - 3)}`;\n        }\n    }\n}\n\n\n"]}

package/src/http/HeaderRegistry.d.ts

@@ -0,0 +1,58 @@
+import { PlatformHeader } from './PlatformHeader';
+import { PlatformHeadersExtension } from './PlatformHeadersExtension';
+/**
+ * HeaderRegistry - The single source of truth for all PlatformHeaders known to
+ * the platform. Port of Java webpieces' HeaderTranslation.
+ *
+ * Every consumer (server filters, logging, metrics, outbound HTTP clients)
+ * reads the header set from this registry, so externally-defined headers are
+ * honored everywhere ("infinitely scalable magic context").
+ *
+ * Constructible in BOTH environments:
+ * - Server (Inversify): WebpiecesModule binds it via
+ *   `toDynamicValue(ctx => new HeaderRegistry(ctx.getAll(HEADER_TYPES.PlatformHeadersExtension)))`
+ *   so every module's PlatformHeadersExtension is collected automatically.
+ * - Browser (no DI): `new HeaderRegistry([new PlatformHeadersExtension([...])])`.
+ *
+ * Duplicate validation (port of Java checkForDuplicates) runs at construction,
+ * so conflicting definitions fail fast at startup:
+ * - Two headers with the same headerName must agree on ALL flags and loggerMdcKey.
+ * - Two headers with the same loggerMdcKey must agree on headerName (and therefore flags).
+ * - Exact duplicates (same name, same flags) collapse to one entry.
+ */
+export declare class HeaderRegistry {
+    private readonly headers;
+    constructor(extensions: PlatformHeadersExtension[]);
+    /**
+     * All registered headers (deduplicated).
+     */
+    getHeaders(): PlatformHeader[];
+    /**
+     * Headers that transfer over the wire (inbound request -> context, and
+     * context -> outbound request). isWantTransferred=true.
+     */
+    getTransferredHeaders(): PlatformHeader[];
+    /**
+     * Header names whose values must be masked in logs. isSecured=true.
+     */
+    getSecuredNames(): string[];
+    /**
+     * Headers exposed as MDC/structured-log dimensions (loggerMdcKey set).
+     */
+    getMdcHeaders(): PlatformHeader[];
+    /**
+     * Look up a header definition by its HTTP name (case-insensitive).
+     */
+    findByName(headerName: string): PlatformHeader | undefined;
+    /**
+     * Port of Java HeaderTranslation.checkForDuplicates: collapse exact
+     * duplicates, throw on conflicting definitions sharing a name or MDC key.
+     */
+    private checkForDuplicates;
+    /**
+     * Two headers sharing a headerName must agree on every flag and the MDC key,
+     * otherwise the platform would behave differently depending on which module's
+     * definition happened to load first.
+     */
+    private assertSameDefinition;
+}

package/src/http/HeaderRegistry.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeaderRegistry = void 0;
+/**
+ * HeaderRegistry - The single source of truth for all PlatformHeaders known to
+ * the platform. Port of Java webpieces' HeaderTranslation.
+ *
+ * Every consumer (server filters, logging, metrics, outbound HTTP clients)
+ * reads the header set from this registry, so externally-defined headers are
+ * honored everywhere ("infinitely scalable magic context").
+ *
+ * Constructible in BOTH environments:
+ * - Server (Inversify): WebpiecesModule binds it via
+ *   `toDynamicValue(ctx => new HeaderRegistry(ctx.getAll(HEADER_TYPES.PlatformHeadersExtension)))`
+ *   so every module's PlatformHeadersExtension is collected automatically.
+ * - Browser (no DI): `new HeaderRegistry([new PlatformHeadersExtension([...])])`.
+ *
+ * Duplicate validation (port of Java checkForDuplicates) runs at construction,
+ * so conflicting definitions fail fast at startup:
+ * - Two headers with the same headerName must agree on ALL flags and loggerMdcKey.
+ * - Two headers with the same loggerMdcKey must agree on headerName (and therefore flags).
+ * - Exact duplicates (same name, same flags) collapse to one entry.
+ */
+class HeaderRegistry {
+    headers;
+    constructor(extensions) {
+        const allHeaders = [];
+        for (const extension of extensions) {
+            allHeaders.push(...extension.getHeaders());
+        }
+        this.headers = this.checkForDuplicates(allHeaders);
+    }
+    /**
+     * All registered headers (deduplicated).
+     */
+    getHeaders() {
+        return this.headers;
+    }
+    /**
+     * Headers that transfer over the wire (inbound request -> context, and
+     * context -> outbound request). isWantTransferred=true.
+     */
+    getTransferredHeaders() {
+        return this.headers.filter((h) => h.isWantTransferred);
+    }
+    /**
+     * Header names whose values must be masked in logs. isSecured=true.
+     */
+    getSecuredNames() {
+        return this.headers
+            .filter((h) => h.isSecured)
+            .map((h) => h.headerName);
+    }
+    /**
+     * Headers exposed as MDC/structured-log dimensions (loggerMdcKey set).
+     */
+    getMdcHeaders() {
+        return this.headers.filter((h) => h.loggerMdcKey !== undefined);
+    }
+    /**
+     * Look up a header definition by its HTTP name (case-insensitive).
+     */
+    findByName(headerName) {
+        const lower = headerName.toLowerCase();
+        return this.headers.find((h) => h.headerName.toLowerCase() === lower);
+    }
+    /**
+     * Port of Java HeaderTranslation.checkForDuplicates: collapse exact
+     * duplicates, throw on conflicting definitions sharing a name or MDC key.
+     */
+    checkForDuplicates(allHeaders) {
+        const byName = new Map();
+        const byMdcKey = new Map();
+        for (const header of allHeaders) {
+            const nameKey = header.headerName.toLowerCase();
+            const existing = byName.get(nameKey);
+            if (existing) {
+                this.assertSameDefinition(existing, header);
+                continue; // exact duplicate - collapse
+            }
+            byName.set(nameKey, header);
+            if (header.loggerMdcKey !== undefined) {
+                const mdcClash = byMdcKey.get(header.loggerMdcKey);
+                if (mdcClash) {
+                    throw new Error(`Duplicate PlatformHeader loggerMdcKey '${header.loggerMdcKey}': ` +
+                        `defined by header '${mdcClash.headerName}' AND header '${header.headerName}'. ` +
+                        `Each MDC key must map to exactly one header.`);
+                }
+                byMdcKey.set(header.loggerMdcKey, header);
+            }
+        }
+        return Array.from(byName.values());
+    }
+    /**
+     * Two headers sharing a headerName must agree on every flag and the MDC key,
+     * otherwise the platform would behave differently depending on which module's
+     * definition happened to load first.
+     */
+    assertSameDefinition(existing, duplicate) {
+        const conflicts = [];
+        if (existing.isWantTransferred !== duplicate.isWantTransferred) {
+            conflicts.push(`isWantTransferred (${existing.isWantTransferred} vs ${duplicate.isWantTransferred})`);
+        }
+        if (existing.isSecured !== duplicate.isSecured) {
+            conflicts.push(`isSecured (${existing.isSecured} vs ${duplicate.isSecured})`);
+        }
+        if (existing.isDimensionForMetrics !== duplicate.isDimensionForMetrics) {
+            conflicts.push(`isDimensionForMetrics (${existing.isDimensionForMetrics} vs ${duplicate.isDimensionForMetrics})`);
+        }
+        if (existing.loggerMdcKey !== duplicate.loggerMdcKey) {
+            conflicts.push(`loggerMdcKey ('${existing.loggerMdcKey}' vs '${duplicate.loggerMdcKey}')`);
+        }
+        if (conflicts.length > 0) {
+            throw new Error(`Conflicting PlatformHeader definitions for '${existing.headerName}': ` +
+                `two modules registered it with different ${conflicts.join(', ')}. ` +
+                `Headers sharing a name must agree on all flags.`);
+        }
+    }
+}
+exports.HeaderRegistry = HeaderRegistry;
+//# sourceMappingURL=HeaderRegistry.js.map

package/src/http/HeaderRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeaderRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HeaderRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { PlatformHeader } from './PlatformHeader';\nimport { PlatformHeadersExtension } from './PlatformHeadersExtension';\n\n/**\n * HeaderRegistry - The single source of truth for all PlatformHeaders known to\n * the platform. Port of Java webpieces' HeaderTranslation.\n *\n * Every consumer (server filters, logging, metrics, outbound HTTP clients)\n * reads the header set from this registry, so externally-defined headers are\n * honored everywhere (\"infinitely scalable magic context\").\n *\n * Constructible in BOTH environments:\n * - Server (Inversify): WebpiecesModule binds it via\n *   `toDynamicValue(ctx => new HeaderRegistry(ctx.getAll(HEADER_TYPES.PlatformHeadersExtension)))`\n *   so every module's PlatformHeadersExtension is collected automatically.\n * - Browser (no DI): `new HeaderRegistry([new PlatformHeadersExtension([...])])`.\n *\n * Duplicate validation (port of Java checkForDuplicates) runs at construction,\n * so conflicting definitions fail fast at startup:\n * - Two headers with the same headerName must agree on ALL flags and loggerMdcKey.\n * - Two headers with the same loggerMdcKey must agree on headerName (and therefore flags).\n * - Exact duplicates (same name, same flags) collapse to one entry.\n */\nexport class HeaderRegistry {\n    private readonly headers: PlatformHeader[];\n\n    constructor(extensions: PlatformHeadersExtension[]) {\n        const allHeaders: PlatformHeader[] = [];\n        for (const extension of extensions) {\n            allHeaders.push(...extension.getHeaders());\n        }\n        this.headers = this.checkForDuplicates(allHeaders);\n    }\n\n    /**\n     * All registered headers (deduplicated).\n     */\n    getHeaders(): PlatformHeader[] {\n        return this.headers;\n    }\n\n    /**\n     * Headers that transfer over the wire (inbound request -> context, and\n     * context -> outbound request). isWantTransferred=true.\n     */\n    getTransferredHeaders(): PlatformHeader[] {\n        return this.headers.filter((h: PlatformHeader) => h.isWantTransferred);\n    }\n\n    /**\n     * Header names whose values must be masked in logs. isSecured=true.\n     */\n    getSecuredNames(): string[] {\n        return this.headers\n            .filter((h: PlatformHeader) => h.isSecured)\n            .map((h: PlatformHeader) => h.headerName);\n    }\n\n    /**\n     * Headers exposed as MDC/structured-log dimensions (loggerMdcKey set).\n     */\n    getMdcHeaders(): PlatformHeader[] {\n        return this.headers.filter((h: PlatformHeader) => h.loggerMdcKey !== undefined);\n    }\n\n    /**\n     * Look up a header definition by its HTTP name (case-insensitive).\n     */\n    findByName(headerName: string): PlatformHeader | undefined {\n        const lower = headerName.toLowerCase();\n        return this.headers.find((h: PlatformHeader) => h.headerName.toLowerCase() === lower);\n    }\n\n    /**\n     * Port of Java HeaderTranslation.checkForDuplicates: collapse exact\n     * duplicates, throw on conflicting definitions sharing a name or MDC key.\n     */\n    private checkForDuplicates(allHeaders: PlatformHeader[]): PlatformHeader[] {\n        const byName = new Map<string, PlatformHeader>();\n        const byMdcKey = new Map<string, PlatformHeader>();\n\n        for (const header of allHeaders) {\n            const nameKey = header.headerName.toLowerCase();\n            const existing = byName.get(nameKey);\n            if (existing) {\n                this.assertSameDefinition(existing, header);\n                continue; // exact duplicate - collapse\n            }\n            byName.set(nameKey, header);\n\n            if (header.loggerMdcKey !== undefined) {\n                const mdcClash = byMdcKey.get(header.loggerMdcKey);\n                if (mdcClash) {\n                    throw new Error(\n                        `Duplicate PlatformHeader loggerMdcKey '${header.loggerMdcKey}': ` +\n                        `defined by header '${mdcClash.headerName}' AND header '${header.headerName}'. ` +\n                        `Each MDC key must map to exactly one header.`,\n                    );\n                }\n                byMdcKey.set(header.loggerMdcKey, header);\n            }\n        }\n\n        return Array.from(byName.values());\n    }\n\n    /**\n     * Two headers sharing a headerName must agree on every flag and the MDC key,\n     * otherwise the platform would behave differently depending on which module's\n     * definition happened to load first.\n     */\n    private assertSameDefinition(existing: PlatformHeader, duplicate: PlatformHeader): void {\n        const conflicts: string[] = [];\n        if (existing.isWantTransferred !== duplicate.isWantTransferred) {\n            conflicts.push(`isWantTransferred (${existing.isWantTransferred} vs ${duplicate.isWantTransferred})`);\n        }\n        if (existing.isSecured !== duplicate.isSecured) {\n            conflicts.push(`isSecured (${existing.isSecured} vs ${duplicate.isSecured})`);\n        }\n        if (existing.isDimensionForMetrics !== duplicate.isDimensionForMetrics) {\n            conflicts.push(`isDimensionForMetrics (${existing.isDimensionForMetrics} vs ${duplicate.isDimensionForMetrics})`);\n        }\n        if (existing.loggerMdcKey !== duplicate.loggerMdcKey) {\n            conflicts.push(`loggerMdcKey ('${existing.loggerMdcKey}' vs '${duplicate.loggerMdcKey}')`);\n        }\n        if (conflicts.length > 0) {\n            throw new Error(\n                `Conflicting PlatformHeader definitions for '${existing.headerName}': ` +\n                `two modules registered it with different ${conflicts.join(', ')}. ` +\n                `Headers sharing a name must agree on all flags.`,\n            );\n        }\n    }\n}\n"]}

package/src/http/HeaderTypes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DI symbols for platform headers system.
+ *
+ * Uses Symbol.for() to create global symbols that work across module boundaries.
+ * This is important for Inversify multiInject pattern where multiple modules
+ * bind to the same symbol.
+ */
+export declare const HEADER_TYPES: {
+    /**
+     * Symbol for PlatformHeadersExtension instances.
+     * Multiple modules can bind PlatformHeadersExtension instances to this symbol,
+     * and consumers can use @multiInject to collect all of them.
+     *
+     * Pattern: Extension (DI-level) vs Plugin (App-level)
+     * - Extensions contribute specific capabilities to framework (headers, converters, etc.)
+     * - Plugins provide complete features with modules + routes (Hibernate, Jackson, etc.)
+     *
+     * Usage:
+     * ```typescript
+     * // In a module
+     * const extension = new PlatformHeadersExtension([header1, header2]);
+     * bind<PlatformHeadersExtension>(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(extension);
+     *
+     * // In a consumer
+     * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}
+     * ```
+     */
+    PlatformHeadersExtension: symbol;
+};

package/src/http/HeaderTypes.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEADER_TYPES = void 0;
+/**
+ * DI symbols for platform headers system.
+ *
+ * Uses Symbol.for() to create global symbols that work across module boundaries.
+ * This is important for Inversify multiInject pattern where multiple modules
+ * bind to the same symbol.
+ */
+exports.HEADER_TYPES = {
+    /**
+     * Symbol for PlatformHeadersExtension instances.
+     * Multiple modules can bind PlatformHeadersExtension instances to this symbol,
+     * and consumers can use @multiInject to collect all of them.
+     *
+     * Pattern: Extension (DI-level) vs Plugin (App-level)
+     * - Extensions contribute specific capabilities to framework (headers, converters, etc.)
+     * - Plugins provide complete features with modules + routes (Hibernate, Jackson, etc.)
+     *
+     * Usage:
+     * ```typescript
+     * // In a module
+     * const extension = new PlatformHeadersExtension([header1, header2]);
+     * bind<PlatformHeadersExtension>(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(extension);
+     *
+     * // In a consumer
+     * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}
+     * ```
+     */
+    PlatformHeadersExtension: Symbol.for('PlatformHeadersExtension'),
+};
+//# sourceMappingURL=HeaderTypes.js.map

package/src/http/HeaderTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeaderTypes.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HeaderTypes.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACU,QAAA,YAAY,GAAG;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,EAAE,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC;CACnE,CAAC","sourcesContent":["/**\n * DI symbols for platform headers system.\n *\n * Uses Symbol.for() to create global symbols that work across module boundaries.\n * This is important for Inversify multiInject pattern where multiple modules\n * bind to the same symbol.\n */\nexport const HEADER_TYPES = {\n    /**\n     * Symbol for PlatformHeadersExtension instances.\n     * Multiple modules can bind PlatformHeadersExtension instances to this symbol,\n     * and consumers can use @multiInject to collect all of them.\n     *\n     * Pattern: Extension (DI-level) vs Plugin (App-level)\n     * - Extensions contribute specific capabilities to framework (headers, converters, etc.)\n     * - Plugins provide complete features with modules + routes (Hibernate, Jackson, etc.)\n     *\n     * Usage:\n     * ```typescript\n     * // In a module\n     * const extension = new PlatformHeadersExtension([header1, header2]);\n     * bind<PlatformHeadersExtension>(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(extension);\n     *\n     * // In a consumer\n     * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}\n     * ```\n     */\n    PlatformHeadersExtension: Symbol.for('PlatformHeadersExtension'),\n};\n"]}

package/src/http/LogApiCall.d.ts

@@ -0,0 +1,41 @@
+import { RouteMetadata } from "./decorators";
+/**
+ * LogApiCall - Generic API call logging utility.
+ *
+ * Used by both server-side (LogApiFilter) and client-side (ClientFactory) for
+ * consistent logging patterns across the framework.
+ *
+ * Logging format patterns:
+ * - [API-{type}-req] ClassName.methodName request={...} headers={...}
+ * - [API-{type}-resp-SUCCESS] ClassName.methodName response={...}
+ * - [API-{type}-resp-OTHER] ClassName.methodName errorType={...}  (user errors)
+ * - [API-{type}-resp-FAIL] ClassName.methodName error={...}  (server errors)
+ */
+export declare class LogApiCall {
+    /**
+     * Execute an API call with logging around it.
+     *
+     * @param type - 'SVR' or 'CLIENT'
+     * @param meta - Route metadata with controllerClassName and methodName
+     * @param requestDto - The request DTO
+     * @param headers - Map of header name -> values
+     * @param splitHeaders - SplitHeaders with secureHeaders and publicHeaders for masking
+     * @param method - The method to execute
+     */
+    execute(type: string, meta: RouteMetadata, requestDto: any, headers: Map<string, any>, method: (dto: any) => Promise<any>): Promise<any>;
+    /**
+     * Check if an error is a user error (expected behavior from server perspective).
+     * User errors are NOT failures - just users making mistakes or validation issues.
+     *
+     * User errors (logged as OTHER, no stack trace):
+     * - HttpBadRequestError (400)
+     * - HttpUnauthorizedError (401)
+     * - HttpForbiddenError (403)
+     * - HttpNotFoundError (404)
+     * - HttpUserError (266)
+     *
+     * @param error - The error to check
+     * @returns true if this is a user error, false for server errors
+     */
+    static isUserError(error: unknown): boolean;
+}