@webpieces/core-util 0.4.894 → 0.4.896

package/src/http/ErrorClassifier.d.ts

@@ -0,0 +1,64 @@
+import { ApiMethodInfo } from './ApiMethodInfo';
+/**
+ * The ONE verdict on a thrown API-call error. Three readers share it, so there is exactly one table
+ * answering "is this error expected, and is it worth repeating?":
+ *
+ * - `RetryStrategy` retries only {@link CallOutcome.TRANSIENT_FAILURE} (and only on a `READ` /
+ *   `WRITE_IDEMPOTENT` endpoint — the ENDPOINT's safety is `CallContext.operation`'s question, never
+ *   the classifier's);
+ * - `LogApiCall` logs {@link CallOutcome.EXPECTED} as `[API-*-resp-OTHER]` (`result='success'`) and
+ *   both failure outcomes as `[API-*-resp-FAIL]` (`result='failure'`);
+ * - the MCP tool-call renderer derives its model-visible `retry` advice from the outcome plus the
+ *   endpoint's operation.
+ */
+export declare enum CallOutcome {
+    /** It threw, but things are WORKING: a 266, a server-side 4xx, an external client's "404 = miss". */
+    EXPECTED = "expected",
+    /** Broken NOW, may work if repeated: unavailable, connection, timeouts, 429/backoff, bad-gateway. */
+    TRANSIENT_FAILURE = "transient",
+    /** Broken, and repeating will not help: a RECEIVED 4xx (our bug), implementation, 501, retries exhausted. */
+    FAILURE = "failure"
+}
+/**
+ * Classifies a thrown API-call error into a {@link CallOutcome}.
+ *
+ * This is BEHAVIOR, so it is an interface (per CLAUDE.md), passed as an object with a NAMED method
+ * rather than a bare function — so "find usages" in an IDE lands on every implementation.
+ *
+ * Registered on {@link ClientRegistry} at startup — the same browser-safe, no-DI, populated-once
+ * singleton that owns URL mappings and the {@link ErrorTranslator}. Resolved most-specific first by
+ * {@link ClientRegistry.classify}:
+ *
+ * 1. `ClientRegistry.addErrorClassifier(new KeyedErrorClassifier(apiClass, c))` — per EXTERNAL
+ *    client, keyed by {@link ApiMethodInfo.apiClass} ('FirestoreAdminClient', 'ClaudeApi',
+ *    'TwilioApi'). Each external API qualifies its errors differently (a Firestore 404 miss is
+ *    EXPECTED; a Twilio 429 is TRANSIENT), so it overrides the tiers below for that apiClass only.
+ * 2. `ClientRegistry.setDefaultErrorClassifier(c)` — ONE per app/company. It reads
+ *    {@link ApiMethodInfo.side}, so a single classifier covers the SERVER router AND every INTERNAL
+ *    client (webpieces http client, cloud tasks).
+ * 3. {@link WebpiecesDefaultErrorClassifier} — the terminal tier, which never defers.
+ *
+ * Internal clients and the server register NOTHING — the ABSENCE of an apiClass entry is the signal.
+ * An external client that forgets to register is FAIL-SAFE: it falls to the tiers below, where every
+ * client-side error except a 266 is a failure.
+ */
+export interface ErrorClassifier {
+    /**
+     * @param error - the already-normalized thrown error (callers pass `toError(err)`)
+     * @param methodInfo - the call identity; `side` distinguishes server/client, `apiClass` the client
+     * @returns the outcome, or `undefined` to DEFER to the next tier (a per-apiClass classifier defers
+     *   to the app default; the app default defers to the webpieces built-in). Deferring is what
+     *   makes classifiers additive AND override-capable.
+     */
+    classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome | undefined;
+}
+/**
+ * A per-external-client registration pair: the {@link ApiMethodInfo.apiClass} to key on, and the
+ * {@link ErrorClassifier} to apply for it. Data only, so it is a class (not an inline object literal),
+ * per CLAUDE.md — handed to {@link ClientRegistry.addErrorClassifier}.
+ */
+export declare class KeyedErrorClassifier {
+    readonly apiClass: string;
+    readonly classifier: ErrorClassifier;
+    constructor(apiClass: string, classifier: ErrorClassifier);
+}

package/src/http/ErrorClassifier.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyedErrorClassifier = exports.CallOutcome = void 0;
+/**
+ * The ONE verdict on a thrown API-call error. Three readers share it, so there is exactly one table
+ * answering "is this error expected, and is it worth repeating?":
+ *
+ * - `RetryStrategy` retries only {@link CallOutcome.TRANSIENT_FAILURE} (and only on a `READ` /
+ *   `WRITE_IDEMPOTENT` endpoint — the ENDPOINT's safety is `CallContext.operation`'s question, never
+ *   the classifier's);
+ * - `LogApiCall` logs {@link CallOutcome.EXPECTED} as `[API-*-resp-OTHER]` (`result='success'`) and
+ *   both failure outcomes as `[API-*-resp-FAIL]` (`result='failure'`);
+ * - the MCP tool-call renderer derives its model-visible `retry` advice from the outcome plus the
+ *   endpoint's operation.
+ */
+var CallOutcome;
+(function (CallOutcome) {
+    /** It threw, but things are WORKING: a 266, a server-side 4xx, an external client's "404 = miss". */
+    CallOutcome["EXPECTED"] = "expected";
+    /** Broken NOW, may work if repeated: unavailable, connection, timeouts, 429/backoff, bad-gateway. */
+    CallOutcome["TRANSIENT_FAILURE"] = "transient";
+    /** Broken, and repeating will not help: a RECEIVED 4xx (our bug), implementation, 501, retries exhausted. */
+    CallOutcome["FAILURE"] = "failure";
+})(CallOutcome || (exports.CallOutcome = CallOutcome = {}));
+/**
+ * A per-external-client registration pair: the {@link ApiMethodInfo.apiClass} to key on, and the
+ * {@link ErrorClassifier} to apply for it. Data only, so it is a class (not an inline object literal),
+ * per CLAUDE.md — handed to {@link ClientRegistry.addErrorClassifier}.
+ */
+class KeyedErrorClassifier {
+    apiClass;
+    classifier;
+    constructor(apiClass, classifier) {
+        this.apiClass = apiClass;
+        this.classifier = classifier;
+    }
+}
+exports.KeyedErrorClassifier = KeyedErrorClassifier;
+//# sourceMappingURL=ErrorClassifier.js.map

