@webpieces/http-client-core 0.4.743 → 0.4.745

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-client-core",
-  "version": "0.4.743",
+  "version": "0.4.745",
   "description": "Isomorphic core of the webpieces HTTP client: the decorator-driven ProxyClient, error translation, and the Proxy trap shared by http-client-node and http-client-browser",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -21,6 +21,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-util": "0.4.743"
+    "@webpieces/core-util": "0.4.745"
   }
 }

package/src/ProxyClient.d.ts

@@ -27,6 +27,7 @@ export declare abstract class ProxyClient {
     protected readonly logApiCall: LogApiCallImpl;
     private routeMap;
     private apiName;
+    private apiClass;
     /**
      * The OUTBOUND filter chain, built once at bind time from {@link clientFilters} and reused for
      * every call. Built once rather than per call because a filter is STATELESS by contract (the
@@ -127,7 +128,7 @@ export declare abstract class ProxyClient {
      */
     protected abstract adaptDownstreamFailure(failure: TranslatedFailure, callId: string): Error;
     /**
-     * Fires immediately BEFORE `fetch`, once per RPC — the progress "start marker". Symmetric with
+     * Fires before the logical call's attempts, once per RPC — the progress "start marker". Symmetric with
      * {@link onRequestEnd}: every start is followed by exactly one end, on every path, so a listener
      * can drive a counter (bar on / bar off) without leaking a permanently-spinning bar.
      *
@@ -140,7 +141,7 @@ export declare abstract class ProxyClient {
      *
      * Subsumes the older header-only hook: this is the ONLY place the `fetch` Response — and thus its
      * `Headers` — exists, so an app that needs to read a response header (e.g. a server-version stamp
-     * for client↔server version matching) reads `outcome.headers`, still BEFORE the body is consumed
+     * for client↔server version matching) reads `outcome.headers` after settlement
      * and on both the ok and error paths. `outcome.ok`/`outcome.error` add the success-or-error
      * signal the header-only seam could not give.
      *
@@ -176,21 +177,11 @@ export declare abstract class ProxyClient {
      * @throws Error naming the endpoint, what it declared, and who its real caller is.
      */
     private refuseEndpointNoClientCanCall;
-    /**
-     * Make an HTTP request based on route metadata and arguments.
-     *
-     * All endpoints are POST-only. The request body is the first argument.
-     */
-    makeRequest(route: RouteMetadata, args: any[]): Promise<any>;
-    /**
-     * Execute the fetch request and handle response.
-     *
-     * Brackets the call with the lifecycle seam: {@link onRequestStart} once before `fetch`, then
-     * {@link onRequestEnd} exactly once on each of the three ways a call can settle. The end hook
-     * fires BEFORE the throw on both failure paths, so a listener always sees the stop marker even
-     * though the caller sees an exception.
-     */
-    private executeFetch;
+    /** One logical call: one lifecycle pair and log entry across all strategy attempts. */
+    makeRequest(route: RouteMetadata, args: unknown[]): Promise<unknown>;
+    private executeCall;
+    /** Fresh mutable request for every attempt, including URL, headers, auth and body. */
+    private prepareRequest;
     /**
      * ONE transmission — the bottom of the filter chain, and the only place `fetch` is called.
      *
@@ -203,44 +194,6 @@ export declare abstract class ProxyClient {
      * will, rather than a raw platform reject.
      */
     private sendOnce;
-    /**
-     * Read a 2xx body, reporting the END marker on both outcomes.
-     *
-     * The content-type gate is the same one the error path uses: a 2xx that is not JSON (a proxy's
-     * captive-portal page, an SPA index.html served by a misrouted CDN) is reported for WHAT ARRIVED,
-     * instead of `SyntaxError: Unexpected token '<'`, which names nothing a reader can act on.
-     */
-    private readSuccessBody;
-    /**
-     * Turn a non-2xx response into the error the caller will see, firing the END marker first — so a
-     * listener always gets its stop marker even though the caller sees an exception. RETURNS the
-     * error rather than throwing it, which keeps the one `throw` visible at the call site.
-     *
-     * The headers still reach the seam here, so a version (or any future) header is observed even on
-     * error responses.
-     *
-     * The body is read through {@link ResponseBodyReader}, which parses ONLY a body whose
-     * content-type says it is JSON. An infra 502/503/504 (load balancer, proxy, cold start on a
-     * scale-to-zero backend) serves HTML, and parsing that used to throw `SyntaxError: Unexpected
-     * token '<'` — discarding the status, so the caller could not tell a booting server from a broken
-     * client. It now becomes a synthesized ProtocolError translated BY STATUS, i.e. a real
-     * `HttpBadGatewayError` / `HttpServiceUnavailableError` / `HttpGatewayTimeoutError`.
-     *
-     * The try/catch stays, for a NARROWER job than before: a body that DECLARED json and was
-     * malformed still throws (that one is a genuine server bug), and the END marker must fire for it
-     * too — an unreported end leaves the app's progress bar spinning forever.
-     *
-     * `translated` is what ClientErrorTranslator picked, and translateError RETURNS a
-     * {@link TranslatedFailure} — so nothing in this seam is ever `unknown`.
-     *
-     * The translated failure then goes through {@link adaptDownstreamFailure}, which is where the two
-     * environments part company (browser rethrows it, node turns a downstream 4xx into its own 500).
-     *
-     * The RequestOutcome reported to {@link onRequestEnd} carries the POST-adapt error, deliberately:
-     * a lifecycle listener must see the SAME error the caller sees, or a progress bar / error toast
-     * says 404 while the thrown exception says 500. That is the identical rule the network-reject path
-     * already follows (it classifies BEFORE onRequestEnd for exactly this reason). The pre-adapt error
-     * is not lost — it is the adapted error's `httpCause`.
-     */
-    private endWithTypedFailure;
+    /** Body consumption is inside the attempt deadline, including non-JSON error bodies. */
+    private readResponse;
 }

package/src/ProxyClient.js

