@webpieces/core-util 0.4.894 → 0.4.896

package/src/http/CallRegistry.d.ts

@@ -1,11 +1,25 @@
 import { Attempt, CallContext, CallStrategy } from './CallStrategy';
-/** ALL has no method; a contract can optionally select one method. */
-type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];
+import { TransportDefault } from './TransportDefault';
 /**
- * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE.
- * Strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.
- * Otherwise timeout method -> API -> ALL -> transport default (30s today).
- * No default retry: only the application knows whether repeating a POST is safe.
+ * Where a policy applies: every contract (`'ALL'`, which has no method), one contract, or one method
+ * of one contract. Exported so other per-call registries (e.g. cloudtasks-client's `GcpTaskRegistry`)
+ * scope their settings with the SAME ladder.
+ */
+export type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];
+/**
+ * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE — ONE implementation,
+ * every transport calls {@link CallRegistry.execute}.
+ *
+ * Ladder: strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.
+ * Otherwise timeout method -> API -> ALL. Otherwise the transport's {@link TransportDefault} (its
+ * timeout, and its strategy if it has one). A registered TIMEOUT is therefore a decision for a single
+ * attempt and also replaces a transport's default strategy; to keep retrying with a different attempt
+ * deadline, register a `RetryStrategy` instead.
+ *
+ * RPC has no default retry (only the application knows whether repeating a POST is safe); Cloud Tasks
+ * enqueue does (see `TransportDefault`). An app opts RPC in with
+ * `CallRegistry.setStrategy(new RetryStrategy(...).run, CatalogApi)` — and `RetryStrategy` never
+ * retries a `WRITE`, even registered at ALL.
  */
 export declare class CallRegistry {
     private static all;
@@ -16,9 +30,18 @@ export declare class CallRegistry {
      * Run one call under its registered policy. `context` names the method (its `methodName` selects
      * the per-method policy) and carries the endpoint's declared operation, so the SAME context a
      * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.
+     *
+     * Every attempt is wrapped so a retried TRANSIENT failure logs one
+     * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).
+     */
+    static execute<T>(api: Function, context: CallContext, attempt: Attempt<T>, fallback: TransportDefault): Promise<T>;
+    /**
+     * The registered TIMEOUT for a call — method -> API -> ALL -> `defaultMs` — ignoring every
+     * strategy. For a transport that hands timing to someone else for this call (Cloud Tasks enqueue
+     * with caller-supplied gax `CallOptions`) and still needs ONE safety cap so a hung channel cannot
+     * block forever. Raise it with {@link CallRegistry.setTimeout}.
      */
-    static execute<T>(api: Function, context: CallContext, attempt: Attempt<T>, defaultMs: number): Promise<T>;
+    static resolveTimeout(api: Function, methodName: string, defaultMs: number): number;
     static clear(): void;
     private static policy;
 }
-export {};

package/src/http/CallRegistry.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallRegistry = void 0;
 const CallDeadline_1 = require("./CallDeadline");