package/src/http/ErrorClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorClassifier.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorClassifier.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,IAAY,WAOX;AAPD,WAAY,WAAW;IACnB,qGAAqG;IACrG,oCAAqB,CAAA;IACrB,qGAAqG;IACrG,8CAA+B,CAAA;IAC/B,6GAA6G;IAC7G,kCAAmB,CAAA;AACvB,CAAC,EAPW,WAAW,2BAAX,WAAW,QAOtB;AAoCD;;;;GAIG;AACH,MAAa,oBAAoB;IAET;IACA;IAFpB,YACoB,QAAgB,EAChB,UAA2B;QAD3B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,eAAU,GAAV,UAAU,CAAiB;IAC5C,CAAC;CACP;AALD,oDAKC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * The ONE verdict on a thrown API-call error. Three readers share it, so there is exactly one table\n * answering \"is this error expected, and is it worth repeating?\":\n *\n * - `RetryStrategy` retries only {@link CallOutcome.TRANSIENT_FAILURE} (and only on a `READ` /\n *   `WRITE_IDEMPOTENT` endpoint — the ENDPOINT's safety is `CallContext.operation`'s question, never\n *   the classifier's);\n * - `LogApiCall` logs {@link CallOutcome.EXPECTED} as `[API-*-resp-OTHER]` (`result='success'`) and\n *   both failure outcomes as `[API-*-resp-FAIL]` (`result='failure'`);\n * - the MCP tool-call renderer derives its model-visible `retry` advice from the outcome plus the\n *   endpoint's operation.\n */\nexport enum CallOutcome {\n    /** It threw, but things are WORKING: a 266, a server-side 4xx, an external client's \"404 = miss\". */\n    EXPECTED = 'expected',\n    /** Broken NOW, may work if repeated: unavailable, connection, timeouts, 429/backoff, bad-gateway. */\n    TRANSIENT_FAILURE = 'transient',\n    /** Broken, and repeating will not help: a RECEIVED 4xx (our bug), implementation, 501, retries exhausted. */\n    FAILURE = 'failure',\n}\n\n/**\n * Classifies a thrown API-call error into a {@link CallOutcome}.\n *\n * This is BEHAVIOR, so it is an interface (per CLAUDE.md), passed as an object with a NAMED method\n * rather than a bare function — so \"find usages\" in an IDE lands on every implementation.\n *\n * Registered on {@link ClientRegistry} at startup — the same browser-safe, no-DI, populated-once\n * singleton that owns URL mappings and the {@link ErrorTranslator}. Resolved most-specific first by\n * {@link ClientRegistry.classify}:\n *\n * 1. `ClientRegistry.addErrorClassifier(new KeyedErrorClassifier(apiClass, c))` — per EXTERNAL\n *    client, keyed by {@link ApiMethodInfo.apiClass} ('FirestoreAdminClient', 'ClaudeApi',\n *    'TwilioApi'). Each external API qualifies its errors differently (a Firestore 404 miss is\n *    EXPECTED; a Twilio 429 is TRANSIENT), so it overrides the tiers below for that apiClass only.\n * 2. `ClientRegistry.setDefaultErrorClassifier(c)` — ONE per app/company. It reads\n *    {@link ApiMethodInfo.side}, so a single classifier covers the SERVER router AND every INTERNAL\n *    client (webpieces http client, cloud tasks).\n * 3. {@link WebpiecesDefaultErrorClassifier} — the terminal tier, which never defers.\n *\n * Internal clients and the server register NOTHING — the ABSENCE of an apiClass entry is the signal.\n * An external client that forgets to register is FAIL-SAFE: it falls to the tiers below, where every\n * client-side error except a 266 is a failure.\n */\nexport interface ErrorClassifier {\n    /**\n     * @param error - the already-normalized thrown error (callers pass `toError(err)`)\n     * @param methodInfo - the call identity; `side` distinguishes server/client, `apiClass` the client\n     * @returns the outcome, or `undefined` to DEFER to the next tier (a per-apiClass classifier defers\n     *   to the app default; the app default defers to the webpieces built-in). Deferring is what\n     *   makes classifiers additive AND override-capable.\n     */\n    classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome | undefined;\n}\n\n/**\n * A per-external-client registration pair: the {@link ApiMethodInfo.apiClass} to key on, and the\n * {@link ErrorClassifier} to apply for it. Data only, so it is a class (not an inline object literal),\n * per CLAUDE.md — handed to {@link ClientRegistry.addErrorClassifier}.\n */\nexport class KeyedErrorClassifier {\n    constructor(\n        public readonly apiClass: string,\n        public readonly classifier: ErrorClassifier,\n    ) {}\n}\n"]}

package/src/http/LogApiCall.d.ts

@@ -28,8 +28,8 @@ import { ApiCallContext } from './ApiCallContext';
  * Logging format patterns:
  * - [API-{side}-req] ClassName.methodName request={...}
  * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}
- * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (user errors)
- * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)
+ * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (CallOutcome.EXPECTED)
+ * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (TRANSIENT_FAILURE or FAILURE — final by position; each retried attempt is logged by CallRegistry as [API-client-attempt-TRANSIENT])
  */
 export declare class LogApiCallImpl {
     private readonly ctx;
@@ -111,20 +111,4 @@ export declare class LogApiCallImpl {
      * and a 0 there would be a lie (JSON.stringify(undefined) returns undefined, not '').
      */
     private byteSize;
-    /**
-     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api
-     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?
-     *
-     * BACK-COMPAT SHIM: the canonical logic now lives in {@link WebpiecesDefaultFailureClassifier}
-     * (the webpieces built-in tier), and the LIVE classification path is
-     * {@link ClientRegistry.classifyFailure} (per-apiClass → app default → built-in). This method
-     * delegates to the built-in so existing callers/tests keep the exact old behavior; it does NOT
-     * consult registered classifiers. `apiClass`/`methodName` are irrelevant to the built-in (it reads
-     * only `side`), hence the empty strings.
-     *
-     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)
-     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call
-     * @returns true if this should be treated as a non-failure (OTHER / result:'success')
-     */
-    isUserError(error: Error, server: boolean): boolean;
 }

package/src/http/LogApiCall.js

@@ -4,11 +4,10 @@ exports.LogApiCallImpl = void 0;
 const errorUtils_1 = require("../lib/errorUtils");
 const LogManager_1 = require("../logging/LogManager");
 const ApiCallInfo_1 = require("./ApiCallInfo");
-const ApiMethodInfo_1 = require("./ApiMethodInfo");
 const WebpiecesCoreHeaders_1 = require("./WebpiecesCoreHeaders");
 const ApiCallLogName_1 = require("./ApiCallLogName");
 const ClientRegistry_1 = require("./ClientRegistry");
-const WebpiecesDefaultFailureClassifier_1 = require("./WebpiecesDefaultFailureClassifier");
+const ErrorClassifier_1 = require("./ErrorClassifier");
 // The console backends special-case THIS logger name into a self-describing [API.{side}.{phase}]
 // bracket (see ApiCallLogName) — so the name here and the name they match are the one constant.
 const log = LogManager_1.LogManager.getLogger(ApiCallLogName_1.LOG_API_CALL_LOGGER_NAME);
@@ -40,8 +39,8 @@ const log = LogManager_1.LogManager.getLogger(ApiCallLogName_1.LOG_API_CALL_LOGG
  * Logging format patterns:
  * - [API-{side}-req] ClassName.methodName request={...}
  * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}
- * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (user errors)
- * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)
+ * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (CallOutcome.EXPECTED)
+ * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (TRANSIENT_FAILURE or FAILURE — final by position; each retried attempt is logged by CallRegistry as [API-client-attempt-TRANSIENT])
  */
 class LogApiCallImpl {
     ctx;
@@ -224,8 +223,10 @@ class LogApiCallImpl {
         // Pluggable classification (ClientRegistry): a per-apiClass EXTERNAL-client classifier wins,
         // else the app default, else the webpieces built-in — which is side-dependent (a 4xx the SERVER
         // raised is a handled non-failure; the same 4xx a CLIENT receives means its call FAILED; 266 is
-        // never a failure either side). `isUser` = "treat as non-failure (OTHER / result:'success')".
-        const isUser = !ClientRegistry_1.ClientRegistry.classifyFailure(error, methodInfo);
+        // never a failure either side). This line is FINAL BY POSITION: it only sees what escaped every
+        // retry, so a TRANSIENT_FAILURE here was never retried (no strategy, or a WRITE) or gave up —
+        // it logs FAIL exactly like a FAILURE. Only EXPECTED is "OTHER / result:'success'".
+        const isUser = ClientRegistry_1.ClientRegistry.classify(error, methodInfo) === ErrorClassifier_1.CallOutcome.EXPECTED;
         stamp(new ApiCallInfo_1.ApiCallInfo(methodInfo, 'response', isUser ? 'success' : 'failure', durationMs, requestSize), () => isUser
             ? log.warn(`[API-${side}-resp-OTHER] ${id} errorType=${errorType} error=${error.message}`)
             : log.error(`[API-${side}-resp-FAIL] ${id} errorType=${errorType} error=${error.message}`));
@@ -246,24 +247,6 @@ class LogApiCallImpl {
         }
         return bytes;
     }
-    /**
-     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api
-     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?
-     *
-     * BACK-COMPAT SHIM: the canonical logic now lives in {@link WebpiecesDefaultFailureClassifier}
-     * (the webpieces built-in tier), and the LIVE classification path is
-     * {@link ClientRegistry.classifyFailure} (per-apiClass → app default → built-in). This method
-     * delegates to the built-in so existing callers/tests keep the exact old behavior; it does NOT
-     * consult registered classifiers. `apiClass`/`methodName` are irrelevant to the built-in (it reads
-     * only `side`), hence the empty strings.
-     *
-     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)
-     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call
-     * @returns true if this should be treated as a non-failure (OTHER / result:'success')
-     */
-    isUserError(error, server) {
-        return !WebpiecesDefaultFailureClassifier_1.WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(error, new ApiMethodInfo_1.ApiMethodInfo(server ? 'server' : 'client', '', ''));
-    }
 }
 exports.LogApiCallImpl = LogApiCallImpl;
 //# sourceMappingURL=LogApiCall.js.map