@@ -32,6 +32,7 @@ class ProxyClient {
     // Assigned by initRoutes(), which every subclass's init() calls immediately after construction.
     routeMap;
     apiName;
+    apiClass;
     /**
      * The OUTBOUND filter chain, built once at bind time from {@link clientFilters} and reused for
      * every call. Built once rather than per call because a filter is STATELESS by contract (the
@@ -102,7 +103,7 @@ class ProxyClient {
         return [];
     }
     /**
-     * Fires immediately BEFORE `fetch`, once per RPC — the progress "start marker". Symmetric with
+     * Fires before the logical call's attempts, once per RPC — the progress "start marker". Symmetric with
      * {@link onRequestEnd}: every start is followed by exactly one end, on every path, so a listener
      * can drive a counter (bar on / bar off) without leaking a permanently-spinning bar.
      *
@@ -115,7 +116,7 @@ class ProxyClient {
      *
      * Subsumes the older header-only hook: this is the ONLY place the `fetch` Response — and thus its
      * `Headers` — exists, so an app that needs to read a response header (e.g. a server-version stamp
-     * for client↔server version matching) reads `outcome.headers`, still BEFORE the body is consumed
+     * for client↔server version matching) reads `outcome.headers` after settlement
      * and on both the ok and error paths. `outcome.ok`/`outcome.error` add the success-or-error
      * signal the header-only seam could not give.
      *
@@ -135,6 +136,7 @@ class ProxyClient {
      */
     initRoutes(apiPrototype, appFilters) {
         this.appFilters = appFilters;
+        this.apiClass = apiPrototype;
         if (!(0, core_util_1.isApiPath)(apiPrototype)) {
             const className = apiPrototype.name || 'Unknown';
             throw new Error(`Class ${className} must be decorated with @ApiPath()`);
@@ -217,82 +219,51 @@ class ProxyClient {
         // outbound-auth filter asks its bound signer to produce the signature, which is the exact
         // mirror of the inbound WebhookAuthCallback that verifies one.
     }
-    /**
-     * Make an HTTP request based on route metadata and arguments.
-     *
-     * All endpoints are POST-only. The request body is the first argument.
-     */
-    // webpieces-disable no-any-unknown -- proxy method: the request DTO (args) + response are erased at the client boundary
+    /** One logical call: one lifecycle pair and log entry across all strategy attempts. */
+    // webpieces-disable no-any-unknown -- request and response DTOs are erased at the proxy boundary
     async makeRequest(route, args) {
         this.refuseEndpointNoClientCanCall(route);
-        // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.
-        const baseUrl = await this.resolveBaseUrl();
-        const httpHeaders = new Map([['Content-Type', 'application/json']]);
-        // Transferred context, request-id chained. The server impl throws here when there is no
-        // active RequestContext — an outbound call with no trace is a bug, not a default. The
-        // destination's own auth mode decides whether trusted keys are part of that set.
-        const contextHeaders = this.outboundContextHeaders(core_util_1.DestinationTrust.forAuthMode(route.authMeta?.mode));
-        for (const entry of contextHeaders.entries()) {
-            httpHeaders.set(entry[0], entry[1]);
-        }
-        // NOTHING mints a credential here. The endpoint's outbound auth is a FILTER, sitting at the
-        // very bottom of the chain, because the URL at this point is only where the call STARTS: an
-        // app filter above may re-point it, and an OIDC token whose audience is the pre-filter URL
-        // is a token for the wrong peer. The minter has to run last, against the settled
-        // destination — see the environment's `clientFilters()`.
-        //
-        // POST body is the first argument as JSON. Serialized HERE, before the filter chain, so a
-        // filter that signs the request signs the exact bytes {@link sendOnce} will transmit.
-        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary
-        let requestDto;
-        let body;
-        if (args.length > 0) {
-            requestDto = args[0];
-            body = JSON.stringify(requestDto);
-        }
-        const request = new ClientRequest_1.ClientRequest(route, this.apiName, baseUrl, httpHeaders, body, requestDto);
-        // Wrap the send in a method for LogApiCall.execute
-        // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary
-        const method = async () => {
-            return this.executeFetch(request);
-        };
-        return await this.execute(route, requestDto, method);
+        const requestDto = args[0];
+        return this.execute(route, requestDto, () => this.executeCall(route, requestDto));
     }
-    /**
-     * Execute the fetch request and handle response.
-     *
-     * Brackets the call with the lifecycle seam: {@link onRequestStart} once before `fetch`, then
-     * {@link onRequestEnd} exactly once on each of the three ways a call can settle. The end hook
-     * fires BEFORE the throw on both failure paths, so a listener always sees the stop marker even
-     * though the caller sees an exception.
-     */
-    // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary
-    async executeFetch(request) {
-        const route = request.route;
+    // webpieces-disable no-any-unknown -- response DTO is erased at the proxy boundary
+    async executeCall(route, requestDto) {
         this.onRequestStart(route);
-        // The START marker fires ONCE per RPC even though a filter may send more than once (the SSRF
-        // guard re-invokes the chain to follow a validated redirect) — start and end still pair up
-        // exactly, which is what lets a listener drive a progress counter.
         let response;
-        // webpieces-disable no-unmanaged-exceptions -- translate a send failure into a lifecycle END, then rethrow
+        // webpieces-disable no-any-unknown -- response DTO is erased at the proxy boundary
+        let result;
+        // webpieces-disable no-unmanaged-exceptions -- report one logical END, preserving the original thrown value
         // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
         try {
-            response = await this.chain.execute(request, () => this.sendOnce(request));
+            result = await core_util_1.CallRegistry.execute(this.apiClass, route.methodName, (timeoutMs) => {
+                response = undefined;
+                return core_util_1.CallDeadline.run(timeoutMs, new core_util_1.CallContext(this.apiName, route.methodName), async (signal) => {
+                    const request = await this.prepareRequest(route, requestDto);
+                    signal.throwIfAborted();
+                    const received = await this.chain.execute(request, () => this.sendOnce(request, signal));
+                    signal.throwIfAborted();
+                    response = received;
+                    return this.readResponse(received, route);
+                });
+            }, 30_000);
         }
         catch (err) {
-            // No Response ever existed — a network reject already classified by sendOnce, or a filter
-            // that refused to send at all (an SSRF policy rejecting a partner's URL). Either way there
-            // is no status and no headers to report, only status 0 and the failure itself, and the
-            // lifecycle listener must see the SAME error the caller is about to.
             const error = (0, core_util_1.toError)(err);
-            this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, 0, undefined, error));
-            throw error;
+            this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, response?.status ?? 0, response?.headers, error));
+            throw err;
         }
-        const callId = `${this.apiName}.${route.methodName}`;
-        if (response.ok) {
-            return this.readSuccessBody(response, route, callId);
-        }
-        throw await this.endWithTypedFailure(response, route, callId);
+        this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(true, response?.status ?? 0, response?.headers));
+        return result;
+    }
+    /** Fresh mutable request for every attempt, including URL, headers, auth and body. */
+    // webpieces-disable no-any-unknown -- request DTO is erased at the proxy boundary
+    async prepareRequest(route, requestDto) {
+        const baseUrl = await this.resolveBaseUrl();
+        const headers = new Map([['Content-Type', 'application/json']]);
+        const context = this.outboundContextHeaders(core_util_1.DestinationTrust.forAuthMode(route.authMeta?.mode));
+        for (const entry of context.entries())
+            headers.set(entry[0], entry[1]);
+        return new ClientRequest_1.ClientRequest(route, this.apiName, baseUrl, headers, JSON.stringify(requestDto), requestDto);
     }
     /**
      * ONE transmission — the bottom of the filter chain, and the only place `fetch` is called.
@@ -305,9 +276,11 @@ class ProxyClient {
      * genuine bug passes through untouched) so that filters above see the same typed error the caller
      * will, rather than a raw platform reject.
      */
-    async sendOnce(request) {
+    async sendOnce(request, signal) {
+        signal.throwIfAborted();
         const options = {
             method: request.route.httpMethod,
+            signal,
             headers: request.headersAsRecord(),
             redirect: request.followRedirects ? 'follow' : 'manual',
         };
@@ -325,81 +298,19 @@ class ProxyClient {
             throw this.networkRejectClassifier.toNetworkError(error, request.url);
         }
     }
-    /**
-     * Read a 2xx body, reporting the END marker on both outcomes.
-     *
-     * The content-type gate is the same one the error path uses: a 2xx that is not JSON (a proxy's
-     * captive-portal page, an SPA index.html served by a misrouted CDN) is reported for WHAT ARRIVED,
-     * instead of `SyntaxError: Unexpected token '<'`, which names nothing a reader can act on.
-     */
-    // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary
-    async readSuccessBody(response, route, callId) {
-        // webpieces-disable no-unmanaged-exceptions -- a malformed 2xx body must still report the END marker
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-        try {
+    /** Body consumption is inside the attempt deadline, including non-JSON error bodies. */
+    // webpieces-disable no-any-unknown -- response DTO is erased at the proxy boundary
+    async readResponse(response, route) {
+        const callId = `${this.apiName}.${route.methodName}`;
+        if (response.ok) {
             if (!this.bodyReader.isJson(response)) {
                 throw new Error(this.bodyReader.describeForeignBody(response, callId, await response.text()));
             }
-            const body = await response.json();
-            this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(true, response.status, response.headers));
-            return body;
-        }
-        catch (err) {
-            const error = (0, core_util_1.toError)(err);
-            this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, response.status, response.headers, error));
-            throw error;
-        }
-    }
-    /**
-     * Turn a non-2xx response into the error the caller will see, firing the END marker first — so a
-     * listener always gets its stop marker even though the caller sees an exception. RETURNS the
-     * error rather than throwing it, which keeps the one `throw` visible at the call site.
-     *
-     * The headers still reach the seam here, so a version (or any future) header is observed even on
-     * error responses.
-     *
-     * The body is read through {@link ResponseBodyReader}, which parses ONLY a body whose
-     * content-type says it is JSON. An infra 502/503/504 (load balancer, proxy, cold start on a
-     * scale-to-zero backend) serves HTML, and parsing that used to throw `SyntaxError: Unexpected
-     * token '<'` — discarding the status, so the caller could not tell a booting server from a broken
-     * client. It now becomes a synthesized ProtocolError translated BY STATUS, i.e. a real
-     * `HttpBadGatewayError` / `HttpServiceUnavailableError` / `HttpGatewayTimeoutError`.
-     *
-     * The try/catch stays, for a NARROWER job than before: a body that DECLARED json and was
-     * malformed still throws (that one is a genuine server bug), and the END marker must fire for it
-     * too — an unreported end leaves the app's progress bar spinning forever.
-     *
-     * `translated` is what ClientErrorTranslator picked, and translateError RETURNS a
-     * {@link TranslatedFailure} — so nothing in this seam is ever `unknown`.
-     *
-     * The translated failure then goes through {@link adaptDownstreamFailure}, which is where the two
-     * environments part company (browser rethrows it, node turns a downstream 4xx into its own 500).
-     *
-     * The RequestOutcome reported to {@link onRequestEnd} carries the POST-adapt error, deliberately:
-     * a lifecycle listener must see the SAME error the caller sees, or a progress bar / error toast
-     * says 404 while the thrown exception says 500. That is the identical rule the network-reject path
-     * already follows (it classifies BEFORE onRequestEnd for exactly this reason). The pre-adapt error
-     * is not lost — it is the adapted error's `httpCause`.
-     */
-    async endWithTypedFailure(response, route, callId) {
-        let translated;
-        // webpieces-disable no-unmanaged-exceptions -- a malformed JSON error body must still report the END marker
-        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-        try {
-            const protocolError = await this.bodyReader.readErrorBody(response, callId);
-            translated = ClientErrorTranslator_1.ClientErrorTranslator.translateError(this.responseDtoFactory.fromFetch(response, protocolError));
-        }
-        catch (err) {
-            const error = (0, core_util_1.toError)(err);
-            // The response CLAIMED JSON and was not parseable — report that failure as the outcome.
-            // It never reaches adaptDownstreamFailure: there is no translated status to adapt, and a
-            // body that broke its own content-type promise is already a defect, not a status answer.
-            this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, response.status, response.headers, error));
-            return error;
+            return response.json();
         }
