@webpieces/core-util 0.3.263 → 0.3.265

package/src/http/LogApiCall.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogApiCall = void 0;
+const errors_1 = require("./errors");
+const errorUtils_1 = require("../lib/errorUtils");
+const LogManager_1 = require("../logging/LogManager");
+const log = LogManager_1.LogManager.getLogger('LogApiCall');
+/**
+ * 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)
+ */
+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
+     */
+    async execute(type, meta, requestDto, headers, method) {
+        // Log request - convert Map to Object for JSON serialization
+        const headersObj = Object.fromEntries(headers);
+        log.info(`[API-${type}-req] ${meta.controllerClassName}.${meta.methodName} ${meta.path} request=${JSON.stringify(requestDto)} headers=${JSON.stringify(headersObj)}`);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller
+        try {
+            if (!requestDto)
+                throw new Error(`Request cannot be null and was from ${meta.controllerClassName}.${meta.methodName}`);
+            const response = await method(requestDto);
+            if (!response)
+                throw new Error(`Response cannot be null and was from ${meta.controllerClassName}.${meta.methodName}`);
+            // Log success response
+            log.info(`[API-${type}-resp-SUCCESS] ${meta.controllerClassName}.${meta.methodName} response=${JSON.stringify(response)}`);
+            return response;
+        }
+        catch (err) {
+            const error = (0, errorUtils_1.toError)(err);
+            const errorType = error.constructor.name;
+            const errorMessage = error.message;
+            // Log error based on type and re-throw
+            if (LogApiCall.isUserError(error)) {
+                log.warn(`[API-${type}-resp-OTHER] ${meta.controllerClassName}.${meta.methodName} errorType=${errorType}`);
+            }
+            else {
+                log.error(`[API-${type}-resp-FAIL] ${meta.controllerClassName}.${meta.methodName} errorType=${errorType} error=${errorMessage}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * 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) {
+        return (error instanceof errors_1.HttpBadRequestError ||
+            error instanceof errors_1.HttpUnauthorizedError ||
+            error instanceof errors_1.HttpForbiddenError ||
+            error instanceof errors_1.HttpNotFoundError ||
+            error instanceof errors_1.HttpUserError);
+    }
+}
+exports.LogApiCall = LogApiCall;
+//# sourceMappingURL=LogApiCall.js.map

package/src/http/LogApiCall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":";;;AACA,qCAMkB;AAClB,kDAA0C;AAC1C,sDAAiD;AAEjD,MAAM,GAAG,GAAG,uBAAU,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;AAG/C;;;;;;;;;;;GAWG;AACH,MAAa,UAAU;IAEnB;;;;;;;;;OASG;IACI,KAAK,CAAC,OAAO,CAChB,IAAY,EACZ,IAAmB,EACnB,UAAe,EACf,OAAyB,EACzB,MAAkC;QAElC,6DAA6D;QAC7D,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC/C,GAAG,CAAC,IAAI,CACJ,QAAQ,IAAI,SAAS,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAC9J,CAAC;QAEF,qHAAqH;QACrH,IAAI,CAAC;YACD,IAAG,CAAC,UAAU;gBACV,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAE1G,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;YAE1C,IAAG,CAAC,QAAQ;gBACR,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAE3G,uBAAuB;YACvB,GAAG,CAAC,IAAI,CACJ,QAAQ,IAAI,kBAAkB,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,UAAU,aAAa,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CACnH,CAAC;YAEF,OAAO,QAAQ,CAAC;QACpB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC;YACzC,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC;YAEnC,uCAAuC;YACvC,IAAI,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,GAAG,CAAC,IAAI,CACJ,QAAQ,IAAI,gBAAgB,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,UAAU,cAAc,SAAS,EAAE,CACnG,CAAC;YACN,CAAC;iBAAM,CAAC;gBACJ,GAAG,CAAC,KAAK,CACL,QAAQ,IAAI,eAAe,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,UAAU,cAAc,SAAS,UAAU,YAAY,EAAE,CACxH,CAAC;YACN,CAAC;YACD,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,WAAW,CAAC,KAAc;QAC7B,OAAO,CACH,KAAK,YAAY,4BAAmB;YACpC,KAAK,YAAY,8BAAqB;YACtC,KAAK,YAAY,2BAAkB;YACnC,KAAK,YAAY,0BAAiB;YAClC,KAAK,YAAY,sBAAa,CACjC,CAAC;IACN,CAAC;CACJ;AAnFD,gCAmFC","sourcesContent":["import {RouteMetadata} from \"./decorators\";\nimport {\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpNotFoundError,\n    HttpUserError,\n} from './errors';\nimport {toError} from \"../lib/errorUtils\";\nimport {LogManager} from \"../logging/LogManager\";\n\nconst log = LogManager.getLogger('LogApiCall');\n\n\n/**\n * LogApiCall - Generic API call logging utility.\n *\n * Used by both server-side (LogApiFilter) and client-side (ClientFactory) for\n * consistent logging patterns across the framework.\n *\n * Logging format patterns:\n * - [API-{type}-req] ClassName.methodName request={...} headers={...}\n * - [API-{type}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{type}-resp-OTHER] ClassName.methodName errorType={...}  (user errors)\n * - [API-{type}-resp-FAIL] ClassName.methodName error={...}  (server errors)\n */\nexport class LogApiCall {\n\n    /**\n     * Execute an API call with logging around it.\n     *\n     * @param type - 'SVR' or 'CLIENT'\n     * @param meta - Route metadata with controllerClassName and methodName\n     * @param requestDto - The request DTO\n     * @param headers - Map of header name -> values\n     * @param splitHeaders - SplitHeaders with secureHeaders and publicHeaders for masking\n     * @param method - The method to execute\n     */\n    public async execute(\n        type: string,\n        meta: RouteMetadata,\n        requestDto: any,\n        headers: Map<string, any>,\n        method: (dto: any) => Promise<any>\n    ): Promise<any> {\n        // Log request - convert Map to Object for JSON serialization\n        const headersObj = Object.fromEntries(headers);\n        log.info(\n            `[API-${type}-req] ${meta.controllerClassName}.${meta.methodName} ${meta.path} request=${JSON.stringify(requestDto)} headers=${JSON.stringify(headersObj)}`\n        );\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            if(!requestDto)\n                throw new Error(`Request cannot be null and was from ${meta.controllerClassName}.${meta.methodName}`);\n            \n            const response = await method(requestDto);\n\n            if(!response)\n                throw new Error(`Response cannot be null and was from ${meta.controllerClassName}.${meta.methodName}`);\n\n            // Log success response\n            log.info(\n                `[API-${type}-resp-SUCCESS] ${meta.controllerClassName}.${meta.methodName} response=${JSON.stringify(response)}`\n            );\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            const errorType = error.constructor.name;\n            const errorMessage = error.message;\n\n            // Log error based on type and re-throw\n            if (LogApiCall.isUserError(error)) {\n                log.warn(\n                    `[API-${type}-resp-OTHER] ${meta.controllerClassName}.${meta.methodName} errorType=${errorType}`\n                );\n            } else {\n                log.error(\n                    `[API-${type}-resp-FAIL] ${meta.controllerClassName}.${meta.methodName} errorType=${errorType} error=${errorMessage}`\n                );\n            }\n            throw error;\n        }\n    }\n\n    /**\n     * Check if an error is a user error (expected behavior from server perspective).\n     * User errors are NOT failures - just users making mistakes or validation issues.\n     *\n     * User errors (logged as OTHER, no stack trace):\n     * - HttpBadRequestError (400)\n     * - HttpUnauthorizedError (401)\n     * - HttpForbiddenError (403)\n     * - HttpNotFoundError (404)\n     * - HttpUserError (266)\n     *\n     * @param error - The error to check\n     * @returns true if this is a user error, false for server errors\n     */\n    static isUserError(error: unknown): boolean {\n        return (\n            error instanceof HttpBadRequestError ||\n            error instanceof HttpUnauthorizedError ||\n            error instanceof HttpForbiddenError ||\n            error instanceof HttpNotFoundError ||\n            error instanceof HttpUserError\n        );\n    }\n}\n"]}

package/src/http/PlatformHeader.d.ts

@@ -0,0 +1,51 @@
+import { Header } from '../Header';
+/**
+ * PlatformHeader - Defines an HTTP header that can be transferred between services.
+ *
+ * Port of Java PlatformHeaders, simplified:
+ * - No isWantLogged flag (deprecated in Java) - "wants MDC logging" is expressed
+ *   by setting loggerMdcKey. Headers without one still appear in API logs
+ *   (masked when isSecured); they just aren't exposed as an MDC dimension key.
+ *
+ * Implements Header interface from core-util to avoid circular dependencies.
+ *
+ * Per CLAUDE.md: "All data-only structures MUST be classes, not interfaces."
+ * This is a data-only class with no business logic methods.
+ */
+export declare class PlatformHeader implements Header {
+    /**
+     * The HTTP header name (e.g., 'x-request-id', 'x-tenant-id').
+     * Also used as the MDC logging key in RequestContext.
+     * Case-insensitive per HTTP spec, but stored in canonical form.
+     */
+    readonly headerName: string;
+    /**
+     * Whether this header should be transferred from HTTP request to RequestContext.
+     * If false, header is defined but not automatically transferred.
+     * Only headers with isWantTransferred=true are copied from incoming requests.
+     */
+    readonly isWantTransferred: boolean;
+    /**
+     * Whether this header contains sensitive data that should be secured/masked in logs.
+     * Examples: Authorization tokens, passwords, API keys.
+     */
+    readonly isSecured: boolean;
+    /**
+     * Whether this header should be used as a dimension for metrics/monitoring.
+     * Examples: x-tenant-id, x-request-id (for distributed tracing).
+     */
+    readonly isDimensionForMetrics: boolean;
+    /**
+     * Key used when exposing this header to the logger's MDC / structured log
+     * dimensions. Port of Java getLoggerMDCKey(). When set, log maps key this
+     * header by it instead of headerName (e.g. 'requestId' vs 'x-request-id').
+     * Undefined = not an MDC dimension (Java: getLoggerMDCKey() == null).
+     */
+    readonly loggerMdcKey?: string;
+    constructor(headerName: string, isWantTransferred?: boolean, isSecured?: boolean, isDimensionForMetrics?: boolean, loggerMdcKey?: string);
+    /**
+     * Get the header name (implements Header interface).
+     * @returns The HTTP header name
+     */
+    getHeaderName(): string;
+}

package/src/http/PlatformHeader.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformHeader = void 0;
+/**
+ * PlatformHeader - Defines an HTTP header that can be transferred between services.
+ *
+ * Port of Java PlatformHeaders, simplified:
+ * - No isWantLogged flag (deprecated in Java) - "wants MDC logging" is expressed
+ *   by setting loggerMdcKey. Headers without one still appear in API logs
+ *   (masked when isSecured); they just aren't exposed as an MDC dimension key.
+ *
+ * Implements Header interface from core-util to avoid circular dependencies.
+ *
+ * Per CLAUDE.md: "All data-only structures MUST be classes, not interfaces."
+ * This is a data-only class with no business logic methods.
+ */
+class PlatformHeader {
+    /**
+     * The HTTP header name (e.g., 'x-request-id', 'x-tenant-id').
+     * Also used as the MDC logging key in RequestContext.
+     * Case-insensitive per HTTP spec, but stored in canonical form.
+     */
+    headerName;
+    /**
+     * Whether this header should be transferred from HTTP request to RequestContext.
+     * If false, header is defined but not automatically transferred.
+     * Only headers with isWantTransferred=true are copied from incoming requests.
+     */
+    isWantTransferred;
+    /**
+     * Whether this header contains sensitive data that should be secured/masked in logs.
+     * Examples: Authorization tokens, passwords, API keys.
+     */
+    isSecured;
+    /**
+     * Whether this header should be used as a dimension for metrics/monitoring.
+     * Examples: x-tenant-id, x-request-id (for distributed tracing).
+     */
+    isDimensionForMetrics;
+    /**
+     * Key used when exposing this header to the logger's MDC / structured log
+     * dimensions. Port of Java getLoggerMDCKey(). When set, log maps key this
+     * header by it instead of headerName (e.g. 'requestId' vs 'x-request-id').
+     * Undefined = not an MDC dimension (Java: getLoggerMDCKey() == null).
+     */
+    loggerMdcKey;
+    constructor(headerName, isWantTransferred = true, isSecured = false, isDimensionForMetrics = false, loggerMdcKey) {
+        this.headerName = headerName;
+        this.isWantTransferred = isWantTransferred;
+        this.isSecured = isSecured;
+        this.isDimensionForMetrics = isDimensionForMetrics;
+        this.loggerMdcKey = loggerMdcKey;
+    }
+    /**
+     * Get the header name (implements Header interface).
+     * @returns The HTTP header name
+     */
+    getHeaderName() {
+        return this.headerName;
+    }
+}
+exports.PlatformHeader = PlatformHeader;
+//# sourceMappingURL=PlatformHeader.js.map

package/src/http/PlatformHeader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformHeader.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/PlatformHeader.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACH,MAAa,cAAc;IACvB;;;;OAIG;IACM,UAAU,CAAS;IAE5B;;;;OAIG;IACM,iBAAiB,CAAU;IAEpC;;;OAGG;IACM,SAAS,CAAU;IAE5B;;;OAGG;IACM,qBAAqB,CAAU;IAExC;;;;;OAKG;IACM,YAAY,CAAU;IAE/B,YACI,UAAkB,EAClB,oBAA6B,IAAI,EACjC,YAAqB,KAAK,EAC1B,wBAAiC,KAAK,EACtC,YAAqB;QAErB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,qBAAqB,GAAG,qBAAqB,CAAC;QACnD,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,aAAa;QACT,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;CACJ;AAxDD,wCAwDC","sourcesContent":["import { Header } from '../Header';\n\n/**\n * PlatformHeader - Defines an HTTP header that can be transferred between services.\n *\n * Port of Java PlatformHeaders, simplified:\n * - No isWantLogged flag (deprecated in Java) - \"wants MDC logging\" is expressed\n *   by setting loggerMdcKey. Headers without one still appear in API logs\n *   (masked when isSecured); they just aren't exposed as an MDC dimension key.\n *\n * Implements Header interface from core-util to avoid circular dependencies.\n *\n * Per CLAUDE.md: \"All data-only structures MUST be classes, not interfaces.\"\n * This is a data-only class with no business logic methods.\n */\nexport class PlatformHeader implements Header {\n    /**\n     * The HTTP header name (e.g., 'x-request-id', 'x-tenant-id').\n     * Also used as the MDC logging key in RequestContext.\n     * Case-insensitive per HTTP spec, but stored in canonical form.\n     */\n    readonly headerName: string;\n\n    /**\n     * Whether this header should be transferred from HTTP request to RequestContext.\n     * If false, header is defined but not automatically transferred.\n     * Only headers with isWantTransferred=true are copied from incoming requests.\n     */\n    readonly isWantTransferred: boolean;\n\n    /**\n     * Whether this header contains sensitive data that should be secured/masked in logs.\n     * Examples: Authorization tokens, passwords, API keys.\n     */\n    readonly isSecured: boolean;\n\n    /**\n     * Whether this header should be used as a dimension for metrics/monitoring.\n     * Examples: x-tenant-id, x-request-id (for distributed tracing).\n     */\n    readonly isDimensionForMetrics: boolean;\n\n    /**\n     * Key used when exposing this header to the logger's MDC / structured log\n     * dimensions. Port of Java getLoggerMDCKey(). When set, log maps key this\n     * header by it instead of headerName (e.g. 'requestId' vs 'x-request-id').\n     * Undefined = not an MDC dimension (Java: getLoggerMDCKey() == null).\n     */\n    readonly loggerMdcKey?: string;\n\n    constructor(\n        headerName: string,\n        isWantTransferred: boolean = true,\n        isSecured: boolean = false,\n        isDimensionForMetrics: boolean = false,\n        loggerMdcKey?: string\n    ) {\n        this.headerName = headerName;\n        this.isWantTransferred = isWantTransferred;\n        this.isSecured = isSecured;\n        this.isDimensionForMetrics = isDimensionForMetrics;\n        this.loggerMdcKey = loggerMdcKey;\n    }\n\n    /**\n     * Get the header name (implements Header interface).\n     * @returns The HTTP header name\n     */\n    getHeaderName(): string {\n        return this.headerName;\n    }\n}\n"]}

package/src/http/PlatformHeadersExtension.d.ts

@@ -0,0 +1,51 @@
+import { PlatformHeader } from './PlatformHeader';
+/**
+ * PlatformHeadersExtension - Extension that contributes platform headers to the framework.
+ *
+ * This is a DI-level extension (not an app-level Plugin).
+ * Multiple modules can bind PlatformHeadersExtension instances, and the framework
+ * collects them via Inversify @multiInject.
+ *
+ * Two-level plugin system:
+ * 1. **Extensions** (DI-level): Contribute specific capabilities to framework
+ *    - Examples: PlatformHeadersExtension, BodyContentExtension, EntityLookupExtension
+ *    - Pattern: Bound via multiInject, consumed by framework
+ *    - Java equivalent: Multibinder<AddPlatformHeaders>, Multibinder<BodyContentBinder>
+ *
+ * 2. **Plugins** (App-level): Provide complete features with modules + routes
+ *    - Examples: HibernatePlugin, JacksonPlugin, Auth0Plugin
+ *    - Pattern: Implements getGuiceModules() + getRouteModules()
+ *    - Java equivalent: Plugin interface with getGuiceModules() + getRouteModules()
+ *
+ * Usage:
+ * ```typescript
+ * // In WebpiecesModule
+ * const coreExtension = new PlatformHeadersExtension([
+ *     WebpiecesCoreHeaders.REQUEST_ID,
+ *     WebpiecesCoreHeaders.CORRELATION_ID,
+ * ]);
+ * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(coreExtension);
+ *
+ * // In CompanyModule
+ * const companyExtension = new PlatformHeadersExtension([
+ *     CompanyHeaders.TENANT_ID,
+ *     CompanyHeaders.API_VERSION,
+ * ]);
+ * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(companyExtension);
+ *
+ * // Framework collects all extensions
+ * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}
+ * ```
+ */
+export declare class PlatformHeadersExtension {
+    /**
+     * The set of platform headers contributed by this extension.
+     */
+    readonly headers: PlatformHeader[];
+    constructor(headers: PlatformHeader[]);
+    /**
+     * Get all headers from this extension.
+     * @returns Array of platform headers
+     */
+    getHeaders(): PlatformHeader[];
+}

package/src/http/PlatformHeadersExtension.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformHeadersExtension = void 0;
+/**
+ * PlatformHeadersExtension - Extension that contributes platform headers to the framework.
+ *
+ * This is a DI-level extension (not an app-level Plugin).
+ * Multiple modules can bind PlatformHeadersExtension instances, and the framework
+ * collects them via Inversify @multiInject.
+ *
+ * Two-level plugin system:
+ * 1. **Extensions** (DI-level): Contribute specific capabilities to framework
+ *    - Examples: PlatformHeadersExtension, BodyContentExtension, EntityLookupExtension
+ *    - Pattern: Bound via multiInject, consumed by framework
+ *    - Java equivalent: Multibinder<AddPlatformHeaders>, Multibinder<BodyContentBinder>
+ *
+ * 2. **Plugins** (App-level): Provide complete features with modules + routes
+ *    - Examples: HibernatePlugin, JacksonPlugin, Auth0Plugin
+ *    - Pattern: Implements getGuiceModules() + getRouteModules()
+ *    - Java equivalent: Plugin interface with getGuiceModules() + getRouteModules()
+ *
+ * Usage:
+ * ```typescript
+ * // In WebpiecesModule
+ * const coreExtension = new PlatformHeadersExtension([
+ *     WebpiecesCoreHeaders.REQUEST_ID,
+ *     WebpiecesCoreHeaders.CORRELATION_ID,
+ * ]);
+ * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(coreExtension);
+ *
+ * // In CompanyModule
+ * const companyExtension = new PlatformHeadersExtension([
+ *     CompanyHeaders.TENANT_ID,
+ *     CompanyHeaders.API_VERSION,
+ * ]);
+ * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(companyExtension);
+ *
+ * // Framework collects all extensions
+ * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}
+ * ```
+ */
+class PlatformHeadersExtension {
+    /**
+     * The set of platform headers contributed by this extension.
+     */
+    headers;
+    constructor(headers) {
+        this.headers = headers;
+    }
+    /**
+     * Get all headers from this extension.
+     * @returns Array of platform headers
+     */
+    getHeaders() {
+        return this.headers;
+    }
+}
+exports.PlatformHeadersExtension = PlatformHeadersExtension;
+//# sourceMappingURL=PlatformHeadersExtension.js.map

package/src/http/PlatformHeadersExtension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlatformHeadersExtension.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/PlatformHeadersExtension.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAa,wBAAwB;IACjC;;OAEG;IACM,OAAO,CAAmB;IAEnC,YAAY,OAAyB;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,UAAU;QACN,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ;AAjBD,4DAiBC","sourcesContent":["import { PlatformHeader } from './PlatformHeader';\n\n/**\n * PlatformHeadersExtension - Extension that contributes platform headers to the framework.\n *\n * This is a DI-level extension (not an app-level Plugin).\n * Multiple modules can bind PlatformHeadersExtension instances, and the framework\n * collects them via Inversify @multiInject.\n *\n * Two-level plugin system:\n * 1. **Extensions** (DI-level): Contribute specific capabilities to framework\n *    - Examples: PlatformHeadersExtension, BodyContentExtension, EntityLookupExtension\n *    - Pattern: Bound via multiInject, consumed by framework\n *    - Java equivalent: Multibinder<AddPlatformHeaders>, Multibinder<BodyContentBinder>\n *\n * 2. **Plugins** (App-level): Provide complete features with modules + routes\n *    - Examples: HibernatePlugin, JacksonPlugin, Auth0Plugin\n *    - Pattern: Implements getGuiceModules() + getRouteModules()\n *    - Java equivalent: Plugin interface with getGuiceModules() + getRouteModules()\n *\n * Usage:\n * ```typescript\n * // In WebpiecesModule\n * const coreExtension = new PlatformHeadersExtension([\n *     WebpiecesCoreHeaders.REQUEST_ID,\n *     WebpiecesCoreHeaders.CORRELATION_ID,\n * ]);\n * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(coreExtension);\n *\n * // In CompanyModule\n * const companyExtension = new PlatformHeadersExtension([\n *     CompanyHeaders.TENANT_ID,\n *     CompanyHeaders.API_VERSION,\n * ]);\n * bind(HEADER_TYPES.PlatformHeadersExtension).toConstantValue(companyExtension);\n *\n * // Framework collects all extensions\n * constructor(@multiInject(HEADER_TYPES.PlatformHeadersExtension) extensions: PlatformHeadersExtension[]) {}\n * ```\n */\nexport class PlatformHeadersExtension {\n    /**\n     * The set of platform headers contributed by this extension.\n     */\n    readonly headers: PlatformHeader[];\n\n    constructor(headers: PlatformHeader[]) {\n        this.headers = headers;\n    }\n\n    /**\n     * Get all headers from this extension.\n     * @returns Array of platform headers\n     */\n    getHeaders(): PlatformHeader[] {\n        return this.headers;\n    }\n}\n"]}

package/src/http/WebpiecesCoreHeaders.d.ts

@@ -0,0 +1,62 @@
+import { PlatformHeader } from './PlatformHeader';
+/**
+ * Core framework headers for distributed tracing and request correlation.
+ *
+ * These are the minimal headers needed by the WebPieces framework for:
+ * - Request tracking across services
+ * - Distributed tracing (REQUEST_ID -> PREVIOUS_REQUEST_ID chaining per hop)
+ * - Request correlation
+ * - Metrics and monitoring
+ *
+ * Pattern inspired by Java MicroSvcHeader enum. Lives in http-api (browser-safe)
+ * so BOTH the http-client (request-id chaining) and http-server can reference it.
+ */
+export declare class WebpiecesCoreHeaders {
+    /**
+     * Unique ID for this request.
+     * Generated by the server if not provided.
+     * Used for distributed tracing and log correlation.
+     */
+    static readonly REQUEST_ID: PlatformHeader;
+    /**
+     * ID of the previous request in the call chain.
+     * When service A calls service B, B receives A's REQUEST_ID as PREVIOUS_REQUEST_ID.
+     * Used for building distributed trace trees.
+     */
+    static readonly PREVIOUS_REQUEST_ID: PlatformHeader;
+    /**
+     * Correlation ID that spans multiple related requests.
+     * Typically set by the API gateway or first service in the chain.
+     * All services in the call chain use the same CORRELATION_ID.
+     */
+    static readonly CORRELATION_ID: PlatformHeader;
+    /**
+     * Turns on test-case recording for this request (Java: x-webpieces-recording).
+     * When present, the server records the endpoint + every downstream call it
+     * makes into a fixture that can be replayed as a test.
+     * Transferred so recording follows the request across service hops.
+     */
+    static readonly RECORDING: PlatformHeader;
+    /**
+     * The bearer credential for an authenticated request. Carries BOTH a user-facing
+     * JWT (@AuthJwt, validated by the app AuthFilter) and a service-to-service Google
+     * OIDC token (@AuthOidc, validated by the framework ServiceAuthFilter) — the two
+     * modes are mutually exclusive per endpoint, so one header serves both. When a
+     * Cloud Task is delivered, Google injects the OIDC token here as `Authorization`.
+     * SECURED — masked in logs.
+     */
+    static readonly AUTHORIZATION: PlatformHeader;
+    /**
+     * Shared-secret credential for internal callers that cannot mint OIDC tokens
+     * (@AuthSharedSecret, validated by ServiceAuthFilter via constant-time compare).
+     * SECURED — masked in logs.
+     */
+    static readonly SHARED_SECRET: PlatformHeader;
+    /**
+     * Get all core headers as an array.
+     * Used by WebpiecesModule to bind headers to DI container.
+     *
+     * @returns Array of all core platform headers
+     */
+    static getAllHeaders(): PlatformHeader[];
+}

package/src/http/WebpiecesCoreHeaders.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebpiecesCoreHeaders = void 0;
+const PlatformHeader_1 = require("./PlatformHeader");
+/**
+ * Core framework headers for distributed tracing and request correlation.
+ *
+ * These are the minimal headers needed by the WebPieces framework for:
+ * - Request tracking across services
+ * - Distributed tracing (REQUEST_ID -> PREVIOUS_REQUEST_ID chaining per hop)
+ * - Request correlation
+ * - Metrics and monitoring
+ *
+ * Pattern inspired by Java MicroSvcHeader enum. Lives in http-api (browser-safe)
+ * so BOTH the http-client (request-id chaining) and http-server can reference it.
+ */
+class WebpiecesCoreHeaders {
+    /**
+     * Unique ID for this request.
+     * Generated by the server if not provided.
+     * Used for distributed tracing and log correlation.
+     */
+    static REQUEST_ID = new PlatformHeader_1.PlatformHeader('x-request-id', true, // transfer (propagate to downstream services)
+    false, // not secured (it's just an ID)
+    true, // use for metrics dimensions
+    'requestId' // MDC key (Java MicroSvcHeader parity)
+    );
+    /**
+     * ID of the previous request in the call chain.
+     * When service A calls service B, B receives A's REQUEST_ID as PREVIOUS_REQUEST_ID.
+     * Used for building distributed trace trees.
+     */
+    static PREVIOUS_REQUEST_ID = new PlatformHeader_1.PlatformHeader('x-previous-request-id', true, false, false, 'previousId' // MDC key (Java MicroSvcHeader parity)
+    );
+    /**
+     * Correlation ID that spans multiple related requests.
+     * Typically set by the API gateway or first service in the chain.
+     * All services in the call chain use the same CORRELATION_ID.
+     */
+    static CORRELATION_ID = new PlatformHeader_1.PlatformHeader('x-correlation-id', true, false, true, // use for metrics dimensions
+    'correlationId' // MDC key
+    );
+    /**
+     * Turns on test-case recording for this request (Java: x-webpieces-recording).
+     * When present, the server records the endpoint + every downstream call it
+     * makes into a fixture that can be replayed as a test.
+     * Transferred so recording follows the request across service hops.
+     */
+    static RECORDING = new PlatformHeader_1.PlatformHeader('x-webpieces-recording', true, false, false);
+    /**
+     * The bearer credential for an authenticated request. Carries BOTH a user-facing
+     * JWT (@AuthJwt, validated by the app AuthFilter) and a service-to-service Google
+     * OIDC token (@AuthOidc, validated by the framework ServiceAuthFilter) — the two
+     * modes are mutually exclusive per endpoint, so one header serves both. When a
+     * Cloud Task is delivered, Google injects the OIDC token here as `Authorization`.
+     * SECURED — masked in logs.
+     */
+    static AUTHORIZATION = new PlatformHeader_1.PlatformHeader('authorization', true, // transfer into RequestContext
+    true, // SECURED - mask in logs
+    false);
+    /**
+     * Shared-secret credential for internal callers that cannot mint OIDC tokens
+     * (@AuthSharedSecret, validated by ServiceAuthFilter via constant-time compare).
+     * SECURED — masked in logs.
+     */
+    static SHARED_SECRET = new PlatformHeader_1.PlatformHeader('x-webpieces-shared-secret', true, // transfer into RequestContext
+    true, // SECURED - mask in logs
+    false);
+    /**
+     * Get all core headers as an array.
+     * Used by WebpiecesModule to bind headers to DI container.
+     *
+     * @returns Array of all core platform headers
+     */
+    static getAllHeaders() {
+        return [
+            WebpiecesCoreHeaders.REQUEST_ID,
+            WebpiecesCoreHeaders.PREVIOUS_REQUEST_ID,
+            WebpiecesCoreHeaders.CORRELATION_ID,
+            WebpiecesCoreHeaders.RECORDING,
+            WebpiecesCoreHeaders.AUTHORIZATION,
+            WebpiecesCoreHeaders.SHARED_SECRET,
+        ];
+    }
+}
+exports.WebpiecesCoreHeaders = WebpiecesCoreHeaders;
+//# sourceMappingURL=WebpiecesCoreHeaders.js.map

package/src/http/WebpiecesCoreHeaders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebpiecesCoreHeaders.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/WebpiecesCoreHeaders.ts"],"names":[],"mappings":";;;AAAA,qDAAkD;AAElD;;;;;;;;;;;GAWG;AACH,MAAa,oBAAoB;IAC7B;;;;OAIG;IACH,MAAM,CAAU,UAAU,GAAG,IAAI,+BAAc,CAC3C,cAAc,EACd,IAAI,EAAS,8CAA8C;IAC3D,KAAK,EAAQ,gCAAgC;IAC7C,IAAI,EAAS,6BAA6B;IAC1C,WAAW,CAAE,uCAAuC;KACvD,CAAC;IAEF;;;;OAIG;IACH,MAAM,CAAU,mBAAmB,GAAG,IAAI,+BAAc,CACpD,uBAAuB,EACvB,IAAI,EACJ,KAAK,EACL,KAAK,EACL,YAAY,CAAE,uCAAuC;KACxD,CAAC;IAEF;;;;OAIG;IACH,MAAM,CAAU,cAAc,GAAG,IAAI,+BAAc,CAC/C,kBAAkB,EAClB,IAAI,EACJ,KAAK,EACL,IAAI,EAAa,6BAA6B;IAC9C,eAAe,CAAE,UAAU;KAC9B,CAAC;IAEF;;;;;OAKG;IACH,MAAM,CAAU,SAAS,GAAG,IAAI,+BAAc,CAC1C,uBAAuB,EACvB,IAAI,EACJ,KAAK,EACL,KAAK,CACR,CAAC;IAEF;;;;;;;OAOG;IACH,MAAM,CAAU,aAAa,GAAG,IAAI,+BAAc,CAC9C,eAAe,EACf,IAAI,EAAI,+BAA+B;IACvC,IAAI,EAAI,yBAAyB;IACjC,KAAK,CACR,CAAC;IAEF;;;;OAIG;IACH,MAAM,CAAU,aAAa,GAAG,IAAI,+BAAc,CAC9C,2BAA2B,EAC3B,IAAI,EAAI,+BAA+B;IACvC,IAAI,EAAI,yBAAyB;IACjC,KAAK,CACR,CAAC;IAEF;;;;;OAKG;IACH,MAAM,CAAC,aAAa;QAChB,OAAO;YACH,oBAAoB,CAAC,UAAU;YAC/B,oBAAoB,CAAC,mBAAmB;YACxC,oBAAoB,CAAC,cAAc;YACnC,oBAAoB,CAAC,SAAS;YAC9B,oBAAoB,CAAC,aAAa;YAClC,oBAAoB,CAAC,aAAa;SACrC,CAAC;IACN,CAAC;;AA/FL,oDAgGC","sourcesContent":["import { PlatformHeader } from './PlatformHeader';\n\n/**\n * Core framework headers for distributed tracing and request correlation.\n *\n * These are the minimal headers needed by the WebPieces framework for:\n * - Request tracking across services\n * - Distributed tracing (REQUEST_ID -> PREVIOUS_REQUEST_ID chaining per hop)\n * - Request correlation\n * - Metrics and monitoring\n *\n * Pattern inspired by Java MicroSvcHeader enum. Lives in http-api (browser-safe)\n * so BOTH the http-client (request-id chaining) and http-server can reference it.\n */\nexport class WebpiecesCoreHeaders {\n    /**\n     * Unique ID for this request.\n     * Generated by the server if not provided.\n     * Used for distributed tracing and log correlation.\n     */\n    static readonly REQUEST_ID = new PlatformHeader(\n        'x-request-id',\n        true,        // transfer (propagate to downstream services)\n        false,       // not secured (it's just an ID)\n        true,        // use for metrics dimensions\n        'requestId'  // MDC key (Java MicroSvcHeader parity)\n    );\n\n    /**\n     * ID of the previous request in the call chain.\n     * When service A calls service B, B receives A's REQUEST_ID as PREVIOUS_REQUEST_ID.\n     * Used for building distributed trace trees.\n     */\n    static readonly PREVIOUS_REQUEST_ID = new PlatformHeader(\n        'x-previous-request-id',\n        true,\n        false,\n        false,\n        'previousId'  // MDC key (Java MicroSvcHeader parity)\n    );\n\n    /**\n     * Correlation ID that spans multiple related requests.\n     * Typically set by the API gateway or first service in the chain.\n     * All services in the call chain use the same CORRELATION_ID.\n     */\n    static readonly CORRELATION_ID = new PlatformHeader(\n        'x-correlation-id',\n        true,\n        false,\n        true,            // use for metrics dimensions\n        'correlationId'  // MDC key\n    );\n\n    /**\n     * Turns on test-case recording for this request (Java: x-webpieces-recording).\n     * When present, the server records the endpoint + every downstream call it\n     * makes into a fixture that can be replayed as a test.\n     * Transferred so recording follows the request across service hops.\n     */\n    static readonly RECORDING = new PlatformHeader(\n        'x-webpieces-recording',\n        true,\n        false,\n        false\n    );\n\n    /**\n     * The bearer credential for an authenticated request. Carries BOTH a user-facing\n     * JWT (@AuthJwt, validated by the app AuthFilter) and a service-to-service Google\n     * OIDC token (@AuthOidc, validated by the framework ServiceAuthFilter) — the two\n     * modes are mutually exclusive per endpoint, so one header serves both. When a\n     * Cloud Task is delivered, Google injects the OIDC token here as `Authorization`.\n     * SECURED — masked in logs.\n     */\n    static readonly AUTHORIZATION = new PlatformHeader(\n        'authorization',\n        true,   // transfer into RequestContext\n        true,   // SECURED - mask in logs\n        false\n    );\n\n    /**\n     * Shared-secret credential for internal callers that cannot mint OIDC tokens\n     * (@AuthSharedSecret, validated by ServiceAuthFilter via constant-time compare).\n     * SECURED — masked in logs.\n     */\n    static readonly SHARED_SECRET = new PlatformHeader(\n        'x-webpieces-shared-secret',\n        true,   // transfer into RequestContext\n        true,   // SECURED - mask in logs\n        false\n    );\n\n    /**\n     * Get all core headers as an array.\n     * Used by WebpiecesModule to bind headers to DI container.\n     *\n     * @returns Array of all core platform headers\n     */\n    static getAllHeaders(): PlatformHeader[] {\n        return [\n            WebpiecesCoreHeaders.REQUEST_ID,\n            WebpiecesCoreHeaders.PREVIOUS_REQUEST_ID,\n            WebpiecesCoreHeaders.CORRELATION_ID,\n            WebpiecesCoreHeaders.RECORDING,\n            WebpiecesCoreHeaders.AUTHORIZATION,\n            WebpiecesCoreHeaders.SHARED_SECRET,\n        ];\n    }\n}\n"]}