package/src/http/LogApiCall.js.map

@@ -1 +1 @@
-{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":"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","sourcesContent":["import { toError } from '../lib/errorUtils';\nimport { LogManager } from '../logging/LogManager';\nimport { ApiCallInfo } from './ApiCallInfo';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { ApiCallContext } from './ApiCallContext';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { ClientRegistry } from './ClientRegistry';\nimport { WEBPIECES_DEFAULT_FAILURE_CLASSIFIER } from './WebpiecesDefaultFailureClassifier';\n\n// The console backends special-case THIS logger name into a self-describing [API.{side}.{phase}]\n// bracket (see ApiCallLogName) — so the name here and the name they match are the one constant.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\n/**\n * LogApiCallImpl - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and\n * client-side (ProxyClient) for one consistent logging shape across the framework.\n *\n * TWO things happen around each call:\n * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).\n * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the\n *    {@link ApiCallContext} seam, so EVERY log line emitted during the call (not just the\n *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as\n *    `jsonPayload.api.{method.{side,apiClass,methodName,controllerName},type,result}`.\n *\n * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →\n * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).\n * It stamps through the {@link ApiCallContext} seam instead, and takes that seam as a REQUIRED\n * CONSTRUCTOR ARGUMENT — there is no process-global holder to install and none to forget. Each\n * environment-specific package constructs its own:\n *\n *   LogApiFilter        (@webpieces/http-routing)        -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   NodeProxyClient     (@webpieces/http-client-node)    -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   TaskProxyClient     (@webpieces/cloudtasks-client)   -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   BrowserProxyClient  (@webpieces/http-client-browser) -> new LogApiCallImpl(new BrowserApiCallContext())\n *\n * NOT a singleton, deliberately: a shared instance would need a shared context, which is the global\n * this constructor replaced. Construct one where you know which environment you are in.\n *\n * Logging format patterns:\n * - [API-{side}-req] ClassName.methodName request={...}\n * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (user errors)\n * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)\n */\nexport class LogApiCallImpl {\n    /**\n     * @param ctx - the environment's {@link ApiCallContext}. REQUIRED, with no default: that is what\n     *   turns \"nobody bootstrapped the context\" into a compile error instead of a throw on the first\n     *   real call in production.\n     */\n    constructor(private readonly ctx: ApiCallContext) {}\n\n    /**\n     * Execute an API call with logging + `api` context-tagging around it.\n     *\n     * @param methodInfo - The transport-neutral call identity (side, apiClass, methodName,\n     *   controllerName?). `apiClass` is what matches a client call to its server handler in the logs.\n     * @param requestDto - The request DTO (external multi-param callers synthesize a small object)\n     * @param method - The method to execute\n     *\n     * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,\n     * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only\n     * for the SYNCHRONOUS span of each log line: set → log → remove. Because the tag is never held across\n     * `await method(...)`, a concurrent browser call (single-threaded, one global slot) can never clobber\n     * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is\n     * exactly what the GCP filters (`jsonPayload.api.*`) want.\n     */\n    public async execute<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n        responseCount?: (response: R) => number | undefined,\n    ): Promise<R> {\n        if (methodInfo.noLogging) {\n            return this.executeUnlogged(methodInfo, requestDto, method);\n        }\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const stamp = this.stamper(this.activeContext());\n\n        // Stringify ONCE and reuse for both the log text and the size — a second JSON.stringify of a\n        // large DTO purely to measure it would double the cost of the thing we are measuring.\n        // Only take the field-masking hit when this call declared sensitive fields; otherwise the plain\n        // JSON.stringify fast path, unchanged for every existing caller.\n        const requestBody = this.serialize(requestDto, methodInfo);\n        const requestSize = this.byteSize(requestBody);\n        // Declared out here so the catch below can read it too. Reassigned just before the call, so\n        // the number times ONLY the call and not our own request-logging.\n        let startMs = Date.now();\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            stamp(new ApiCallInfo(methodInfo, 'request', undefined, undefined, requestSize), () =>\n                log.info(`[API-${side}-req] ${id} request=${requestBody}`),\n            );\n\n            if (!requestDto) throw new Error(`Request cannot be null and was from ${id}`);\n\n            startMs = Date.now();\n            const response = await method(requestDto);\n            const durationMs = Date.now() - startMs;\n\n            const responseBody = this.serialize(response, methodInfo);\n            const count = this.selectResponseCount(response, responseCount, side, id);\n            stamp(\n                new ApiCallInfo(\n                    methodInfo,\n                    'response',\n                    'success',\n                    durationMs,\n                    requestSize,\n                    this.byteSize(responseBody),\n                    count,\n                ),\n                () => log.info(`[API-${side}-resp-SUCCESS] ${id} response=${responseBody}`),\n            );\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            // Duration comes off the SAME start as the success path, so a slow failure (a timeout, a\n            // hung dependency) reports its real cost rather than nothing.\n            this.logFailure(error, methodInfo, Date.now() - startMs, requestSize, stamp);\n            throw err;\n        }\n    }\n\n    /**\n     * Build the tag-and-emit span used around every `[API-*]` line.\n     *\n     * set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,\n     * never across an await, so a single browser global slot can never be clobbered by a concurrent\n     * call. `ctx` is passed in (rather than read from `this`) so the caller has already proven it is\n     * ACTIVE before anything is stamped.\n     */\n    private stamper(ctx: ApiCallContext): (info: ApiCallInfo, emit: () => void) => void {\n        const key = WebpiecesCoreHeaders.API_CALL_INFO;\n        return (info: ApiCallInfo, emit: () => void): void => {\n            ctx.set(key, info);\n            // webpieces-disable no-unmanaged-exceptions -- cleanup must run when a logging backend throws\n            try {\n                emit();\n            } finally {\n                ctx.remove(key);\n            }\n        };\n    }\n\n    /**\n     * The `@Endpoint(..., { noLogging: true })` path: run the call and say NOTHING about it.\n     *\n     * No `[API-*]` line, no {@link ApiCallInfo} stamp, and no serialization of either DTO — a\n     * noLogging route is a log shipper or a log-ingest endpoint, so a line describing the call IS the\n     * thing being shipped, and emitting it feeds the next batch its own payload (#976).\n     *\n     * It deliberately does NOT call {@link activeContext}: that guard exists because a call with\n     * nowhere to STAMP a tag is a bug, and this path stamps nothing. A noLogging call is therefore\n     * legal outside a RequestContext scope, which is exactly where a flusher tends to run.\n     *\n     * The null-request check is kept, because it is a contract error and not observability — a\n     * noLogging route deserves the same error as every other route, and the throw propagates to the caller\n     * unlogged here, exactly as the logged path re-throws.\n     *\n     * `responseCount` is not taken: it feeds only the `api.responseCount` tag, which is not emitted.\n     */\n    private async executeUnlogged<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n    ): Promise<R> {\n        if (!requestDto) {\n            throw new Error(\n                `Request cannot be null and was from ${methodInfo.apiClass}.${methodInfo.methodName}`,\n            );\n        }\n        return method(requestDto);\n    }\n\n    /**\n     * Evaluate an opt-in logical-item count without allowing observability code to affect the call.\n     * Warnings deliberately contain neither request nor response bodies (nor the invalid value).\n     */\n    private selectResponseCount<R>(\n        response: R,\n        selector: ((response: R) => number | undefined) | undefined,\n        side: string,\n        id: string,\n    ): number | undefined {\n        if (!selector) {\n            return undefined;\n        }\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an observability callback must not fail the API call\n        try {\n            const count = selector(response);\n            if (\n                count === undefined ||\n                (Number.isFinite(count) && Number.isInteger(count) && count >= 0)\n            ) {\n                return count;\n            }\n            this.warnInvalidResponseCount(side, id, 'returned an invalid value');\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            this.warnInvalidResponseCount(side, id, 'threw');\n        }\n        return undefined;\n    }\n\n    private warnInvalidResponseCount(side: string, id: string, reason: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a warning backend must not replace a successful API response\n        try {\n            log.warn(\n                `[API-${side}-resp-COUNT-WARN] ${id} responseCount selector ${reason}; omitting responseCount`,\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            // The API response is authoritative; observability failures are intentionally ignored here.\n        }\n    }\n\n    /**\n     * Serialize a DTO for the LOG LINE ONLY. With no mask on the call, this is a plain JSON.stringify\n     * (byte-for-byte the old behavior, no walk) so existing callers pay nothing. With a mask, it runs\n     * {@link MaskSpec.stringify}, which produces a masked STRING without ever mutating the DTO — so the\n     * object handed to the transport, and thus the value ON THE WIRE, is unchanged.\n     */\n    private serialize(\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches execute)\n        dto: unknown,\n        methodInfo: ApiMethodInfo,\n    ): string | undefined {\n        return methodInfo.mask ? methodInfo.mask.stringify(dto) : JSON.stringify(dto);\n    }\n\n    /**\n     * The ApiCallContext to stamp into. It cannot be MISSING (it is a constructor argument), but it\n     * can be INACTIVE — a Node context used outside any `RequestContext.run(...)` scope. That throws:\n     * an api call with nowhere to tag is a bug.\n     */\n    private activeContext(): ApiCallContext {\n        const ctx = this.ctx;\n        if (!ctx.isActive()) {\n            throw new Error(\n                'LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside a ' +\n                    'RequestContext.run(...) scope — a server filter opens one per request, and a ' +\n                    'non-webpieces host must open one around the work that calls a webpieces client. ' +\n                    '(A BrowserApiCallContext is always active, so this can only be the Node side.)',\n            );\n        }\n        return ctx;\n    }\n\n    /**\n     * Tag + log a thrown call. There is no responseSize — a throw produced no response body to measure.\n     */\n    private logFailure(\n        error: Error,\n        methodInfo: ApiMethodInfo,\n        durationMs: number,\n        requestSize: number | undefined,\n        stamp: (info: ApiCallInfo, emit: () => void) => void,\n    ): void {\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const errorType = error.constructor.name;\n        // The MESSAGE is on BOTH branches, and that is load-bearing: this is the ONLY operator line\n        // per failure now that `ApiErrorBoundary` writes none. An operator error message is never\n        // published to a caller (see `ApiErrorCodec.publicMessage`), so the log is the one place it\n        // exists at all — dropping it on the caller-error branch would lose it outright.\n        // Pluggable classification (ClientRegistry): a per-apiClass EXTERNAL-client classifier wins,\n        // else the app default, else the webpieces built-in — which is side-dependent (a 4xx the SERVER\n        // raised is a handled non-failure; the same 4xx a CLIENT receives means its call FAILED; 266 is\n        // never a failure either side). `isUser` = \"treat as non-failure (OTHER / result:'success')\".\n        const isUser = !ClientRegistry.classifyFailure(error, methodInfo);\n\n        stamp(\n            new ApiCallInfo(\n                methodInfo,\n                'response',\n                isUser ? 'success' : 'failure',\n                durationMs,\n                requestSize,\n            ),\n            () =>\n                isUser\n                    ? log.warn(\n                          `[API-${side}-resp-OTHER] ${id} errorType=${errorType} error=${error.message}`,\n                      )\n                    : log.error(\n                          `[API-${side}-resp-FAIL] ${id} errorType=${errorType} error=${error.message}`,\n                      ),\n        );\n    }\n\n    /**\n     * UTF-8 byte size without platform-specific encoding globals: LogApiCall runs in the\n     * browser bundle. Undefined in, undefined out — a `Promise<void>` method has no body to measure,\n     * and a 0 there would be a lie (JSON.stringify(undefined) returns undefined, not '').\n     */\n    private byteSize(serialized: string | undefined): number | undefined {\n        if (serialized === undefined) {\n            return undefined;\n        }\n        let bytes = 0;\n        for (const character of serialized) {\n            const code = character.codePointAt(0)!;\n            bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;\n        }\n        return bytes;\n    }\n\n    /**\n     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api\n     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?\n     *\n     * BACK-COMPAT SHIM: the canonical logic now lives in {@link WebpiecesDefaultFailureClassifier}\n     * (the webpieces built-in tier), and the LIVE classification path is\n     * {@link ClientRegistry.classifyFailure} (per-apiClass → app default → built-in). This method\n     * delegates to the built-in so existing callers/tests keep the exact old behavior; it does NOT\n     * consult registered classifiers. `apiClass`/`methodName` are irrelevant to the built-in (it reads\n     * only `side`), hence the empty strings.\n     *\n     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)\n     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call\n     * @returns true if this should be treated as a non-failure (OTHER / result:'success')\n     */\n    isUserError(error: Error, server: boolean): boolean {\n        return !WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(\n            error,\n            new ApiMethodInfo(server ? 'server' : 'client', '', ''),\n        );\n    }\n}\n"]}
+{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":"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","sourcesContent":["import { toError } from '../lib/errorUtils';\nimport { LogManager } from '../logging/LogManager';\nimport { ApiCallInfo } from './ApiCallInfo';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { ApiCallContext } from './ApiCallContext';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { ClientRegistry } from './ClientRegistry';\nimport { CallOutcome } from './ErrorClassifier';\n\n// The console backends special-case THIS logger name into a self-describing [API.{side}.{phase}]\n// bracket (see ApiCallLogName) — so the name here and the name they match are the one constant.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\n/**\n * LogApiCallImpl - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and\n * client-side (ProxyClient) for one consistent logging shape across the framework.\n *\n * TWO things happen around each call:\n * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).\n * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the\n *    {@link ApiCallContext} seam, so EVERY log line emitted during the call (not just the\n *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as\n *    `jsonPayload.api.{method.{side,apiClass,methodName,controllerName},type,result}`.\n *\n * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →\n * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).\n * It stamps through the {@link ApiCallContext} seam instead, and takes that seam as a REQUIRED\n * CONSTRUCTOR ARGUMENT — there is no process-global holder to install and none to forget. Each\n * environment-specific package constructs its own:\n *\n *   LogApiFilter        (@webpieces/http-routing)        -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   NodeProxyClient     (@webpieces/http-client-node)    -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   TaskProxyClient     (@webpieces/cloudtasks-client)   -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   BrowserProxyClient  (@webpieces/http-client-browser) -> new LogApiCallImpl(new BrowserApiCallContext())\n *\n * NOT a singleton, deliberately: a shared instance would need a shared context, which is the global\n * this constructor replaced. Construct one where you know which environment you are in.\n *\n * Logging format patterns:\n * - [API-{side}-req] ClassName.methodName request={...}\n * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (CallOutcome.EXPECTED)\n * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (TRANSIENT_FAILURE or FAILURE — final by position; each retried attempt is logged by CallRegistry as [API-client-attempt-TRANSIENT])\n */\nexport class LogApiCallImpl {\n    /**\n     * @param ctx - the environment's {@link ApiCallContext}. REQUIRED, with no default: that is what\n     *   turns \"nobody bootstrapped the context\" into a compile error instead of a throw on the first\n     *   real call in production.\n     */\n    constructor(private readonly ctx: ApiCallContext) {}\n\n    /**\n     * Execute an API call with logging + `api` context-tagging around it.\n     *\n     * @param methodInfo - The transport-neutral call identity (side, apiClass, methodName,\n     *   controllerName?). `apiClass` is what matches a client call to its server handler in the logs.\n     * @param requestDto - The request DTO (external multi-param callers synthesize a small object)\n     * @param method - The method to execute\n     *\n     * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,\n     * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only\n     * for the SYNCHRONOUS span of each log line: set → log → remove. Because the tag is never held across\n     * `await method(...)`, a concurrent browser call (single-threaded, one global slot) can never clobber\n     * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is\n     * exactly what the GCP filters (`jsonPayload.api.*`) want.\n     */\n    public async execute<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n        responseCount?: (response: R) => number | undefined,\n    ): Promise<R> {\n        if (methodInfo.noLogging) {\n            return this.executeUnlogged(methodInfo, requestDto, method);\n        }\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const stamp = this.stamper(this.activeContext());\n\n        // Stringify ONCE and reuse for both the log text and the size — a second JSON.stringify of a\n        // large DTO purely to measure it would double the cost of the thing we are measuring.\n        // Only take the field-masking hit when this call declared sensitive fields; otherwise the plain\n        // JSON.stringify fast path, unchanged for every existing caller.\n        const requestBody = this.serialize(requestDto, methodInfo);\n        const requestSize = this.byteSize(requestBody);\n        // Declared out here so the catch below can read it too. Reassigned just before the call, so\n        // the number times ONLY the call and not our own request-logging.\n        let startMs = Date.now();\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            stamp(new ApiCallInfo(methodInfo, 'request', undefined, undefined, requestSize), () =>\n                log.info(`[API-${side}-req] ${id} request=${requestBody}`),\n            );\n\n            if (!requestDto) throw new Error(`Request cannot be null and was from ${id}`);\n\n            startMs = Date.now();\n            const response = await method(requestDto);\n            const durationMs = Date.now() - startMs;\n\n            const responseBody = this.serialize(response, methodInfo);\n            const count = this.selectResponseCount(response, responseCount, side, id);\n            stamp(\n                new ApiCallInfo(\n                    methodInfo,\n                    'response',\n                    'success',\n                    durationMs,\n                    requestSize,\n                    this.byteSize(responseBody),\n                    count,\n                ),\n                () => log.info(`[API-${side}-resp-SUCCESS] ${id} response=${responseBody}`),\n            );\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            // Duration comes off the SAME start as the success path, so a slow failure (a timeout, a\n            // hung dependency) reports its real cost rather than nothing.\n            this.logFailure(error, methodInfo, Date.now() - startMs, requestSize, stamp);\n            throw err;\n        }\n    }\n\n    /**\n     * Build the tag-and-emit span used around every `[API-*]` line.\n     *\n     * set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,\n     * never across an await, so a single browser global slot can never be clobbered by a concurrent\n     * call. `ctx` is passed in (rather than read from `this`) so the caller has already proven it is\n     * ACTIVE before anything is stamped.\n     */\n    private stamper(ctx: ApiCallContext): (info: ApiCallInfo, emit: () => void) => void {\n        const key = WebpiecesCoreHeaders.API_CALL_INFO;\n        return (info: ApiCallInfo, emit: () => void): void => {\n            ctx.set(key, info);\n            // webpieces-disable no-unmanaged-exceptions -- cleanup must run when a logging backend throws\n            try {\n                emit();\n            } finally {\n                ctx.remove(key);\n            }\n        };\n    }\n\n    /**\n     * The `@Endpoint(..., { noLogging: true })` path: run the call and say NOTHING about it.\n     *\n     * No `[API-*]` line, no {@link ApiCallInfo} stamp, and no serialization of either DTO — a\n     * noLogging route is a log shipper or a log-ingest endpoint, so a line describing the call IS the\n     * thing being shipped, and emitting it feeds the next batch its own payload (#976).\n     *\n     * It deliberately does NOT call {@link activeContext}: that guard exists because a call with\n     * nowhere to STAMP a tag is a bug, and this path stamps nothing. A noLogging call is therefore\n     * legal outside a RequestContext scope, which is exactly where a flusher tends to run.\n     *\n     * The null-request check is kept, because it is a contract error and not observability — a\n     * noLogging route deserves the same error as every other route, and the throw propagates to the caller\n     * unlogged here, exactly as the logged path re-throws.\n     *\n     * `responseCount` is not taken: it feeds only the `api.responseCount` tag, which is not emitted.\n     */\n    private async executeUnlogged<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n    ): Promise<R> {\n        if (!requestDto) {\n            throw new Error(\n                `Request cannot be null and was from ${methodInfo.apiClass}.${methodInfo.methodName}`,\n            );\n        }\n        return method(requestDto);\n    }\n\n    /**\n     * Evaluate an opt-in logical-item count without allowing observability code to affect the call.\n     * Warnings deliberately contain neither request nor response bodies (nor the invalid value).\n     */\n    private selectResponseCount<R>(\n        response: R,\n        selector: ((response: R) => number | undefined) | undefined,\n        side: string,\n        id: string,\n    ): number | undefined {\n        if (!selector) {\n            return undefined;\n        }\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an observability callback must not fail the API call\n        try {\n            const count = selector(response);\n            if (\n                count === undefined ||\n                (Number.isFinite(count) && Number.isInteger(count) && count >= 0)\n            ) {\n                return count;\n            }\n            this.warnInvalidResponseCount(side, id, 'returned an invalid value');\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            this.warnInvalidResponseCount(side, id, 'threw');\n        }\n        return undefined;\n    }\n\n    private warnInvalidResponseCount(side: string, id: string, reason: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a warning backend must not replace a successful API response\n        try {\n            log.warn(\n                `[API-${side}-resp-COUNT-WARN] ${id} responseCount selector ${reason}; omitting responseCount`,\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            // The API response is authoritative; observability failures are intentionally ignored here.\n        }\n    }\n\n    /**\n     * Serialize a DTO for the LOG LINE ONLY. With no mask on the call, this is a plain JSON.stringify\n     * (byte-for-byte the old behavior, no walk) so existing callers pay nothing. With a mask, it runs\n     * {@link MaskSpec.stringify}, which produces a masked STRING without ever mutating the DTO — so the\n     * object handed to the transport, and thus the value ON THE WIRE, is unchanged.\n     */\n    private serialize(\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches execute)\n        dto: unknown,\n        methodInfo: ApiMethodInfo,\n    ): string | undefined {\n        return methodInfo.mask ? methodInfo.mask.stringify(dto) : JSON.stringify(dto);\n    }\n\n    /**\n     * The ApiCallContext to stamp into. It cannot be MISSING (it is a constructor argument), but it\n     * can be INACTIVE — a Node context used outside any `RequestContext.run(...)` scope. That throws:\n     * an api call with nowhere to tag is a bug.\n     */\n    private activeContext(): ApiCallContext {\n        const ctx = this.ctx;\n        if (!ctx.isActive()) {\n            throw new Error(\n                'LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside a ' +\n                    'RequestContext.run(...) scope — a server filter opens one per request, and a ' +\n                    'non-webpieces host must open one around the work that calls a webpieces client. ' +\n                    '(A BrowserApiCallContext is always active, so this can only be the Node side.)',\n            );\n        }\n        return ctx;\n    }\n\n    /**\n     * Tag + log a thrown call. There is no responseSize — a throw produced no response body to measure.\n     */\n    private logFailure(\n        error: Error,\n        methodInfo: ApiMethodInfo,\n        durationMs: number,\n        requestSize: number | undefined,\n        stamp: (info: ApiCallInfo, emit: () => void) => void,\n    ): void {\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const errorType = error.constructor.name;\n        // The MESSAGE is on BOTH branches, and that is load-bearing: this is the ONLY operator line\n        // per failure now that `ApiErrorBoundary` writes none. An operator error message is never\n        // published to a caller (see `ApiErrorCodec.publicMessage`), so the log is the one place it\n        // exists at all — dropping it on the caller-error branch would lose it outright.\n        // Pluggable classification (ClientRegistry): a per-apiClass EXTERNAL-client classifier wins,\n        // else the app default, else the webpieces built-in — which is side-dependent (a 4xx the SERVER\n        // raised is a handled non-failure; the same 4xx a CLIENT receives means its call FAILED; 266 is\n        // never a failure either side). This line is FINAL BY POSITION: it only sees what escaped every\n        // retry, so a TRANSIENT_FAILURE here was never retried (no strategy, or a WRITE) or gave up —\n        // it logs FAIL exactly like a FAILURE. Only EXPECTED is \"OTHER / result:'success'\".\n        const isUser = ClientRegistry.classify(error, methodInfo) === CallOutcome.EXPECTED;\n\n        stamp(\n            new ApiCallInfo(\n                methodInfo,\n                'response',\n                isUser ? 'success' : 'failure',\n                durationMs,\n                requestSize,\n            ),\n            () =>\n                isUser\n                    ? log.warn(\n                          `[API-${side}-resp-OTHER] ${id} errorType=${errorType} error=${error.message}`,\n                      )\n                    : log.error(\n                          `[API-${side}-resp-FAIL] ${id} errorType=${errorType} error=${error.message}`,\n                      ),\n        );\n    }\n\n    /**\n     * UTF-8 byte size without platform-specific encoding globals: LogApiCall runs in the\n     * browser bundle. Undefined in, undefined out — a `Promise<void>` method has no body to measure,\n     * and a 0 there would be a lie (JSON.stringify(undefined) returns undefined, not '').\n     */\n    private byteSize(serialized: string | undefined): number | undefined {\n        if (serialized === undefined) {\n            return undefined;\n        }\n        let bytes = 0;\n        for (const character of serialized) {\n            const code = character.codePointAt(0)!;\n            bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;\n        }\n        return bytes;\n    }\n}\n"]}

package/src/http/RetryStrategy.d.ts

@@ -0,0 +1,32 @@
+import { CallStrategy } from './CallStrategy';
+/**
+ * THE webpieces retry strategy, shared by every transport — register its {@link RetryStrategy.run}
+ * with `CallRegistry.setStrategy(...)`, or hand it to a `TransportDefault`.
+ *
+ * Two questions, two owners, and it asks both:
+ *
+ * - **the ERROR** — `ClientRegistry.classify(error, …)`. Only `CallOutcome.TRANSIENT_FAILURE` is
+ *   retried; an EXPECTED or FAILURE outcome is a definitive answer and is rethrown unchanged.
+ * - **the ENDPOINT** — `CallContext.operation`. A `WRITE` is NEVER retried, even when this strategy is
+ *   registered at ALL: a transient error on a non-idempotent write may already have happened.
+ *
+ * Each attempt gets its own `attemptTimeoutMs` deadline. Between attempts it waits
+ * `initialDelayMs`, then multiplies by `delayMultiplier`, capped at `maxDelayMs`.
+ *
+ * When it RETRIED and ran out, it throws {@link ApiRetriesExhaustedError} (`cause` = the last
+ * attempt's error), which is classified FAILURE so no layer above retries again. A call that made a
+ * single attempt — `maxRetries` 0, a `WRITE`, a non-transient error — rethrows its own error unchanged.
+ */
+export declare class RetryStrategy {
+    readonly attemptTimeoutMs: number;
+    readonly maxRetries: number;
+    readonly initialDelayMs: number;
+    readonly delayMultiplier: number;
+    readonly maxDelayMs: number;
+    /** The {@link CallStrategy} to register. A bound field, so `strategy.run` can be passed around. */
+    readonly run: CallStrategy<unknown>;
+    constructor(attemptTimeoutMs: number, maxRetries: number, initialDelayMs: number, delayMultiplier: number, maxDelayMs: number);
+    private execute;
+    private static requireWhole;
+    private static sleep;
+}

package/src/http/RetryStrategy.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryStrategy = void 0;
+const CallDeadline_1 = require("./CallDeadline");
+const ClientRegistry_1 = require("./ClientRegistry");
+const ErrorClassifier_1 = require("./ErrorClassifier");
+const ApiMethodInfo_1 = require("./ApiMethodInfo");
+const HttpEndpointOptions_1 = require("./HttpEndpointOptions");
+const ApiError_1 = require("../errors/ApiError");
+const errorUtils_1 = require("../lib/errorUtils");
+/**
+ * THE webpieces retry strategy, shared by every transport — register its {@link RetryStrategy.run}
+ * with `CallRegistry.setStrategy(...)`, or hand it to a `TransportDefault`.
+ *
+ * Two questions, two owners, and it asks both:
+ *
+ * - **the ERROR** — `ClientRegistry.classify(error, …)`. Only `CallOutcome.TRANSIENT_FAILURE` is
+ *   retried; an EXPECTED or FAILURE outcome is a definitive answer and is rethrown unchanged.
+ * - **the ENDPOINT** — `CallContext.operation`. A `WRITE` is NEVER retried, even when this strategy is
+ *   registered at ALL: a transient error on a non-idempotent write may already have happened.
+ *
+ * Each attempt gets its own `attemptTimeoutMs` deadline. Between attempts it waits
+ * `initialDelayMs`, then multiplies by `delayMultiplier`, capped at `maxDelayMs`.
+ *
+ * When it RETRIED and ran out, it throws {@link ApiRetriesExhaustedError} (`cause` = the last
+ * attempt's error), which is classified FAILURE so no layer above retries again. A call that made a
+ * single attempt — `maxRetries` 0, a `WRITE`, a non-transient error — rethrows its own error unchanged.
+ */
+class RetryStrategy {
+    attemptTimeoutMs;
+    maxRetries;
+    initialDelayMs;
+    delayMultiplier;
+    maxDelayMs;
+    /** The {@link CallStrategy} to register. A bound field, so `strategy.run` can be passed around. */
+    // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs
+    run;
+    constructor(attemptTimeoutMs, maxRetries, initialDelayMs, delayMultiplier, maxDelayMs) {
+        this.attemptTimeoutMs = attemptTimeoutMs;
+        this.maxRetries = maxRetries;
+        this.initialDelayMs = initialDelayMs;
+        this.delayMultiplier = delayMultiplier;
+        this.maxDelayMs = maxDelayMs;
+        CallDeadline_1.CallDeadline.validate(attemptTimeoutMs);
+        RetryStrategy.requireWhole('maxRetries', maxRetries);
+        RetryStrategy.requireWhole('initialDelayMs', initialDelayMs);
+        RetryStrategy.requireWhole('maxDelayMs', maxDelayMs);
+        if (!Number.isFinite(delayMultiplier) || delayMultiplier < 1) {
+            throw new RangeError('delayMultiplier must be finite and at least 1');
+        }
+        // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs
+        this.run = (call, ctx) => this.execute(call, ctx);
+    }
+    // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs
+    async execute(call, ctx) {
+        const methodInfo = new ApiMethodInfo_1.ApiMethodInfo('client', ctx.apiName, ctx.methodName);
+        let delayMs = this.initialDelayMs;
+        for (let attempt = 1;; attempt++) {
+            // webpieces-disable no-unmanaged-exceptions -- a strategy decides per failure whether to retry
+            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+            try {
+                return await call(this.attemptTimeoutMs);
+            }
+            catch (err) {
+                const error = (0, errorUtils_1.toError)(err);
+                const retryable = ctx.operation !== HttpEndpointOptions_1.WRITE &&
+                    ClientRegistry_1.ClientRegistry.classify(error, methodInfo) === ErrorClassifier_1.CallOutcome.TRANSIENT_FAILURE;
+                if (!retryable) {
+                    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a definitive answer is rethrown unchanged
+                    throw err;
+                }
+                if (attempt > this.maxRetries) {
+                    if (attempt === 1) {
+                        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- never retried, so nothing was exhausted
+                        throw err;
+                    }
+                    throw new ApiError_1.ApiRetriesExhaustedError(attempt, error);
+                }
+                await RetryStrategy.sleep(delayMs);
+                delayMs = Math.min(delayMs * this.delayMultiplier, this.maxDelayMs);
+            }
+        }
+    }
+    // webpieces-disable no-function-outside-class -- constructor argument guard
+    static requireWhole(name, value) {
+        if (!Number.isInteger(value) || value < 0) {
+            throw new RangeError(`${name} must be a non-negative integer`);
+        }
+    }
+    // webpieces-disable no-function-outside-class -- backoff timer
+    static sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.RetryStrategy = RetryStrategy;
+//# sourceMappingURL=RetryStrategy.js.map

package/src/http/RetryStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryStrategy.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RetryStrategy.ts"],"names":[],"mappings":"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","sourcesContent":["import { Attempt, CallContext, CallStrategy } from './CallStrategy';\nimport { CallDeadline } from './CallDeadline';\nimport { ClientRegistry } from './ClientRegistry';\nimport { CallOutcome } from './ErrorClassifier';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { WRITE } from './HttpEndpointOptions';\nimport { ApiRetriesExhaustedError } from '../errors/ApiError';\nimport { toError } from '../lib/errorUtils';\n\n/**\n * THE webpieces retry strategy, shared by every transport — register its {@link RetryStrategy.run}\n * with `CallRegistry.setStrategy(...)`, or hand it to a `TransportDefault`.\n *\n * Two questions, two owners, and it asks both:\n *\n * - **the ERROR** — `ClientRegistry.classify(error, …)`. Only `CallOutcome.TRANSIENT_FAILURE` is\n *   retried; an EXPECTED or FAILURE outcome is a definitive answer and is rethrown unchanged.\n * - **the ENDPOINT** — `CallContext.operation`. A `WRITE` is NEVER retried, even when this strategy is\n *   registered at ALL: a transient error on a non-idempotent write may already have happened.\n *\n * Each attempt gets its own `attemptTimeoutMs` deadline. Between attempts it waits\n * `initialDelayMs`, then multiplies by `delayMultiplier`, capped at `maxDelayMs`.\n *\n * When it RETRIED and ran out, it throws {@link ApiRetriesExhaustedError} (`cause` = the last\n * attempt's error), which is classified FAILURE so no layer above retries again. A call that made a\n * single attempt — `maxRetries` 0, a `WRITE`, a non-transient error — rethrows its own error unchanged.\n */\nexport class RetryStrategy {\n    /** The {@link CallStrategy} to register. A bound field, so `strategy.run` can be passed around. */\n    // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n    readonly run: CallStrategy<unknown>;\n\n    constructor(\n        readonly attemptTimeoutMs: number,\n        readonly maxRetries: number,\n        readonly initialDelayMs: number,\n        readonly delayMultiplier: number,\n        readonly maxDelayMs: number,\n    ) {\n        CallDeadline.validate(attemptTimeoutMs);\n        RetryStrategy.requireWhole('maxRetries', maxRetries);\n        RetryStrategy.requireWhole('initialDelayMs', initialDelayMs);\n        RetryStrategy.requireWhole('maxDelayMs', maxDelayMs);\n        if (!Number.isFinite(delayMultiplier) || delayMultiplier < 1) {\n            throw new RangeError('delayMultiplier must be finite and at least 1');\n        }\n        // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n        this.run = (call: Attempt<unknown>, ctx: CallContext): Promise<unknown> => this.execute(call, ctx);\n    }\n\n    // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n    private async execute(call: Attempt<unknown>, ctx: CallContext): Promise<unknown> {\n        const methodInfo = new ApiMethodInfo('client', ctx.apiName, ctx.methodName);\n        let delayMs = this.initialDelayMs;\n        for (let attempt = 1; ; attempt++) {\n            // webpieces-disable no-unmanaged-exceptions -- a strategy decides per failure whether to retry\n            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n            try {\n                return await call(this.attemptTimeoutMs);\n            } catch (err: unknown) {\n                const error = toError(err);\n                const retryable =\n                    ctx.operation !== WRITE &&\n                    ClientRegistry.classify(error, methodInfo) === CallOutcome.TRANSIENT_FAILURE;\n                if (!retryable) {\n                    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a definitive answer is rethrown unchanged\n                    throw err;\n                }\n                if (attempt > this.maxRetries) {\n                    if (attempt === 1) {\n                        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- never retried, so nothing was exhausted\n                        throw err;\n                    }\n                    throw new ApiRetriesExhaustedError(attempt, error);\n                }\n                await RetryStrategy.sleep(delayMs);\n                delayMs = Math.min(delayMs * this.delayMultiplier, this.maxDelayMs);\n            }\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- constructor argument guard\n    private static requireWhole(name: string, value: number): void {\n        if (!Number.isInteger(value) || value < 0) {\n            throw new RangeError(`${name} must be a non-negative integer`);\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- backoff timer\n    private static sleep(ms: number): Promise<void> {\n        return new Promise<void>((resolve: () => void) => setTimeout(resolve, ms));\n    }\n}\n"]}

package/src/http/TransportDefault.d.ts

@@ -0,0 +1,25 @@
+import { CallStrategy } from './CallStrategy';
+/**
+ * What a TRANSPORT does for a call nobody registered a policy for — the last rung of
+ * {@link CallRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →
+ * ALL, else this).
+ *
+ * It is the ONLY per-transport difference: every transport calls the same `CallRegistry.execute`, so
+ * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.
+ *
+ * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no
+ *   default retry, because only the application knows whether repeating a POST is safe.
+ * - Cloud Tasks enqueue: `new TransportDefault(30_000, new RetryStrategy(5_000, 3, 500, 2, 4_000).run)`
+ *   — enqueue is idempotent by construction (one task name for every attempt), so it retries.
+ */
+export declare class TransportDefault {
+    /** The single attempt's deadline when no strategy (registered or default) runs. */
+    readonly timeoutMs: number;
+    /** The transport's own strategy; when set it owns timing exactly like a registered one. */
+    readonly strategy?: CallStrategy<unknown> | undefined;
+    constructor(
+    /** The single attempt's deadline when no strategy (registered or default) runs. */
+    timeoutMs: number, 
+    /** The transport's own strategy; when set it owns timing exactly like a registered one. */
+    strategy?: CallStrategy<unknown> | undefined);
+}

package/src/http/TransportDefault.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransportDefault = void 0;
+/**
+ * What a TRANSPORT does for a call nobody registered a policy for — the last rung of
+ * {@link CallRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →
+ * ALL, else this).
+ *
+ * It is the ONLY per-transport difference: every transport calls the same `CallRegistry.execute`, so
+ * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.
+ *
+ * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no
+ *   default retry, because only the application knows whether repeating a POST is safe.
+ * - Cloud Tasks enqueue: `new TransportDefault(30_000, new RetryStrategy(5_000, 3, 500, 2, 4_000).run)`
+ *   — enqueue is idempotent by construction (one task name for every attempt), so it retries.
+ */
+class TransportDefault {
+    timeoutMs;
+    strategy;
+    constructor(
+    /** The single attempt's deadline when no strategy (registered or default) runs. */
+    timeoutMs, 
+    /** The transport's own strategy; when set it owns timing exactly like a registered one. */
+    // webpieces-disable no-any-unknown -- transport strategies span heterogeneous response DTOs
+    strategy) {
+        this.timeoutMs = timeoutMs;
+        this.strategy = strategy;
+    }
+}
+exports.TransportDefault = TransportDefault;
+//# sourceMappingURL=TransportDefault.js.map

package/src/http/TransportDefault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TransportDefault.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/TransportDefault.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IAGZ;IAGA;IALb;IACI,mFAAmF;IAC1E,SAAiB;IAC1B,2FAA2F;IAC3F,4FAA4F;IACnF,QAAgC;QAHhC,cAAS,GAAT,SAAS,CAAQ;QAGjB,aAAQ,GAAR,QAAQ,CAAwB;IAC1C,CAAC;CACP;AARD,4CAQC","sourcesContent":["import { CallStrategy } from './CallStrategy';\n\n/**\n * What a TRANSPORT does for a call nobody registered a policy for — the last rung of\n * {@link CallRegistry.execute}'s ladder (strategy method → API → ALL, else timeout method → API →\n * ALL, else this).\n *\n * It is the ONLY per-transport difference: every transport calls the same `CallRegistry.execute`, so\n * a strategy registered at ALL / API / method governs RPC and Cloud Tasks enqueue identically.\n *\n * - RPC (node and browser, through `ProxyClient`): `new TransportDefault(30_000)` — one attempt, no\n *   default retry, because only the application knows whether repeating a POST is safe.\n * - Cloud Tasks enqueue: `new TransportDefault(30_000, new RetryStrategy(5_000, 3, 500, 2, 4_000).run)`\n *   — enqueue is idempotent by construction (one task name for every attempt), so it retries.\n */\nexport class TransportDefault {\n    constructor(\n        /** The single attempt's deadline when no strategy (registered or default) runs. */\n        readonly timeoutMs: number,\n        /** The transport's own strategy; when set it owns timing exactly like a registered one. */\n        // webpieces-disable no-any-unknown -- transport strategies span heterogeneous response DTOs\n        readonly strategy?: CallStrategy<unknown>,\n    ) {}\n}\n"]}

package/src/http/WebpiecesDefaultErrorClassifier.d.ts

@@ -0,0 +1,42 @@
+import { ApiMethodInfo } from './ApiMethodInfo';
+import { CallOutcome, ErrorClassifier } from './ErrorClassifier';
+/**
+ * The webpieces built-in {@link ErrorClassifier} — the terminal tier, used when no per-apiClass
+ * classifier and no app default claims an error. Two tables, one per question:
+ *
+ * # 1. EXPECTED or not — "are things WORKING?"
+ *
+ * NOT "was it an HTTP 4xx vs 5xx" — the two differ (see 408). Classification is by portable Error
+ * TYPE, never by transport: this runs over in-process calls, queue handlers and HTTP through one code
+ * path and only ever sees a thrown Error.
+ *
+ * - ApiEndUserError (266): ALWAYS expected, server OR client — an expected "user made a mistake".
+ * - SERVER — a healthy server correctly rejecting a CLIENT'S mistake is metrics NOISE, not a failure:
+ *   ApiBadRequestError (400), ApiUnauthorizedError (401), ApiForbiddenError (403), ApiNotFoundError
+ *   (404), ApiConflictError (409), ApiPreconditionFailedError (412), ApiUnsupportedMediaTypeError
+ *   (415), ApiUnprocessableError (422), an ApiCodedError whose `isCallerError()` is true (below 500,
+ *   except 408/429), and an OAuthProtocolError below 500 (a refused grant is the OAuth protocol
+ *   working, #1176). ApiRequestTimeoutError (408) is deliberately absent: the client may NEVER have
+ *   seen the response.
+ * - CLIENT: receiving ANY error except 266 means the outbound call failed — never expected here.
+ *   (An external client whose 404 means "miss" registers its own classifier for that.)
+ *
+ * # 2. TRANSIENT or FAILURE — "may repeating it work?"
+ *
+ * The kind table that used to live inside the MCP renderer:
+ *
+ * - TRANSIENT: request-timeout (408), dependency-timeout (504, incl. a client's own
+ *   `ApiCallTimeoutError`), bad-gateway (502 proxy), unavailable (503), rate-limited (429),
+ *   dependency-backoff, connection, and an ApiCodedError of 408/429.
+ * - FAILURE: everything else — a received 4xx (our bug), implementation, not-implemented (501), a
+ *   generic dependency defect, and {@link ApiRetriesExhaustedError}, which is checked FIRST: it is an
+ *   `ApiDependencyError`, and classifying it transient would let every layer above retry again.
+ */
+export declare class WebpiecesDefaultErrorClassifier implements ErrorClassifier {
+    /** Terminal tier — NEVER returns undefined. */
+    classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome;
+    private isExpected;
+    private isTransient;
+}
+/** Process-wide built-in instance — stateless, so one shared instance is enough. */
+export declare const WEBPIECES_DEFAULT_ERROR_CLASSIFIER: WebpiecesDefaultErrorClassifier;