-        const adapted = this.adaptDownstreamFailure(translated, callId);
-        this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, response.status, response.headers, adapted));
-        return adapted;
+        const protocolError = await this.bodyReader.readErrorBody(response, callId);
+        const translated = ClientErrorTranslator_1.ClientErrorTranslator.translateError(this.responseDtoFactory.fromFetch(response, protocolError));
+        throw this.adaptDownstreamFailure(translated, callId);
     }
 }
 exports.ProxyClient = ProxyClient;

package/src/ProxyClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"ProxyClient.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMeta,\n    isFormPost,\n    isRawBody,\n    getMaskSpec,\n    AuthMeta,\n    DestinationTrust,\n    RouteMetadata,\n    LogApiCallImpl,\n    ApiMethodInfo,\n    toError,\n    NetworkRejectClassifier,\n    FilterChain,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientFilterDefinition } from './ClientFilter';\nimport { ClientRequest } from './ClientRequest';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\nimport { HttpResponseDtoFactory } from './HttpResponseDtoFactory';\nimport { RequestOutcome } from './RequestOutcome';\nimport { ResponseBodyReader } from './ResponseBodyReader';\nimport { TranslatedFailure } from './TranslatedFailure';\n\n/**\n * ProxyClient - the HTTP call engine behind one API contract's client proxy.\n *\n * Contains ONLY what a browser can run: the route map built from the contract's decorators, URL\n * assembly, `fetch`, error translation, and logging. It holds no context object, no credentials,\n * and no recorder — it ASKS ITSELF for those through the hooks below, and each subclass answers\n * from its own environment.\n *\n * That is why the class is abstract rather than parameterized by a collaborator: a shared\n * header-provider seam would drag Node's AsyncLocalStorage vocabulary into a browser bundle and the\n * browser's store vocabulary into a server, and neither has any use for the other.\n *\n *   NodeProxyClient    (@webpieces/http-client-node)    -> RequestContext, Secrets, mintIdToken, recording\n *   BrowserProxyClient (@webpieces/http-client-browser) -> an app-held store, no credentials, no recording\n *\n * TWO-PHASE: collaborators arrive on the subclass constructor (so a DI container can supply them),\n * while the per-client state — which contract, which target — arrives on the subclass's `init`,\n * which calls {@link initRoutes}. That is what lets a factory hold a `Provider<ProxyClient>` and\n * hand out a fresh, independently-configured client per contract.\n */\nexport abstract class ProxyClient {\n    // Assigned by initRoutes(), which every subclass's init() calls immediately after construction.\n    private routeMap!: Map<string, RouteMetadata>;\n    private apiName!: string;\n\n    /**\n     * The OUTBOUND filter chain, built once at bind time from {@link clientFilters} and reused for\n     * every call. Built once rather than per call because a filter is STATELESS by contract (the\n     * per-call state is the {@link ClientRequest} the chain is handed), exactly as on the server.\n     */\n    private chain!: FilterChain<ClientRequest, Response>;\n\n    /**\n     * The app's own filters, as handed to `createRpcClient`. Set by {@link initRoutes} BEFORE it\n     * calls {@link clientFilters}, so an environment's built-ins may read the app's intent off them\n     * — @webpieces/http-client-node takes the SSRF policy from an installed `ContextBaseUrlFilter`\n     * that way, which keeps the one legitimate relaxation at the same construction site as the\n     * decision to be re-pointable at all.\n     */\n    protected appFilters: ClientFilterDefinition[] = [];\n\n    // Stateless + dependency-free, so the browser bundle keeps no DI on the fetch path.\n    private readonly networkRejectClassifier = new NetworkRejectClassifier();\n\n    // Same shape and same reason: stateless, so it is constructed here rather than injected.\n    private readonly bodyReader = new ResponseBodyReader();\n\n    /**\n     * fetch `Response` -> the transport-neutral {@link HttpResponseDto} an app's `ErrorTranslators`\n     * sees. Normalising HERE is what makes `fromWire` receive the identical shape in node and in the\n     * browser: both environments share this class, and this is the only place either builds a DTO.\n     */\n    private readonly responseDtoFactory = new HttpResponseDtoFactory();\n\n    /**\n     * @param logApiCall - built by the SUBCLASS's package around that environment's ApiCallContext\n     *   (node: RequestContextApiCallContext; browser: BrowserApiCallContext). REQUIRED, with no\n     *   default: core-util cannot construct either one, and a default here would have to reach for a\n     *   process-global — which is exactly the throw-on-first-call this parameter deleted.\n     */\n    constructor(protected readonly logApiCall: LogApiCallImpl) {}\n\n    // ---------------------------------------------------------------- environment hooks\n\n    /** The callee's base URL. Async because a server may derive it from container metadata. */\n    protected abstract resolveBaseUrl(): Promise<string>;\n\n    /**\n     * Context headers to put on the wire. Server reads RequestContext; browser reads its store.\n     *\n     * `destination` is derived from THIS route's auth mode and decides whether TRUSTED context keys\n     * (`x-user-id`, `x-org-id`, `x-webpieces-roles`) may ride along — see {@link DestinationTrust}.\n     * It is a required argument on purpose: a defaulted \"send everything\" would put the permissive\n     * answer one keystroke away and make the safe one opt-in.\n     *\n     * RENAMED from `outboundHeaders()` in the same change that added `destination`, and the rename IS\n     * the migration. TypeScript accepts an override that declares FEWER parameters than its base, so a\n     * downstream `protected override outboundHeaders(): Map<string, string>` would have kept compiling\n     * and silently ignored the gate — the permissive behaviour surviving as a second spelling. Against\n     * the NEW name that subclass fails twice over: `override` names a member the base no longer has,\n     * and this abstract member is left unimplemented.\n     */\n    protected abstract outboundContextHeaders(destination: DestinationTrust): Map<string, string>;\n\n    /**\n     * Run the call. The default just logs it. Test-case RECORDING is a server concept, so\n     * NodeProxyClient overrides this to capture the call when a recorder is in the context.\n     *\n     * Context fields are NOT passed in: a logging backend stamps them onto every record itself.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    protected async execute(\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        // apiClass = the CONTRACT name (this.apiName, e.g. 'SaveApi') so this client log line MATCHES\n        // the server's for the same call. A client has no impl class, so controllerName is omitted.\n        const info = new ApiMethodInfo('client', this.apiName, route.methodName, undefined, route.mask);\n        return this.logApiCall.execute(info, requestDto, method);\n    }\n\n    /**\n     * Reject, at bind time, an endpoint this environment cannot satisfy — e.g. a browser cannot\n     * mint the OIDC token an @AuthOidc endpoint demands. Surfacing it here beats failing on the\n     * first call in production. The default accepts everything.\n     */\n    protected assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string): void {}\n\n    /**\n     * The FRAMEWORK filters this environment installs on every client it builds, BENEATH whatever\n     * the app passed to `createRpcClient`. The default installs none, so the browser runs the exact\n     * code path it ran before the chain existed.\n     *\n     * \"Beneath\" is not a priority — see {@link initRoutes}. These are the filters that must judge\n     * and sign what is ACTUALLY about to be sent, so no app priority may be allowed to get under\n     * them: @webpieces/http-client-node installs its SSRF guard and its outbound-auth minter here,\n     * and both would be defeated by an app filter that re-pointed the URL below them. Neither\n     * concept can live in this class, because reading a RequestContext, resolving DNS and minting\n     * an OIDC token are all things a browser bundle must never contain.\n     */\n    protected clientFilters(): ClientFilterDefinition[] {\n        return [];\n    }\n\n    /**\n     * Adapt a translated downstream failure into the error THIS environment's caller should see.\n     *\n     * THE INVARIANT, and the reason this hook exists at all:\n     *\n     *   A status received from a downstream dependency describes OUR request to it. It is never the\n     *   status we return to OUR caller. The server that answered 404 is correct; the server that\n     *   asked for a route that does not exist is broken, and must say so as a 500.\n     *\n     * That invariant reads differently in the two environments, which is exactly why the ISOMORPHIC\n     * {@link ClientErrorTranslator} cannot settle it:\n     * - BROWSER: the client IS the end user's agent, so the downstream IS the answer. Pass it through\n     *   unchanged.\n     * - NODE: server-to-server. A 4xx from a dependency is a caller-side defect (wrong path, wrong\n     *   base URL, an undeployed dependency, bad service credentials), so the caller owns it as a 500.\n     *\n     * ABSTRACT, not a defaulted pass-through, for the same reason\n     * {@link outboundContextHeaders} takes a required `destination`: a permissive default puts the\n     * wrong answer one keystroke away. A new environment subclass must SAY which of the two it is,\n     * and there are exactly two subclasses in the repo, so the compile error is the migration.\n     *\n     * @param failure - the translated error, its provenance (app-registered vs built-in), and the\n     *                  downstream status\n     * @param callId  - `ApiName.methodName`, so a rewritten message can still name the call\n     */\n    protected abstract adaptDownstreamFailure(failure: TranslatedFailure, callId: string): Error;\n\n    /**\n     * Fires immediately BEFORE `fetch`, once per RPC — the progress \"start marker\". Symmetric with\n     * {@link onRequestEnd}: every start is followed by exactly one end, on every path, so a listener\n     * can drive a counter (bar on / bar off) without leaking a permanently-spinning bar.\n     *\n     * The default is a no-op, so every existing subclass is unaffected.\n     */\n    protected onRequestStart(_route: RouteMetadata): void {}\n\n    /**\n     * Fires exactly ONCE after the call settles, on EVERY path (2xx, HTTP error, network reject) —\n     * the \"stop marker\", carrying how it settled.\n     *\n     * Subsumes the older header-only hook: this is the ONLY place the `fetch` Response — and thus its\n     * `Headers` — exists, so an app that needs to read a response header (e.g. a server-version stamp\n     * for client↔server version matching) reads `outcome.headers`, still BEFORE the body is consumed\n     * and on both the ok and error paths. `outcome.ok`/`outcome.error` add the success-or-error\n     * signal the header-only seam could not give.\n     *\n     * The default is a no-op, so every existing subclass is unaffected.\n     */\n    protected onRequestEnd(_route: RouteMetadata, _outcome: RequestOutcome): void {}\n\n    // ---------------------------------------------------------------- contract binding\n\n    /**\n     * Bind this client to one API contract: read @ApiPath/@Endpoint/@Auth* off the prototype and\n     * build the route map once. Each subclass's `init(api, config)` stores its own config, then\n     * calls this.\n     *\n     * @param appFilters the app's OUTBOUND filters for this client, from `createRpcClient`. They are\n     *        merged with {@link clientFilters} and sorted by priority, highest OUTERMOST.\n     * @throws Error if the prototype lacks @ApiPath, or declares an endpoint this environment\n     *         cannot satisfy (see {@link assertEndpointSupported}).\n     */\n    protected initRoutes(apiPrototype: ApiPrototype<object>, appFilters: ClientFilterDefinition[]): void {\n        this.appFilters = appFilters;\n        if (!isApiPath(apiPrototype)) {\n            const className = apiPrototype.name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiPath()`);\n        }\n\n        const basePath = getApiPath(apiPrototype)!;\n        const endpoints = getEndpoints(apiPrototype) || {};\n\n        // apiName as the class name so client logs read \"SaveApi.save\", not \"undefined.save\"\n        this.apiName = apiPrototype.name || 'UnknownApi';\n\n        this.routeMap = new Map<string, RouteMetadata>();\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            const fullPath = basePath + endpointPath;\n            // Capture the endpoint's auth mode so the client can mint delivery auth per\n            // @AuthOidc / @AuthSharedSecret, exactly as the server verifies it.\n            const authMeta = getAuthMeta(apiPrototype, methodName);\n            this.assertEndpointSupported(authMeta, methodName);\n            const formPost = isFormPost(apiPrototype, methodName);\n            this.routeMap.set(\n                methodName,\n                new RouteMetadata(\n                    'POST', fullPath, methodName, this.apiName, authMeta, undefined, formPost,\n                    getMaskSpec(apiPrototype, methodName), isRawBody(apiPrototype, methodName),\n                ),\n            );\n        }\n\n        // APP filters first (highest priority OUTERMOST, matching the server's FilterMatcher), then\n        // the framework built-ins, ALWAYS innermost. Two separate sorts rather than one over the\n        // union, deliberately: an app priority orders app filters against each other and nothing\n        // else, so no number an app can type — however large — gets underneath the SSRF guard or the\n        // credential minter. A single sorted list would make \"displace the guard\" a matter of typing\n        // a bigger integer, and a security control an app can outrank by accident is not a control.\n        //\n        // Sorted here, once, so FilterChain itself never sorts — priority lives on the DEFINITION,\n        // not on the filter.\n        const byPriority = (a: ClientFilterDefinition, b: ClientFilterDefinition): number =>\n            b.priority - a.priority;\n        const ordered = [...[...this.appFilters].sort(byPriority), ...[...this.clientFilters()].sort(byPriority)];\n        this.chain = new FilterChain<ClientRequest, Response>(\n            ordered.map((definition: ClientFilterDefinition) => definition.filter),\n        );\n    }\n\n    /** The contract's class name, for logs and recordings. */\n    protected contractName(): string {\n        return this.apiName;\n    }\n\n    /** Check if a route exists for the given method name. */\n    hasRoute(methodName: string): boolean {\n        return this.routeMap.has(methodName);\n    }\n\n    /**\n     * Get route metadata for a method name.\n     * @throws Error if no route found\n     */\n    getRoute(methodName: string): RouteMetadata {\n        const route = this.routeMap.get(methodName);\n        if (!route) {\n            throw new Error(`No route found for method ${methodName}`);\n        }\n        return route;\n    }\n\n    // ---------------------------------------------------------------- the call\n\n    /**\n     * FAIL FAST, PER METHOD, at call time: some endpoints exist for a caller that is not us, and this\n     * proxy could only ever build a request they are obliged to reject. Refusing here rather than at\n     * bind time means an api that MIXES such endpoints with normal ones still yields a working client\n     * for the normal ones; only calling the un-callable method throws.\n     *\n     * @throws Error naming the endpoint, what it declared, and who its real caller is.\n     */\n    private refuseEndpointNoClientCanCall(route: RouteMetadata): void {\n        // formPost exists ONLY for EXTERNAL inbound webhooks (e.g. Twilio is the caller). This proxy\n        // JSON.stringifies the body, so calling one would silently send a wrong-encoded body.\n        if (route.formPost) {\n            throw new Error(\n                `${this.apiName}.${route.methodName} is @Endpoint(..., { formPost: true }) — the ` +\n                `webpieces client does not support calling form-encoded endpoints yet. formPost is ` +\n                `for EXTERNAL inbound webhooks (e.g. Twilio) only. If this endpoint needs a ` +\n                `service-to-service client, set formPost:false (or remove it) so it uses JSON.`,\n            );\n        }\n        const authMode = route.authMeta?.mode;\n        // @AuthApiKey: the credential is a CUSTOMER-held key, and the header carrying it is the app's\n        // ApiKeyHook's choice, so this client has nothing to send and the call is a guaranteed 401.\n        if (authMode?.kind === 'apikey') {\n            throw new Error(\n                `${this.apiName}.${route.methodName} is @AuthApiKey('${authMode.regime}') — only the partner ` +\n                `holding that api key can call it, and the header carrying it is the app's ApiKeyHook's choice, ` +\n                `so a webpieces client has no credential to send.`,\n            );\n        }\n        // @AuthWebhook is DELIBERATELY absent from this list. It used to be here, on the assumption\n        // that the vendor is always somebody else — but `@AuthWebhook(name)` names a signing SCHEME,\n        // not a direction, and for an OUTBOUND partner webhook WE are the vendor. The environment's\n        // outbound-auth filter asks its bound signer to produce the signature, which is the exact\n        // mirror of the inbound WebhookAuthCallback that verifies one.\n    }\n\n    /**\n     * Make an HTTP request based on route metadata and arguments.\n     *\n     * All endpoints are POST-only. The request body is the first argument.\n     */\n    // webpieces-disable no-any-unknown -- proxy method: the request DTO (args) + response are erased at the client boundary\n    async makeRequest(route: RouteMetadata, args: any[]): Promise<any> {\n        this.refuseEndpointNoClientCanCall(route);\n        // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.\n        const baseUrl = await this.resolveBaseUrl();\n\n        const httpHeaders = new Map<string, string>([['Content-Type', 'application/json']]);\n\n        // Transferred context, request-id chained. The server impl throws here when there is no\n        // active RequestContext — an outbound call with no trace is a bug, not a default. The\n        // destination's own auth mode decides whether trusted keys are part of that set.\n        const contextHeaders = this.outboundContextHeaders(DestinationTrust.forAuthMode(route.authMeta?.mode));\n        for (const entry of contextHeaders.entries()) {\n            httpHeaders.set(entry[0], entry[1]);\n        }\n\n        // NOTHING mints a credential here. The endpoint's outbound auth is a FILTER, sitting at the\n        // very bottom of the chain, because the URL at this point is only where the call STARTS: an\n        // app filter above may re-point it, and an OIDC token whose audience is the pre-filter URL\n        // is a token for the wrong peer. The minter has to run last, against the settled\n        // destination — see the environment's `clientFilters()`.\n        //\n        // POST body is the first argument as JSON. Serialized HERE, before the filter chain, so a\n        // filter that signs the request signs the exact bytes {@link sendOnce} will transmit.\n        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n        let requestDto: unknown;\n        let body: string | undefined;\n        if (args.length > 0) {\n            requestDto = args[0];\n            body = JSON.stringify(requestDto);\n        }\n\n        const request = new ClientRequest(route, this.apiName, baseUrl, httpHeaders, body, requestDto);\n\n        // Wrap the send in a method for LogApiCall.execute\n        // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary\n        const method = async (): Promise<unknown> => {\n            return this.executeFetch(request);\n        };\n\n        return await this.execute(route, requestDto, method);\n    }\n\n    /**\n     * Execute the fetch request and handle response.\n     *\n     * Brackets the call with the lifecycle seam: {@link onRequestStart} once before `fetch`, then\n     * {@link onRequestEnd} exactly once on each of the three ways a call can settle. The end hook\n     * fires BEFORE the throw on both failure paths, so a listener always sees the stop marker even\n     * though the caller sees an exception.\n     */\n    // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary\n    private async executeFetch(request: ClientRequest): Promise<unknown> {\n        const route = request.route;\n        this.onRequestStart(route);\n\n        // The START marker fires ONCE per RPC even though a filter may send more than once (the SSRF\n        // guard re-invokes the chain to follow a validated redirect) — start and end still pair up\n        // exactly, which is what lets a listener drive a progress counter.\n        let response: Response;\n        // webpieces-disable no-unmanaged-exceptions -- translate a send failure into a lifecycle END, then rethrow\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            response = await this.chain.execute(request, () => this.sendOnce(request));\n        } catch (err: unknown) {\n            // No Response ever existed — a network reject already classified by sendOnce, or a filter\n            // that refused to send at all (an SSRF policy rejecting a partner's URL). Either way there\n            // is no status and no headers to report, only status 0 and the failure itself, and the\n            // lifecycle listener must see the SAME error the caller is about to.\n            const error = toError(err);\n            this.onRequestEnd(route, new RequestOutcome(false, 0, undefined, error));\n            throw error;\n        }\n\n        const callId = `${this.apiName}.${route.methodName}`;\n        if (response.ok) {\n            return this.readSuccessBody(response, route, callId);\n        }\n        throw await this.endWithTypedFailure(response, route, callId);\n    }\n\n    /**\n     * ONE transmission — the bottom of the filter chain, and the only place `fetch` is called.\n     *\n     * Everything it sends comes off the {@link ClientRequest} as the chain left it, so a filter's\n     * edits to the url, the headers or the serialized body are exactly what goes on the wire. It may\n     * run more than once for a single RPC when a filter follows a redirect.\n     *\n     * A network reject (offline, DNS, CORS preflight) is classified into a typed OfflineError here (a\n     * genuine bug passes through untouched) so that filters above see the same typed error the caller\n     * will, rather than a raw platform reject.\n     */\n    private async sendOnce(request: ClientRequest): Promise<Response> {\n        const options: RequestInit = {\n            method: request.route.httpMethod,\n            headers: request.headersAsRecord(),\n            redirect: request.followRedirects ? 'follow' : 'manual',\n        };\n        if (request.body !== undefined) {\n            options.body = request.body;\n        }\n        // webpieces-disable no-unmanaged-exceptions -- classify a network reject, then rethrow it typed\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-fetch -- this IS the generated-client implementation the rule points everyone to\n            return await fetch(request.url, options);\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw this.networkRejectClassifier.toNetworkError(error, request.url);\n        }\n    }\n\n    /**\n     * Read a 2xx body, reporting the END marker on both outcomes.\n     *\n     * The content-type gate is the same one the error path uses: a 2xx that is not JSON (a proxy's\n     * captive-portal page, an SPA index.html served by a misrouted CDN) is reported for WHAT ARRIVED,\n     * instead of `SyntaxError: Unexpected token '<'`, which names nothing a reader can act on.\n     */\n    // webpieces-disable no-any-unknown -- the response DTO's type is erased at the proxy boundary\n    private async readSuccessBody(response: Response, route: RouteMetadata, callId: string): Promise<unknown> {\n        // webpieces-disable no-unmanaged-exceptions -- a malformed 2xx body must still report the END marker\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            if (!this.bodyReader.isJson(response)) {\n                throw new Error(this.bodyReader.describeForeignBody(response, callId, await response.text()));\n            }\n            const body = await response.json();\n            this.onRequestEnd(route, new RequestOutcome(true, response.status, response.headers));\n            return body;\n        } catch (err: unknown) {\n            const error = toError(err);\n            this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n            throw error;\n        }\n    }\n\n    /**\n     * Turn a non-2xx response into the error the caller will see, firing the END marker first — so a\n     * listener always gets its stop marker even though the caller sees an exception. RETURNS the\n     * error rather than throwing it, which keeps the one `throw` visible at the call site.\n     *\n     * The headers still reach the seam here, so a version (or any future) header is observed even on\n     * error responses.\n     *\n     * The body is read through {@link ResponseBodyReader}, which parses ONLY a body whose\n     * content-type says it is JSON. An infra 502/503/504 (load balancer, proxy, cold start on a\n     * scale-to-zero backend) serves HTML, and parsing that used to throw `SyntaxError: Unexpected\n     * token '<'` — discarding the status, so the caller could not tell a booting server from a broken\n     * client. It now becomes a synthesized ProtocolError translated BY STATUS, i.e. a real\n     * `HttpBadGatewayError` / `HttpServiceUnavailableError` / `HttpGatewayTimeoutError`.\n     *\n     * The try/catch stays, for a NARROWER job than before: a body that DECLARED json and was\n     * malformed still throws (that one is a genuine server bug), and the END marker must fire for it\n     * too — an unreported end leaves the app's progress bar spinning forever.\n     *\n     * `translated` is what ClientErrorTranslator picked, and translateError RETURNS a\n     * {@link TranslatedFailure} — so nothing in this seam is ever `unknown`.\n     *\n     * The translated failure then goes through {@link adaptDownstreamFailure}, which is where the two\n     * environments part company (browser rethrows it, node turns a downstream 4xx into its own 500).\n     *\n     * The RequestOutcome reported to {@link onRequestEnd} carries the POST-adapt error, deliberately:\n     * a lifecycle listener must see the SAME error the caller sees, or a progress bar / error toast\n     * says 404 while the thrown exception says 500. That is the identical rule the network-reject path\n     * already follows (it classifies BEFORE onRequestEnd for exactly this reason). The pre-adapt error\n     * is not lost — it is the adapted error's `httpCause`.\n     */\n    private async endWithTypedFailure(response: Response, route: RouteMetadata, callId: string): Promise<Error> {\n        let translated: TranslatedFailure;\n        // webpieces-disable no-unmanaged-exceptions -- a malformed JSON error body must still report the END marker\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const protocolError = await this.bodyReader.readErrorBody(response, callId);\n            translated = ClientErrorTranslator.translateError(\n                this.responseDtoFactory.fromFetch(response, protocolError),\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            // The response CLAIMED JSON and was not parseable — report that failure as the outcome.\n            // It never reaches adaptDownstreamFailure: there is no translated status to adapt, and a\n            // body that broke its own content-type promise is already a defect, not a status answer.\n            this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n            return error;\n        }\n\n        const adapted = this.adaptDownstreamFailure(translated, callId);\n        this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, adapted));\n        return adapted;\n    }\n}\n"]}
+{"version":3,"file":"ProxyClient.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMeta,\n    isFormPost,\n    isRawBody,\n    getMaskSpec,\n    AuthMeta,\n    DestinationTrust,\n    RouteMetadata,\n    LogApiCallImpl,\n    ApiMethodInfo,\n    toError,\n    NetworkRejectClassifier,\n    FilterChain,\n    CallRegistry,\n    CallDeadline,\n    CallContext,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientFilterDefinition } from './ClientFilter';\nimport { ClientRequest } from './ClientRequest';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\nimport { HttpResponseDtoFactory } from './HttpResponseDtoFactory';\nimport { RequestOutcome } from './RequestOutcome';\nimport { ResponseBodyReader } from './ResponseBodyReader';\nimport { TranslatedFailure } from './TranslatedFailure';\n\n/**\n * ProxyClient - the HTTP call engine behind one API contract's client proxy.\n *\n * Contains ONLY what a browser can run: the route map built from the contract's decorators, URL\n * assembly, `fetch`, error translation, and logging. It holds no context object, no credentials,\n * and no recorder — it ASKS ITSELF for those through the hooks below, and each subclass answers\n * from its own environment.\n *\n * That is why the class is abstract rather than parameterized by a collaborator: a shared\n * header-provider seam would drag Node's AsyncLocalStorage vocabulary into a browser bundle and the\n * browser's store vocabulary into a server, and neither has any use for the other.\n *\n *   NodeProxyClient    (@webpieces/http-client-node)    -> RequestContext, Secrets, mintIdToken, recording\n *   BrowserProxyClient (@webpieces/http-client-browser) -> an app-held store, no credentials, no recording\n *\n * TWO-PHASE: collaborators arrive on the subclass constructor (so a DI container can supply them),\n * while the per-client state — which contract, which target — arrives on the subclass's `init`,\n * which calls {@link initRoutes}. That is what lets a factory hold a `Provider<ProxyClient>` and\n * hand out a fresh, independently-configured client per contract.\n */\nexport abstract class ProxyClient {\n    // Assigned by initRoutes(), which every subclass's init() calls immediately after construction.\n    private routeMap!: Map<string, RouteMetadata>;\n    private apiName!: string;\n    private apiClass!: ApiPrototype<object>;\n\n    /**\n     * The OUTBOUND filter chain, built once at bind time from {@link clientFilters} and reused for\n     * every call. Built once rather than per call because a filter is STATELESS by contract (the\n     * per-call state is the {@link ClientRequest} the chain is handed), exactly as on the server.\n     */\n    private chain!: FilterChain<ClientRequest, Response>;\n\n    /**\n     * The app's own filters, as handed to `createRpcClient`. Set by {@link initRoutes} BEFORE it\n     * calls {@link clientFilters}, so an environment's built-ins may read the app's intent off them\n     * — @webpieces/http-client-node takes the SSRF policy from an installed `ContextBaseUrlFilter`\n     * that way, which keeps the one legitimate relaxation at the same construction site as the\n     * decision to be re-pointable at all.\n     */\n    protected appFilters: ClientFilterDefinition[] = [];\n\n    // Stateless + dependency-free, so the browser bundle keeps no DI on the fetch path.\n    private readonly networkRejectClassifier = new NetworkRejectClassifier();\n\n    // Same shape and same reason: stateless, so it is constructed here rather than injected.\n    private readonly bodyReader = new ResponseBodyReader();\n\n    /**\n     * fetch `Response` -> the transport-neutral {@link HttpResponseDto} an app's `ErrorTranslators`\n     * sees. Normalising HERE is what makes `fromWire` receive the identical shape in node and in the\n     * browser: both environments share this class, and this is the only place either builds a DTO.\n     */\n    private readonly responseDtoFactory = new HttpResponseDtoFactory();\n\n    /**\n     * @param logApiCall - built by the SUBCLASS's package around that environment's ApiCallContext\n     *   (node: RequestContextApiCallContext; browser: BrowserApiCallContext). REQUIRED, with no\n     *   default: core-util cannot construct either one, and a default here would have to reach for a\n     *   process-global — which is exactly the throw-on-first-call this parameter deleted.\n     */\n    constructor(protected readonly logApiCall: LogApiCallImpl) {}\n\n    // ---------------------------------------------------------------- environment hooks\n\n    /** The callee's base URL. Async because a server may derive it from container metadata. */\n    protected abstract resolveBaseUrl(): Promise<string>;\n\n    /**\n     * Context headers to put on the wire. Server reads RequestContext; browser reads its store.\n     *\n     * `destination` is derived from THIS route's auth mode and decides whether TRUSTED context keys\n     * (`x-user-id`, `x-org-id`, `x-webpieces-roles`) may ride along — see {@link DestinationTrust}.\n     * It is a required argument on purpose: a defaulted \"send everything\" would put the permissive\n     * answer one keystroke away and make the safe one opt-in.\n     *\n     * RENAMED from `outboundHeaders()` in the same change that added `destination`, and the rename IS\n     * the migration. TypeScript accepts an override that declares FEWER parameters than its base, so a\n     * downstream `protected override outboundHeaders(): Map<string, string>` would have kept compiling\n     * and silently ignored the gate — the permissive behaviour surviving as a second spelling. Against\n     * the NEW name that subclass fails twice over: `override` names a member the base no longer has,\n     * and this abstract member is left unimplemented.\n     */\n    protected abstract outboundContextHeaders(destination: DestinationTrust): Map<string, string>;\n\n    /**\n     * Run the call. The default just logs it. Test-case RECORDING is a server concept, so\n     * NodeProxyClient overrides this to capture the call when a recorder is in the context.\n     *\n     * Context fields are NOT passed in: a logging backend stamps them onto every record itself.\n     */\n    // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    protected async execute(\n        route: RouteMetadata,\n        requestDto: unknown,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n        method: () => Promise<unknown>,\n        // webpieces-disable no-any-unknown -- DTO types are erased at the proxy boundary\n    ): Promise<unknown> {\n        // apiClass = the CONTRACT name (this.apiName, e.g. 'SaveApi') so this client log line MATCHES\n        // the server's for the same call. A client has no impl class, so controllerName is omitted.\n        const info = new ApiMethodInfo('client', this.apiName, route.methodName, undefined, route.mask);\n        return this.logApiCall.execute(info, requestDto, method);\n    }\n\n    /**\n     * Reject, at bind time, an endpoint this environment cannot satisfy — e.g. a browser cannot\n     * mint the OIDC token an @AuthOidc endpoint demands. Surfacing it here beats failing on the\n     * first call in production. The default accepts everything.\n     */\n    protected assertEndpointSupported(_authMeta: AuthMeta | undefined, _methodName: string): void {}\n\n    /**\n     * The FRAMEWORK filters this environment installs on every client it builds, BENEATH whatever\n     * the app passed to `createRpcClient`. The default installs none, so the browser runs the exact\n     * code path it ran before the chain existed.\n     *\n     * \"Beneath\" is not a priority — see {@link initRoutes}. These are the filters that must judge\n     * and sign what is ACTUALLY about to be sent, so no app priority may be allowed to get under\n     * them: @webpieces/http-client-node installs its SSRF guard and its outbound-auth minter here,\n     * and both would be defeated by an app filter that re-pointed the URL below them. Neither\n     * concept can live in this class, because reading a RequestContext, resolving DNS and minting\n     * an OIDC token are all things a browser bundle must never contain.\n     */\n    protected clientFilters(): ClientFilterDefinition[] {\n        return [];\n    }\n\n    /**\n     * Adapt a translated downstream failure into the error THIS environment's caller should see.\n     *\n     * THE INVARIANT, and the reason this hook exists at all:\n     *\n     *   A status received from a downstream dependency describes OUR request to it. It is never the\n     *   status we return to OUR caller. The server that answered 404 is correct; the server that\n     *   asked for a route that does not exist is broken, and must say so as a 500.\n     *\n     * That invariant reads differently in the two environments, which is exactly why the ISOMORPHIC\n     * {@link ClientErrorTranslator} cannot settle it:\n     * - BROWSER: the client IS the end user's agent, so the downstream IS the answer. Pass it through\n     *   unchanged.\n     * - NODE: server-to-server. A 4xx from a dependency is a caller-side defect (wrong path, wrong\n     *   base URL, an undeployed dependency, bad service credentials), so the caller owns it as a 500.\n     *\n     * ABSTRACT, not a defaulted pass-through, for the same reason\n     * {@link outboundContextHeaders} takes a required `destination`: a permissive default puts the\n     * wrong answer one keystroke away. A new environment subclass must SAY which of the two it is,\n     * and there are exactly two subclasses in the repo, so the compile error is the migration.\n     *\n     * @param failure - the translated error, its provenance (app-registered vs built-in), and the\n     *                  downstream status\n     * @param callId  - `ApiName.methodName`, so a rewritten message can still name the call\n     */\n    protected abstract adaptDownstreamFailure(failure: TranslatedFailure, callId: string): Error;\n\n    /**\n     * Fires before the logical call's attempts, once per RPC — the progress \"start marker\". Symmetric with\n     * {@link onRequestEnd}: every start is followed by exactly one end, on every path, so a listener\n     * can drive a counter (bar on / bar off) without leaking a permanently-spinning bar.\n     *\n     * The default is a no-op, so every existing subclass is unaffected.\n     */\n    protected onRequestStart(_route: RouteMetadata): void {}\n\n    /**\n     * Fires exactly ONCE after the call settles, on EVERY path (2xx, HTTP error, network reject) —\n     * the \"stop marker\", carrying how it settled.\n     *\n     * Subsumes the older header-only hook: this is the ONLY place the `fetch` Response — and thus its\n     * `Headers` — exists, so an app that needs to read a response header (e.g. a server-version stamp\n     * for client↔server version matching) reads `outcome.headers` after settlement\n     * and on both the ok and error paths. `outcome.ok`/`outcome.error` add the success-or-error\n     * signal the header-only seam could not give.\n     *\n     * The default is a no-op, so every existing subclass is unaffected.\n     */\n    protected onRequestEnd(_route: RouteMetadata, _outcome: RequestOutcome): void {}\n\n    // ---------------------------------------------------------------- contract binding\n\n    /**\n     * Bind this client to one API contract: read @ApiPath/@Endpoint/@Auth* off the prototype and\n     * build the route map once. Each subclass's `init(api, config)` stores its own config, then\n     * calls this.\n     *\n     * @param appFilters the app's OUTBOUND filters for this client, from `createRpcClient`. They are\n     *        merged with {@link clientFilters} and sorted by priority, highest OUTERMOST.\n     * @throws Error if the prototype lacks @ApiPath, or declares an endpoint this environment\n     *         cannot satisfy (see {@link assertEndpointSupported}).\n     */\n    protected initRoutes(apiPrototype: ApiPrototype<object>, appFilters: ClientFilterDefinition[]): void {\n        this.appFilters = appFilters;\n        this.apiClass = apiPrototype;\n        if (!isApiPath(apiPrototype)) {\n            const className = apiPrototype.name || 'Unknown';\n            throw new Error(`Class ${className} must be decorated with @ApiPath()`);\n        }\n\n        const basePath = getApiPath(apiPrototype)!;\n        const endpoints = getEndpoints(apiPrototype) || {};\n\n        // apiName as the class name so client logs read \"SaveApi.save\", not \"undefined.save\"\n        this.apiName = apiPrototype.name || 'UnknownApi';\n\n        this.routeMap = new Map<string, RouteMetadata>();\n        for (const [methodName, endpointPath] of Object.entries(endpoints)) {\n            const fullPath = basePath + endpointPath;\n            // Capture the endpoint's auth mode so the client can mint delivery auth per\n            // @AuthOidc / @AuthSharedSecret, exactly as the server verifies it.\n            const authMeta = getAuthMeta(apiPrototype, methodName);\n            this.assertEndpointSupported(authMeta, methodName);\n            const formPost = isFormPost(apiPrototype, methodName);\n            this.routeMap.set(\n                methodName,\n                new RouteMetadata(\n                    'POST', fullPath, methodName, this.apiName, authMeta, undefined, formPost,\n                    getMaskSpec(apiPrototype, methodName), isRawBody(apiPrototype, methodName),\n                ),\n            );\n        }\n\n        // APP filters first (highest priority OUTERMOST, matching the server's FilterMatcher), then\n        // the framework built-ins, ALWAYS innermost. Two separate sorts rather than one over the\n        // union, deliberately: an app priority orders app filters against each other and nothing\n        // else, so no number an app can type — however large — gets underneath the SSRF guard or the\n        // credential minter. A single sorted list would make \"displace the guard\" a matter of typing\n        // a bigger integer, and a security control an app can outrank by accident is not a control.\n        //\n        // Sorted here, once, so FilterChain itself never sorts — priority lives on the DEFINITION,\n        // not on the filter.\n        const byPriority = (a: ClientFilterDefinition, b: ClientFilterDefinition): number =>\n            b.priority - a.priority;\n        const ordered = [...[...this.appFilters].sort(byPriority), ...[...this.clientFilters()].sort(byPriority)];\n        this.chain = new FilterChain<ClientRequest, Response>(\n            ordered.map((definition: ClientFilterDefinition) => definition.filter),\n        );\n    }\n\n    /** The contract's class name, for logs and recordings. */\n    protected contractName(): string {\n        return this.apiName;\n    }\n\n    /** Check if a route exists for the given method name. */\n    hasRoute(methodName: string): boolean {\n        return this.routeMap.has(methodName);\n    }\n\n    /**\n     * Get route metadata for a method name.\n     * @throws Error if no route found\n     */\n    getRoute(methodName: string): RouteMetadata {\n        const route = this.routeMap.get(methodName);\n        if (!route) {\n            throw new Error(`No route found for method ${methodName}`);\n        }\n        return route;\n    }\n\n    // ---------------------------------------------------------------- the call\n\n    /**\n     * FAIL FAST, PER METHOD, at call time: some endpoints exist for a caller that is not us, and this\n     * proxy could only ever build a request they are obliged to reject. Refusing here rather than at\n     * bind time means an api that MIXES such endpoints with normal ones still yields a working client\n     * for the normal ones; only calling the un-callable method throws.\n     *\n     * @throws Error naming the endpoint, what it declared, and who its real caller is.\n     */\n    private refuseEndpointNoClientCanCall(route: RouteMetadata): void {\n        // formPost exists ONLY for EXTERNAL inbound webhooks (e.g. Twilio is the caller). This proxy\n        // JSON.stringifies the body, so calling one would silently send a wrong-encoded body.\n        if (route.formPost) {\n            throw new Error(\n                `${this.apiName}.${route.methodName} is @Endpoint(..., { formPost: true }) — the ` +\n                `webpieces client does not support calling form-encoded endpoints yet. formPost is ` +\n                `for EXTERNAL inbound webhooks (e.g. Twilio) only. If this endpoint needs a ` +\n                `service-to-service client, set formPost:false (or remove it) so it uses JSON.`,\n            );\n        }\n        const authMode = route.authMeta?.mode;\n        // @AuthApiKey: the credential is a CUSTOMER-held key, and the header carrying it is the app's\n        // ApiKeyHook's choice, so this client has nothing to send and the call is a guaranteed 401.\n        if (authMode?.kind === 'apikey') {\n            throw new Error(\n                `${this.apiName}.${route.methodName} is @AuthApiKey('${authMode.regime}') — only the partner ` +\n                `holding that api key can call it, and the header carrying it is the app's ApiKeyHook's choice, ` +\n                `so a webpieces client has no credential to send.`,\n            );\n        }\n        // @AuthWebhook is DELIBERATELY absent from this list. It used to be here, on the assumption\n        // that the vendor is always somebody else — but `@AuthWebhook(name)` names a signing SCHEME,\n        // not a direction, and for an OUTBOUND partner webhook WE are the vendor. The environment's\n        // outbound-auth filter asks its bound signer to produce the signature, which is the exact\n        // mirror of the inbound WebhookAuthCallback that verifies one.\n    }\n\n    /** One logical call: one lifecycle pair and log entry across all strategy attempts. */\n    // webpieces-disable no-any-unknown -- request and response DTOs are erased at the proxy boundary\n    async makeRequest(route: RouteMetadata, args: unknown[]): Promise<unknown> {\n        this.refuseEndpointNoClientCanCall(route);\n        const requestDto = args[0];\n        return this.execute(route, requestDto, () => this.executeCall(route, requestDto));\n    }\n\n    // webpieces-disable no-any-unknown -- response DTO is erased at the proxy boundary\n    private async executeCall(route: RouteMetadata, requestDto: unknown): Promise<unknown> {\n        this.onRequestStart(route);\n        let response: Response | undefined;\n        // webpieces-disable no-any-unknown -- response DTO is erased at the proxy boundary\n        let result: unknown;\n        // webpieces-disable no-unmanaged-exceptions -- report one logical END, preserving the original thrown value\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            result = await CallRegistry.execute(this.apiClass, route.methodName, (timeoutMs: number) => {\n                response = undefined;\n                return CallDeadline.run(timeoutMs, new CallContext(this.apiName, route.methodName),\n                    async (signal: AbortSignal) => {\n                        const request = await this.prepareRequest(route, requestDto);\n                        signal.throwIfAborted();\n                        const received = await this.chain.execute(request, () => this.sendOnce(request, signal));\n                        signal.throwIfAborted();\n                        response = received;\n                        return this.readResponse(received, route);\n                    });\n            }, 30_000);\n        } catch (err: unknown) {\n            const error = toError(err);\n            this.onRequestEnd(route, new RequestOutcome(false, response?.status ?? 0, response?.headers, error));\n            throw err;\n        }\n        this.onRequestEnd(route, new RequestOutcome(true, response?.status ?? 0, response?.headers));\n        return result;\n    }\n\n    /** Fresh mutable request for every attempt, including URL, headers, auth and body. */\n    // webpieces-disable no-any-unknown -- request DTO is erased at the proxy boundary\n    private async prepareRequest(route: RouteMetadata, requestDto: unknown): Promise<ClientRequest> {\n        const baseUrl = await this.resolveBaseUrl();\n        const headers = new Map<string, string>([['Content-Type', 'application/json']]);\n        const context = this.outboundContextHeaders(DestinationTrust.forAuthMode(route.authMeta?.mode));\n        for (const entry of context.entries()) headers.set(entry[0], entry[1]);\n        return new ClientRequest(route, this.apiName, baseUrl, headers, JSON.stringify(requestDto), requestDto);\n    }\n\n    /**\n     * ONE transmission — the bottom of the filter chain, and the only place `fetch` is called.\n     *\n     * Everything it sends comes off the {@link ClientRequest} as the chain left it, so a filter's\n     * edits to the url, the headers or the serialized body are exactly what goes on the wire. It may\n     * run more than once for a single RPC when a filter follows a redirect.\n     *\n     * A network reject (offline, DNS, CORS preflight) is classified into a typed OfflineError here (a\n     * genuine bug passes through untouched) so that filters above see the same typed error the caller\n     * will, rather than a raw platform reject.\n     */\n    private async sendOnce(request: ClientRequest, signal: AbortSignal): Promise<Response> {\n        signal.throwIfAborted();\n        const options: RequestInit = {\n            method: request.route.httpMethod,\n            signal,\n            headers: request.headersAsRecord(),\n            redirect: request.followRedirects ? 'follow' : 'manual',\n        };\n        if (request.body !== undefined) {\n            options.body = request.body;\n        }\n        // webpieces-disable no-unmanaged-exceptions -- classify a network reject, then rethrow it typed\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            // webpieces-disable no-fetch -- this IS the generated-client implementation the rule points everyone to\n            return await fetch(request.url, options);\n        } catch (err: unknown) {\n            const error = toError(err);\n            throw this.networkRejectClassifier.toNetworkError(error, request.url);\n        }\n    }\n\n    /** Body consumption is inside the attempt deadline, including non-JSON error bodies. */\n    // webpieces-disable no-any-unknown -- response DTO is erased at the proxy boundary\n    private async readResponse(response: Response, route: RouteMetadata): Promise<unknown> {\n        const callId = `${this.apiName}.${route.methodName}`;\n        if (response.ok) {\n            if (!this.bodyReader.isJson(response)) {\n                throw new Error(this.bodyReader.describeForeignBody(response, callId, await response.text()));\n            }\n            return response.json();\n        }\n        const protocolError = await this.bodyReader.readErrorBody(response, callId);\n        const translated = ClientErrorTranslator.translateError(\n            this.responseDtoFactory.fromFetch(response, protocolError),\n        );\n        throw this.adaptDownstreamFailure(translated, callId);\n    }\n}\n"]}

