@webpieces/core-util 0.3.380 → 0.3.382

package/package.json

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

package/src/http/ClientRegistry.d.ts

@@ -1,44 +1,113 @@
+import { ErrorTranslation, ErrorWireForm } from './ErrorTranslation';
+import { ProtocolError } from './errors';
 /**
- * ClientRegistry - the process-global `svcName -> base URL` table of per-environment URL overrides
- * used to route outbound client calls.
+ * Derives a base URL for a service name that has NO registered mapping — the pluggable half of
+ * {@link ClientRegistry} resolution. One per environment, installed once at startup:
  *
- * On GCP a client resolves a peer's base URL deterministically from `K_SERVICE` + project + region
- * (see gcp-identity `resolveServiceUrl`), so same-project/same-region services need NO registration.
- * Everything the derivation cannot describe — a localhost port, another region, another project, a
- * host that is not Cloud Run at all, or a browser that cannot read `K_SERVICE` — is registered here
- * instead. Each environment populates the registry (from its own per-env config) with the URLs it
- * needs; a registered mapping WINS over GCP derivation.
+ * - `gcpCloudRunDeriver()` (@webpieces/gcp-identity) — the Cloud Run formula, read from the metadata
+ *   server. For code running ON GCP.
+ * - `gcpCloudRunDeriver(new GcpCloudRunTarget(projectNumber, region))` — the SAME formula with the
+ *   values supplied from config, for code running OFF GCP that still calls Cloud Run (a CLI, CI).
+ * - {@link templateDeriver} (this package, browser-safe) — pure string substitution, for AWS or
+ *   anything else with predictable DNS.
+ * - none at all — a browser goes same-origin, and localhost/tests hand-register their mappings.
+ */
+export type ServiceUrlDeriver = (svcName: string) => Promise<string>;
+/**
+ * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every
+ * environment. A client is built once but a URL is per-environment, so the URL belongs here rather
+ * than on the client: clients carry ONLY a svcName.
+ *
+ * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:
  *
- * - **http-client-node / cloudtasks-client** resolve through gcp-identity `resolveServiceUrl`: it
- *   checks {@link ClientRegistry.tryLookup} first (override), then derives on GCP, then throws
- *   off-GCP if unregistered — a missing mapping is a setup bug, not a silent mis-route.
- * - **http-client-browser** cannot derive GCP URLs, so it resolves purely via
- *   {@link ClientRegistry.lookup}; the Angular app registers each svcName at startup.
+ *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region
+ *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.
+ *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or
+ *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,
+ *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on
+ *      their own.
+ *   3. else the caller's fallback: the BROWSER goes relative (same origin — see
+ *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),
+ *      because a server has no "own origin" and an unresolvable peer is a setup bug.
  *
  * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally
  * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is
  * why it lives in core-util rather than gcp-identity.
  *
  * ```ts
- * // startup, populated from the current environment's config:
+ * // startup, from the current environment's config:
  * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202
  * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');
+ * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP
  * ```
  */
 export declare class ClientRegistry {
     /** svcName -> resolved base URL. Process-global; populated at startup per environment. */
     private static readonly mappings;
+    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */
+    private static deriver;
+    /**
+     * App-supplied error translations, consulted BEFORE webpieces' built-in error mapping (both
+     * directions). Process-global, populated once at startup on the SERVER and in the BROWSER — the
+     * same no-DI pattern as {@link ClientRegistry.mappings} above. Consulted in registration order,
+     * first match wins, so a later-registered app type AND an override of a built-in status both
+     * work. See {@link ErrorTranslation}.
+     */
+    private static readonly errorTranslations;
     /** Map a service name to `http://localhost:<port>`. */
     static addMapping(svcName: string, port: number): void;
-    /** Map a service name to an explicit base URL (any host / any environment). */
+    /**
+     * Map a service name to an explicit base URL (any host / any environment).
+     *
+     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.
+     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.
+     */
     static addUrlMapping(svcName: string, url: string): void;
-    /** The registered override for `svcName`, or undefined if none. Non-throwing. */
+    /**
+     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO
+     * mapping. Optional: an environment that registers every svcName it calls needs none.
+     */
+    static setDeriver(fn: ServiceUrlDeriver): void;
+    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */
     static tryLookup(svcName: string): string | undefined;
     /**
-     * Resolve `svcName` to its registered base URL. THROWS with actionable guidance if the service
-     * was never registered — used where there is no GCP-derivation fallback (the browser).
+     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.
+     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.
      */
     static lookup(svcName: string): string;
-    /** Reset the registry. For tests, so the process-global map does not leak across specs. */
+    /**
+     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.
+     * Non-throwing — the BROWSER uses this and treats undefined as "" (relative → same origin),
+     * which is what a browser app calling the backend it was served from wants by default.
+     *
+     * Note the `!== undefined` guard: an empty-string mapping is a legal answer ("this service is
+     * same-origin"), so it must NOT fall through to derivation.
+     */
+    static tryResolve(svcName: string): Promise<string | undefined>;
+    /**
+     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no "own
+     * origin" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and
+     * say how to fix it.
+     */
+    static resolve(svcName: string): Promise<string>;
+    /**
+     * Register an app error translation. Consulted BEFORE webpieces' built-in mapping, in
+     * registration order (first match wins), so later app types AND overrides of built-ins both
+     * work. Call ONCE at startup — on the server AND in the browser — mirroring
+     * {@link ClientRegistry.addMapping}. See {@link ErrorTranslation}.
+     */
+    static addErrorTranslation(translation: ErrorTranslation): void;
+    /**
+     * exception → wire (SERVER side). The first registered translation that claims `error` wins;
+     * `undefined` if none does — the caller then falls through to the generic webpieces mapping.
+     */
+    static tryTranslateToWire(error: Error): ErrorWireForm | undefined;
+    /**
+     * wire → exception (CLIENT side). The first registered translation that claims
+     * `(statusCode, protocolError)` wins; `undefined` if none does — the caller then falls through
+     * to the generic webpieces switch.
+     */
+    static tryTranslateFromWire(statusCode: number, protocolError: ProtocolError): Error | undefined;
+    /** Reset mappings, the deriver, AND error translations. For tests, so the process-globals do not leak across specs. */
     static clear(): void;
 }

package/src/http/ClientRegistry.js

