@webpieces/http-client-core 0.4.645 → 0.4.647

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-client-core",
-  "version": "0.4.645",
+  "version": "0.4.647",
   "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.645"
+    "@webpieces/core-util": "0.4.647"
   }
 }

package/src/ClientErrorTranslator.d.ts

@@ -25,6 +25,7 @@ export declare class ClientErrorTranslator {
      * - 408 → HttpTimeoutError
      * - 500 → HttpInternalServerError
      * - 502 → HttpBadGatewayError
+     * - 503 → HttpServiceUnavailableError
      * - 504 → HttpGatewayTimeoutError
      * - 598 → HttpVendorError (with waitSeconds) - custom status code
      * - other → generic HttpError

package/src/ClientErrorTranslator.js

@@ -28,6 +28,7 @@ class ClientErrorTranslator {
      * - 408 → HttpTimeoutError
      * - 500 → HttpInternalServerError
      * - 502 → HttpBadGatewayError
+     * - 503 → HttpServiceUnavailableError
      * - 504 → HttpGatewayTimeoutError
      * - 598 → HttpVendorError (with waitSeconds) - custom status code
      * - other → generic HttpError
@@ -66,6 +67,8 @@ class ClientErrorTranslator {
                 return new core_util_1.HttpInternalServerError(message);
             case 502:
                 return new core_util_1.HttpBadGatewayError(message);
+            case 503:
+                return new core_util_1.HttpServiceUnavailableError(message);
             case 504:
                 return new core_util_1.HttpGatewayTimeoutError(message);
             case 598: // HttpVendorError - custom status code for vendor/external service errors

package/src/ClientErrorTranslator.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientErrorTranslator.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ClientErrorTranslator.ts"],"names":[],"mappings":";;;AAAA,oDAc8B;AAE9B;;;;;;;;;;;;GAYG;AACH,MAAa,qBAAqB;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,cAAc,CAAC,QAAkB,EAAE,aAA4B;QAClE,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;QACnC,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,QAAQ,CAAC,UAAU,IAAI,eAAe,CAAC;QAChF,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;QAEtC,yFAAyF;QACzF,yFAAyF;QACzF,sFAAsF;QACtF,0FAA0F;QAC1F,MAAM,MAAM,GAAG,0BAAc,CAAC,oBAAoB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QAC9E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,yFAAyF;QACzF,QAAQ,UAAU,EAAE,CAAC;YACjB,KAAK,GAAG;gBACJ,OAAO,IAAI,+BAAmB,CAC1B,OAAO,EACP,aAAa,CAAC,KAAK,EACnB,aAAa,CAAC,eAAe,CAChC,CAAC;YAEN,KAAK,GAAG,EAAE,sDAAsD;gBAC5D,OAAO,IAAI,yBAAa,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;YAE/D,KAAK,GAAG;gBACJ,OAAO,IAAI,iCAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAEvD,KAAK,GAAG;gBACJ,OAAO,IAAI,8BAAkB,CAAC,OAAO,CAAC,CAAC;YAE3C,KAAK,GAAG;gBACJ,OAAO,IAAI,6BAAiB,CAAC,OAAO,CAAC,CAAC;YAE1C,KAAK,GAAG;gBACJ,OAAO,IAAI,4BAAgB,CAAC,OAAO,CAAC,CAAC;YAEzC,KAAK,GAAG;gBACJ,OAAO,IAAI,mCAAuB,CAAC,OAAO,CAAC,CAAC;YAEhD,KAAK,GAAG;gBACJ,OAAO,IAAI,+BAAmB,CAAC,OAAO,CAAC,CAAC;YAE5C,KAAK,GAAG;gBACJ,OAAO,IAAI,mCAAuB,CAAC,OAAO,CAAC,CAAC;YAEhD,KAAK,GAAG,EAAE,0EAA0E;gBAChF,OAAO,IAAI,2BAAe,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;YAEnE;gBACI,oFAAoF;gBACpF,iFAAiF;gBACjF,OAAO,IAAI,qBAAS,CAChB,OAAO,IAAI,kCAAkC,UAAU,EAAE,EACzD,UAAU,EACV,OAAO,CACV,CAAC;QACV,CAAC;IACL,CAAC;CACJ;AAjFD,sDAiFC","sourcesContent":["import {\n    ProtocolError,\n    ClientRegistry,\n    HttpError,\n    HttpBadRequestError,\n    HttpUserError,\n    HttpVendorError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpNotFoundError,\n    HttpTimeoutError,\n    HttpInternalServerError,\n    HttpBadGatewayError,\n    HttpGatewayTimeoutError,\n} from '@webpieces/core-util';\n\n/**\n * ClientErrorTranslator - Translates HTTP error responses to HttpError exceptions.\n *\n * This is the CLIENT-SIDE reverse of ExpressWrapper.handleError() on the server.\n * It reconstructs typed HttpError exceptions from ProtocolError JSON responses.\n *\n * Architecture:\n * - Server: HttpError → ExpressWrapper.handleError() → ProtocolError JSON\n * - Client: ProtocolError JSON → ClientErrorTranslator.translateError() → HttpError\n *\n * This achieves symmetric error handling - server throws typed exceptions,\n * client receives typed exceptions.\n */\nexport class ClientErrorTranslator {\n    /**\n     * Parse error response and reconstruct appropriate HttpError subclass.\n     *\n     * Maps HTTP status codes to error types (symmetric with server):\n     * - 400 → HttpBadRequestError (with field, guiAlertMessage)\n     * - 266 → HttpUserError (with errorCode) - 2xx code for user validation\n     * - 401 → HttpUnauthorizedError\n     * - 403 → HttpForbiddenError\n     * - 404 → HttpNotFoundError\n     * - 408 → HttpTimeoutError\n     * - 500 → HttpInternalServerError\n     * - 502 → HttpBadGatewayError\n     * - 504 → HttpGatewayTimeoutError\n     * - 598 → HttpVendorError (with waitSeconds) - custom status code\n     * - other → generic HttpError\n     *\n     * @param response - Fetch Response object\n     * @param protocolError - Parsed ProtocolError from response body\n     * @returns HttpError subclass instance\n     */\n    static translateError(response: Response, protocolError: ProtocolError): Error {\n        const statusCode = response.status;\n        const message = protocolError.message || response.statusText || 'Unknown error';\n        const subType = protocolError.subType;\n\n        // App-registered translations win, so an app can reconstruct its OWN error types (e.g. a\n        // custom 460) AND override built-ins. `undefined` means \"not mine\" — fall through to the\n        // built-in switch below, which stays the generic default. Symmetric with the server's\n        // ExpressWrapper.handleError(), which consults ClientRegistry.tryTranslateToWire() first.\n        const custom = ClientRegistry.tryTranslateFromWire(statusCode, protocolError);\n        if (custom !== undefined) {\n            return custom;\n        }\n\n        // Map status codes to error types (symmetric with server's ExpressWrapper.handleError())\n        switch (statusCode) {\n            case 400:\n                return new HttpBadRequestError(\n                    message,\n                    protocolError.field,\n                    protocolError.guiAlertMessage,\n                );\n\n            case 266: // HttpUserError - 2xx code for user validation errors\n                return new HttpUserError(message, protocolError.errorCode);\n\n            case 401:\n                return new HttpUnauthorizedError(message, subType);\n\n            case 403:\n                return new HttpForbiddenError(message);\n\n            case 404:\n                return new HttpNotFoundError(message);\n\n            case 408:\n                return new HttpTimeoutError(message);\n\n            case 500:\n                return new HttpInternalServerError(message);\n\n            case 502:\n                return new HttpBadGatewayError(message);\n\n            case 504:\n                return new HttpGatewayTimeoutError(message);\n\n            case 598: // HttpVendorError - custom status code for vendor/external service errors\n                return new HttpVendorError(message, protocolError.waitSeconds);\n\n            default:\n                // Unknown status code and no app translation claimed it: still a real HttpError (so\n                // `err instanceof HttpError` holds after the RPC hop), carrying the status code.\n                return new HttpError(\n                    message || `could not translate statusCode=${statusCode}`,\n                    statusCode,\n                    subType,\n                );\n        }\n    }\n}\n"]}
+{"version":3,"file":"ClientErrorTranslator.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ClientErrorTranslator.ts"],"names":[],"mappings":";;;AAAA,oDAe8B;AAE9B;;;;;;;;;;;;GAYG;AACH,MAAa,qBAAqB;IAC9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,cAAc,CAAC,QAAkB,EAAE,aAA4B;QAClE,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;QACnC,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,QAAQ,CAAC,UAAU,IAAI,eAAe,CAAC;QAChF,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;QAEtC,yFAAyF;QACzF,yFAAyF;QACzF,sFAAsF;QACtF,0FAA0F;QAC1F,MAAM,MAAM,GAAG,0BAAc,CAAC,oBAAoB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QAC9E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACvB,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,yFAAyF;QACzF,QAAQ,UAAU,EAAE,CAAC;YACjB,KAAK,GAAG;gBACJ,OAAO,IAAI,+BAAmB,CAC1B,OAAO,EACP,aAAa,CAAC,KAAK,EACnB,aAAa,CAAC,eAAe,CAChC,CAAC;YAEN,KAAK,GAAG,EAAE,sDAAsD;gBAC5D,OAAO,IAAI,yBAAa,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;YAE/D,KAAK,GAAG;gBACJ,OAAO,IAAI,iCAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAEvD,KAAK,GAAG;gBACJ,OAAO,IAAI,8BAAkB,CAAC,OAAO,CAAC,CAAC;YAE3C,KAAK,GAAG;gBACJ,OAAO,IAAI,6BAAiB,CAAC,OAAO,CAAC,CAAC;YAE1C,KAAK,GAAG;gBACJ,OAAO,IAAI,4BAAgB,CAAC,OAAO,CAAC,CAAC;YAEzC,KAAK,GAAG;gBACJ,OAAO,IAAI,mCAAuB,CAAC,OAAO,CAAC,CAAC;YAEhD,KAAK,GAAG;gBACJ,OAAO,IAAI,+BAAmB,CAAC,OAAO,CAAC,CAAC;YAE5C,KAAK,GAAG;gBACJ,OAAO,IAAI,uCAA2B,CAAC,OAAO,CAAC,CAAC;YAEpD,KAAK,GAAG;gBACJ,OAAO,IAAI,mCAAuB,CAAC,OAAO,CAAC,CAAC;YAEhD,KAAK,GAAG,EAAE,0EAA0E;gBAChF,OAAO,IAAI,2BAAe,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;YAEnE;gBACI,oFAAoF;gBACpF,iFAAiF;gBACjF,OAAO,IAAI,qBAAS,CAChB,OAAO,IAAI,kCAAkC,UAAU,EAAE,EACzD,UAAU,EACV,OAAO,CACV,CAAC;QACV,CAAC;IACL,CAAC;CACJ;AArFD,sDAqFC","sourcesContent":["import {\n    ProtocolError,\n    ClientRegistry,\n    HttpError,\n    HttpBadRequestError,\n    HttpUserError,\n    HttpVendorError,\n    HttpUnauthorizedError,\n    HttpForbiddenError,\n    HttpNotFoundError,\n    HttpTimeoutError,\n    HttpInternalServerError,\n    HttpBadGatewayError,\n    HttpServiceUnavailableError,\n    HttpGatewayTimeoutError,\n} from '@webpieces/core-util';\n\n/**\n * ClientErrorTranslator - Translates HTTP error responses to HttpError exceptions.\n *\n * This is the CLIENT-SIDE reverse of ExpressWrapper.handleError() on the server.\n * It reconstructs typed HttpError exceptions from ProtocolError JSON responses.\n *\n * Architecture:\n * - Server: HttpError → ExpressWrapper.handleError() → ProtocolError JSON\n * - Client: ProtocolError JSON → ClientErrorTranslator.translateError() → HttpError\n *\n * This achieves symmetric error handling - server throws typed exceptions,\n * client receives typed exceptions.\n */\nexport class ClientErrorTranslator {\n    /**\n     * Parse error response and reconstruct appropriate HttpError subclass.\n     *\n     * Maps HTTP status codes to error types (symmetric with server):\n     * - 400 → HttpBadRequestError (with field, guiAlertMessage)\n     * - 266 → HttpUserError (with errorCode) - 2xx code for user validation\n     * - 401 → HttpUnauthorizedError\n     * - 403 → HttpForbiddenError\n     * - 404 → HttpNotFoundError\n     * - 408 → HttpTimeoutError\n     * - 500 → HttpInternalServerError\n     * - 502 → HttpBadGatewayError\n     * - 503 → HttpServiceUnavailableError\n     * - 504 → HttpGatewayTimeoutError\n     * - 598 → HttpVendorError (with waitSeconds) - custom status code\n     * - other → generic HttpError\n     *\n     * @param response - Fetch Response object\n     * @param protocolError - Parsed ProtocolError from response body\n     * @returns HttpError subclass instance\n     */\n    static translateError(response: Response, protocolError: ProtocolError): Error {\n        const statusCode = response.status;\n        const message = protocolError.message || response.statusText || 'Unknown error';\n        const subType = protocolError.subType;\n\n        // App-registered translations win, so an app can reconstruct its OWN error types (e.g. a\n        // custom 460) AND override built-ins. `undefined` means \"not mine\" — fall through to the\n        // built-in switch below, which stays the generic default. Symmetric with the server's\n        // ExpressWrapper.handleError(), which consults ClientRegistry.tryTranslateToWire() first.\n        const custom = ClientRegistry.tryTranslateFromWire(statusCode, protocolError);\n        if (custom !== undefined) {\n            return custom;\n        }\n\n        // Map status codes to error types (symmetric with server's ExpressWrapper.handleError())\n        switch (statusCode) {\n            case 400:\n                return new HttpBadRequestError(\n                    message,\n                    protocolError.field,\n                    protocolError.guiAlertMessage,\n                );\n\n            case 266: // HttpUserError - 2xx code for user validation errors\n                return new HttpUserError(message, protocolError.errorCode);\n\n            case 401:\n                return new HttpUnauthorizedError(message, subType);\n\n            case 403:\n                return new HttpForbiddenError(message);\n\n            case 404:\n                return new HttpNotFoundError(message);\n\n            case 408:\n                return new HttpTimeoutError(message);\n\n            case 500:\n                return new HttpInternalServerError(message);\n\n            case 502:\n                return new HttpBadGatewayError(message);\n\n            case 503:\n                return new HttpServiceUnavailableError(message);\n\n            case 504:\n                return new HttpGatewayTimeoutError(message);\n\n            case 598: // HttpVendorError - custom status code for vendor/external service errors\n                return new HttpVendorError(message, protocolError.waitSeconds);\n\n            default:\n                // Unknown status code and no app translation claimed it: still a real HttpError (so\n                // `err instanceof HttpError` holds after the RPC hop), carrying the status code.\n                return new HttpError(\n                    message || `could not translate statusCode=${statusCode}`,\n                    statusCode,\n                    subType,\n                );\n        }\n    }\n}\n"]}

package/src/ProxyClient.d.ts

@@ -26,6 +26,7 @@ export declare abstract class ProxyClient {
     private routeMap;
     private apiName;
     private readonly networkRejectClassifier;
+    private readonly bodyReader;
     constructor(logApiCall?: LogApiCallImpl);
     /** The callee's base URL. Async because a server may derive it from container metadata. */
     protected abstract resolveBaseUrl(): Promise<string>;
@@ -118,4 +119,35 @@ export declare abstract class ProxyClient {
      * though the caller sees an exception.
      */
     private executeFetch;
+    /**
+     * 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 the HttpError subclass ClientErrorTranslator picked, and translateError RETURNS
+     * Error — so nothing in this seam is ever `unknown`.
+     */
+    private endWithTypedFailure;
 }

package/src/ProxyClient.js

@@ -4,6 +4,7 @@ exports.ProxyClient = void 0;
 const core_util_1 = require("@webpieces/core-util");
 const ClientErrorTranslator_1 = require("./ClientErrorTranslator");
 const RequestOutcome_1 = require("./RequestOutcome");
+const ResponseBodyReader_1 = require("./ResponseBodyReader");
 /**
  * ProxyClient - the HTTP call engine behind one API contract's client proxy.
  *
@@ -31,6 +32,8 @@ class ProxyClient {
     apiName;
     // Stateless + dependency-free, so the browser bundle keeps no DI on the fetch path.
     networkRejectClassifier = new core_util_1.NetworkRejectClassifier();
+    // Same shape and same reason: stateless, so it is constructed here rather than injected.
+    bodyReader = new ResponseBodyReader_1.ResponseBodyReader();
     constructor(logApiCall = core_util_1.LogApiCall) {
         this.logApiCall = logApiCall;
     }
@@ -219,48 +222,75 @@ class ProxyClient {
             this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, 0, undefined, networkError));
             throw networkError;
         }
+        const callId = `${this.apiName}.${route.methodName}`;
         if (response.ok) {
-            // webpieces-disable no-unmanaged-exceptions -- a malformed 2xx body must still report the END marker
-            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-            try {
-                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;
+            return this.readSuccessBody(response, route, callId);
+        }
+        throw await this.endWithTypedFailure(response, route, callId);
+    }
+    /**
+     * 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 {
+            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;
         }
-        // Handle errors (non-2xx responses): parse ProtocolError from the response body and
-        // reconstruct the appropriate HttpError subclass. The headers still reach the seam here, so
-        // a version (or any future) header is observed even on error responses.
-        //
-        // The parse is GUARDED because a non-2xx body is not always ours: an infra 502/504 (load
-        // balancer, proxy) returns HTML, and `response.json()` throws on it. Unguarded, the END
-        // marker would never fire for exactly the 5xx case the seam exists to catch — the caller
-        // would see the throw while the app's progress bar span never closed. Either way the caller
-        // still gets the same failure it always got; only the lifecycle report is new.
-        //
-        // `translated` is the HttpError subclass ClientErrorTranslator picked, and translateError
-        // RETURNS Error — so nothing in this seam is ever `unknown`.
+    }
+    /**
+     * 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 the HttpError subclass ClientErrorTranslator picked, and translateError RETURNS
+     * Error — so nothing in this seam is ever `unknown`.
+     */
+    async endWithTypedFailure(response, route, callId) {
         let translated;
-        // webpieces-disable no-unmanaged-exceptions -- a non-JSON error body must still report the END marker
+        // 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 response.json());
+            const protocolError = await this.bodyReader.readErrorBody(response, callId);
             translated = ClientErrorTranslator_1.ClientErrorTranslator.translateError(response, protocolError);
         }
         catch (err) {
             const error = (0, core_util_1.toError)(err);
-            // The error body was not ours (e.g. an infra 502 serving HTML), so there was no
-            // ProtocolError to translate — report the parse failure itself as the outcome.
+            // The response CLAIMED JSON and was not parseable — report that failure as the outcome.
             this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, response.status, response.headers, error));
-            throw error;
+            return error;
         }
         this.onRequestEnd(route, new RequestOutcome_1.RequestOutcome(false, response.status, response.headers, translated));
-        throw translated;
+        return translated;
     }
 }
 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    ProtocolError,\n    LogApiCall,\n    LogApiCallImpl,\n    ApiMethodInfo,\n    toError,\n    NetworkRejectClassifier,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\nimport { RequestOutcome } from './RequestOutcome';\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    // Stateless + dependency-free, so the browser bundle keeps no DI on the fetch path.\n    private readonly networkRejectClassifier = new NetworkRejectClassifier();\n\n    constructor(protected readonly logApiCall: LogApiCallImpl = LogApiCall) {}\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     * Attach the endpoint's outbound credential. Service-to-service auth (@AuthOidc bearer,\n     * @AuthSharedSecret value) is a SERVER concept; a browser has neither a minter nor a Secrets\n     * store, so it attaches nothing and its user JWT simply travels as a transferred context key.\n     */\n    protected async attachOutboundAuth(\n        _route: RouteMetadata,\n        _baseUrl: string,\n        _httpHeaders: Record<string, string>,\n    ): Promise<void> {}\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     * 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     * @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>): void {\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\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     * 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        // FAIL FAST: formPost endpoints exist ONLY for EXTERNAL inbound webhooks (e.g. Twilio is the\n        // caller — there is no webpieces client for them). This proxy JSON.stringifies the body, so\n        // calling one would silently send a wrong-encoded body. Refuse it here — PER METHOD, at call\n        // time — so an API mixing normal + formPost endpoints still gives a working client for the\n        // normal ones; only calling the formPost method throws.\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        // FAIL FAST, same shape and same reason: an @AuthWebhook endpoint is verified by the VENDOR's\n        // signature over the request, which no webpieces client can produce. Refusing here — per\n        // method, at call time — means an api that mixes webhook + normal endpoints still yields a\n        // working client for the normal ones.\n        const authMode = route.authMeta?.mode;\n        if (authMode?.kind === 'webhook') {\n            throw new Error(\n                `${this.apiName}.${route.methodName} is @AuthWebhook('${authMode.name}') — only ` +\n                `${authMode.name} can call it, because only ${authMode.name} can produce the signature ` +\n                `its WebhookAuthCallback verifies. It is not callable from a webpieces client.`,\n            );\n        }\n        // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.\n        const baseUrl = await this.resolveBaseUrl();\n        const url = `${baseUrl}${route.path}`;\n\n        const httpHeaders: Record<string, string> = {\n            'Content-Type': 'application/json',\n        };\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[entry[0]] = entry[1];\n        }\n\n        await this.attachOutboundAuth(route, baseUrl, httpHeaders);\n\n        const options: RequestInit = {\n            method: route.httpMethod,\n            headers: httpHeaders,\n        };\n\n        // POST body is the first argument as JSON\n        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n        let requestDto: unknown;\n        if (args.length > 0) {\n            requestDto = args[0];\n            options.body = JSON.stringify(requestDto);\n        }\n\n        // Wrap fetch 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(url, options, route);\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(url: string, options: RequestInit, route: RouteMetadata): Promise<unknown> {\n        this.onRequestStart(route);\n\n        // A network reject (offline, DNS, CORS preflight) means no Response ever existed, so there is\n        // no status and no headers to report — only status 0 and the failure itself. toNetworkError\n        // turns that reject into a typed OfflineError (a genuine bug passes through untouched), and we\n        // classify BEFORE onRequestEnd so a lifecycle listener sees the SAME typed error the caller will.\n        let response: Response;\n        // webpieces-disable no-unmanaged-exceptions -- translate a network reject into a lifecycle END, then rethrow\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            response = await fetch(url, options);\n        } catch (err: unknown) {\n            const error = toError(err);\n            const networkError = this.networkRejectClassifier.toNetworkError(error, url);\n            this.onRequestEnd(route, new RequestOutcome(false, 0, undefined, networkError));\n            throw networkError;\n        }\n\n        if (response.ok) {\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                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        // Handle errors (non-2xx responses): parse ProtocolError from the response body and\n        // reconstruct the appropriate HttpError subclass. The headers still reach the seam here, so\n        // a version (or any future) header is observed even on error responses.\n        //\n        // The parse is GUARDED because a non-2xx body is not always ours: an infra 502/504 (load\n        // balancer, proxy) returns HTML, and `response.json()` throws on it. Unguarded, the END\n        // marker would never fire for exactly the 5xx case the seam exists to catch — the caller\n        // would see the throw while the app's progress bar span never closed. Either way the caller\n        // still gets the same failure it always got; only the lifecycle report is new.\n        //\n        // `translated` is the HttpError subclass ClientErrorTranslator picked, and translateError\n        // RETURNS Error — so nothing in this seam is ever `unknown`.\n        let translated: Error;\n        // webpieces-disable no-unmanaged-exceptions -- a non-JSON error body must still report the END marker\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            const protocolError = (await response.json()) as ProtocolError;\n            translated = ClientErrorTranslator.translateError(response, protocolError);\n        } catch (err: unknown) {\n            const error = toError(err);\n            // The error body was not ours (e.g. an infra 502 serving HTML), so there was no\n            // ProtocolError to translate — report the parse failure itself as the outcome.\n            this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n            throw error;\n        }\n\n        this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, translated));\n        throw translated;\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    LogApiCall,\n    LogApiCallImpl,\n    ApiMethodInfo,\n    toError,\n    NetworkRejectClassifier,\n} from '@webpieces/core-util';\nimport { ApiPrototype } from './ApiPrototype';\nimport { ClientErrorTranslator } from './ClientErrorTranslator';\nimport { RequestOutcome } from './RequestOutcome';\nimport { ResponseBodyReader } from './ResponseBodyReader';\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    // 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    constructor(protected readonly logApiCall: LogApiCallImpl = LogApiCall) {}\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     * Attach the endpoint's outbound credential. Service-to-service auth (@AuthOidc bearer,\n     * @AuthSharedSecret value) is a SERVER concept; a browser has neither a minter nor a Secrets\n     * store, so it attaches nothing and its user JWT simply travels as a transferred context key.\n     */\n    protected async attachOutboundAuth(\n        _route: RouteMetadata,\n        _baseUrl: string,\n        _httpHeaders: Record<string, string>,\n    ): Promise<void> {}\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     * 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     * @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>): void {\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\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     * 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        // FAIL FAST: formPost endpoints exist ONLY for EXTERNAL inbound webhooks (e.g. Twilio is the\n        // caller — there is no webpieces client for them). This proxy JSON.stringifies the body, so\n        // calling one would silently send a wrong-encoded body. Refuse it here — PER METHOD, at call\n        // time — so an API mixing normal + formPost endpoints still gives a working client for the\n        // normal ones; only calling the formPost method throws.\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        // FAIL FAST, same shape and same reason: an @AuthWebhook endpoint is verified by the VENDOR's\n        // signature over the request, which no webpieces client can produce. Refusing here — per\n        // method, at call time — means an api that mixes webhook + normal endpoints still yields a\n        // working client for the normal ones.\n        const authMode = route.authMeta?.mode;\n        if (authMode?.kind === 'webhook') {\n            throw new Error(\n                `${this.apiName}.${route.methodName} is @AuthWebhook('${authMode.name}') — only ` +\n                `${authMode.name} can call it, because only ${authMode.name} can produce the signature ` +\n                `its WebhookAuthCallback verifies. It is not callable from a webpieces client.`,\n            );\n        }\n        // Resolved per call (memoized underneath on a server), so building a client stayed synchronous.\n        const baseUrl = await this.resolveBaseUrl();\n        const url = `${baseUrl}${route.path}`;\n\n        const httpHeaders: Record<string, string> = {\n            'Content-Type': 'application/json',\n        };\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[entry[0]] = entry[1];\n        }\n\n        await this.attachOutboundAuth(route, baseUrl, httpHeaders);\n\n        const options: RequestInit = {\n            method: route.httpMethod,\n            headers: httpHeaders,\n        };\n\n        // POST body is the first argument as JSON\n        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n        let requestDto: unknown;\n        if (args.length > 0) {\n            requestDto = args[0];\n            options.body = JSON.stringify(requestDto);\n        }\n\n        // Wrap fetch 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(url, options, route);\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(url: string, options: RequestInit, route: RouteMetadata): Promise<unknown> {\n        this.onRequestStart(route);\n\n        // A network reject (offline, DNS, CORS preflight) means no Response ever existed, so there is\n        // no status and no headers to report — only status 0 and the failure itself. toNetworkError\n        // turns that reject into a typed OfflineError (a genuine bug passes through untouched), and we\n        // classify BEFORE onRequestEnd so a lifecycle listener sees the SAME typed error the caller will.\n        let response: Response;\n        // webpieces-disable no-unmanaged-exceptions -- translate a network reject into a lifecycle END, then rethrow\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            response = await fetch(url, options);\n        } catch (err: unknown) {\n            const error = toError(err);\n            const networkError = this.networkRejectClassifier.toNetworkError(error, url);\n            this.onRequestEnd(route, new RequestOutcome(false, 0, undefined, networkError));\n            throw networkError;\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     * 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 the HttpError subclass ClientErrorTranslator picked, and translateError RETURNS\n     * Error — so nothing in this seam is ever `unknown`.\n     */\n    private async endWithTypedFailure(response: Response, route: RouteMetadata, callId: string): Promise<Error> {\n        let translated: Error;\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(response, protocolError);\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            this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, error));\n            return error;\n        }\n\n        this.onRequestEnd(route, new RequestOutcome(false, response.status, response.headers, translated));\n        return translated;\n    }\n}\n"]}

package/src/ResponseBodyReader.d.ts

@@ -0,0 +1,43 @@
+import { ProtocolError } from '@webpieces/core-util';
+/**
+ * ResponseBodyReader — decides whether a response body may be `JSON.parse`d AT ALL, from its
+ * `content-type`, before anything tries.
+ *
+ * WHY THIS EXISTS: the client used to call `response.json()` on every body regardless of what the
+ * response said it was. A scale-to-zero backend answers a cold start with the load balancer's own
+ * **HTML** error page, so a 502 arrived at the app as `SyntaxError: Unexpected token '<'` — the
+ * status thrown away, and infrastructure indistinguishable from a code defect. Apps showed users a
+ * "Client Bug" dialog for a server that was merely booting.
+ *
+ * The rule, and the whole of it: **only parse a body that CLAIMS to be JSON.** Then
+ * - a non-JSON error body becomes a synthesized {@link ProtocolError} that `ClientErrorTranslator`
+ *   maps by STATUS — 502 → `HttpBadGatewayError`, 503 → `HttpServiceUnavailableError`, 504 →
+ *   `HttpGatewayTimeoutError` — so a caller can decide "the server is waking, retry";
+ * - a `SyntaxError` from `JSON.parse` goes back to meaning what it should: a response that SAID it
+ *   was JSON and was malformed. That is a real bug, and it is exactly the signal the old
+ *   parse-everything path destroyed.
+ */
+export declare class ResponseBodyReader {
+    /** True when the response DECLARES a JSON body, and is therefore safe to `JSON.parse`. */
+    isJson(response: Response): boolean;
+    /**
+     * Read a NON-2xx body as a {@link ProtocolError}, whatever it turns out to be.
+     *
+     * - Declared JSON → parse it. A malformed one still throws `SyntaxError`, on purpose: the server
+     *   promised JSON and broke the promise, which is a genuine defect worth surfacing as one.
+     * - Anything else → synthesize a ProtocolError describing what actually arrived, so the caller
+     *   gets the STATUS-derived typed error instead of a parse failure.
+     *
+     * @param response - the fetch Response, already known to be non-ok
+     * @param callId   - `ApiName.methodName`, so the message names the call that failed
+     */
+    readErrorBody(response: Response, callId: string): Promise<ProtocolError>;
+    /**
+     * The message for a body that is not ours. It names the status, the content-type that gave it
+     * away, and a short quote of the body — the three facts needed to tell "Google Frontend served
+     * its own 502 page" apart from "our server returned an error".
+     */
+    describeForeignBody(response: Response, callId: string, body: string): string;
+    /** First {@link SNIPPET_CHARS} characters, whitespace collapsed so an HTML page stays one line. */
+    private snippet;
+}

package/src/ResponseBodyReader.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResponseBodyReader = void 0;
+const core_util_1 = require("@webpieces/core-util");
+/**
+ * `application/json`, plus every `+json` structured suffix (`application/problem+json`,
+ * `application/vnd.acme.v2+json`). Parameters (`; charset=utf-8`) are ignored, and matching is
+ * case-insensitive because a content-type is case-insensitive on the wire.
+ */
+const JSON_CONTENT_TYPE = /^application\/(?:[\w.+-]+\+)?json\s*(?:;|$)/i;
+/** How much of a non-JSON body to quote in the error message — enough to identify it, not a dump. */
+const SNIPPET_CHARS = 200;
+/**
+ * ResponseBodyReader — decides whether a response body may be `JSON.parse`d AT ALL, from its
+ * `content-type`, before anything tries.
+ *
+ * WHY THIS EXISTS: the client used to call `response.json()` on every body regardless of what the
+ * response said it was. A scale-to-zero backend answers a cold start with the load balancer's own
+ * **HTML** error page, so a 502 arrived at the app as `SyntaxError: Unexpected token '<'` — the
+ * status thrown away, and infrastructure indistinguishable from a code defect. Apps showed users a
+ * "Client Bug" dialog for a server that was merely booting.
+ *
+ * The rule, and the whole of it: **only parse a body that CLAIMS to be JSON.** Then
+ * - a non-JSON error body becomes a synthesized {@link ProtocolError} that `ClientErrorTranslator`
+ *   maps by STATUS — 502 → `HttpBadGatewayError`, 503 → `HttpServiceUnavailableError`, 504 →
+ *   `HttpGatewayTimeoutError` — so a caller can decide "the server is waking, retry";
+ * - a `SyntaxError` from `JSON.parse` goes back to meaning what it should: a response that SAID it
+ *   was JSON and was malformed. That is a real bug, and it is exactly the signal the old
+ *   parse-everything path destroyed.
+ */
+class ResponseBodyReader {
+    /** True when the response DECLARES a JSON body, and is therefore safe to `JSON.parse`. */
+    isJson(response) {
+        const contentType = response.headers.get('content-type');
+        if (!contentType) {
+            return false;
+        }
+        return JSON_CONTENT_TYPE.test(contentType.trim());
+    }
+    /**
+     * Read a NON-2xx body as a {@link ProtocolError}, whatever it turns out to be.
+     *
+     * - Declared JSON → parse it. A malformed one still throws `SyntaxError`, on purpose: the server
+     *   promised JSON and broke the promise, which is a genuine defect worth surfacing as one.
+     * - Anything else → synthesize a ProtocolError describing what actually arrived, so the caller
+     *   gets the STATUS-derived typed error instead of a parse failure.
+     *
+     * @param response - the fetch Response, already known to be non-ok
+     * @param callId   - `ApiName.methodName`, so the message names the call that failed
+     */
+    async readErrorBody(response, callId) {
+        if (this.isJson(response)) {
+            return (await response.json());
+        }
+        const protocolError = new core_util_1.ProtocolError();
+        protocolError.message = this.describeForeignBody(response, callId, await response.text());
+        return protocolError;
+    }
+    /**
+     * The message for a body that is not ours. It names the status, the content-type that gave it
+     * away, and a short quote of the body — the three facts needed to tell "Google Frontend served
+     * its own 502 page" apart from "our server returned an error".
+     */
+    describeForeignBody(response, callId, body) {
+        const contentType = response.headers.get('content-type') || '(none)';
+        return (`${callId}: HTTP ${response.status} with content-type "${contentType}" — this response did ` +
+            `not come from the webpieces server (no ProtocolError body). It is almost certainly ` +
+            `infrastructure: a load balancer, a proxy, or a cold start on a scale-to-zero backend. ` +
+            `body=${JSON.stringify(this.snippet(body))}`);
+    }
+    /** First {@link SNIPPET_CHARS} characters, whitespace collapsed so an HTML page stays one line. */
+    snippet(body) {
+        const collapsed = body.replace(/\s+/g, ' ').trim();
+        if (collapsed.length <= SNIPPET_CHARS) {
+            return collapsed;
+        }
+        return `${collapsed.slice(0, SNIPPET_CHARS)}…`;
+    }
+}
+exports.ResponseBodyReader = ResponseBodyReader;
+//# sourceMappingURL=ResponseBodyReader.js.map

package/src/ResponseBodyReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseBodyReader.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/ResponseBodyReader.ts"],"names":[],"mappings":";;;AAAA,oDAAqD;AAErD;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,8CAA8C,CAAC;AAEzE,qGAAqG;AACrG,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,kBAAkB;IAC3B,0FAA0F;IAC1F,MAAM,CAAC,QAAkB;QACrB,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACzD,IAAI,CAAC,WAAW,EAAE,CAAC;YACf,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,CAAC,QAAkB,EAAE,MAAc;QAClD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAkB,CAAC;QACpD,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,yBAAa,EAAE,CAAC;QAC1C,aAAa,CAAC,OAAO,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1F,OAAO,aAAa,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,QAAkB,EAAE,MAAc,EAAE,IAAY;QAChE,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,QAAQ,CAAC;QACrE,OAAO,CACH,GAAG,MAAM,UAAU,QAAQ,CAAC,MAAM,uBAAuB,WAAW,wBAAwB;YAC5F,qFAAqF;YACrF,wFAAwF;YACxF,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAC/C,CAAC;IACN,CAAC;IAED,mGAAmG;IAC3F,OAAO,CAAC,IAAY;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,SAAS,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;YACpC,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC;IACnD,CAAC;CACJ;AAtDD,gDAsDC","sourcesContent":["import { ProtocolError } from '@webpieces/core-util';\n\n/**\n * `application/json`, plus every `+json` structured suffix (`application/problem+json`,\n * `application/vnd.acme.v2+json`). Parameters (`; charset=utf-8`) are ignored, and matching is\n * case-insensitive because a content-type is case-insensitive on the wire.\n */\nconst JSON_CONTENT_TYPE = /^application\\/(?:[\\w.+-]+\\+)?json\\s*(?:;|$)/i;\n\n/** How much of a non-JSON body to quote in the error message — enough to identify it, not a dump. */\nconst SNIPPET_CHARS = 200;\n\n/**\n * ResponseBodyReader — decides whether a response body may be `JSON.parse`d AT ALL, from its\n * `content-type`, before anything tries.\n *\n * WHY THIS EXISTS: the client used to call `response.json()` on every body regardless of what the\n * response said it was. A scale-to-zero backend answers a cold start with the load balancer's own\n * **HTML** error page, so a 502 arrived at the app as `SyntaxError: Unexpected token '<'` — the\n * status thrown away, and infrastructure indistinguishable from a code defect. Apps showed users a\n * \"Client Bug\" dialog for a server that was merely booting.\n *\n * The rule, and the whole of it: **only parse a body that CLAIMS to be JSON.** Then\n * - a non-JSON error body becomes a synthesized {@link ProtocolError} that `ClientErrorTranslator`\n *   maps by STATUS — 502 → `HttpBadGatewayError`, 503 → `HttpServiceUnavailableError`, 504 →\n *   `HttpGatewayTimeoutError` — so a caller can decide \"the server is waking, retry\";\n * - a `SyntaxError` from `JSON.parse` goes back to meaning what it should: a response that SAID it\n *   was JSON and was malformed. That is a real bug, and it is exactly the signal the old\n *   parse-everything path destroyed.\n */\nexport class ResponseBodyReader {\n    /** True when the response DECLARES a JSON body, and is therefore safe to `JSON.parse`. */\n    isJson(response: Response): boolean {\n        const contentType = response.headers.get('content-type');\n        if (!contentType) {\n            return false;\n        }\n        return JSON_CONTENT_TYPE.test(contentType.trim());\n    }\n\n    /**\n     * Read a NON-2xx body as a {@link ProtocolError}, whatever it turns out to be.\n     *\n     * - Declared JSON → parse it. A malformed one still throws `SyntaxError`, on purpose: the server\n     *   promised JSON and broke the promise, which is a genuine defect worth surfacing as one.\n     * - Anything else → synthesize a ProtocolError describing what actually arrived, so the caller\n     *   gets the STATUS-derived typed error instead of a parse failure.\n     *\n     * @param response - the fetch Response, already known to be non-ok\n     * @param callId   - `ApiName.methodName`, so the message names the call that failed\n     */\n    async readErrorBody(response: Response, callId: string): Promise<ProtocolError> {\n        if (this.isJson(response)) {\n            return (await response.json()) as ProtocolError;\n        }\n\n        const protocolError = new ProtocolError();\n        protocolError.message = this.describeForeignBody(response, callId, await response.text());\n        return protocolError;\n    }\n\n    /**\n     * The message for a body that is not ours. It names the status, the content-type that gave it\n     * away, and a short quote of the body — the three facts needed to tell \"Google Frontend served\n     * its own 502 page\" apart from \"our server returned an error\".\n     */\n    describeForeignBody(response: Response, callId: string, body: string): string {\n        const contentType = response.headers.get('content-type') || '(none)';\n        return (\n            `${callId}: HTTP ${response.status} with content-type \"${contentType}\" — this response did ` +\n            `not come from the webpieces server (no ProtocolError body). It is almost certainly ` +\n            `infrastructure: a load balancer, a proxy, or a cold start on a scale-to-zero backend. ` +\n            `body=${JSON.stringify(this.snippet(body))}`\n        );\n    }\n\n    /** First {@link SNIPPET_CHARS} characters, whitespace collapsed so an HTML page stays one line. */\n    private snippet(body: string): string {\n        const collapsed = body.replace(/\\s+/g, ' ').trim();\n        if (collapsed.length <= SNIPPET_CHARS) {\n            return collapsed;\n        }\n        return `${collapsed.slice(0, SNIPPET_CHARS)}…`;\n    }\n}\n"]}

package/src/index.d.ts

@@ -29,3 +29,4 @@ export { RequestOutcome } from './RequestOutcome';
 export type { ApiPrototype } from './ApiPrototype';
 export { buildClientProxy } from './buildClientProxy';
 export { ClientErrorTranslator } from './ClientErrorTranslator';
+export { ResponseBodyReader } from './ResponseBodyReader';

package/src/index.js

@@ -26,7 +26,7 @@
  * a browser bundle, and nothing browser-only (a ContextReader store) reaches a server.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClientErrorTranslator = exports.buildClientProxy = exports.RequestOutcome = exports.ProxyClient = void 0;
+exports.ResponseBodyReader = exports.ClientErrorTranslator = exports.buildClientProxy = exports.RequestOutcome = exports.ProxyClient = void 0;
 var ProxyClient_1 = require("./ProxyClient");
 Object.defineProperty(exports, "ProxyClient", { enumerable: true, get: function () { return ProxyClient_1.ProxyClient; } });
 var RequestOutcome_1 = require("./RequestOutcome");
@@ -35,4 +35,6 @@ var buildClientProxy_1 = require("./buildClientProxy");
 Object.defineProperty(exports, "buildClientProxy", { enumerable: true, get: function () { return buildClientProxy_1.buildClientProxy; } });
 var ClientErrorTranslator_1 = require("./ClientErrorTranslator");
 Object.defineProperty(exports, "ClientErrorTranslator", { enumerable: true, get: function () { return ClientErrorTranslator_1.ClientErrorTranslator; } });
+var ResponseBodyReader_1 = require("./ResponseBodyReader");
+Object.defineProperty(exports, "ResponseBodyReader", { enumerable: true, get: function () { return ResponseBodyReader_1.ResponseBodyReader; } });
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAEvB,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AACzB,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA","sourcesContent":["/**\n * @webpieces/http-client-core\n *\n * The ISOMORPHIC core of the webpieces HTTP client — everything that reads an API contract's\n * decorators and turns a method call into an HTTP request, with no opinion about where the\n * magic context comes from or whether a DI container exists.\n *\n * You almost certainly want one of its two environment packages instead:\n * - Server:  @webpieces/http-client-node    (inversify-wired, reads RequestContext, mints OIDC)\n * - Browser: @webpieces/http-client-browser (no DI — React or Angular, app-managed context store)\n *\n * Architecture:\n * ```\n * http-api (defines the contract)\n *    ^\n *    +-- http-routing (server: contract -> handlers)\n *    +-- http-client-core (contract -> HTTP requests)   <- YOU ARE HERE\n *          +-- http-client-node     (RequestContext + Secrets + OIDC + inversify factory)\n *          +-- http-client-browser  (app-held store + plain factory, no DI)\n * ```\n *\n * There is no context/credential/recording seam here at all: ProxyClient is ABSTRACT and asks its\n * subclass for the base URL, the context headers, the log map, the outbound credential, and the\n * recorder. Nothing server-only (RequestContext, Secrets, mintIdToken, TestCaseRecorder) can reach\n * a browser bundle, and nothing browser-only (a ContextReader store) reaches a server.\n */\n\nexport { ProxyClient } from './ProxyClient';\nexport { RequestOutcome } from './RequestOutcome';\nexport type { ApiPrototype } from './ApiPrototype';\nexport { buildClientProxy } from './buildClientProxy';\nexport { ClientErrorTranslator } from './ClientErrorTranslator';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/http/http-client-core/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAEvB,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AACzB,iEAAgE;AAAvD,8HAAA,qBAAqB,OAAA;AAC9B,2DAA0D;AAAjD,wHAAA,kBAAkB,OAAA","sourcesContent":["/**\n * @webpieces/http-client-core\n *\n * The ISOMORPHIC core of the webpieces HTTP client — everything that reads an API contract's\n * decorators and turns a method call into an HTTP request, with no opinion about where the\n * magic context comes from or whether a DI container exists.\n *\n * You almost certainly want one of its two environment packages instead:\n * - Server:  @webpieces/http-client-node    (inversify-wired, reads RequestContext, mints OIDC)\n * - Browser: @webpieces/http-client-browser (no DI — React or Angular, app-managed context store)\n *\n * Architecture:\n * ```\n * http-api (defines the contract)\n *    ^\n *    +-- http-routing (server: contract -> handlers)\n *    +-- http-client-core (contract -> HTTP requests)   <- YOU ARE HERE\n *          +-- http-client-node     (RequestContext + Secrets + OIDC + inversify factory)\n *          +-- http-client-browser  (app-held store + plain factory, no DI)\n * ```\n *\n * There is no context/credential/recording seam here at all: ProxyClient is ABSTRACT and asks its\n * subclass for the base URL, the context headers, the log map, the outbound credential, and the\n * recorder. Nothing server-only (RequestContext, Secrets, mintIdToken, TestCaseRecorder) can reach\n * a browser bundle, and nothing browser-only (a ContextReader store) reaches a server.\n */\n\nexport { ProxyClient } from './ProxyClient';\nexport { RequestOutcome } from './RequestOutcome';\nexport type { ApiPrototype } from './ApiPrototype';\nexport { buildClientProxy } from './buildClientProxy';\nexport { ClientErrorTranslator } from './ClientErrorTranslator';\nexport { ResponseBodyReader } from './ResponseBodyReader';\n"]}