package/src/RequestOutcome.d.ts

@@ -2,7 +2,7 @@
  * How one RPC call SETTLED — the payload of {@link ProxyClient.onRequestEnd}.
  *
  * DATA ONLY (no behavior), so it is a class with an explicit constructor rather than an interface:
- * each of the three settle paths in `ProxyClient.executeFetch` constructs it by name, and a reader
+ * `ProxyClient.executeCall` constructs it by name on settlement, and a reader
  * can see at the call site which path produced which shape.
  *
  * The three shapes, one per path:
@@ -10,17 +10,16 @@
  * - HTTP error     `new RequestOutcome(false, status, headers, error)`  — the translated HttpError
  * - network reject `new RequestOutcome(false, 0, undefined, error)`     — no Response ever existed
  *
- * A fourth path exists but is not a fourth SHAPE: a body that fails to parse (an infra 502 serving
- * HTML) settles as an HTTP error carrying the parse failure.
+ * A timeout or body parse failure uses the failure shape, with headers/status if they arrived.
  */
 export declare class RequestOutcome {
-    /** `response.ok` — true only on a 2xx. */
+    /** True when the logical call succeeded, including a strategy recovering from an error. */
     readonly ok: boolean;
-    /** The HTTP status; 0 when `fetch` itself rejected (network / offline), where there is no status. */
+    /** The last attempt's HTTP status, or 0 when no response arrived. */
     readonly status: number;
     /**
      * The Response headers, present whenever an HTTP Response existed (ok OR error) and absent
-     * only on a network reject. Read BEFORE the body is consumed, which is what lets an app pull
+     * when no response arrived. Available after settlement, which lets an app pull
      * a server-version stamp off an error response.
      */
     readonly headers?: Headers | undefined;
@@ -35,13 +34,13 @@ export declare class RequestOutcome {
      */
     readonly error?: Error | undefined;
     constructor(
-    /** `response.ok` — true only on a 2xx. */
+    /** True when the logical call succeeded, including a strategy recovering from an error. */
     ok: boolean, 
-    /** The HTTP status; 0 when `fetch` itself rejected (network / offline), where there is no status. */
+    /** The last attempt's HTTP status, or 0 when no response arrived. */
     status: number, 
     /**
      * The Response headers, present whenever an HTTP Response existed (ok OR error) and absent
-     * only on a network reject. Read BEFORE the body is consumed, which is what lets an app pull
+     * when no response arrived. Available after settlement, which lets an app pull
      * a server-version stamp off an error response.
      */
     headers?: Headers | undefined, 

package/src/RequestOutcome.js

@@ -5,7 +5,7 @@ exports.RequestOutcome = void 0;
  * How one RPC call SETTLED — the payload of {@link ProxyClient.onRequestEnd}.
  *
  * DATA ONLY (no behavior), so it is a class with an explicit constructor rather than an interface:
- * each of the three settle paths in `ProxyClient.executeFetch` constructs it by name, and a reader
+ * `ProxyClient.executeCall` constructs it by name on settlement, and a reader
  * can see at the call site which path produced which shape.
  *
  * The three shapes, one per path:
@@ -13,8 +13,7 @@ exports.RequestOutcome = void 0;
  * - HTTP error     `new RequestOutcome(false, status, headers, error)`  — the translated HttpError
  * - network reject `new RequestOutcome(false, 0, undefined, error)`     — no Response ever existed
  *
- * A fourth path exists but is not a fourth SHAPE: a body that fails to parse (an infra 502 serving
- * HTML) settles as an HTTP error carrying the parse failure.
+ * A timeout or body parse failure uses the failure shape, with headers/status if they arrived.
  */
 class RequestOutcome {
     ok;
@@ -22,13 +21,13 @@ class RequestOutcome {
     headers;
     error;
     constructor(
-    /** `response.ok` — true only on a 2xx. */
+    /** True when the logical call succeeded, including a strategy recovering from an error. */
     ok, 
-    /** The HTTP status; 0 when `fetch` itself rejected (network / offline), where there is no status. */
+    /** The last attempt's HTTP status, or 0 when no response arrived. */
     status, 
     /**
      * The Response headers, present whenever an HTTP Response existed (ok OR error) and absent
-     * only on a network reject. Read BEFORE the body is consumed, which is what lets an app pull
+     * when no response arrived. Available after settlement, which lets an app pull
      * a server-version stamp off an error response.
      */
     headers, 

package/src/RequestOutcome.js.map

@@ -1 +1 @@
-{"version":3,"file":"RequestOutcome.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/RequestOutcome.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAa,cAAc;IAGH;IAEA;IAMA;IAUA;IApBpB;IACI,0CAA0C;IAC1B,EAAW;IAC3B,qGAAqG;IACrF,MAAc;IAC9B;;;;OAIG;IACa,OAAiB;IACjC;;;;;;;;OAQG;IACa,KAAa;QAlBb,OAAE,GAAF,EAAE,CAAS;QAEX,WAAM,GAAN,MAAM,CAAQ;QAMd,YAAO,GAAP,OAAO,CAAU;QAUjB,UAAK,GAAL,KAAK,CAAQ;IAC9B,CAAC;CACP;AAvBD,wCAuBC","sourcesContent":["/**\n * How one RPC call SETTLED — the payload of {@link ProxyClient.onRequestEnd}.\n *\n * DATA ONLY (no behavior), so it is a class with an explicit constructor rather than an interface:\n * each of the three settle paths in `ProxyClient.executeFetch` constructs it by name, and a reader\n * can see at the call site which path produced which shape.\n *\n * The three shapes, one per path:\n * - 2xx            `new RequestOutcome(true, status, headers)`          — no error\n * - HTTP error     `new RequestOutcome(false, status, headers, error)`  — the translated HttpError\n * - network reject `new RequestOutcome(false, 0, undefined, error)`     — no Response ever existed\n *\n * A fourth path exists but is not a fourth SHAPE: a body that fails to parse (an infra 502 serving\n * HTML) settles as an HTTP error carrying the parse failure.\n */\nexport class RequestOutcome {\n    constructor(\n        /** `response.ok` — true only on a 2xx. */\n        public readonly ok: boolean,\n        /** The HTTP status; 0 when `fetch` itself rejected (network / offline), where there is no status. */\n        public readonly status: number,\n        /**\n         * The Response headers, present whenever an HTTP Response existed (ok OR error) and absent\n         * only on a network reject. Read BEFORE the body is consumed, which is what lets an app pull\n         * a server-version stamp off an error response.\n         */\n        public readonly headers?: Headers,\n        /**\n         * Set on every non-success path: for a non-2xx, the error the CALLER will see — i.e. what\n         * `ClientErrorTranslator` picked AFTER `ProxyClient.adaptDownstreamFailure` had its say, so a\n         * listener never disagrees with the thrown exception (on a server that is the 500 wrapping a\n         * downstream 4xx, with the original reachable as `httpCause`). Otherwise the network/parse\n         * failure normalized through `toError`. Always a real `Error` — never `unknown`, because\n         * nothing here is untyped: `translateError` RETURNS a typed `TranslatedFailure`, and every\n         * rejection reaching this class has been through `toError`.\n         */\n        public readonly error?: Error,\n    ) {}\n}\n"]}
+{"version":3,"file":"RequestOutcome.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/RequestOutcome.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;GAaG;AACH,MAAa,cAAc;IAGH;IAEA;IAMA;IAUA;IApBpB;IACI,2FAA2F;IAC3E,EAAW;IAC3B,qEAAqE;IACrD,MAAc;IAC9B;;;;OAIG;IACa,OAAiB;IACjC;;;;;;;;OAQG;IACa,KAAa;QAlBb,OAAE,GAAF,EAAE,CAAS;QAEX,WAAM,GAAN,MAAM,CAAQ;QAMd,YAAO,GAAP,OAAO,CAAU;QAUjB,UAAK,GAAL,KAAK,CAAQ;IAC9B,CAAC;CACP;AAvBD,wCAuBC","sourcesContent":["/**\n * How one RPC call SETTLED — the payload of {@link ProxyClient.onRequestEnd}.\n *\n * DATA ONLY (no behavior), so it is a class with an explicit constructor rather than an interface:\n * `ProxyClient.executeCall` constructs it by name on settlement, and a reader\n * can see at the call site which path produced which shape.\n *\n * The three shapes, one per path:\n * - 2xx            `new RequestOutcome(true, status, headers)`          — no error\n * - HTTP error     `new RequestOutcome(false, status, headers, error)`  — the translated HttpError\n * - network reject `new RequestOutcome(false, 0, undefined, error)`     — no Response ever existed\n *\n * A timeout or body parse failure uses the failure shape, with headers/status if they arrived.\n */\nexport class RequestOutcome {\n    constructor(\n        /** True when the logical call succeeded, including a strategy recovering from an error. */\n        public readonly ok: boolean,\n        /** The last attempt's HTTP status, or 0 when no response arrived. */\n        public readonly status: number,\n        /**\n         * The Response headers, present whenever an HTTP Response existed (ok OR error) and absent\n         * when no response arrived. Available after settlement, which lets an app pull\n         * a server-version stamp off an error response.\n         */\n        public readonly headers?: Headers,\n        /**\n         * Set on every non-success path: for a non-2xx, the error the CALLER will see — i.e. what\n         * `ClientErrorTranslator` picked AFTER `ProxyClient.adaptDownstreamFailure` had its say, so a\n         * listener never disagrees with the thrown exception (on a server that is the 500 wrapping a\n         * downstream 4xx, with the original reachable as `httpCause`). Otherwise the network/parse\n         * failure normalized through `toError`. Always a real `Error` — never `unknown`, because\n         * nothing here is untyped: `translateError` RETURNS a typed `TranslatedFailure`, and every\n         * rejection reaching this class has been through `toError`.\n         */\n        public readonly error?: Error,\n    ) {}\n}\n"]}