@@ -2,53 +2,77 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientRegistry = void 0;
 /**
- * ClientRegistry - the process-global `svcName -> base URL` table of per-environment URL overrides
- * used to route outbound client calls.
+ * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every
+ * environment. A client is built once but a URL is per-environment, so the URL belongs here rather
+ * than on the client: clients carry ONLY a svcName.
  *
- * On GCP a client resolves a peer's base URL deterministically from `K_SERVICE` + project + region
- * (see gcp-identity `resolveServiceUrl`), so same-project/same-region services need NO registration.
- * Everything the derivation cannot describe — a localhost port, another region, another project, a
- * host that is not Cloud Run at all, or a browser that cannot read `K_SERVICE` — is registered here
- * instead. Each environment populates the registry (from its own per-env config) with the URLs it
- * needs; a registered mapping WINS over GCP derivation.
+ * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:
  *
- * - **http-client-node / cloudtasks-client** resolve through gcp-identity `resolveServiceUrl`: it
- *   checks {@link ClientRegistry.tryLookup} first (override), then derives on GCP, then throws
- *   off-GCP if unregistered — a missing mapping is a setup bug, not a silent mis-route.
- * - **http-client-browser** cannot derive GCP URLs, so it resolves purely via
- *   {@link ClientRegistry.lookup}; the Angular app registers each svcName at startup.
+ *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region
+ *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.
+ *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or
+ *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,
+ *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on
+ *      their own.
+ *   3. else the caller's fallback: the BROWSER goes relative (same origin — see
+ *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),
+ *      because a server has no "own origin" and an unresolvable peer is a setup bug.
  *
  * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally
  * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is
  * why it lives in core-util rather than gcp-identity.
  *
  * ```ts
- * // startup, populated from the current environment's config:
+ * // startup, from the current environment's config:
  * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202
  * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');
+ * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP
  * ```
  */
 class ClientRegistry {
     /** svcName -> resolved base URL. Process-global; populated at startup per environment. */
     static mappings = new Map();
+    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */
+    static deriver;
+    /**
+     * App-supplied error translations, consulted BEFORE webpieces' built-in error mapping (both
+     * directions). Process-global, populated once at startup on the SERVER and in the BROWSER — the
+     * same no-DI pattern as {@link ClientRegistry.mappings} above. Consulted in registration order,
+     * first match wins, so a later-registered app type AND an override of a built-in status both
+     * work. See {@link ErrorTranslation}.
+     */
+    static errorTranslations = [];
     /** Map a service name to `http://localhost:<port>`. */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static addMapping(svcName, port) {
         ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);
     }
-    /** Map a service name to an explicit base URL (any host / any environment). */
+    /**
+     * Map a service name to an explicit base URL (any host / any environment).
+     *
+     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.
+     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.
+     */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static addUrlMapping(svcName, url) {
         ClientRegistry.mappings.set(svcName, url);
     }
-    /** The registered override for `svcName`, or undefined if none. Non-throwing. */
+    /**
+     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO
+     * mapping. Optional: an environment that registers every svcName it calls needs none.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static setDeriver(fn) {
+        ClientRegistry.deriver = fn;
+    }
+    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static tryLookup(svcName) {
         return ClientRegistry.mappings.get(svcName);
     }
     /**
-     * Resolve `svcName` to its registered base URL. THROWS with actionable guidance if the service
-     * was never registered — used where there is no GCP-derivation fallback (the browser).
+     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.
+     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static lookup(svcName) {
@@ -60,10 +84,87 @@ class ClientRegistry {
         }
         return url;
     }
-    /** Reset the registry. For tests, so the process-global map does not leak across specs. */
+    /**
+     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.
+     * Non-throwing — the BROWSER uses this and treats undefined as "" (relative → same origin),
+     * which is what a browser app calling the backend it was served from wants by default.
+     *
+     * Note the `!== undefined` guard: an empty-string mapping is a legal answer ("this service is
+     * same-origin"), so it must NOT fall through to derivation.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static tryResolve(svcName) {
+        const override = ClientRegistry.tryLookup(svcName);
+        if (override !== undefined) {
+            return Promise.resolve(override);
+        }
+        if (!ClientRegistry.deriver) {
+            return Promise.resolve(undefined);
+        }
+        return ClientRegistry.deriver(svcName);
+    }
+    /**
+     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no "own
+     * origin" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and
+     * say how to fix it.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static async resolve(svcName) {
+        const url = await ClientRegistry.tryResolve(svcName);
+        if (url === undefined) {
+            throw new Error(`No URL for service "${svcName}".\n` +
+                `  - localhost/AWS: ClientRegistry.addMapping('${svcName}', 8401)\n` +
+                `                or ClientRegistry.addUrlMapping('${svcName}', 'https://...')\n` +
+                `  - GCP: install a deriver — ClientRegistry.setDeriver(gcpCloudRunDeriver())\n` +
+                `  - typo? svcName must be the CLOUD RUN service name, not your project/module name`);
+        }
+        return url;
+    }
+    /**
+     * Register an app error translation. Consulted BEFORE webpieces' built-in mapping, in
+     * registration order (first match wins), so later app types AND overrides of built-ins both
+     * work. Call ONCE at startup — on the server AND in the browser — mirroring
+     * {@link ClientRegistry.addMapping}. See {@link ErrorTranslation}.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static addErrorTranslation(translation) {
+        ClientRegistry.errorTranslations.push(translation);
+    }
+    /**
+     * exception → wire (SERVER side). The first registered translation that claims `error` wins;
+     * `undefined` if none does — the caller then falls through to the generic webpieces mapping.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static tryTranslateToWire(error) {
+        for (const translation of ClientRegistry.errorTranslations) {
+            const wire = translation.toWire(error);
+            if (wire !== undefined) {
+                return wire;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * wire → exception (CLIENT side). The first registered translation that claims
+     * `(statusCode, protocolError)` wins; `undefined` if none does — the caller then falls through
+     * to the generic webpieces switch.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static tryTranslateFromWire(statusCode, protocolError) {
+        for (const translation of ClientRegistry.errorTranslations) {
+            const err = translation.fromWire(statusCode, protocolError);
+            if (err !== undefined) {
+                return err;
+            }
+        }
+        return undefined;
+    }
+    /** Reset mappings, the deriver, AND error translations. For tests, so the process-globals do not leak across specs. */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static clear() {
         ClientRegistry.mappings.clear();
+        ClientRegistry.deriver = undefined;
+        ClientRegistry.errorTranslations.length = 0;
     }
 }
 exports.ClientRegistry = ClientRegistry;