+const ClientRegistry_1 = require("./ClientRegistry");
+const ErrorClassifier_1 = require("./ErrorClassifier");
+const ApiMethodInfo_1 = require("./ApiMethodInfo");
+const LogManager_1 = require("../logging/LogManager");
+const ApiCallLogName_1 = require("./ApiCallLogName");
+const errorUtils_1 = require("../lib/errorUtils");
+// The same logger LogApiCall writes its [API-*] lines to, so an attempt line sits beside the final one.
+const log = LogManager_1.LogManager.getLogger(ApiCallLogName_1.LOG_API_CALL_LOGGER_NAME);
 class CallPolicy {
     timeoutMs;
     // webpieces-disable no-any-unknown -- global policy spans heterogeneous response DTOs
@@ -12,10 +20,66 @@ class ApiCallPolicies {
     methods = new Map();
 }
 /**
- * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE.
- * Strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.
- * Otherwise timeout method -> API -> ALL -> transport default (30s today).
- * No default retry: only the application knows whether repeating a POST is safe.
+ * Counts the attempts of ONE call and logs each retried TRANSIENT failure. It wraps the attempt
+ * BEFORE any strategy sees it, so an app-written strategy gets the same lines as `RetryStrategy`.
+ *
+ * The line for attempt N is written when attempt N+1 STARTS — i.e. only for an attempt that was
+ * actually retried. The last attempt's failure is what escapes, and `LogApiCall`'s final
+ * `[API-client-resp-FAIL]` line covers it, so a call that gave up after 4 attempts logs 3 attempt
+ * lines and 1 FAIL line, never the last failure twice. An EXPECTED or FAILURE attempt is not logged
+ * here either; the final line covers it.
+ */
+class LoggedAttempts {
+    context;
+    attempt;
+    attempts = 0;
+    pendingTransient;
+    constructor(context, attempt) {
+        this.context = context;
+        this.attempt = attempt;
+    }
+    run = async (timeoutMs) => {
+        this.flushRetried();
+        this.attempts += 1;
+        // webpieces-disable no-unmanaged-exceptions -- observe the attempt's failure, rethrow it unchanged
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return await this.attempt(timeoutMs);
+        }
+        catch (err) {
+            const error = (0, errorUtils_1.toError)(err);
+            const methodInfo = new ApiMethodInfo_1.ApiMethodInfo('client', this.context.apiName, this.context.methodName);
+            this.pendingTransient =
+                ClientRegistry_1.ClientRegistry.classify(error, methodInfo) === ErrorClassifier_1.CallOutcome.TRANSIENT_FAILURE
+                    ? error
+                    : undefined;
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the attempt's own failure unchanged
+            throw err;
+        }
+    };
+    flushRetried() {
+        const error = this.pendingTransient;
+        if (error === undefined)
+            return;
+        this.pendingTransient = undefined;
+        log.warn(`[API-client-attempt-TRANSIENT] ${this.context.apiName}.${this.context.methodName} ` +
+            `attempt ${this.attempts} errorType=${error.constructor.name} error=${error.message}`);
+    }
+}
+/**
+ * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE — ONE implementation,
+ * every transport calls {@link CallRegistry.execute}.
+ *
+ * Ladder: strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.
+ * Otherwise timeout method -> API -> ALL. Otherwise the transport's {@link TransportDefault} (its
+ * timeout, and its strategy if it has one). A registered TIMEOUT is therefore a decision for a single
+ * attempt and also replaces a transport's default strategy; to keep retrying with a different attempt
+ * deadline, register a `RetryStrategy` instead.
+ *
+ * RPC has no default retry (only the application knows whether repeating a POST is safe); Cloud Tasks
+ * enqueue does (see `TransportDefault`). An app opts RPC in with
+ * `CallRegistry.setStrategy(new RetryStrategy(...).run, CatalogApi)` — and `RetryStrategy` never
+ * retries a `WRITE`, even registered at ALL.
  */
 class CallRegistry {
     static all = new CallPolicy();
@@ -36,16 +100,38 @@ class CallRegistry {
      * Run one call under its registered policy. `context` names the method (its `methodName` selects
      * the per-method policy) and carries the endpoint's declared operation, so the SAME context a
      * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.
+     *
+     * Every attempt is wrapped so a retried TRANSIENT failure logs one
+     * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).
      */
     // webpieces-disable no-function-outside-class -- transport-independent policy execution
-    static async execute(api, context, attempt, defaultMs) {
+    static async execute(api, context, attempt, fallback) {
+        const logged = new LoggedAttempts(context, attempt).run;
         const policies = CallRegistry.apis.get(api);
         const method = policies?.methods.get(context.methodName);
         const strategy = method?.strategy ?? policies?.policy.strategy ?? CallRegistry.all.strategy;
         if (strategy !== undefined) {
-            return (await strategy(attempt, context));
+            return (await strategy(logged, context));
         }
-        return attempt(method?.timeoutMs ??
+        const timeoutMs = method?.timeoutMs ?? policies?.policy.timeoutMs ?? CallRegistry.all.timeoutMs;
+        if (timeoutMs !== undefined) {
+            return logged(timeoutMs);
+        }
+        if (fallback.strategy !== undefined) {
+            return (await fallback.strategy(logged, context));
+        }
+        return logged(fallback.timeoutMs);
+    }
+    /**
+     * The registered TIMEOUT for a call — method -> API -> ALL -> `defaultMs` — ignoring every
+     * strategy. For a transport that hands timing to someone else for this call (Cloud Tasks enqueue
+     * with caller-supplied gax `CallOptions`) and still needs ONE safety cap so a hung channel cannot
+     * block forever. Raise it with {@link CallRegistry.setTimeout}.
+     */
+    // webpieces-disable no-function-outside-class -- process-global registry lookup
+    static resolveTimeout(api, methodName, defaultMs) {
+        const policies = CallRegistry.apis.get(api);
+        return (policies?.methods.get(methodName)?.timeoutMs ??
             policies?.policy.timeoutMs ??
             CallRegistry.all.timeoutMs ??
             defaultMs);

package/src/http/CallRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { Attempt, CallContext, CallStrategy } from './CallStrategy';\nimport { CallDeadline } from './CallDeadline';\n\n/** ALL has no method; a contract can optionally select one method. */\ntype CallScope = [api: 'ALL'] | [api: Function, methodName?: string];\n\nclass CallPolicy {\n    timeoutMs?: number;\n    // webpieces-disable no-any-unknown -- global policy spans heterogeneous response DTOs\n    strategy?: CallStrategy<unknown>;\n}\n\nclass ApiCallPolicies {\n    readonly policy = new CallPolicy();\n    readonly methods = new Map<string, CallPolicy>();\n}\n\n/**\n * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE.\n * Strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.\n * Otherwise timeout method -> API -> ALL -> transport default (30s today).\n * No default retry: only the application knows whether repeating a POST is safe.\n */\nexport class CallRegistry {\n    private static all = new CallPolicy();\n    private static readonly apis = new Map<Function, ApiCallPolicies>();\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setTimeout(timeoutMs: number | undefined, ...scope: CallScope): void {\n        if (timeoutMs !== undefined) CallDeadline.validate(timeoutMs);\n        CallRegistry.policy(scope[0], scope[1]).timeoutMs = timeoutMs;\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setStrategy(\n        // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n        strategy: CallStrategy<unknown> | undefined,\n        ...scope: CallScope\n    ): void {\n        CallRegistry.policy(scope[0], scope[1]).strategy = strategy;\n    }\n\n    /**\n     * Run one call under its registered policy. `context` names the method (its `methodName` selects\n     * the per-method policy) and carries the endpoint's declared operation, so the SAME context a\n     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.\n     */\n    // webpieces-disable no-function-outside-class -- transport-independent policy execution\n    static async execute<T>(\n        api: Function,\n        context: CallContext,\n        attempt: Attempt<T>,\n        defaultMs: number,\n    ): Promise<T> {\n        const policies = CallRegistry.apis.get(api);\n        const method = policies?.methods.get(context.methodName);\n        const strategy = method?.strategy ?? policies?.policy.strategy ?? CallRegistry.all.strategy;\n        if (strategy !== undefined) {\n            return (await strategy(attempt, context)) as T;\n        }\n        return attempt(\n            method?.timeoutMs ??\n                policies?.policy.timeoutMs ??\n                CallRegistry.all.timeoutMs ??\n                defaultMs,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry reset for tests\n    static clear(): void {\n        CallRegistry.all = new CallPolicy();\n        CallRegistry.apis.clear();\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry storage\n    private static policy(api: Function | 'ALL', methodName?: string): CallPolicy {\n        if (api === 'ALL') {\n            return CallRegistry.all;\n        }\n        let policies = CallRegistry.apis.get(api);\n        if (!policies) {\n            policies = new ApiCallPolicies();\n            CallRegistry.apis.set(api, policies);\n        }\n        if (methodName === undefined) return policies.policy;\n        let policy = policies.methods.get(methodName);\n        if (!policy) {\n            policy = new CallPolicy();\n            policies.methods.set(methodName, policy);\n        }\n        return policy;\n    }\n}\n"]}
+{"version":3,"file":"CallRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { Attempt, CallContext, CallStrategy } from './CallStrategy';\nimport { CallDeadline } from './CallDeadline';\nimport { TransportDefault } from './TransportDefault';\nimport { ClientRegistry } from './ClientRegistry';\nimport { CallOutcome } from './ErrorClassifier';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { LogManager } from '../logging/LogManager';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { toError } from '../lib/errorUtils';\n\n// The same logger LogApiCall writes its [API-*] lines to, so an attempt line sits beside the final one.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\n/**\n * Where a policy applies: every contract (`'ALL'`, which has no method), one contract, or one method\n * of one contract. Exported so other per-call registries (e.g. cloudtasks-client's `GcpTaskRegistry`)\n * scope their settings with the SAME ladder.\n */\nexport type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];\n\nclass CallPolicy {\n    timeoutMs?: number;\n    // webpieces-disable no-any-unknown -- global policy spans heterogeneous response DTOs\n    strategy?: CallStrategy<unknown>;\n}\n\nclass ApiCallPolicies {\n    readonly policy = new CallPolicy();\n    readonly methods = new Map<string, CallPolicy>();\n}\n\n/**\n * Counts the attempts of ONE call and logs each retried TRANSIENT failure. It wraps the attempt\n * BEFORE any strategy sees it, so an app-written strategy gets the same lines as `RetryStrategy`.\n *\n * The line for attempt N is written when attempt N+1 STARTS — i.e. only for an attempt that was\n * actually retried. The last attempt's failure is what escapes, and `LogApiCall`'s final\n * `[API-client-resp-FAIL]` line covers it, so a call that gave up after 4 attempts logs 3 attempt\n * lines and 1 FAIL line, never the last failure twice. An EXPECTED or FAILURE attempt is not logged\n * here either; the final line covers it.\n */\nclass LoggedAttempts<T> {\n    private attempts = 0;\n    private pendingTransient?: Error;\n\n    constructor(\n        private readonly context: CallContext,\n        private readonly attempt: Attempt<T>,\n    ) {}\n\n    readonly run: Attempt<T> = async (timeoutMs: number): Promise<T> => {\n        this.flushRetried();\n        this.attempts += 1;\n        // webpieces-disable no-unmanaged-exceptions -- observe the attempt's failure, rethrow it unchanged\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await this.attempt(timeoutMs);\n        } catch (err: unknown) {\n            const error = toError(err);\n            const methodInfo = new ApiMethodInfo('client', this.context.apiName, this.context.methodName);\n            this.pendingTransient =\n                ClientRegistry.classify(error, methodInfo) === CallOutcome.TRANSIENT_FAILURE\n                    ? error\n                    : undefined;\n            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the attempt's own failure unchanged\n            throw err;\n        }\n    };\n\n    private flushRetried(): void {\n        const error = this.pendingTransient;\n        if (error === undefined) return;\n        this.pendingTransient = undefined;\n        log.warn(\n            `[API-client-attempt-TRANSIENT] ${this.context.apiName}.${this.context.methodName} ` +\n                `attempt ${this.attempts} errorType=${error.constructor.name} error=${error.message}`,\n        );\n    }\n}\n\n/**\n * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE — ONE implementation,\n * every transport calls {@link CallRegistry.execute}.\n *\n * Ladder: strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.\n * Otherwise timeout method -> API -> ALL. Otherwise the transport's {@link TransportDefault} (its\n * timeout, and its strategy if it has one). A registered TIMEOUT is therefore a decision for a single\n * attempt and also replaces a transport's default strategy; to keep retrying with a different attempt\n * deadline, register a `RetryStrategy` instead.\n *\n * RPC has no default retry (only the application knows whether repeating a POST is safe); Cloud Tasks\n * enqueue does (see `TransportDefault`). An app opts RPC in with\n * `CallRegistry.setStrategy(new RetryStrategy(...).run, CatalogApi)` — and `RetryStrategy` never\n * retries a `WRITE`, even registered at ALL.\n */\nexport class CallRegistry {\n    private static all = new CallPolicy();\n    private static readonly apis = new Map<Function, ApiCallPolicies>();\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setTimeout(timeoutMs: number | undefined, ...scope: CallScope): void {\n        if (timeoutMs !== undefined) CallDeadline.validate(timeoutMs);\n        CallRegistry.policy(scope[0], scope[1]).timeoutMs = timeoutMs;\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setStrategy(\n        // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n        strategy: CallStrategy<unknown> | undefined,\n        ...scope: CallScope\n    ): void {\n        CallRegistry.policy(scope[0], scope[1]).strategy = strategy;\n    }\n\n    /**\n     * Run one call under its registered policy. `context` names the method (its `methodName` selects\n     * the per-method policy) and carries the endpoint's declared operation, so the SAME context a\n     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.\n     *\n     * Every attempt is wrapped so a retried TRANSIENT failure logs one\n     * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).\n     */\n    // webpieces-disable no-function-outside-class -- transport-independent policy execution\n    static async execute<T>(\n        api: Function,\n        context: CallContext,\n        attempt: Attempt<T>,\n        fallback: TransportDefault,\n    ): Promise<T> {\n        const logged = new LoggedAttempts<T>(context, attempt).run;\n        const policies = CallRegistry.apis.get(api);\n        const method = policies?.methods.get(context.methodName);\n        const strategy = method?.strategy ?? policies?.policy.strategy ?? CallRegistry.all.strategy;\n        if (strategy !== undefined) {\n            return (await strategy(logged, context)) as T;\n        }\n        const timeoutMs = method?.timeoutMs ?? policies?.policy.timeoutMs ?? CallRegistry.all.timeoutMs;\n        if (timeoutMs !== undefined) {\n            return logged(timeoutMs);\n        }\n        if (fallback.strategy !== undefined) {\n            return (await fallback.strategy(logged, context)) as T;\n        }\n        return logged(fallback.timeoutMs);\n    }\n\n    /**\n     * The registered TIMEOUT for a call — method -> API -> ALL -> `defaultMs` — ignoring every\n     * strategy. For a transport that hands timing to someone else for this call (Cloud Tasks enqueue\n     * with caller-supplied gax `CallOptions`) and still needs ONE safety cap so a hung channel cannot\n     * block forever. Raise it with {@link CallRegistry.setTimeout}.\n     */\n    // webpieces-disable no-function-outside-class -- process-global registry lookup\n    static resolveTimeout(api: Function, methodName: string, defaultMs: number): number {\n        const policies = CallRegistry.apis.get(api);\n        return (\n            policies?.methods.get(methodName)?.timeoutMs ??\n            policies?.policy.timeoutMs ??\n            CallRegistry.all.timeoutMs ??\n            defaultMs\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry reset for tests\n    static clear(): void {\n        CallRegistry.all = new CallPolicy();\n        CallRegistry.apis.clear();\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry storage\n    private static policy(api: Function | 'ALL', methodName?: string): CallPolicy {\n        if (api === 'ALL') {\n            return CallRegistry.all;\n        }\n        let policies = CallRegistry.apis.get(api);\n        if (!policies) {\n            policies = new ApiCallPolicies();\n            CallRegistry.apis.set(api, policies);\n        }\n        if (methodName === undefined) return policies.policy;\n        let policy = policies.methods.get(methodName);\n        if (!policy) {\n            policy = new CallPolicy();\n            policies.methods.set(methodName, policy);\n        }\n        return policy;\n    }\n}\n"]}

package/src/http/CallRegistryCompileAssertions.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const CallRegistry_1 = require("./CallRegistry");
+const CallStrategy_1 = require("./CallStrategy");
+const HttpEndpointOptions_1 = require("./HttpEndpointOptions");
 /** Compiled by tsc (spec files are not), never executed. */
 class CallRegistryCompileAssertions {
     check() {
@@ -9,5 +11,12 @@ class CallRegistryCompileAssertions {
         // @ts-expect-error ALL cannot select a method
         CallRegistry_1.CallRegistry.setStrategy(undefined, 'ALL', 'work');
     }
+    /** The transport fallback is a TransportDefault (timeout + optional strategy), never a bare number. */
+    fallbackIsATransportDefault() {
+        const context = new CallStrategy_1.CallContext('Api', 'work', HttpEndpointOptions_1.WRITE);
+        void CallRegistry_1.CallRegistry.execute(CallRegistryCompileAssertions, context, (ms) => Promise.resolve(ms), 
+        // @ts-expect-error execute(..., defaultMs: number) became execute(..., fallback: TransportDefault)
+        30_000);
+    }
 }
 //# sourceMappingURL=CallRegistryCompileAssertions.js.map

package/src/http/CallRegistryCompileAssertions.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallRegistryCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistryCompileAssertions.ts"],"names":[],"mappings":";;AAAA,iDAA8C;AAE9C,4DAA4D;AAC5D,MAAM,6BAA6B;IAC/B,KAAK;QACD,8CAA8C;QAC9C,2BAAY,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC5C,8CAA8C;QAC9C,2BAAY,CAAC,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;CACJ","sourcesContent":["import { CallRegistry } from './CallRegistry';\n\n/** Compiled by tsc (spec files are not), never executed. */\nclass CallRegistryCompileAssertions {\n    check(): void {\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setTimeout(100, 'ALL', 'work');\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setStrategy(undefined, 'ALL', 'work');\n    }\n}\n"]}
+{"version":3,"file":"CallRegistryCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistryCompileAssertions.ts"],"names":[],"mappings":";;AAAA,iDAA8C;AAC9C,iDAA6C;AAC7C,+DAA8C;AAE9C,4DAA4D;AAC5D,MAAM,6BAA6B;IAC/B,KAAK;QACD,8CAA8C;QAC9C,2BAAY,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC5C,8CAA8C;QAC9C,2BAAY,CAAC,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,uGAAuG;IACvG,2BAA2B;QACvB,MAAM,OAAO,GAAG,IAAI,0BAAW,CAAC,KAAK,EAAE,MAAM,EAAE,2BAAK,CAAC,CAAC;QACtD,KAAK,2BAAY,CAAC,OAAO,CACrB,6BAA6B,EAC7B,OAAO,EACP,CAAC,EAAU,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,mGAAmG;QACnG,MAAM,CACT,CAAC;IACN,CAAC;CACJ","sourcesContent":["import { CallRegistry } from './CallRegistry';\nimport { CallContext } from './CallStrategy';\nimport { WRITE } from './HttpEndpointOptions';\n\n/** Compiled by tsc (spec files are not), never executed. */\nclass CallRegistryCompileAssertions {\n    check(): void {\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setTimeout(100, 'ALL', 'work');\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setStrategy(undefined, 'ALL', 'work');\n    }\n\n    /** The transport fallback is a TransportDefault (timeout + optional strategy), never a bare number. */\n    fallbackIsATransportDefault(): void {\n        const context = new CallContext('Api', 'work', WRITE);\n        void CallRegistry.execute(\n            CallRegistryCompileAssertions,\n            context,\n            (ms: number) => Promise.resolve(ms),\n            // @ts-expect-error execute(..., defaultMs: number) became execute(..., fallback: TransportDefault)\n            30_000,\n        );\n    }\n}\n"]}

package/src/http/ClientRegistry.d.ts

@@ -1,5 +1,5 @@
 import { ErrorTranslator } from './ErrorTranslator';
-import { FailureClassifier } from './FailureClassifier';
+import { CallOutcome, ErrorClassifier, KeyedErrorClassifier } from './ErrorClassifier';
 import { ApiMethodInfo } from './ApiMethodInfo';
 /**
  * Derives a base URL for a service name that has NO registered mapping — the pluggable half of
@@ -69,20 +69,20 @@ export declare class ClientRegistry {
      */
     private static errorTranslator;
     /**
-     * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
-     * so a single strategy covers the server router AND all internal clients. NEVER undefined: it
-     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}) and
-     * {@link ClientRegistry.setDefaultFailureClassifier} replaces it. Populated once at startup on the
+     * The app/company DEFAULT {@link ErrorClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
+     * so a single classifier covers the server router AND all internal clients. NEVER undefined: it
+     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}) and
+     * {@link ClientRegistry.setDefaultErrorClassifier} replaces it. Populated once at startup on the
      * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.
      */
-    private static appDefaultFailureClassifier;
+    private static appDefaultErrorClassifier;
     /**
-     * Per-EXTERNAL-client {@link FailureClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
+     * Per-EXTERNAL-client {@link ErrorClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
      * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external
      * client overrides the default for its own apiClass only. Internal clients / the server register
-     * nothing here and fall through to the default. See {@link ClientRegistry.classifyFailure}.
+     * nothing here and fall through to the default. See {@link ClientRegistry.classify}.
      */
-    private static readonly failureClassifiersByApiClass;
+    private static readonly errorClassifiersByApiClass;
     /** Map a service name to `http://localhost:<port>`. */
     static addMapping(svcName: string, port: number): void;
     /**
@@ -138,33 +138,35 @@ export declare class ClientRegistry {
      */
     static getErrorTranslator(): ErrorTranslator;
     /**
-     * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and
+     * Set the app/company DEFAULT error classifier — ONE per process, covering the server router and
      * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the
      * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier
-     * claims. See {@link FailureClassifier}.
+     * claims. See {@link ErrorClassifier}.
      */
-    static setDefaultFailureClassifier(classifier: FailureClassifier): void;
+    static setDefaultErrorClassifier(classifier: ErrorClassifier): void;
     /**
-     * Register a per-EXTERNAL-client failure classifier, keyed by {@link ApiMethodInfo.apiClass}
-     * (e.g. 'FirestoreAdminClient'). Consulted BEFORE the default tier for calls with that apiClass.
-     * Call ONCE at startup. See {@link FailureClassifier}.
+     * Register a per-EXTERNAL-client error classifier, keyed by its
+     * {@link KeyedErrorClassifier.apiClass} (e.g. 'FirestoreAdminClient'). Consulted BEFORE the
+     * default tier for calls with that apiClass. Call ONCE at startup. See {@link ErrorClassifier}.
      */
-    static addFailureClassifier(apiClass: string, classifier: FailureClassifier): void;
+    static addErrorClassifier(keyed: KeyedErrorClassifier): void;
     /**
-     * Is this thrown API-call error a real FAILURE (true) or an expected non-failure (false)?
-     * Resolved most-specific-first, and ALWAYS definitive (returns a boolean):
+     * The {@link CallOutcome} of a thrown API-call error. Resolved most-specific-first, and ALWAYS
+     * definitive:
      *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;
-     *   2. else the app default classifier, if one was set — unless it defers;
-     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}), which never defers.
-     * A `?? true` backstop keeps an unexpectedly-deferring built-in fail-safe (treat as failure).
+     *   2. else the app default classifier — unless it defers;
+     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.
+     *
+     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `CallRegistry`'s per-attempt
+     * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.
      */
-    static classifyFailure(error: Error, methodInfo: ApiMethodInfo): boolean;
+    static classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome;
     /**
      * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec
      * cannot leak its registrations into the next.
      *
      * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole
-     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default failure
+     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default error
      * classifier are non-optional now, so "cleared" is not a state they have. A spec that wants
      * webpieces' own behaviour back asks for exactly that.
      */

package/src/http/ClientRegistry.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientRegistry = void 0;
-const WebpiecesDefaultFailureClassifier_1 = require("./WebpiecesDefaultFailureClassifier");
+const WebpiecesDefaultErrorClassifier_1 = require("./WebpiecesDefaultErrorClassifier");
 const WebpiecesDefaultErrorTranslator_1 = require("./WebpiecesDefaultErrorTranslator");
 /**
  * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every
@@ -58,20 +58,20 @@ class ClientRegistry {
      */
     static errorTranslator = WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
     /**
-     * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
-     * so a single strategy covers the server router AND all internal clients. NEVER undefined: it
-     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}) and
-     * {@link ClientRegistry.setDefaultFailureClassifier} replaces it. Populated once at startup on the
+     * The app/company DEFAULT {@link ErrorClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
+     * so a single classifier covers the server router AND all internal clients. NEVER undefined: it
+     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}) and
+     * {@link ClientRegistry.setDefaultErrorClassifier} replaces it. Populated once at startup on the
      * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.
      */
-    static appDefaultFailureClassifier = WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;
+    static appDefaultErrorClassifier = WebpiecesDefaultErrorClassifier_1.WEBPIECES_DEFAULT_ERROR_CLASSIFIER;
     /**
-     * Per-EXTERNAL-client {@link FailureClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
+     * Per-EXTERNAL-client {@link ErrorClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
      * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external
      * client overrides the default for its own apiClass only. Internal clients / the server register
-     * nothing here and fall through to the default. See {@link ClientRegistry.classifyFailure}.
+     * nothing here and fall through to the default. See {@link ClientRegistry.classify}.
      */
-    static failureClassifiersByApiClass = new Map();
+    static errorClassifiersByApiClass = new Map();
     /** 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) {
@@ -177,53 +177,55 @@ class ClientRegistry {
         return ClientRegistry.errorTranslator;
     }
     /**
-     * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and
+     * Set the app/company DEFAULT error classifier — ONE per process, covering the server router and
      * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the
      * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier
-     * claims. See {@link FailureClassifier}.
+     * claims. See {@link ErrorClassifier}.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static setDefaultFailureClassifier(classifier) {
-        ClientRegistry.appDefaultFailureClassifier = classifier;
+    static setDefaultErrorClassifier(classifier) {
+        ClientRegistry.appDefaultErrorClassifier = classifier;
     }
     /**
-     * Register a per-EXTERNAL-client failure classifier, keyed by {@link ApiMethodInfo.apiClass}
-     * (e.g. 'FirestoreAdminClient'). Consulted BEFORE the default tier for calls with that apiClass.
-     * Call ONCE at startup. See {@link FailureClassifier}.
+     * Register a per-EXTERNAL-client error classifier, keyed by its
+     * {@link KeyedErrorClassifier.apiClass} (e.g. 'FirestoreAdminClient'). Consulted BEFORE the
+     * default tier for calls with that apiClass. Call ONCE at startup. See {@link ErrorClassifier}.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static addFailureClassifier(apiClass, classifier) {
-        ClientRegistry.failureClassifiersByApiClass.set(apiClass, classifier);
+    static addErrorClassifier(keyed) {
+        ClientRegistry.errorClassifiersByApiClass.set(keyed.apiClass, keyed.classifier);
     }
     /**
-     * Is this thrown API-call error a real FAILURE (true) or an expected non-failure (false)?
-     * Resolved most-specific-first, and ALWAYS definitive (returns a boolean):
+     * The {@link CallOutcome} of a thrown API-call error. Resolved most-specific-first, and ALWAYS
+     * definitive:
      *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;
-     *   2. else the app default classifier, if one was set — unless it defers;
-     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}), which never defers.
-     * A `?? true` backstop keeps an unexpectedly-deferring built-in fail-safe (treat as failure).
+     *   2. else the app default classifier — unless it defers;
+     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.
+     *
+     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `CallRegistry`'s per-attempt
+     * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static classifyFailure(error, methodInfo) {
-        const perClient = ClientRegistry.failureClassifiersByApiClass.get(methodInfo.apiClass);
+    static classify(error, methodInfo) {
+        const perClient = ClientRegistry.errorClassifiersByApiClass.get(methodInfo.apiClass);
         if (perClient !== undefined) {
-            const verdict = perClient.isFailure(error, methodInfo);
+            const verdict = perClient.classify(error, methodInfo);
             if (verdict !== undefined) {
                 return verdict;
             }
         }
-        const verdict = ClientRegistry.appDefaultFailureClassifier.isFailure(error, methodInfo);
+        const verdict = ClientRegistry.appDefaultErrorClassifier.classify(error, methodInfo);
         if (verdict !== undefined) {
             return verdict;
         }
-        return WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(error, methodInfo) ?? true;
+        return WebpiecesDefaultErrorClassifier_1.WEBPIECES_DEFAULT_ERROR_CLASSIFIER.classify(error, methodInfo);
     }
     /**
      * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec
      * cannot leak its registrations into the next.
      *
      * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole
-     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default failure
+     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default error
      * classifier are non-optional now, so "cleared" is not a state they have. A spec that wants
      * webpieces' own behaviour back asks for exactly that.
      */
@@ -232,8 +234,8 @@ class ClientRegistry {
         ClientRegistry.mappings.clear();
         ClientRegistry.deriver = undefined;
         ClientRegistry.errorTranslator = WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
-        ClientRegistry.appDefaultFailureClassifier = WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;
-        ClientRegistry.failureClassifiersByApiClass.clear();
+        ClientRegistry.appDefaultErrorClassifier = WebpiecesDefaultErrorClassifier_1.WEBPIECES_DEFAULT_ERROR_CLASSIFIER;
+        ClientRegistry.errorClassifiersByApiClass.clear();
     }
 }
 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":"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","sourcesContent":["import { ErrorTranslator } from './ErrorTranslator';\nimport { FailureClassifier } from './FailureClassifier';\nimport { WEBPIECES_DEFAULT_FAILURE_CLASSIFIER } from './WebpiecesDefaultFailureClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { ApiMethodInfo } from './ApiMethodInfo';\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 * A `svcName` should be the nx MODULE name of the service you are calling — that is the one name\n * `architecture:validate-runtime-architecture` can verify actually exists, so a typo or a rename\n * fails the build instead of failing in production. When the DEPLOYED name differs (an environment\n * prefix like `tf-`, or a Cloud Run service named unlike its module), translate it in ONE place —\n * the deriver below, or a `serviceName` alias in the module's project.json — never at the call site.\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     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}\n     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same\n     * no-DI pattern as {@link ClientRegistry.mappings} above.\n     *\n     * There is no \"did anyone register one\" question anywhere in the framework because this field\n     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an\n     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.\n     *\n     * ONE, not a list, on purpose: an app that has several layers of error policy composes them\n     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit\n     * in the order two unrelated startup paths happened to register.\n     */\n    private static errorTranslator: ErrorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n\n    /**\n     * The app/company DEFAULT {@link FailureClassifier} — ONE per process, reads {@link ApiMethodInfo.side}\n     * so a single strategy covers the server router AND all internal clients. NEVER undefined: it\n     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}) and\n     * {@link ClientRegistry.setDefaultFailureClassifier} replaces it. Populated once at startup on the\n     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.\n     */\n    private static appDefaultFailureClassifier: FailureClassifier =\n        WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;\n\n    /**\n     * Per-EXTERNAL-client {@link FailureClassifier}s, keyed by {@link ApiMethodInfo.apiClass}\n     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external\n     * client overrides the default for its own apiClass only. Internal clients / the server register\n     * nothing here and fall through to the default. See {@link ClientRegistry.classifyFailure}.\n     */\n    private static readonly failureClassifiersByApiClass = new Map<string, FailureClassifier>();\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                    `  - deployed name differs from the module name (e.g. a 'tf-' prefix)? Translate it ONCE\\n` +\n                    `    in the deriver — setDeriver(s => gcpCloudRunDeriver()('tf-' + s)) — so every call\\n` +\n                    `    site keeps naming the MODULE, which architecture:validate-runtime-architecture checks`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for\n     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping\n     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring\n     * {@link ClientRegistry.addMapping}.\n     *\n     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setErrorTranslator(translator: ErrorTranslator): void {\n        ClientRegistry.errorTranslator = translator;\n    }\n\n    /**\n     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.\n     *\n     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and\n     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),\n     * so every call site in the framework is one unconditional line.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static getErrorTranslator(): ErrorTranslator {\n        return ClientRegistry.errorTranslator;\n    }\n\n    /**\n     * Set the app/company DEFAULT failure classifier — ONE per process, covering the server router and\n     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the\n     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier\n     * claims. See {@link FailureClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDefaultFailureClassifier(classifier: FailureClassifier): void {\n        ClientRegistry.appDefaultFailureClassifier = classifier;\n    }\n\n    /**\n     * Register a per-EXTERNAL-client failure classifier, keyed by {@link ApiMethodInfo.apiClass}\n     * (e.g. 'FirestoreAdminClient'). Consulted BEFORE the default tier for calls with that apiClass.\n     * Call ONCE at startup. See {@link FailureClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addFailureClassifier(apiClass: string, classifier: FailureClassifier): void {\n        ClientRegistry.failureClassifiersByApiClass.set(apiClass, classifier);\n    }\n\n    /**\n     * Is this thrown API-call error a real FAILURE (true) or an expected non-failure (false)?\n     * Resolved most-specific-first, and ALWAYS definitive (returns a boolean):\n     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;\n     *   2. else the app default classifier, if one was set — unless it defers;\n     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_FAILURE_CLASSIFIER}), which never defers.\n     * A `?? true` backstop keeps an unexpectedly-deferring built-in fail-safe (treat as failure).\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static classifyFailure(error: Error, methodInfo: ApiMethodInfo): boolean {\n        const perClient = ClientRegistry.failureClassifiersByApiClass.get(methodInfo.apiClass);\n        if (perClient !== undefined) {\n            const verdict = perClient.isFailure(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        const verdict = ClientRegistry.appDefaultFailureClassifier.isFailure(error, methodInfo);\n        if (verdict !== undefined) {\n            return verdict;\n        }\n        return WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(error, methodInfo) ?? true;\n    }\n\n    /**\n     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec\n     * cannot leak its registrations into the next.\n     *\n     * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole\n     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default failure\n     * classifier are non-optional now, so \"cleared\" is not a state they have. A spec that wants\n     * webpieces' own behaviour back asks for exactly that.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static resetForTests(): void {\n        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n        ClientRegistry.appDefaultFailureClassifier = WEBPIECES_DEFAULT_FAILURE_CLASSIFIER;\n        ClientRegistry.failureClassifiersByApiClass.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 { ErrorTranslator } from './ErrorTranslator';\nimport { CallOutcome, ErrorClassifier, KeyedErrorClassifier } from './ErrorClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_CLASSIFIER } from './WebpiecesDefaultErrorClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { ApiMethodInfo } from './ApiMethodInfo';\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 * A `svcName` should be the nx MODULE name of the service you are calling — that is the one name\n * `architecture:validate-runtime-architecture` can verify actually exists, so a typo or a rename\n * fails the build instead of failing in production. When the DEPLOYED name differs (an environment\n * prefix like `tf-`, or a Cloud Run service named unlike its module), translate it in ONE place —\n * the deriver below, or a `serviceName` alias in the module's project.json — never at the call site.\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     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}\n     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same\n     * no-DI pattern as {@link ClientRegistry.mappings} above.\n     *\n     * There is no \"did anyone register one\" question anywhere in the framework because this field\n     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an\n     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.\n     *\n     * ONE, not a list, on purpose: an app that has several layers of error policy composes them\n     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit\n     * in the order two unrelated startup paths happened to register.\n     */\n    private static errorTranslator: ErrorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n\n    /**\n     * The app/company DEFAULT {@link ErrorClassifier} — ONE per process, reads {@link ApiMethodInfo.side}\n     * so a single classifier covers the server router AND all internal clients. NEVER undefined: it\n     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}) and\n     * {@link ClientRegistry.setDefaultErrorClassifier} replaces it. Populated once at startup on the\n     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.\n     */\n    private static appDefaultErrorClassifier: ErrorClassifier = WEBPIECES_DEFAULT_ERROR_CLASSIFIER;\n\n    /**\n     * Per-EXTERNAL-client {@link ErrorClassifier}s, keyed by {@link ApiMethodInfo.apiClass}\n     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external\n     * client overrides the default for its own apiClass only. Internal clients / the server register\n     * nothing here and fall through to the default. See {@link ClientRegistry.classify}.\n     */\n    private static readonly errorClassifiersByApiClass = new Map<string, ErrorClassifier>();\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                    `  - deployed name differs from the module name (e.g. a 'tf-' prefix)? Translate it ONCE\\n` +\n                    `    in the deriver — setDeriver(s => gcpCloudRunDeriver()('tf-' + s)) — so every call\\n` +\n                    `    site keeps naming the MODULE, which architecture:validate-runtime-architecture checks`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for\n     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping\n     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring\n     * {@link ClientRegistry.addMapping}.\n     *\n     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setErrorTranslator(translator: ErrorTranslator): void {\n        ClientRegistry.errorTranslator = translator;\n    }\n\n    /**\n     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.\n     *\n     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and\n     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),\n     * so every call site in the framework is one unconditional line.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static getErrorTranslator(): ErrorTranslator {\n        return ClientRegistry.errorTranslator;\n    }\n\n    /**\n     * Set the app/company DEFAULT error classifier — ONE per process, covering the server router and\n     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the\n     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier\n     * claims. See {@link ErrorClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDefaultErrorClassifier(classifier: ErrorClassifier): void {\n        ClientRegistry.appDefaultErrorClassifier = classifier;\n    }\n\n    /**\n     * Register a per-EXTERNAL-client error classifier, keyed by its\n     * {@link KeyedErrorClassifier.apiClass} (e.g. 'FirestoreAdminClient'). Consulted BEFORE the\n     * default tier for calls with that apiClass. Call ONCE at startup. See {@link ErrorClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addErrorClassifier(keyed: KeyedErrorClassifier): void {\n        ClientRegistry.errorClassifiersByApiClass.set(keyed.apiClass, keyed.classifier);\n    }\n\n    /**\n     * The {@link CallOutcome} of a thrown API-call error. Resolved most-specific-first, and ALWAYS\n     * definitive:\n     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;\n     *   2. else the app default classifier — unless it defers;\n     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.\n     *\n     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `CallRegistry`'s per-attempt\n     * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome {\n        const perClient = ClientRegistry.errorClassifiersByApiClass.get(methodInfo.apiClass);\n        if (perClient !== undefined) {\n            const verdict = perClient.classify(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        const verdict = ClientRegistry.appDefaultErrorClassifier.classify(error, methodInfo);\n        if (verdict !== undefined) {\n            return verdict;\n        }\n        return WEBPIECES_DEFAULT_ERROR_CLASSIFIER.classify(error, methodInfo);\n    }\n\n    /**\n     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec\n     * cannot leak its registrations into the next.\n     *\n     * It RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole\n     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default error\n     * classifier are non-optional now, so \"cleared\" is not a state they have. A spec that wants\n     * webpieces' own behaviour back asks for exactly that.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static resetForTests(): void {\n        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n        ClientRegistry.appDefaultErrorClassifier = WEBPIECES_DEFAULT_ERROR_CLASSIFIER;\n        ClientRegistry.errorClassifiersByApiClass.clear();\n    }\n}\n"]}