package/src/http/ClientRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ClientRegistry.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAa,cAAc;IACvB,0FAA0F;IAClF,MAAM,CAAU,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE7D,uDAAuD;IACvD,wJAAwJ;IACxJ,MAAM,CAAC,UAAU,CAAC,OAAe,EAAE,IAAY;QAC3C,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,oBAAoB,IAAI,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,+EAA+E;IAC/E,wJAAwJ;IACxJ,MAAM,CAAC,aAAa,CAAC,OAAe,EAAE,GAAW;QAC7C,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED,iFAAiF;IACjF,wJAAwJ;IACxJ,MAAM,CAAC,SAAS,CAAC,OAAe;QAC5B,OAAO,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;;OAGG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,MAAM,CAAC,OAAe;QACzB,MAAM,GAAG,GAAG,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACX,kCAAkC,OAAO,6BAA6B;gBACtE,oEAAoE;gBACpE,iEAAiE,CACpE,CAAC;QACN,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED,2FAA2F;IAC3F,wJAAwJ;IACxJ,MAAM,CAAC,KAAK;QACR,cAAc,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACpC,CAAC;;AA3CL,wCA4CC","sourcesContent":["/**\n * ClientRegistry - the process-global `svcName -> base URL` table of per-environment URL overrides\n * used to route outbound client calls.\n *\n * On GCP a client resolves a peer's base URL deterministically from `K_SERVICE` + project + region\n * (see gcp-identity `resolveServiceUrl`), so same-project/same-region services need NO registration.\n * Everything the derivation cannot describe — a localhost port, another region, another project, a\n * host that is not Cloud Run at all, or a browser that cannot read `K_SERVICE` — is registered here\n * instead. Each environment populates the registry (from its own per-env config) with the URLs it\n * needs; a registered mapping WINS over GCP derivation.\n *\n * - **http-client-node / cloudtasks-client** resolve through gcp-identity `resolveServiceUrl`: it\n *   checks {@link ClientRegistry.tryLookup} first (override), then derives on GCP, then throws\n *   off-GCP if unregistered — a missing mapping is a setup bug, not a silent mis-route.\n * - **http-client-browser** cannot derive GCP URLs, so it resolves purely via\n *   {@link ClientRegistry.lookup}; the Angular app registers each svcName at startup.\n *\n * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally\n * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is\n * why it lives in core-util rather than gcp-identity.\n *\n * ```ts\n * // startup, populated from the current environment's config:\n * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202\n * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');\n * ```\n */\nexport class ClientRegistry {\n    /** svcName -> resolved base URL. Process-global; populated at startup per environment. */\n    private static readonly mappings = new Map<string, string>();\n\n    /** Map a service name to `http://localhost:<port>`. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addMapping(svcName: string, port: number): void {\n        ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);\n    }\n\n    /** Map a service name to an explicit base URL (any host / any environment). */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addUrlMapping(svcName: string, url: string): void {\n        ClientRegistry.mappings.set(svcName, url);\n    }\n\n    /** The registered override for `svcName`, or undefined if none. Non-throwing. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryLookup(svcName: string): string | undefined {\n        return ClientRegistry.mappings.get(svcName);\n    }\n\n    /**\n     * Resolve `svcName` to its registered base URL. THROWS with actionable guidance if the service\n     * was never registered — used where there is no GCP-derivation fallback (the browser).\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static lookup(svcName: string): string {\n        const url = ClientRegistry.tryLookup(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL registered for service \"${svcName}\". Register it at startup: ` +\n                `ClientRegistry.addMapping(svcName, port) for a localhost port, or ` +\n                `ClientRegistry.addUrlMapping(svcName, url) for an explicit URL.`,\n            );\n        }\n        return url;\n    }\n\n    /** Reset the registry. For tests, so the process-global map does not leak across specs. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static clear(): void {\n        ClientRegistry.mappings.clear();\n    }\n}\n"]}
+{"version":3,"file":"ClientRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ClientRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { ErrorTranslation, ErrorWireForm } from './ErrorTranslation';\nimport { ProtocolError } from './errors';\n\n/**\n * Derives a base URL for a service name that has NO registered mapping — the pluggable half of\n * {@link ClientRegistry} resolution. One per environment, installed once at startup:\n *\n * - `gcpCloudRunDeriver()` (@webpieces/gcp-identity) — the Cloud Run formula, read from the metadata\n *   server. For code running ON GCP.\n * - `gcpCloudRunDeriver(new GcpCloudRunTarget(projectNumber, region))` — the SAME formula with the\n *   values supplied from config, for code running OFF GCP that still calls Cloud Run (a CLI, CI).\n * - {@link templateDeriver} (this package, browser-safe) — pure string substitution, for AWS or\n *   anything else with predictable DNS.\n * - none at all — a browser goes same-origin, and localhost/tests hand-register their mappings.\n */\nexport type ServiceUrlDeriver = (svcName: string) => Promise<string>;\n\n/**\n * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every\n * environment. A client is built once but a URL is per-environment, so the URL belongs here rather\n * than on the client: clients carry ONLY a svcName.\n *\n * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:\n *\n *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region\n *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.\n *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or\n *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,\n *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on\n *      their own.\n *   3. else the caller's fallback: the BROWSER goes relative (same origin — see\n *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),\n *      because a server has no \"own origin\" and an unresolvable peer is a setup bug.\n *\n * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally\n * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is\n * why it lives in core-util rather than gcp-identity.\n *\n * ```ts\n * // startup, from the current environment's config:\n * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202\n * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');\n * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP\n * ```\n */\nexport class ClientRegistry {\n    /** svcName -> resolved base URL. Process-global; populated at startup per environment. */\n    private static readonly mappings = new Map<string, string>();\n\n    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */\n    private static deriver: ServiceUrlDeriver | undefined;\n\n    /**\n     * App-supplied error translations, consulted BEFORE webpieces' built-in error mapping (both\n     * directions). Process-global, populated once at startup on the SERVER and in the BROWSER — the\n     * same no-DI pattern as {@link ClientRegistry.mappings} above. Consulted in registration order,\n     * first match wins, so a later-registered app type AND an override of a built-in status both\n     * work. See {@link ErrorTranslation}.\n     */\n    private static readonly errorTranslations: ErrorTranslation[] = [];\n\n    /** Map a service name to `http://localhost:<port>`. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addMapping(svcName: string, port: number): void {\n        ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);\n    }\n\n    /**\n     * Map a service name to an explicit base URL (any host / any environment).\n     *\n     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.\n     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addUrlMapping(svcName: string, url: string): void {\n        ClientRegistry.mappings.set(svcName, url);\n    }\n\n    /**\n     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO\n     * mapping. Optional: an environment that registers every svcName it calls needs none.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDeriver(fn: ServiceUrlDeriver): void {\n        ClientRegistry.deriver = fn;\n    }\n\n    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryLookup(svcName: string): string | undefined {\n        return ClientRegistry.mappings.get(svcName);\n    }\n\n    /**\n     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.\n     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static lookup(svcName: string): string {\n        const url = ClientRegistry.tryLookup(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL registered for service \"${svcName}\". Register it at startup: ` +\n                `ClientRegistry.addMapping(svcName, port) for a localhost port, or ` +\n                `ClientRegistry.addUrlMapping(svcName, url) for an explicit URL.`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.\n     * Non-throwing — the BROWSER uses this and treats undefined as \"\" (relative → same origin),\n     * which is what a browser app calling the backend it was served from wants by default.\n     *\n     * Note the `!== undefined` guard: an empty-string mapping is a legal answer (\"this service is\n     * same-origin\"), so it must NOT fall through to derivation.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryResolve(svcName: string): Promise<string | undefined> {\n        const override = ClientRegistry.tryLookup(svcName);\n        if (override !== undefined) {\n            return Promise.resolve(override);\n        }\n        if (!ClientRegistry.deriver) {\n            return Promise.resolve(undefined);\n        }\n        return ClientRegistry.deriver(svcName);\n    }\n\n    /**\n     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no \"own\n     * origin\" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and\n     * say how to fix it.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static async resolve(svcName: string): Promise<string> {\n        const url = await ClientRegistry.tryResolve(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL for service \"${svcName}\".\\n` +\n                `  - localhost/AWS: ClientRegistry.addMapping('${svcName}', 8401)\\n` +\n                `                or ClientRegistry.addUrlMapping('${svcName}', 'https://...')\\n` +\n                `  - GCP: install a deriver — ClientRegistry.setDeriver(gcpCloudRunDeriver())\\n` +\n                `  - typo? svcName must be the CLOUD RUN service name, not your project/module name`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Register an app error translation. Consulted BEFORE webpieces' built-in mapping, in\n     * registration order (first match wins), so later app types AND overrides of built-ins both\n     * work. Call ONCE at startup — on the server AND in the browser — mirroring\n     * {@link ClientRegistry.addMapping}. See {@link ErrorTranslation}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addErrorTranslation(translation: ErrorTranslation): void {\n        ClientRegistry.errorTranslations.push(translation);\n    }\n\n    /**\n     * exception → wire (SERVER side). The first registered translation that claims `error` wins;\n     * `undefined` if none does — the caller then falls through to the generic webpieces mapping.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryTranslateToWire(error: Error): ErrorWireForm | undefined {\n        for (const translation of ClientRegistry.errorTranslations) {\n            const wire = translation.toWire(error);\n            if (wire !== undefined) {\n                return wire;\n            }\n        }\n        return undefined;\n    }\n\n    /**\n     * wire → exception (CLIENT side). The first registered translation that claims\n     * `(statusCode, protocolError)` wins; `undefined` if none does — the caller then falls through\n     * to the generic webpieces switch.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryTranslateFromWire(statusCode: number, protocolError: ProtocolError): Error | undefined {\n        for (const translation of ClientRegistry.errorTranslations) {\n            const err = translation.fromWire(statusCode, protocolError);\n            if (err !== undefined) {\n                return err;\n            }\n        }\n        return undefined;\n    }\n\n    /** Reset mappings, the deriver, AND error translations. For tests, so the process-globals do not leak across specs. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static clear(): void {\n        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslations.length = 0;\n    }\n}\n"]}

package/src/http/ErrorTranslation.d.ts

@@ -0,0 +1,47 @@
+import { ProtocolError } from './errors';
+/**
+ * ErrorWireForm - the wire representation an error translates to: the HTTP status code plus the
+ * {@link ProtocolError} body fields. This is exactly what the server writes and the client reads,
+ * so the two directions of a translation agree on the same shape.
+ *
+ * Data-only structure (a class, not an inline object literal, per the webpieces guidelines) so
+ * every producer constructs it explicitly.
+ */
+export declare class ErrorWireForm {
+    readonly statusCode: number;
+    readonly protocolError: ProtocolError;
+    constructor(statusCode: number, protocolError: ProtocolError);
+}
+/**
+ * ErrorTranslation - a bidirectional, app-supplied translation between one (or more) exception
+ * types and their wire form. An app registers translations ONCE at startup (server AND browser)
+ * via {@link ClientRegistry.addErrorTranslation}; they are consulted BEFORE the built-in webpieces
+ * mapping (the hard-coded status-code switch on the client, the `instanceof HttpError` ladder on
+ * the server).
+ *
+ * BOTH methods return `undefined` to mean "not mine — fall through to the next registered
+ * translation, then to generic webpieces." This single rule is what lets translations be additive
+ * (an app ADDS a new error type, e.g. a custom 460) AND override-capable (an app REPLACES how a
+ * built-in status like 400 is written/reconstructed): a translation that returns a value wins;
+ * one that returns undefined steps aside.
+ *
+ * Symmetry: `toWire` runs on the SERVER (exception → JSON) and `fromWire` runs on the CLIENT
+ * (JSON → exception). Because {@link ErrorTranslation} and {@link ClientRegistry} live in core-util
+ * (browser-safe, zero node deps), the identical translation object serves the node server and the
+ * Angular/browser client — the same halves the app supplies together.
+ *
+ * This is a business-logic contract (methods, not data), so it is an interface per the webpieces
+ * guidelines.
+ */
+export interface ErrorTranslation {
+    /**
+     * exception → JSON. Return the wire form for `error`, or `undefined` if this translation does
+     * not handle `error` (→ fall through to the next translation, then to generic webpieces).
+     */
+    toWire(error: Error): ErrorWireForm | undefined;
+    /**
+     * JSON → exception. Return the reconstructed, typed error for `(statusCode, protocolError)`, or
+     * `undefined` to fall through to the next translation, then to the generic webpieces switch.
+     */
+    fromWire(statusCode: number, protocolError: ProtocolError): Error | undefined;
+}

package/src/http/ErrorTranslation.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorWireForm = void 0;
+/**
+ * ErrorWireForm - the wire representation an error translates to: the HTTP status code plus the
+ * {@link ProtocolError} body fields. This is exactly what the server writes and the client reads,
+ * so the two directions of a translation agree on the same shape.
+ *
+ * Data-only structure (a class, not an inline object literal, per the webpieces guidelines) so
+ * every producer constructs it explicitly.
+ */
+class ErrorWireForm {
+    statusCode;
+    protocolError;
+    constructor(statusCode, protocolError) {
+        this.statusCode = statusCode;
+        this.protocolError = protocolError;
+    }
+}
+exports.ErrorWireForm = ErrorWireForm;
+//# sourceMappingURL=ErrorTranslation.js.map

package/src/http/ErrorTranslation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorTranslation.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorTranslation.ts"],"names":[],"mappings":";;;AAEA;;;;;;;GAOG;AACH,MAAa,aAAa;IAEF;IACA;IAFpB,YACoB,UAAkB,EAClB,aAA4B;QAD5B,eAAU,GAAV,UAAU,CAAQ;QAClB,kBAAa,GAAb,aAAa,CAAe;IAC7C,CAAC;CACP;AALD,sCAKC","sourcesContent":["import { ProtocolError } from './errors';\n\n/**\n * ErrorWireForm - the wire representation an error translates to: the HTTP status code plus the\n * {@link ProtocolError} body fields. This is exactly what the server writes and the client reads,\n * so the two directions of a translation agree on the same shape.\n *\n * Data-only structure (a class, not an inline object literal, per the webpieces guidelines) so\n * every producer constructs it explicitly.\n */\nexport class ErrorWireForm {\n    constructor(\n        public readonly statusCode: number,\n        public readonly protocolError: ProtocolError,\n    ) {}\n}\n\n/**\n * ErrorTranslation - a bidirectional, app-supplied translation between one (or more) exception\n * types and their wire form. An app registers translations ONCE at startup (server AND browser)\n * via {@link ClientRegistry.addErrorTranslation}; they are consulted BEFORE the built-in webpieces\n * mapping (the hard-coded status-code switch on the client, the `instanceof HttpError` ladder on\n * the server).\n *\n * BOTH methods return `undefined` to mean \"not mine — fall through to the next registered\n * translation, then to generic webpieces.\" This single rule is what lets translations be additive\n * (an app ADDS a new error type, e.g. a custom 460) AND override-capable (an app REPLACES how a\n * built-in status like 400 is written/reconstructed): a translation that returns a value wins;\n * one that returns undefined steps aside.\n *\n * Symmetry: `toWire` runs on the SERVER (exception → JSON) and `fromWire` runs on the CLIENT\n * (JSON → exception). Because {@link ErrorTranslation} and {@link ClientRegistry} live in core-util\n * (browser-safe, zero node deps), the identical translation object serves the node server and the\n * Angular/browser client — the same halves the app supplies together.\n *\n * This is a business-logic contract (methods, not data), so it is an interface per the webpieces\n * guidelines.\n */\nexport interface ErrorTranslation {\n    /**\n     * exception → JSON. Return the wire form for `error`, or `undefined` if this translation does\n     * not handle `error` (→ fall through to the next translation, then to generic webpieces).\n     */\n    toWire(error: Error): ErrorWireForm | undefined;\n\n    /**\n     * JSON → exception. Return the reconstructed, typed error for `(statusCode, protocolError)`, or\n     * `undefined` to fall through to the next translation, then to the generic webpieces switch.\n     */\n    fromWire(statusCode: number, protocolError: ProtocolError): Error | undefined;\n}\n"]}

package/src/http/templateDeriver.d.ts

@@ -0,0 +1,20 @@
+import { ServiceUrlDeriver } from './ClientRegistry';
+/**
+ * A {@link ServiceUrlDeriver} for any environment whose service URLs are a PREDICTABLE FORMULA —
+ * AWS behind Route53, a k8s cluster, a corp DNS zone, anything not Cloud Run. Pure string
+ * substitution, so it is browser-safe and pulls in no cloud SDK.
+ *
+ * `{svc}` is the service name being resolved; every other `{key}` comes from `vars`:
+ *
+ * ```ts
+ * ClientRegistry.setDeriver(templateDeriver('https://{svc}.example.com'));                       // prod
+ * ClientRegistry.setDeriver(templateDeriver('https://{svc}.{env}.example.com', { env: 'qa' }));  // per-env
+ * ```
+ *
+ * Nothing about this is GCP-specific, which is the point: an AWS deployment installs THIS (or no
+ * deriver at all, and registers its mappings) and never pulls in gcp-metadata.
+ *
+ * @throws Error at DERIVE time if the pattern still holds an unsubstituted `{key}` — a typo in the
+ *         pattern (or a var you forgot to pass) must not silently ship a bogus hostname.
+ */
+export declare function templateDeriver(pattern: string, vars?: Record<string, string>): ServiceUrlDeriver;

package/src/http/templateDeriver.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.templateDeriver = templateDeriver;
+/**
+ * A {@link ServiceUrlDeriver} for any environment whose service URLs are a PREDICTABLE FORMULA —
+ * AWS behind Route53, a k8s cluster, a corp DNS zone, anything not Cloud Run. Pure string
+ * substitution, so it is browser-safe and pulls in no cloud SDK.
+ *
+ * `{svc}` is the service name being resolved; every other `{key}` comes from `vars`:
+ *
+ * ```ts
+ * ClientRegistry.setDeriver(templateDeriver('https://{svc}.example.com'));                       // prod
+ * ClientRegistry.setDeriver(templateDeriver('https://{svc}.{env}.example.com', { env: 'qa' }));  // per-env
+ * ```
+ *
+ * Nothing about this is GCP-specific, which is the point: an AWS deployment installs THIS (or no
+ * deriver at all, and registers its mappings) and never pulls in gcp-metadata.
+ *
+ * @throws Error at DERIVE time if the pattern still holds an unsubstituted `{key}` — a typo in the
+ *         pattern (or a var you forgot to pass) must not silently ship a bogus hostname.
+ */
+// webpieces-disable no-function-outside-class -- a deriver IS a function; this is the factory that closes over the pattern (see ServiceUrlDeriver)
+function templateDeriver(pattern, vars = {}) {
+    // async, so a bad pattern REJECTS like every other resolution failure rather than throwing
+    // synchronously out of ClientRegistry.tryResolve.
+    return async (svcName) => {
+        const substitutions = { ...vars, svc: svcName };
+        const url = pattern.replace(/\{(\w+)\}/g, (placeholder, key) => {
+            const value = substitutions[key];
+            return value === undefined ? placeholder : value;
+        });
+        const leftover = /\{(\w+)\}/.exec(url);
+        if (leftover) {
+            throw new Error(`templateDeriver('${pattern}') cannot resolve "${svcName}": no value for {${leftover[1]}}. ` +
+                `Pass it in the vars argument, e.g. templateDeriver(pattern, { ${leftover[1]}: '...' }).`);
+        }
+        return url;
+    };
+}
+//# sourceMappingURL=templateDeriver.js.map

package/src/http/templateDeriver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templateDeriver.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/templateDeriver.ts"],"names":[],"mappings":";;AAqBA,0CAmBC;AAtCD;;;;;;;;;;;;;;;;;GAiBG;AACH,mJAAmJ;AACnJ,SAAgB,eAAe,CAAC,OAAe,EAAE,OAA+B,EAAE;IAC9E,2FAA2F;IAC3F,kDAAkD;IAClD,OAAO,KAAK,EAAE,OAAe,EAAmB,EAAE;QAC9C,MAAM,aAAa,GAA2B,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;QACxE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,WAAmB,EAAE,GAAW,EAAU,EAAE;YACnF,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;YACjC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;QACrD,CAAC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,QAAQ,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACX,oBAAoB,OAAO,sBAAsB,OAAO,oBAAoB,QAAQ,CAAC,CAAC,CAAC,KAAK;gBAC5F,iEAAiE,QAAQ,CAAC,CAAC,CAAC,aAAa,CAC5F,CAAC;QACN,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC,CAAC;AACN,CAAC","sourcesContent":["import { ServiceUrlDeriver } from './ClientRegistry';\n\n/**\n * A {@link ServiceUrlDeriver} for any environment whose service URLs are a PREDICTABLE FORMULA —\n * AWS behind Route53, a k8s cluster, a corp DNS zone, anything not Cloud Run. Pure string\n * substitution, so it is browser-safe and pulls in no cloud SDK.\n *\n * `{svc}` is the service name being resolved; every other `{key}` comes from `vars`:\n *\n * ```ts\n * ClientRegistry.setDeriver(templateDeriver('https://{svc}.example.com'));                       // prod\n * ClientRegistry.setDeriver(templateDeriver('https://{svc}.{env}.example.com', { env: 'qa' }));  // per-env\n * ```\n *\n * Nothing about this is GCP-specific, which is the point: an AWS deployment installs THIS (or no\n * deriver at all, and registers its mappings) and never pulls in gcp-metadata.\n *\n * @throws Error at DERIVE time if the pattern still holds an unsubstituted `{key}` — a typo in the\n *         pattern (or a var you forgot to pass) must not silently ship a bogus hostname.\n */\n// webpieces-disable no-function-outside-class -- a deriver IS a function; this is the factory that closes over the pattern (see ServiceUrlDeriver)\nexport function templateDeriver(pattern: string, vars: Record<string, string> = {}): ServiceUrlDeriver {\n    // async, so a bad pattern REJECTS like every other resolution failure rather than throwing\n    // synchronously out of ClientRegistry.tryResolve.\n    return async (svcName: string): Promise<string> => {\n        const substitutions: Record<string, string> = { ...vars, svc: svcName };\n        const url = pattern.replace(/\\{(\\w+)\\}/g, (placeholder: string, key: string): string => {\n            const value = substitutions[key];\n            return value === undefined ? placeholder : value;\n        });\n\n        const leftover = /\\{(\\w+)\\}/.exec(url);\n        if (leftover) {\n            throw new Error(\n                `templateDeriver('${pattern}') cannot resolve \"${svcName}\": no value for {${leftover[1]}}. ` +\n                `Pass it in the vars argument, e.g. templateDeriver(pattern, { ${leftover[1]}: '...' }).`,\n            );\n        }\n        return url;\n    };\n}\n"]}

package/src/index.d.ts

@@ -23,6 +23,10 @@ export { ProtocolError, HttpError, HttpNotFoundError, EndpointNotFoundError, Htt
 export { InstantDto, DateDto, TimeDto, DateTimeDto, InstantUtil, DateUtil, TimeUtil, DateTimeUtil, } from './http/datetime';
 export { HeaderRegistry } from './http/HeaderRegistry';
 export { ClientRegistry } from './http/ClientRegistry';
+export type { ServiceUrlDeriver } from './http/ClientRegistry';
+export { ErrorWireForm } from './http/ErrorTranslation';
+export type { ErrorTranslation } from './http/ErrorTranslation';
+export { templateDeriver } from './http/templateDeriver';
 export { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';
 export { ContextReader } from './http/ContextReader';
 export type { ContextRead } from './http/ContextReader';

package/src/index.js

@@ -9,7 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ENTITY_NOT_FOUND = exports.HttpUserError = exports.HttpVendorError = exports.HttpInternalServerError = exports.HttpGatewayTimeoutError = exports.HttpBadGatewayError = exports.HttpTimeoutError = exports.HttpForbiddenError = exports.HttpUnauthorizedError = exports.HttpBadRequestError = exports.EndpointNotFoundError = exports.HttpNotFoundError = exports.HttpError = exports.ProtocolError = exports.Secrets = exports.METADATA_KEYS = exports.RouteMetadata = exports.AuthMeta = exports.validateNoConflictingDecorators = exports.getQueueName = exports.assertPubSubConventions = exports.assertApiKind = exports.getApiKind = exports.assertEveryEndpointHasAuthMode = exports.getAuthMode = exports.getAuthMeta = exports.isApiPath = exports.getEndpoints = exports.getApiPath = exports.Queue = exports.PubSub = exports.Rpc = exports.AuthSharedSecret = exports.AuthOidc = exports.Auth = exports.AuthJwt = exports.Public = exports.AuthenticationConfig = exports.Authentication = exports.Endpoint = exports.ApiPath = exports.LogManager = exports.ConsoleLoggerFactory = exports.ConsoleLogger = exports.DESIGN_METADATA_KEYS = exports.isDocumentDesign = exports.DocumentDesign = exports.ContextTuple = exports.ContextKey = exports.toError = void 0;
-exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.LogApiCall = exports.ContextMgr = exports.WebpiecesCoreHeaders = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = void 0;
+exports.SerializedError = exports.SerializedMap = exports.RecordSerializer = exports.getDoNotRecordFields = exports.DoNotRecord = exports.RecordedTestCase = exports.RecordedError = exports.RecordedEndpoint = exports.RecorderKeys = exports.LogApiCall = exports.ContextMgr = exports.WebpiecesCoreHeaders = exports.templateDeriver = exports.ErrorWireForm = exports.ClientRegistry = exports.HeaderRegistry = exports.DateTimeUtil = exports.TimeUtil = exports.DateUtil = exports.InstantUtil = exports.NO_REG_CODE = exports.WRONG_COMPANY = exports.WRONG_DOMAIN = exports.EMAIL_NOT_CONFIRMED = exports.NOT_APPROVED = exports.WRONG_LOGIN = exports.WRONG_LOGIN_TYPE = void 0;
 var errorUtils_1 = require("./lib/errorUtils");
 Object.defineProperty(exports, "toError", { enumerable: true, get: function () { return errorUtils_1.toError; } });
 var ContextKey_1 = require("./ContextKey");
@@ -102,6 +102,12 @@ var HeaderRegistry_1 = require("./http/HeaderRegistry");
 Object.defineProperty(exports, "HeaderRegistry", { enumerable: true, get: function () { return HeaderRegistry_1.HeaderRegistry; } });
 var ClientRegistry_1 = require("./http/ClientRegistry");
 Object.defineProperty(exports, "ClientRegistry", { enumerable: true, get: function () { return ClientRegistry_1.ClientRegistry; } });
+// Pluggable, bidirectional error translation (app exception <-> wire form). Registered on
+// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.
+var ErrorTranslation_1 = require("./http/ErrorTranslation");
+Object.defineProperty(exports, "ErrorWireForm", { enumerable: true, get: function () { return ErrorTranslation_1.ErrorWireForm; } });
+var templateDeriver_1 = require("./http/templateDeriver");
+Object.defineProperty(exports, "templateDeriver", { enumerable: true, get: function () { return templateDeriver_1.templateDeriver; } });
 var WebpiecesCoreHeaders_1 = require("./http/WebpiecesCoreHeaders");
 Object.defineProperty(exports, "WebpiecesCoreHeaders", { enumerable: true, get: function () { return WebpiecesCoreHeaders_1.WebpiecesCoreHeaders; } });
 // BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the HttpError hierarchy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    Authentication,\n    AuthenticationConfig,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    Public,\n    AuthJwt,\n    Auth,\n    AuthOidc,\n    AuthSharedSecret,\n    // API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n    Rpc,\n    PubSub,\n    Queue,\n    getApiPath,\n    getEndpoints,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n    validateNoConflictingDecorators,\n    AuthMeta,\n    RouteMetadata,\n    METADATA_KEYS,\n} from './http/decorators';\nexport type { AuthMode, ApiKind, JwtRequirement } from './http/decorators';\n// Client-side shared-secret store (the value THIS service sends per @AuthSharedSecret key).\nexport { Secrets } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// HTTP errors\nexport {\n    ProtocolError,\n    HttpError,\n    HttpNotFoundError,\n    EndpointNotFoundError,\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpTimeoutError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    HttpInternalServerError,\n    HttpVendorError,\n    HttpUserError,\n    // Error subtype constants\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './http/errors';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\nexport type { ContextRead } from './http/ContextReader';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above)\nexport { LogApiCall } from './http/LogApiCall';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport { RecordedEndpoint, RecordedError, RecordedTestCase } from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/core/core-util/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;AAEH,+CAA2C;AAAlC,qGAAA,OAAO,OAAA;AAChB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AAErB,+EAA+E;AAC/E,kFAAkF;AAClF,yCAAyC;AACzC,mDAA0F;AAAjF,gHAAA,cAAc,OAAA;AAAE,kHAAA,gBAAgB,OAAA;AAAE,sHAAA,oBAAoB,OAAA;AAO/D,yDAAwD;AAA/C,8GAAA,aAAa,OAAA;AACtB,uEAAsE;AAA7D,4HAAA,oBAAoB,OAAA;AAC7B,mDAAkD;AAAzC,wGAAA,UAAU,OAAA;AAEnB,8DAA8D;AAC9D,sEAAsE;AACtE,sEAAsE;AACtE,uEAAuE;AACvE,kEAAkE;AAElE,4BAA4B;AAC5B,gDA6B2B;AA5BvB,qGAAA,OAAO,OAAA;AACP,sGAAA,QAAQ,OAAA;AACR,4GAAA,cAAc,OAAA;AACd,kHAAA,oBAAoB,OAAA;AACpB,mEAAmE;AACnE,oGAAA,MAAM,OAAA;AACN,qGAAA,OAAO,OAAA;AACP,kGAAA,IAAI,OAAA;AACJ,sGAAA,QAAQ,OAAA;AACR,8GAAA,gBAAgB,OAAA;AAChB,sDAAsD;AACtD,iGAAA,GAAG,OAAA;AACH,oGAAA,MAAM,OAAA;AACN,mGAAA,KAAK,OAAA;AACL,wGAAA,UAAU,OAAA;AACV,0GAAA,YAAY,OAAA;AACZ,uGAAA,SAAS,OAAA;AACT,yGAAA,WAAW,OAAA;AACX,yGAAA,WAAW,OAAA;AACX,4HAAA,8BAA8B,OAAA;AAC9B,wGAAA,UAAU,OAAA;AACV,2GAAA,aAAa,OAAA;AACb,qHAAA,uBAAuB,OAAA;AACvB,0GAAA,YAAY,OAAA;AACZ,6HAAA,+BAA+B,OAAA;AAC/B,sGAAA,QAAQ,OAAA;AACR,2GAAA,aAAa,OAAA;AACb,2GAAA,aAAa,OAAA;AAGjB,4FAA4F;AAC5F,0CAAyC;AAAhC,kGAAA,OAAO,OAAA;AAKhB,cAAc;AACd,wCAuBuB;AAtBnB,uGAAA,aAAa,OAAA;AACb,mGAAA,SAAS,OAAA;AACT,2GAAA,iBAAiB,OAAA;AACjB,+GAAA,qBAAqB,OAAA;AACrB,6GAAA,mBAAmB,OAAA;AACnB,+GAAA,qBAAqB,OAAA;AACrB,4GAAA,kBAAkB,OAAA;AAClB,0GAAA,gBAAgB,OAAA;AAChB,6GAAA,mBAAmB,OAAA;AACnB,iHAAA,uBAAuB,OAAA;AACvB,iHAAA,uBAAuB,OAAA;AACvB,yGAAA,eAAe,OAAA;AACf,uGAAA,aAAa,OAAA;AACb,0BAA0B;AAC1B,0GAAA,gBAAgB,OAAA;AAChB,0GAAA,gBAAgB,OAAA;AAChB,qGAAA,WAAW,OAAA;AACX,sGAAA,YAAY,OAAA;AACZ,6GAAA,mBAAmB,OAAA;AACnB,sGAAA,YAAY,OAAA;AACZ,uGAAA,aAAa,OAAA;AACb,qGAAA,WAAW,OAAA;AAGf,iEAAiE;AACjE,4CASyB;AAJrB,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,oGAAA,QAAQ,OAAA;AACR,wGAAA,YAAY,OAAA;AAGhB,mEAAmE;AACnE,wDAAuD;AAA9C,gHAAA,cAAc,OAAA;AACvB,wDAAuD;AAA9C,gHAAA,cAAc,OAAA;AAEvB,0FAA0F;AAC1F,4FAA4F;AAC5F,4DAAwD;AAA/C,iHAAA,aAAa,OAAA;AAEtB,0DAAyD;AAAhD,kHAAA,eAAe,OAAA;AACxB,oEAAmE;AAA1D,4HAAA,oBAAoB,OAAA;AAI7B,iGAAiG;AACjG,gGAAgG;AAChG,kEAAkE;AAClE,gDAA+C;AAAtC,wGAAA,UAAU,OAAA;AAEnB,kDAAkD;AAClD,gDAA+C;AAAtC,wGAAA,UAAU,OAAA;AAEnB,iFAAiF;AACjF,qEAAkF;AAAvD,gHAAA,YAAY,OAAA;AACvC,qEAAqG;AAA5F,oHAAA,gBAAgB,OAAA;AAAE,iHAAA,aAAa,OAAA;AAAE,oHAAA,gBAAgB,OAAA;AAC1D,2DAAgF;AAAvE,0GAAA,WAAW,OAAA;AAAE,mHAAA,oBAAoB,OAAA;AAC1C,qEAAoG;AAA3F,oHAAA,gBAAgB,OAAA;AAAE,iHAAA,aAAa,OAAA;AAAE,mHAAA,eAAe,OAAA","sourcesContent":["/**\n * @webpieces/core-util\n *\n * Utility functions for WebPieces applications.\n * This package works in both browser and Node.js environments.\n *\n * @packageDocumentation\n */\n\nexport { toError } from './lib/errorUtils';\nexport { ContextKey } from './ContextKey';\nexport { ContextTuple } from './ContextTuple';\n\n// @DocumentDesign — DI-design-root marker. Applies to ANY project kind (server\n// controllers AND library impl classes), so it lives here (browser + Node) rather\n// than in a server-only routing package.\nexport { DocumentDesign, isDocumentDesign, DESIGN_METADATA_KEYS } from './DocumentDesign';\n\n// Logging (merged from former @webpieces/wp-logging).\n// Pluggable logging interface + a browser-safe console default; apps plug in\n// bunyan/winston/pino/etc. via LogManager.setFactory(...). Browser + Node.\nexport type { Logger, LogLevel } from './logging/Logger';\nexport type { LoggerFactory } from './logging/LoggerFactory';\nexport { ConsoleLogger } from './logging/ConsoleLogger';\nexport { ConsoleLoggerFactory } from './logging/ConsoleLoggerFactory';\nexport { LogManager } from './logging/LogManager';\n\n// HTTP API contract (merged from former @webpieces/http-api).\n// Shared HTTP API definition consumed by both client and server: REST\n// decorators, the HttpError hierarchy, datetime DTOs, platform-header\n// registry/readers, ValidateImplementation, and the test-case recorder\n// contract. Pure definitions — express-free, browser + Node safe.\n\n// API definition decorators\nexport {\n    ApiPath,\n    Endpoint,\n    Authentication,\n    AuthenticationConfig,\n    // Auth mode decorators (clean service-to-service + user JWT model)\n    Public,\n    AuthJwt,\n    Auth,\n    AuthOidc,\n    AuthSharedSecret,\n    // API kind (RPC vs PubSub/Cloud Tasks) + queue naming\n    Rpc,\n    PubSub,\n    Queue,\n    getApiPath,\n    getEndpoints,\n    isApiPath,\n    getAuthMeta,\n    getAuthMode,\n    assertEveryEndpointHasAuthMode,\n    getApiKind,\n    assertApiKind,\n    assertPubSubConventions,\n    getQueueName,\n    validateNoConflictingDecorators,\n    AuthMeta,\n    RouteMetadata,\n    METADATA_KEYS,\n} from './http/decorators';\nexport type { AuthMode, ApiKind, JwtRequirement } from './http/decorators';\n// Client-side shared-secret store (the value THIS service sends per @AuthSharedSecret key).\nexport { Secrets } from './http/Secrets';\n\n// Type validators\nexport { ValidateImplementation } from './http/validators';\n\n// HTTP errors\nexport {\n    ProtocolError,\n    HttpError,\n    HttpNotFoundError,\n    EndpointNotFoundError,\n    HttpBadRequestError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpTimeoutError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n    HttpInternalServerError,\n    HttpVendorError,\n    HttpUserError,\n    // Error subtype constants\n    ENTITY_NOT_FOUND,\n    WRONG_LOGIN_TYPE,\n    WRONG_LOGIN,\n    NOT_APPROVED,\n    EMAIL_NOT_CONFIRMED,\n    WRONG_DOMAIN,\n    WRONG_COMPANY,\n    NO_REG_CODE,\n} from './http/errors';\n\n// Date/Time DTOs and Utilities (inspired by Java Time / JSR-310)\nexport {\n    InstantDto,\n    DateDto,\n    TimeDto,\n    DateTimeDto,\n    InstantUtil,\n    DateUtil,\n    TimeUtil,\n    DateTimeUtil,\n} from './http/datetime';\n\n// Context keys + registry (the global magic-context header system)\nexport { HeaderRegistry } from './http/HeaderRegistry';\nexport { ClientRegistry } from './http/ClientRegistry';\nexport type { ServiceUrlDeriver } from './http/ClientRegistry';\n// Pluggable, bidirectional error translation (app exception <-> wire form). Registered on\n// ClientRegistry at startup; consulted before the built-in webpieces mapping on BOTH sides.\nexport { ErrorWireForm } from './http/ErrorTranslation';\nexport type { ErrorTranslation } from './http/ErrorTranslation';\nexport { templateDeriver } from './http/templateDeriver';\nexport { WebpiecesCoreHeaders } from './http/WebpiecesCoreHeaders';\nexport { ContextReader } from './http/ContextReader';\nexport type { ContextRead } from './http/ContextReader';\n\n// BROWSER-ONLY outbound-header propagation (app-held store + registry -> outbound HTTP headers).\n// Only @webpieces/http-client-browser may name it; the server reads RequestContext directly via\n// RequestContextHeaders in the Node-only @webpieces/core-context.\nexport { ContextMgr } from './http/ContextMgr';\n\n// API-call logging helper (uses LogManager above)\nexport { LogApiCall } from './http/LogApiCall';\n\n// Test-case recording contract (impl lives in http-server; hooks in http-client)\nexport { TestCaseRecorder, RecorderKeys } from './http/recorder/TestCaseRecorder';\nexport { RecordedEndpoint, RecordedError, RecordedTestCase } from './http/recorder/RecordedEndpoint';\nexport { DoNotRecord, getDoNotRecordFields } from './http/recorder/DoNotRecord';\nexport { RecordSerializer, SerializedMap, SerializedError } from './http/recorder/RecordSerializer';\n"]}