@webpieces/core-util 0.4.793 → 0.4.794

package/package.json

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

package/src/http/ApiMethodInfo.d.ts

@@ -35,6 +35,12 @@ export declare class ApiMethodInfo {
      *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.
      *  Rides the call identity so the spec travels with the api definition, not a global app config. */
     readonly mask?: MaskSpec | undefined;
+    /** OPTIONAL — true when the route declared `@Endpoint(..., { background: true })`: this call is
+     *  plumbing the user did not ask for (a log shipper, a heartbeat, a telemetry flush), so
+     *  {@link LogApiCallImpl} emits NO `[API-*-req]`/`[API-*-resp-*]` line and stamps no
+     *  {@link ApiCallInfo} tag for it. Read once at route-build time and handed here, exactly as
+     *  {@link mask} is. Default (absent/false) = the ordinary, fully-logged call. */
+    readonly background: boolean;
     constructor(side: ApiSide, 
     /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both
      *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */
@@ -49,5 +55,11 @@ export declare class ApiMethodInfo {
      *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an
      *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.
      *  Rides the call identity so the spec travels with the api definition, not a global app config. */
-    mask?: MaskSpec | undefined);
+    mask?: MaskSpec | undefined, 
+    /** OPTIONAL — true when the route declared `@Endpoint(..., { background: true })`: this call is
+     *  plumbing the user did not ask for (a log shipper, a heartbeat, a telemetry flush), so
+     *  {@link LogApiCallImpl} emits NO `[API-*-req]`/`[API-*-resp-*]` line and stamps no
+     *  {@link ApiCallInfo} tag for it. Read once at route-build time and handed here, exactly as
+     *  {@link mask} is. Default (absent/false) = the ordinary, fully-logged call. */
+    background?: boolean);
 }

package/src/http/ApiMethodInfo.js

@@ -25,6 +25,7 @@ class ApiMethodInfo {
     methodName;
     controllerName;
     mask;
+    background;
     constructor(side, 
     /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both
      *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */
@@ -39,12 +40,19 @@ class ApiMethodInfo {
      *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an
      *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.
      *  Rides the call identity so the spec travels with the api definition, not a global app config. */
-    mask) {
+    mask, 
+    /** OPTIONAL — true when the route declared `@Endpoint(..., { background: true })`: this call is
+     *  plumbing the user did not ask for (a log shipper, a heartbeat, a telemetry flush), so
+     *  {@link LogApiCallImpl} emits NO `[API-*-req]`/`[API-*-resp-*]` line and stamps no
+     *  {@link ApiCallInfo} tag for it. Read once at route-build time and handed here, exactly as
+     *  {@link mask} is. Default (absent/false) = the ordinary, fully-logged call. */
+    background = false) {
         this.side = side;
         this.apiClass = apiClass;
         this.methodName = methodName;
         this.controllerName = controllerName;
         this.mask = mask;
+        this.background = background;
     }
 }
 exports.ApiMethodInfo = ApiMethodInfo;

package/src/http/ApiMethodInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiMethodInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiMethodInfo.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAOH,MAAa,aAAa;IAET;IAGA;IAEA;IAGA;IAMA;IAfb,YACa,IAAa;IACtB;2FACuF;IAC9E,QAAgB;IACzB,2DAA2D;IAClD,UAAkB;IAC3B;gGAC4F;IACnF,cAAuB;IAChC;;;;wGAIoG;IAC3F,IAAe;QAdf,SAAI,GAAJ,IAAI,CAAS;QAGb,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,eAAU,GAAV,UAAU,CAAQ;QAGlB,mBAAc,GAAd,cAAc,CAAS;QAMvB,SAAI,GAAJ,IAAI,CAAW;IACzB,CAAC;CACP;AAlBD,sCAkBC","sourcesContent":["/**\n * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to\n * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,\n * and external wrapped clients like the firestore admin client).\n *\n * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,\n * pubsub/queue enqueues, and multi-param external clients returning Promise<void>/Promise<unknown>.\n * None of those own an `httpMethod`/`path`, so LogApiCall must not depend on the HTTP-shaped\n * `RouteMetadata`. This carries only what identifies the call.\n *\n * MATCHING is the point of {@link apiClass}: a CLIENT call and the SERVER handler for the same logical\n * method must log the SAME identity so `jsonPayload.api.method.apiClass=\"SaveApi\"` filters both sides\n * together. The API CONTRACT class name (e.g. 'SaveApi') is available on both sides — the client only\n * ever knows it, and the server carries it alongside its impl name — so it, not the server's impl\n * class, is the required key.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\nimport {MaskSpec} from \"./LogFieldMask\";\n\n/** Which end of the exchange this process is: the caller ('client') or the handler ('server'). */\nexport type ApiSide = 'client' | 'server';\n\nexport class ApiMethodInfo {\n    constructor(\n        readonly side: ApiSide,\n        /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both\n         *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */\n        readonly apiClass: string,\n        /** REQUIRED — the method on the contract (e.g. 'save'). */\n        readonly methodName: string,\n        /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no\n         *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */\n        readonly controllerName?: string,\n        /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO\n         *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}\n         *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an\n         *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.\n         *  Rides the call identity so the spec travels with the api definition, not a global app config. */\n        readonly mask?: MaskSpec,\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiMethodInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiMethodInfo.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAOH,MAAa,aAAa;IAET;IAGA;IAEA;IAGA;IAMA;IAMA;IArBb,YACa,IAAa;IACtB;2FACuF;IAC9E,QAAgB;IACzB,2DAA2D;IAClD,UAAkB;IAC3B;gGAC4F;IACnF,cAAuB;IAChC;;;;wGAIoG;IAC3F,IAAe;IACxB;;;;qFAIiF;IACxE,aAAsB,KAAK;QApB3B,SAAI,GAAJ,IAAI,CAAS;QAGb,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,eAAU,GAAV,UAAU,CAAQ;QAGlB,mBAAc,GAAd,cAAc,CAAS;QAMvB,SAAI,GAAJ,IAAI,CAAW;QAMf,eAAU,GAAV,UAAU,CAAiB;IACrC,CAAC;CACP;AAxBD,sCAwBC","sourcesContent":["/**\n * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to\n * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,\n * and external wrapped clients like the firestore admin client).\n *\n * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,\n * pubsub/queue enqueues, and multi-param external clients returning Promise<void>/Promise<unknown>.\n * None of those own an `httpMethod`/`path`, so LogApiCall must not depend on the HTTP-shaped\n * `RouteMetadata`. This carries only what identifies the call.\n *\n * MATCHING is the point of {@link apiClass}: a CLIENT call and the SERVER handler for the same logical\n * method must log the SAME identity so `jsonPayload.api.method.apiClass=\"SaveApi\"` filters both sides\n * together. The API CONTRACT class name (e.g. 'SaveApi') is available on both sides — the client only\n * ever knows it, and the server carries it alongside its impl name — so it, not the server's impl\n * class, is the required key.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\nimport {MaskSpec} from \"./LogFieldMask\";\n\n/** Which end of the exchange this process is: the caller ('client') or the handler ('server'). */\nexport type ApiSide = 'client' | 'server';\n\nexport class ApiMethodInfo {\n    constructor(\n        readonly side: ApiSide,\n        /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both\n         *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */\n        readonly apiClass: string,\n        /** REQUIRED — the method on the contract (e.g. 'save'). */\n        readonly methodName: string,\n        /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no\n         *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */\n        readonly controllerName?: string,\n        /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO\n         *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}\n         *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an\n         *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.\n         *  Rides the call identity so the spec travels with the api definition, not a global app config. */\n        readonly mask?: MaskSpec,\n        /** OPTIONAL — true when the route declared `@Endpoint(..., { background: true })`: this call is\n         *  plumbing the user did not ask for (a log shipper, a heartbeat, a telemetry flush), so\n         *  {@link LogApiCallImpl} emits NO `[API-*-req]`/`[API-*-resp-*]` line and stamps no\n         *  {@link ApiCallInfo} tag for it. Read once at route-build time and handed here, exactly as\n         *  {@link mask} is. Default (absent/false) = the ordinary, fully-logged call. */\n        readonly background: boolean = false,\n    ) {}\n}\n"]}

package/src/http/HttpEndpointOptions.d.ts

@@ -19,6 +19,28 @@ export interface EndpointOptions {
      * that sign flat form bodies, e.g. `{ formPost: true, rawBody: true }`.
      */
     rawBody?: boolean;
+    /**
+     * This route is plumbing the USER did not ask for — a log shipper, a heartbeat, a telemetry
+     * flush. It is not progress to report, and it must not be logged as an api call, because the
+     * line it would write is itself the thing being shipped.
+     *
+     * Rides the route metadata for the same reason {@link formPost} and {@link rawBody} do: the
+     * consumer branches on the ROUTE, without knowing the apiClass/methodName. Two consumers read
+     * it today — {@link LogApiCallImpl} emits no `[API-*-req]`/`[API-*-resp-*]` line for the call,
+     * and an app's `RequestLifecycleListener` can skip its progress bar and its own RPC
+     * instrumentation.
+     *
+     * WHY a declaration and not a suppression switch: shipping a log over a logged transport logs
+     * about shipping logs. The two mechanisms that do not know the endpoint both failed in prod
+     * (see #976) — a wall-clock "we are shipping" boolean swallowed unrelated lines including an
+     * error alarm, and a logger-name allowlist was incomplete by construction the moment anyone
+     * added a logger, producing a steady-state 4-lines-per-second request loop on an idle page.
+     * The ENDPOINT is the only stable, declarative fact, so it is where the decision belongs.
+     *
+     * Default false: absent means the ordinary, fully-logged route. The quiet path is the one you
+     * have to say out loud, so `grep -rn background` lists every endpoint webpieces stops logging.
+     */
+    background?: boolean;
 }
 /** An external endpoint must also identify the outside system that calls it. */
 export interface ExternalEndpointOptions extends EndpointOptions {

package/src/http/HttpEndpointOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpEndpointOptions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HttpEndpointOptions.ts"],"names":[],"mappings":"","sourcesContent":["import { ExternalSystemKind } from './external-caller';\nimport { ContractHttpMethod, EndpointResponseType } from './HttpContract';\n\n/** Options for one `@Endpoint`, stored parallel to the method-to-path metadata. */\nexport interface EndpointOptions {\n    /** HTTP verb for this route. Defaults to POST. */\n    httpMethod?: ContractHttpMethod;\n    /** Return only a JSON body (default), or the full transport-neutral status/header/body value. */\n    responseType?: EndpointResponseType;\n    /**\n     * Parse the request body as application/x-www-form-urlencoded instead of JSON. The request\n     * DTO must be flat; urlencoded has no nesting. Default false = JSON.\n     */\n    formPost?: boolean;\n    /**\n     * Retain the verbatim request bytes and absolute URL for a `@WpAuthWebhook` callback to verify.\n     * This is retention, not new buffering: the Express adapter already accumulates the body.\n     *\n     * `@WpAuthWebhook` requires this option at wiring time. It combines with `formPost` for vendors\n     * that sign flat form bodies, e.g. `{ formPost: true, rawBody: true }`.\n     */\n    rawBody?: boolean;\n}\n\n/** An external endpoint must also identify the outside system that calls it. */\nexport interface ExternalEndpointOptions extends EndpointOptions {\n    /** The outside system (`'twilio'`) — graph identity, not display text. */\n    calledBy: string;\n    /** What that caller is; picks its graph shape. Defaults to `'saas'`. */\n    callerKind?: ExternalSystemKind;\n}\n"]}
+{"version":3,"file":"HttpEndpointOptions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/HttpEndpointOptions.ts"],"names":[],"mappings":"","sourcesContent":["import { ExternalSystemKind } from './external-caller';\nimport { ContractHttpMethod, EndpointResponseType } from './HttpContract';\n\n/** Options for one `@Endpoint`, stored parallel to the method-to-path metadata. */\nexport interface EndpointOptions {\n    /** HTTP verb for this route. Defaults to POST. */\n    httpMethod?: ContractHttpMethod;\n    /** Return only a JSON body (default), or the full transport-neutral status/header/body value. */\n    responseType?: EndpointResponseType;\n    /**\n     * Parse the request body as application/x-www-form-urlencoded instead of JSON. The request\n     * DTO must be flat; urlencoded has no nesting. Default false = JSON.\n     */\n    formPost?: boolean;\n    /**\n     * Retain the verbatim request bytes and absolute URL for a `@WpAuthWebhook` callback to verify.\n     * This is retention, not new buffering: the Express adapter already accumulates the body.\n     *\n     * `@WpAuthWebhook` requires this option at wiring time. It combines with `formPost` for vendors\n     * that sign flat form bodies, e.g. `{ formPost: true, rawBody: true }`.\n     */\n    rawBody?: boolean;\n    /**\n     * This route is plumbing the USER did not ask for — a log shipper, a heartbeat, a telemetry\n     * flush. It is not progress to report, and it must not be logged as an api call, because the\n     * line it would write is itself the thing being shipped.\n     *\n     * Rides the route metadata for the same reason {@link formPost} and {@link rawBody} do: the\n     * consumer branches on the ROUTE, without knowing the apiClass/methodName. Two consumers read\n     * it today — {@link LogApiCallImpl} emits no `[API-*-req]`/`[API-*-resp-*]` line for the call,\n     * and an app's `RequestLifecycleListener` can skip its progress bar and its own RPC\n     * instrumentation.\n     *\n     * WHY a declaration and not a suppression switch: shipping a log over a logged transport logs\n     * about shipping logs. The two mechanisms that do not know the endpoint both failed in prod\n     * (see #976) — a wall-clock \"we are shipping\" boolean swallowed unrelated lines including an\n     * error alarm, and a logger-name allowlist was incomplete by construction the moment anyone\n     * added a logger, producing a steady-state 4-lines-per-second request loop on an idle page.\n     * The ENDPOINT is the only stable, declarative fact, so it is where the decision belongs.\n     *\n     * Default false: absent means the ordinary, fully-logged route. The quiet path is the one you\n     * have to say out loud, so `grep -rn background` lists every endpoint webpieces stops logging.\n     */\n    background?: boolean;\n}\n\n/** An external endpoint must also identify the outside system that calls it. */\nexport interface ExternalEndpointOptions extends EndpointOptions {\n    /** The outside system (`'twilio'`) — graph identity, not display text. */\n    calledBy: string;\n    /** What that caller is; picks its graph shape. Defaults to `'saas'`. */\n    callerKind?: ExternalSystemKind;\n}\n"]}

package/src/http/LogApiCall.d.ts

@@ -55,6 +55,33 @@ export declare class LogApiCallImpl {
      * exactly what the GCP filters (`jsonPayload.api.*`) want.
      */
     execute<Q, R>(methodInfo: ApiMethodInfo, requestDto: Q, method: (dto: Q) => Promise<R>, responseCount?: (response: R) => number | undefined): Promise<R>;
+    /**
+     * Build the tag-and-emit span used around every `[API-*]` line.
+     *
+     * set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,
+     * never across an await, so a single browser global slot can never be clobbered by a concurrent
+     * call. `ctx` is passed in (rather than read from `this`) so the caller has already proven it is
+     * ACTIVE before anything is stamped.
+     */
+    private stamper;
+    /**
+     * The `@Endpoint(..., { background: true })` path: run the call and say NOTHING about it.
+     *
+     * No `[API-*]` line, no {@link ApiCallInfo} stamp, and no serialization of either DTO — a
+     * background route is a log shipper or a heartbeat, so a line describing the call IS the thing
+     * being shipped, and emitting it feeds the next batch its own payload (#976).
+     *
+     * It deliberately does NOT call {@link activeContext}: that guard exists because a call with
+     * nowhere to STAMP a tag is a bug, and this path stamps nothing. A background call is therefore
+     * legal outside a RequestContext scope, which is exactly where a flusher tends to run.
+     *
+     * The null-request check is kept, because it is a contract error and not observability — a
+     * background route deserves the same error as any other, and the throw propagates to the caller
+     * unlogged here, exactly as the logged path re-throws.
+     *
+     * `responseCount` is not taken: it feeds only the `api.responseCount` tag, which is not emitted.
+     */
+    private executeUnlogged;
     /**
      * Evaluate an opt-in logical-item count without allowing observability code to affect the call.
      * Warnings deliberately contain neither request nor response bodies (nor the invalid value).

package/src/http/LogApiCall.js

@@ -69,22 +69,12 @@ class LogApiCallImpl {
      * exactly what the GCP filters (`jsonPayload.api.*`) want.
      */
     async execute(methodInfo, requestDto, method, responseCount) {
-        const ctx = this.activeContext();
-        const key = WebpiecesCoreHeaders_1.WebpiecesCoreHeaders.API_CALL_INFO;
+        if (methodInfo.background) {
+            return this.executeUnlogged(methodInfo, requestDto, method);
+        }
         const side = methodInfo.side;
         const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;
-        // set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,
-        // never across an await, so a single browser global slot can never be clobbered by a concurrent call.
-        const stamp = (info, emit) => {
-            ctx.set(key, info);
-            // webpieces-disable no-unmanaged-exceptions -- cleanup must run when a logging backend throws
-            try {
-                emit();
-            }
-            finally {
-                ctx.remove(key);
-            }
-        };
+        const stamp = this.stamper(this.activeContext());
         // Stringify ONCE and reuse for both the log text and the size — a second JSON.stringify of a
         // large DTO purely to measure it would double the cost of the thing we are measuring.
         // Only take the field-masking hit when this call declared sensitive fields; otherwise the plain
@@ -115,6 +105,50 @@ class LogApiCallImpl {
             throw err;
         }
     }
+    /**
+     * Build the tag-and-emit span used around every `[API-*]` line.
+     *
+     * set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,
+     * never across an await, so a single browser global slot can never be clobbered by a concurrent
+     * call. `ctx` is passed in (rather than read from `this`) so the caller has already proven it is
+     * ACTIVE before anything is stamped.
+     */
+    stamper(ctx) {
+        const key = WebpiecesCoreHeaders_1.WebpiecesCoreHeaders.API_CALL_INFO;
+        return (info, emit) => {
+            ctx.set(key, info);
+            // webpieces-disable no-unmanaged-exceptions -- cleanup must run when a logging backend throws
+            try {
+                emit();
+            }
+            finally {
+                ctx.remove(key);
+            }
+        };
+    }
+    /**
+     * The `@Endpoint(..., { background: true })` path: run the call and say NOTHING about it.
+     *
+     * No `[API-*]` line, no {@link ApiCallInfo} stamp, and no serialization of either DTO — a
+     * background route is a log shipper or a heartbeat, so a line describing the call IS the thing
+     * being shipped, and emitting it feeds the next batch its own payload (#976).
+     *
+     * It deliberately does NOT call {@link activeContext}: that guard exists because a call with
+     * nowhere to STAMP a tag is a bug, and this path stamps nothing. A background call is therefore
+     * legal outside a RequestContext scope, which is exactly where a flusher tends to run.
+     *
+     * The null-request check is kept, because it is a contract error and not observability — a
+     * background route deserves the same error as any other, and the throw propagates to the caller
+     * unlogged here, exactly as the logged path re-throws.
+     *
+     * `responseCount` is not taken: it feeds only the `api.responseCount` tag, which is not emitted.
+     */
+    async executeUnlogged(methodInfo, requestDto, method) {
+        if (!requestDto) {
+            throw new Error(`Request cannot be null and was from ${methodInfo.apiClass}.${methodInfo.methodName}`);
+        }
+        return method(requestDto);
+    }
     /**
      * Evaluate an opt-in logical-item count without allowing observability code to affect the call.
      * Warnings deliberately contain neither request nor response bodies (nor the invalid value).

package/src/http/LogApiCall.js.map

@@ -1 +1 @@
-{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":"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","sourcesContent":["import { toError } from '../lib/errorUtils';\nimport { LogManager } from '../logging/LogManager';\nimport { ApiCallInfo } from './ApiCallInfo';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { ApiCallContext } from './ApiCallContext';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { ClientRegistry } from './ClientRegistry';\nimport { WEBPIECES_DEFAULT_FAILURE_CLASSIFIER } from './WebpiecesDefaultFailureClassifier';\n\n// The console backends special-case THIS logger name into a self-describing [API.{side}.{phase}]\n// bracket (see ApiCallLogName) — so the name here and the name they match are the one constant.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\n/**\n * LogApiCallImpl - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and\n * client-side (ProxyClient) for one consistent logging shape across the framework.\n *\n * TWO things happen around each call:\n * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).\n * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the\n *    {@link ApiCallContext} seam, so EVERY log line emitted during the call (not just the\n *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as\n *    `jsonPayload.api.{method.{side,apiClass,methodName,controllerName},type,result}`.\n *\n * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →\n * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).\n * It stamps through the {@link ApiCallContext} seam instead, and takes that seam as a REQUIRED\n * CONSTRUCTOR ARGUMENT — there is no process-global holder to install and none to forget. Each\n * environment-specific package constructs its own:\n *\n *   LogApiFilter        (@webpieces/http-routing)        -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   NodeProxyClient     (@webpieces/http-client-node)    -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   TaskProxyClient     (@webpieces/cloudtasks-client)   -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   BrowserProxyClient  (@webpieces/http-client-browser) -> new LogApiCallImpl(new BrowserApiCallContext())\n *\n * NOT a singleton, deliberately: a shared instance would need a shared context, which is the global\n * this constructor replaced. Construct one where you know which environment you are in.\n *\n * Logging format patterns:\n * - [API-{side}-req] ClassName.methodName request={...}\n * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (user errors)\n * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)\n */\nexport class LogApiCallImpl {\n    /**\n     * @param ctx - the environment's {@link ApiCallContext}. REQUIRED, with no default: that is what\n     *   turns \"nobody bootstrapped the context\" into a compile error instead of a throw on the first\n     *   real call in production.\n     */\n    constructor(private readonly ctx: ApiCallContext) {}\n\n    /**\n     * Execute an API call with logging + `api` context-tagging around it.\n     *\n     * @param methodInfo - The transport-neutral call identity (side, apiClass, methodName,\n     *   controllerName?). `apiClass` is what matches a client call to its server handler in the logs.\n     * @param requestDto - The request DTO (external multi-param callers synthesize a small object)\n     * @param method - The method to execute\n     *\n     * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,\n     * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only\n     * for the SYNCHRONOUS span of each log line: set → log → remove. Because the tag is never held across\n     * `await method(...)`, a concurrent browser call (single-threaded, one global slot) can never clobber\n     * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is\n     * exactly what the GCP filters (`jsonPayload.api.*`) want.\n     */\n    public async execute<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n        responseCount?: (response: R) => number | undefined,\n    ): Promise<R> {\n        const ctx = this.activeContext();\n        const key = WebpiecesCoreHeaders.API_CALL_INFO;\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        // set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,\n        // never across an await, so a single browser global slot can never be clobbered by a concurrent call.\n        const stamp = (info: ApiCallInfo, emit: () => void): void => {\n            ctx.set(key, info);\n            // webpieces-disable no-unmanaged-exceptions -- cleanup must run when a logging backend throws\n            try {\n                emit();\n            } finally {\n                ctx.remove(key);\n            }\n        };\n\n        // Stringify ONCE and reuse for both the log text and the size — a second JSON.stringify of a\n        // large DTO purely to measure it would double the cost of the thing we are measuring.\n        // Only take the field-masking hit when this call declared sensitive fields; otherwise the plain\n        // JSON.stringify fast path, unchanged for every existing caller.\n        const requestBody = this.serialize(requestDto, methodInfo);\n        const requestSize = this.byteSize(requestBody);\n        // Declared out here so the catch below can read it too. Reassigned just before the call, so\n        // the number times ONLY the call and not our own request-logging.\n        let startMs = Date.now();\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            stamp(new ApiCallInfo(methodInfo, 'request', undefined, undefined, requestSize), () =>\n                log.info(`[API-${side}-req] ${id} request=${requestBody}`),\n            );\n\n            if (!requestDto) throw new Error(`Request cannot be null and was from ${id}`);\n\n            startMs = Date.now();\n            const response = await method(requestDto);\n            const durationMs = Date.now() - startMs;\n\n            const responseBody = this.serialize(response, methodInfo);\n            const count = this.selectResponseCount(response, responseCount, side, id);\n            stamp(\n                new ApiCallInfo(\n                    methodInfo,\n                    'response',\n                    'success',\n                    durationMs,\n                    requestSize,\n                    this.byteSize(responseBody),\n                    count,\n                ),\n                () => log.info(`[API-${side}-resp-SUCCESS] ${id} response=${responseBody}`),\n            );\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            // Duration comes off the SAME start as the success path, so a slow failure (a timeout, a\n            // hung dependency) reports its real cost rather than nothing.\n            this.logFailure(error, methodInfo, Date.now() - startMs, requestSize, stamp);\n            throw err;\n        }\n    }\n\n    /**\n     * Evaluate an opt-in logical-item count without allowing observability code to affect the call.\n     * Warnings deliberately contain neither request nor response bodies (nor the invalid value).\n     */\n    private selectResponseCount<R>(\n        response: R,\n        selector: ((response: R) => number | undefined) | undefined,\n        side: string,\n        id: string,\n    ): number | undefined {\n        if (!selector) {\n            return undefined;\n        }\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an observability callback must not fail the API call\n        try {\n            const count = selector(response);\n            if (\n                count === undefined ||\n                (Number.isFinite(count) && Number.isInteger(count) && count >= 0)\n            ) {\n                return count;\n            }\n            this.warnInvalidResponseCount(side, id, 'returned an invalid value');\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            this.warnInvalidResponseCount(side, id, 'threw');\n        }\n        return undefined;\n    }\n\n    private warnInvalidResponseCount(side: string, id: string, reason: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a warning backend must not replace a successful API response\n        try {\n            log.warn(\n                `[API-${side}-resp-COUNT-WARN] ${id} responseCount selector ${reason}; omitting responseCount`,\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            // The API response is authoritative; observability failures are intentionally ignored here.\n        }\n    }\n\n    /**\n     * Serialize a DTO for the LOG LINE ONLY. With no mask on the call, this is a plain JSON.stringify\n     * (byte-for-byte the old behavior, no walk) so existing callers pay nothing. With a mask, it runs\n     * {@link MaskSpec.stringify}, which produces a masked STRING without ever mutating the DTO — so the\n     * object handed to the transport, and thus the value ON THE WIRE, is unchanged.\n     */\n    private serialize(\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches execute)\n        dto: unknown,\n        methodInfo: ApiMethodInfo,\n    ): string | undefined {\n        return methodInfo.mask ? methodInfo.mask.stringify(dto) : JSON.stringify(dto);\n    }\n\n    /**\n     * The ApiCallContext to stamp into. It cannot be MISSING (it is a constructor argument), but it\n     * can be INACTIVE — a Node context used outside any `RequestContext.run(...)` scope. That throws:\n     * an api call with nowhere to tag is a bug.\n     */\n    private activeContext(): ApiCallContext {\n        const ctx = this.ctx;\n        if (!ctx.isActive()) {\n            throw new Error(\n                'LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside a ' +\n                    'RequestContext.run(...) scope — a server filter opens one per request, and a ' +\n                    'non-webpieces host must open one around the work that calls a webpieces client. ' +\n                    '(A BrowserApiCallContext is always active, so this can only be the Node side.)',\n            );\n        }\n        return ctx;\n    }\n\n    /**\n     * Tag + log a thrown call. There is no responseSize — a throw produced no response body to measure.\n     */\n    private logFailure(\n        error: Error,\n        methodInfo: ApiMethodInfo,\n        durationMs: number,\n        requestSize: number | undefined,\n        stamp: (info: ApiCallInfo, emit: () => void) => void,\n    ): void {\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const errorType = error.constructor.name;\n        // The MESSAGE is on BOTH branches, and that is load-bearing: this is the ONLY operator line\n        // per failure now that `ApiErrorBoundary` writes none. An operator error message is never\n        // published to a caller (see `ApiErrorCodec.publicMessage`), so the log is the one place it\n        // exists at all — dropping it on the caller-error branch would lose it outright.\n        // Pluggable classification (ClientRegistry): a per-apiClass EXTERNAL-client classifier wins,\n        // else the app default, else the webpieces built-in — which is side-dependent (a 4xx the SERVER\n        // raised is a handled non-failure; the same 4xx a CLIENT receives means its call FAILED; 266 is\n        // never a failure either side). `isUser` = \"treat as non-failure (OTHER / result:'success')\".\n        const isUser = !ClientRegistry.classifyFailure(error, methodInfo);\n\n        stamp(\n            new ApiCallInfo(\n                methodInfo,\n                'response',\n                isUser ? 'success' : 'failure',\n                durationMs,\n                requestSize,\n            ),\n            () =>\n                isUser\n                    ? log.warn(\n                          `[API-${side}-resp-OTHER] ${id} errorType=${errorType} error=${error.message}`,\n                      )\n                    : log.error(\n                          `[API-${side}-resp-FAIL] ${id} errorType=${errorType} error=${error.message}`,\n                      ),\n        );\n    }\n\n    /**\n     * UTF-8 byte size without platform-specific encoding globals: LogApiCall runs in the\n     * browser bundle. Undefined in, undefined out — a `Promise<void>` method has no body to measure,\n     * and a 0 there would be a lie (JSON.stringify(undefined) returns undefined, not '').\n     */\n    private byteSize(serialized: string | undefined): number | undefined {\n        if (serialized === undefined) {\n            return undefined;\n        }\n        let bytes = 0;\n        for (const character of serialized) {\n            const code = character.codePointAt(0)!;\n            bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;\n        }\n        return bytes;\n    }\n\n    /**\n     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api\n     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?\n     *\n     * BACK-COMPAT SHIM: the canonical logic now lives in {@link WebpiecesDefaultFailureClassifier}\n     * (the webpieces built-in tier), and the LIVE classification path is\n     * {@link ClientRegistry.classifyFailure} (per-apiClass → app default → built-in). This method\n     * delegates to the built-in so existing callers/tests keep the exact old behavior; it does NOT\n     * consult registered classifiers. `apiClass`/`methodName` are irrelevant to the built-in (it reads\n     * only `side`), hence the empty strings.\n     *\n     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)\n     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call\n     * @returns true if this should be treated as a non-failure (OTHER / result:'success')\n     */\n    isUserError(error: Error, server: boolean): boolean {\n        return !WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(\n            error,\n            new ApiMethodInfo(server ? 'server' : 'client', '', ''),\n        );\n    }\n}\n"]}
+{"version":3,"file":"LogApiCall.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/LogApiCall.ts"],"names":[],"mappings":";;;AAAA,kDAA4C;AAC5C,sDAAmD;AACnD,+CAA4C;AAC5C,mDAAgD;AAEhD,iEAA8D;AAC9D,qDAA4D;AAC5D,qDAAkD;AAClD,2FAA2F;AAE3F,iGAAiG;AACjG,gGAAgG;AAChG,MAAM,GAAG,GAAG,uBAAU,CAAC,SAAS,CAAC,yCAAwB,CAAC,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,cAAc;IAMM;IAL7B;;;;OAIG;IACH,YAA6B,GAAmB;QAAnB,QAAG,GAAH,GAAG,CAAgB;IAAG,CAAC;IAEpD;;;;;;;;;;;;;;OAcG;IACI,KAAK,CAAC,OAAO,CAChB,UAAyB,EACzB,UAAa,EACb,MAA8B,EAC9B,aAAmD;QAEnD,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC7B,MAAM,EAAE,GAAG,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;QAEjD,6FAA6F;QAC7F,sFAAsF;QACtF,gGAAgG;QAChG,iEAAiE;QACjE,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC/C,4FAA4F;QAC5F,kEAAkE;QAClE,IAAI,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEzB,qHAAqH;QACrH,IAAI,CAAC;YACD,KAAK,CAAC,IAAI,yBAAW,CAAC,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,CAClF,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,SAAS,EAAE,YAAY,WAAW,EAAE,CAAC,CAC7D,CAAC;YAEF,IAAI,CAAC,UAAU;gBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,EAAE,EAAE,CAAC,CAAC;YAE9E,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;YAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;YAExC,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1E,KAAK,CACD,IAAI,yBAAW,CACX,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAC3B,KAAK,CACR,EACD,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,kBAAkB,EAAE,aAAa,YAAY,EAAE,CAAC,CAC9E,CAAC;YAEF,OAAO,QAAQ,CAAC;QACpB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,yFAAyF;YACzF,8DAA8D;YAC9D,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;YAC7E,MAAM,GAAG,CAAC;QACd,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACK,OAAO,CAAC,GAAmB;QAC/B,MAAM,GAAG,GAAG,2CAAoB,CAAC,aAAa,CAAC;QAC/C,OAAO,CAAC,IAAiB,EAAE,IAAgB,EAAQ,EAAE;YACjD,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACnB,8FAA8F;YAC9F,IAAI,CAAC;gBACD,IAAI,EAAE,CAAC;YACX,CAAC;oBAAS,CAAC;gBACP,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;QACL,CAAC,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACK,KAAK,CAAC,eAAe,CACzB,UAAyB,EACzB,UAAa,EACb,MAA8B;QAE9B,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACX,uCAAuC,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,UAAU,EAAE,CACxF,CAAC;QACN,CAAC;QACD,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACK,mBAAmB,CACvB,QAAW,EACX,QAA2D,EAC3D,IAAY,EACZ,EAAU;QAEV,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,OAAO,SAAS,CAAC;QACrB,CAAC;QAED,sHAAsH;QACtH,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACjC,IACI,KAAK,KAAK,SAAS;gBACnB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,EACnE,CAAC;gBACC,OAAO,KAAK,CAAC;YACjB,CAAC;YACD,IAAI,CAAC,wBAAwB,CAAC,IAAI,EAAE,EAAE,EAAE,2BAA2B,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,KAAK,KAAK,CAAC;YACX,IAAI,CAAC,wBAAwB,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAEO,wBAAwB,CAAC,IAAY,EAAE,EAAU,EAAE,MAAc;QACrE,8HAA8H;QAC9H,IAAI,CAAC;YACD,GAAG,CAAC,IAAI,CACJ,QAAQ,IAAI,qBAAqB,EAAE,2BAA2B,MAAM,0BAA0B,CACjG,CAAC;QACN,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,IAAA,oBAAO,EAAC,GAAG,CAAC,CAAC;YAC3B,KAAK,KAAK,CAAC;YACX,4FAA4F;QAChG,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,SAAS;IACb,uGAAuG;IACvG,GAAY,EACZ,UAAyB;QAEzB,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAClF,CAAC;IAED;;;;OAIG;IACK,aAAa;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACX,+EAA+E;gBAC3E,+EAA+E;gBAC/E,kFAAkF;gBAClF,gFAAgF,CACvF,CAAC;QACN,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;OAEG;IACK,UAAU,CACd,KAAY,EACZ,UAAyB,EACzB,UAAkB,EAClB,WAA+B,EAC/B,KAAoD;QAEpD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC7B,MAAM,EAAE,GAAG,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC;QAC7D,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC;QACzC,4FAA4F;QAC5F,0FAA0F;QAC1F,4FAA4F;QAC5F,iFAAiF;QACjF,6FAA6F;QAC7F,gGAAgG;QAChG,gGAAgG;QAChG,8FAA8F;QAC9F,MAAM,MAAM,GAAG,CAAC,+BAAc,CAAC,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAElE,KAAK,CACD,IAAI,yBAAW,CACX,UAAU,EACV,UAAU,EACV,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAC9B,UAAU,EACV,WAAW,CACd,EACD,GAAG,EAAE,CACD,MAAM;YACF,CAAC,CAAC,GAAG,CAAC,IAAI,CACJ,QAAQ,IAAI,gBAAgB,EAAE,cAAc,SAAS,UAAU,KAAK,CAAC,OAAO,EAAE,CACjF;YACH,CAAC,CAAC,GAAG,CAAC,KAAK,CACL,QAAQ,IAAI,eAAe,EAAE,cAAc,SAAS,UAAU,KAAK,CAAC,OAAO,EAAE,CAChF,CACd,CAAC;IACN,CAAC;IAED;;;;OAIG;IACK,QAAQ,CAAC,UAA8B;QAC3C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC;YACvC,KAAK,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,KAAY,EAAE,MAAe;QACrC,OAAO,CAAC,wEAAoC,CAAC,SAAS,CAClD,KAAK,EACL,IAAI,6BAAa,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAC1D,CAAC;IACN,CAAC;CACJ;AAnSD,wCAmSC","sourcesContent":["import { toError } from '../lib/errorUtils';\nimport { LogManager } from '../logging/LogManager';\nimport { ApiCallInfo } from './ApiCallInfo';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { ApiCallContext } from './ApiCallContext';\nimport { WebpiecesCoreHeaders } from './WebpiecesCoreHeaders';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { ClientRegistry } from './ClientRegistry';\nimport { WEBPIECES_DEFAULT_FAILURE_CLASSIFIER } from './WebpiecesDefaultFailureClassifier';\n\n// The console backends special-case THIS logger name into a self-describing [API.{side}.{phase}]\n// bracket (see ApiCallLogName) — so the name here and the name they match are the one constant.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\n/**\n * LogApiCallImpl - Generic API call logging utility, used by BOTH server-side (LogApiFilter) and\n * client-side (ProxyClient) for one consistent logging shape across the framework.\n *\n * TWO things happen around each call:\n * 1. Text lines are emitted (the human-readable `[API-...]` patterns below).\n * 2. A structured {@link ApiCallInfo} tag is stamped into the ambient request context via the\n *    {@link ApiCallContext} seam, so EVERY log line emitted during the call (not just the\n *    req/resp lines) inherits a filterable `api` object — surfacing in GCP as\n *    `jsonPayload.api.{method.{side,apiClass,methodName,controllerName},type,result}`.\n *\n * BROWSER-SAFE: this lives in core-util and runs in the browser bundle (via ProxyClient →\n * BrowserProxyClient), so it MUST NOT import `RequestContext` (Node async_hooks, and a circular dep).\n * It stamps through the {@link ApiCallContext} seam instead, and takes that seam as a REQUIRED\n * CONSTRUCTOR ARGUMENT — there is no process-global holder to install and none to forget. Each\n * environment-specific package constructs its own:\n *\n *   LogApiFilter        (@webpieces/http-routing)        -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   NodeProxyClient     (@webpieces/http-client-node)    -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   TaskProxyClient     (@webpieces/cloudtasks-client)   -> new LogApiCallImpl(new RequestContextApiCallContext())\n *   BrowserProxyClient  (@webpieces/http-client-browser) -> new LogApiCallImpl(new BrowserApiCallContext())\n *\n * NOT a singleton, deliberately: a shared instance would need a shared context, which is the global\n * this constructor replaced. Construct one where you know which environment you are in.\n *\n * Logging format patterns:\n * - [API-{side}-req] ClassName.methodName request={...}\n * - [API-{side}-resp-SUCCESS] ClassName.methodName response={...}\n * - [API-{side}-resp-OTHER] ClassName.methodName errorType={...} error={...}  (user errors)\n * - [API-{side}-resp-FAIL] ClassName.methodName error={...}  (server errors)\n */\nexport class LogApiCallImpl {\n    /**\n     * @param ctx - the environment's {@link ApiCallContext}. REQUIRED, with no default: that is what\n     *   turns \"nobody bootstrapped the context\" into a compile error instead of a throw on the first\n     *   real call in production.\n     */\n    constructor(private readonly ctx: ApiCallContext) {}\n\n    /**\n     * Execute an API call with logging + `api` context-tagging around it.\n     *\n     * @param methodInfo - The transport-neutral call identity (side, apiClass, methodName,\n     *   controllerName?). `apiClass` is what matches a client call to its server handler in the logs.\n     * @param requestDto - The request DTO (external multi-param callers synthesize a small object)\n     * @param method - The method to execute\n     *\n     * Correlation fields (requestId, tenantId, ...) are NOT stamped here — a logging BACKEND owns that,\n     * reading RequestContext on every record. What IS stamped here is the per-call `api` tag, and only\n     * for the SYNCHRONOUS span of each log line: set → log → remove. Because the tag is never held across\n     * `await method(...)`, a concurrent browser call (single-threaded, one global slot) can never clobber\n     * it. Cost: only the `[API-*]` req/resp lines carry `api`, not lines emitted mid-call — which is\n     * exactly what the GCP filters (`jsonPayload.api.*`) want.\n     */\n    public async execute<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n        responseCount?: (response: R) => number | undefined,\n    ): Promise<R> {\n        if (methodInfo.background) {\n            return this.executeUnlogged(methodInfo, requestDto, method);\n        }\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const stamp = this.stamper(this.activeContext());\n\n        // Stringify ONCE and reuse for both the log text and the size — a second JSON.stringify of a\n        // large DTO purely to measure it would double the cost of the thing we are measuring.\n        // Only take the field-masking hit when this call declared sensitive fields; otherwise the plain\n        // JSON.stringify fast path, unchanged for every existing caller.\n        const requestBody = this.serialize(requestDto, methodInfo);\n        const requestSize = this.byteSize(requestBody);\n        // Declared out here so the catch below can read it too. Reassigned just before the call, so\n        // the number times ONLY the call and not our own request-logging.\n        let startMs = Date.now();\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- LogApiCall logs errors before re-throwing to caller\n        try {\n            stamp(new ApiCallInfo(methodInfo, 'request', undefined, undefined, requestSize), () =>\n                log.info(`[API-${side}-req] ${id} request=${requestBody}`),\n            );\n\n            if (!requestDto) throw new Error(`Request cannot be null and was from ${id}`);\n\n            startMs = Date.now();\n            const response = await method(requestDto);\n            const durationMs = Date.now() - startMs;\n\n            const responseBody = this.serialize(response, methodInfo);\n            const count = this.selectResponseCount(response, responseCount, side, id);\n            stamp(\n                new ApiCallInfo(\n                    methodInfo,\n                    'response',\n                    'success',\n                    durationMs,\n                    requestSize,\n                    this.byteSize(responseBody),\n                    count,\n                ),\n                () => log.info(`[API-${side}-resp-SUCCESS] ${id} response=${responseBody}`),\n            );\n\n            return response;\n        } catch (err: unknown) {\n            const error = toError(err);\n            // Duration comes off the SAME start as the success path, so a slow failure (a timeout, a\n            // hung dependency) reports its real cost rather than nothing.\n            this.logFailure(error, methodInfo, Date.now() - startMs, requestSize, stamp);\n            throw err;\n        }\n    }\n\n    /**\n     * Build the tag-and-emit span used around every `[API-*]` line.\n     *\n     * set → emit → remove, as ONE synchronous span: the tag is live only while the logger reads it,\n     * never across an await, so a single browser global slot can never be clobbered by a concurrent\n     * call. `ctx` is passed in (rather than read from `this`) so the caller has already proven it is\n     * ACTIVE before anything is stamped.\n     */\n    private stamper(ctx: ApiCallContext): (info: ApiCallInfo, emit: () => void) => void {\n        const key = WebpiecesCoreHeaders.API_CALL_INFO;\n        return (info: ApiCallInfo, emit: () => void): void => {\n            ctx.set(key, info);\n            // webpieces-disable no-unmanaged-exceptions -- cleanup must run when a logging backend throws\n            try {\n                emit();\n            } finally {\n                ctx.remove(key);\n            }\n        };\n    }\n\n    /**\n     * The `@Endpoint(..., { background: true })` path: run the call and say NOTHING about it.\n     *\n     * No `[API-*]` line, no {@link ApiCallInfo} stamp, and no serialization of either DTO — a\n     * background route is a log shipper or a heartbeat, so a line describing the call IS the thing\n     * being shipped, and emitting it feeds the next batch its own payload (#976).\n     *\n     * It deliberately does NOT call {@link activeContext}: that guard exists because a call with\n     * nowhere to STAMP a tag is a bug, and this path stamps nothing. A background call is therefore\n     * legal outside a RequestContext scope, which is exactly where a flusher tends to run.\n     *\n     * The null-request check is kept, because it is a contract error and not observability — a\n     * background route deserves the same error as any other, and the throw propagates to the caller\n     * unlogged here, exactly as the logged path re-throws.\n     *\n     * `responseCount` is not taken: it feeds only the `api.responseCount` tag, which is not emitted.\n     */\n    private async executeUnlogged<Q, R>(\n        methodInfo: ApiMethodInfo,\n        requestDto: Q,\n        method: (dto: Q) => Promise<R>,\n    ): Promise<R> {\n        if (!requestDto) {\n            throw new Error(\n                `Request cannot be null and was from ${methodInfo.apiClass}.${methodInfo.methodName}`,\n            );\n        }\n        return method(requestDto);\n    }\n\n    /**\n     * Evaluate an opt-in logical-item count without allowing observability code to affect the call.\n     * Warnings deliberately contain neither request nor response bodies (nor the invalid value).\n     */\n    private selectResponseCount<R>(\n        response: R,\n        selector: ((response: R) => number | undefined) | undefined,\n        side: string,\n        id: string,\n    ): number | undefined {\n        if (!selector) {\n            return undefined;\n        }\n\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- an observability callback must not fail the API call\n        try {\n            const count = selector(response);\n            if (\n                count === undefined ||\n                (Number.isFinite(count) && Number.isInteger(count) && count >= 0)\n            ) {\n                return count;\n            }\n            this.warnInvalidResponseCount(side, id, 'returned an invalid value');\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            this.warnInvalidResponseCount(side, id, 'threw');\n        }\n        return undefined;\n    }\n\n    private warnInvalidResponseCount(side: string, id: string, reason: string): void {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- a warning backend must not replace a successful API response\n        try {\n            log.warn(\n                `[API-${side}-resp-COUNT-WARN] ${id} responseCount selector ${reason}; omitting responseCount`,\n            );\n        } catch (err: unknown) {\n            const error = toError(err);\n            void error;\n            // The API response is authoritative; observability failures are intentionally ignored here.\n        }\n    }\n\n    /**\n     * Serialize a DTO for the LOG LINE ONLY. With no mask on the call, this is a plain JSON.stringify\n     * (byte-for-byte the old behavior, no walk) so existing callers pay nothing. With a mask, it runs\n     * {@link MaskSpec.stringify}, which produces a masked STRING without ever mutating the DTO — so the\n     * object handed to the transport, and thus the value ON THE WIRE, is unchanged.\n     */\n    private serialize(\n        // webpieces-disable no-any-unknown -- DTO types are erased at the api/proxy boundary (matches execute)\n        dto: unknown,\n        methodInfo: ApiMethodInfo,\n    ): string | undefined {\n        return methodInfo.mask ? methodInfo.mask.stringify(dto) : JSON.stringify(dto);\n    }\n\n    /**\n     * The ApiCallContext to stamp into. It cannot be MISSING (it is a constructor argument), but it\n     * can be INACTIVE — a Node context used outside any `RequestContext.run(...)` scope. That throws:\n     * an api call with nowhere to tag is a bug.\n     */\n    private activeContext(): ApiCallContext {\n        const ctx = this.ctx;\n        if (!ctx.isActive()) {\n            throw new Error(\n                'LogApiCall requires an ACTIVE ApiCallContext. On a Node server, run inside a ' +\n                    'RequestContext.run(...) scope — a server filter opens one per request, and a ' +\n                    'non-webpieces host must open one around the work that calls a webpieces client. ' +\n                    '(A BrowserApiCallContext is always active, so this can only be the Node side.)',\n            );\n        }\n        return ctx;\n    }\n\n    /**\n     * Tag + log a thrown call. There is no responseSize — a throw produced no response body to measure.\n     */\n    private logFailure(\n        error: Error,\n        methodInfo: ApiMethodInfo,\n        durationMs: number,\n        requestSize: number | undefined,\n        stamp: (info: ApiCallInfo, emit: () => void) => void,\n    ): void {\n        const side = methodInfo.side;\n        const id = `${methodInfo.apiClass}.${methodInfo.methodName}`;\n        const errorType = error.constructor.name;\n        // The MESSAGE is on BOTH branches, and that is load-bearing: this is the ONLY operator line\n        // per failure now that `ApiErrorBoundary` writes none. An operator error message is never\n        // published to a caller (see `ApiErrorCodec.publicMessage`), so the log is the one place it\n        // exists at all — dropping it on the caller-error branch would lose it outright.\n        // Pluggable classification (ClientRegistry): a per-apiClass EXTERNAL-client classifier wins,\n        // else the app default, else the webpieces built-in — which is side-dependent (a 4xx the SERVER\n        // raised is a handled non-failure; the same 4xx a CLIENT receives means its call FAILED; 266 is\n        // never a failure either side). `isUser` = \"treat as non-failure (OTHER / result:'success')\".\n        const isUser = !ClientRegistry.classifyFailure(error, methodInfo);\n\n        stamp(\n            new ApiCallInfo(\n                methodInfo,\n                'response',\n                isUser ? 'success' : 'failure',\n                durationMs,\n                requestSize,\n            ),\n            () =>\n                isUser\n                    ? log.warn(\n                          `[API-${side}-resp-OTHER] ${id} errorType=${errorType} error=${error.message}`,\n                      )\n                    : log.error(\n                          `[API-${side}-resp-FAIL] ${id} errorType=${errorType} error=${error.message}`,\n                      ),\n        );\n    }\n\n    /**\n     * UTF-8 byte size without platform-specific encoding globals: LogApiCall runs in the\n     * browser bundle. Undefined in, undefined out — a `Promise<void>` method has no body to measure,\n     * and a 0 there would be a lie (JSON.stringify(undefined) returns undefined, not '').\n     */\n    private byteSize(serialized: string | undefined): number | undefined {\n        if (serialized === undefined) {\n            return undefined;\n        }\n        let bytes = 0;\n        for (const character of serialized) {\n            const code = character.codePointAt(0)!;\n            bytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;\n        }\n        return bytes;\n    }\n\n    /**\n     * Is this error a NON-failure for HEALTH/METRICS — the process working CORRECTLY (log OTHER, api\n     * result:'success') — rather than a real failure to surface (log FAIL, result:'failure')?\n     *\n     * BACK-COMPAT SHIM: the canonical logic now lives in {@link WebpiecesDefaultFailureClassifier}\n     * (the webpieces built-in tier), and the LIVE classification path is\n     * {@link ClientRegistry.classifyFailure} (per-apiClass → app default → built-in). This method\n     * delegates to the built-in so existing callers/tests keep the exact old behavior; it does NOT\n     * consult registered classifiers. `apiClass`/`methodName` are irrelevant to the built-in (it reads\n     * only `side`), hence the empty strings.\n     *\n     * @param error  - The already-normalized error (callers pass toError(err), never a raw catch value)\n     * @param server - True when this side is the SERVER handling an inbound call; false for a CLIENT's outbound call\n     * @returns true if this should be treated as a non-failure (OTHER / result:'success')\n     */\n    isUserError(error: Error, server: boolean): boolean {\n        return !WEBPIECES_DEFAULT_FAILURE_CLASSIFIER.isFailure(\n            error,\n            new ApiMethodInfo(server ? 'server' : 'client', '', ''),\n        );\n    }\n}\n"]}

package/src/http/RouteMetadata.d.ts

@@ -46,6 +46,18 @@ export declare class RouteMetadata {
      * the body from the ROUTE, without knowing the apiClass/methodName.
      */
     readonly rawBody: boolean;
+    /**
+     * True when @Endpoint(..., { background: true }): this route is plumbing the user did not ask
+     * for (a log shipper, a heartbeat, a telemetry flush). Rides the route metadata for the same
+     * reason {@link formPost} and {@link rawBody} do — each consumer branches on the ROUTE, without
+     * knowing the apiClass/methodName.
+     *
+     * Read by {@link LogApiCallImpl} (via ApiMethodInfo, exactly as {@link mask} is) so no
+     * `[API-*-req]`/`[API-*-resp-*]` line is emitted for the call, and readable from an app's
+     * `RequestLifecycleListener.onRequestStart/onRequestEnd` so a progress bar and any app-level RPC
+     * instrumentation can skip it too. Default false = an ordinary, fully-logged route.
+     */
+    readonly background: boolean;
     constructor(httpMethod: string, path: string, methodName: string, controllerClassName?: string, authMeta?: AuthMeta, apiName?: string, formPost?: boolean, mask?: MaskSpec, rawBody?: boolean, 
     /** Explicit path/query mappings, in API declaration order. */
     parameterBindings?: readonly HttpParameterBinding[], 
@@ -54,5 +66,5 @@ export declare class RouteMetadata {
     /** Whether clients receive only the body or the complete status/header/body response. */
     responseType?: EndpointResponseType, 
     /** Present only for `(ResponseStream) => Promise<RequestStream>` contracts. */
-    streaming?: StreamingEndpointMetadata | undefined);
+    streaming?: StreamingEndpointMetadata | undefined, background?: boolean);
 }

package/src/http/RouteMetadata.js

@@ -41,6 +41,18 @@ class RouteMetadata {
      * the body from the ROUTE, without knowing the apiClass/methodName.
      */
     rawBody;
+    /**
+     * True when @Endpoint(..., { background: true }): this route is plumbing the user did not ask
+     * for (a log shipper, a heartbeat, a telemetry flush). Rides the route metadata for the same
+     * reason {@link formPost} and {@link rawBody} do — each consumer branches on the ROUTE, without
+     * knowing the apiClass/methodName.
+     *
+     * Read by {@link LogApiCallImpl} (via ApiMethodInfo, exactly as {@link mask} is) so no
+     * `[API-*-req]`/`[API-*-resp-*]` line is emitted for the call, and readable from an app's
+     * `RequestLifecycleListener.onRequestStart/onRequestEnd` so a progress bar and any app-level RPC
+     * instrumentation can skip it too. Default false = an ordinary, fully-logged route.
+     */
+    background;
     constructor(httpMethod, path, methodName, controllerClassName, authMeta, apiName, formPost = false, mask, rawBody = false, 
     /** Explicit path/query mappings, in API declaration order. */
     parameterBindings = [], 
@@ -49,7 +61,7 @@ class RouteMetadata {
     /** Whether clients receive only the body or the complete status/header/body response. */
     responseType = 'body', 
     /** Present only for `(ResponseStream) => Promise<RequestStream>` contracts. */
-    streaming) {
+    streaming, background = false) {
         this.parameterBindings = parameterBindings;
         this.bodyParameterIndex = bodyParameterIndex;
         this.responseType = responseType;
@@ -67,6 +79,7 @@ class RouteMetadata {
         this.bodyParameterIndex = bodyParameterIndex;
         this.responseType = responseType;
         this.streaming = streaming;
+        this.background = background;
     }
 }
 exports.RouteMetadata = RouteMetadata;

package/src/http/RouteMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadata.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;GAQG;AACH,MAAa,aAAa;IAuCT;IAEA;IAEA;IAEA;IA5Cb,UAAU,CAAS;IACnB,IAAI,CAAS;IACb,UAAU,CAAS;IACnB,mBAAmB,CAAU;IAC7B,QAAQ,CAAY;IACpB,wFAAwF;IACxF,OAAO,CAAU;IACjB;;;;OAIG;IACM,QAAQ,CAAU;IAC3B;;;;OAIG;IACM,IAAI,CAAY;IACzB;;;;;OAKG;IACM,OAAO,CAAU;IAE1B,YACI,UAAkB,EAClB,IAAY,EACZ,UAAkB,EAClB,mBAA4B,EAC5B,QAAmB,EACnB,OAAgB,EAChB,WAAoB,KAAK,EACzB,IAAe,EACf,UAAmB,KAAK;IACxB,8DAA8D;IACrD,oBAAqD,EAAE;IAChE,8EAA8E;IACrE,kBAA2B;IACpC,yFAAyF;IAChF,eAAqC,MAAM;IACpD,+EAA+E;IACtE,SAAqC;QANrC,sBAAiB,GAAjB,iBAAiB,CAAsC;QAEvD,uBAAkB,GAAlB,kBAAkB,CAAS;QAE3B,iBAAY,GAAZ,YAAY,CAA+B;QAE3C,cAAS,GAAT,SAAS,CAA4B;QAE9C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,mBAAmB,GAAG,mBAAmB,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ;AA7DD,sCA6DC","sourcesContent":["import { MaskSpec } from './LogFieldMask';\nimport { AuthMeta } from './auth-mode';\nimport { EndpointResponseType, HttpParameterBinding } from './HttpContract';\nimport { StreamingEndpointMetadata } from './StreamingContract';\n\n/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by ProxyClient\n * and ApiRoutingFactory.\n *\n * Lives in its own file (one class per file) purely for file size, exactly as `api-kind.ts` and\n * `external-caller.ts` were split off `decorators.ts` before it. Nothing about its role changed.\n */\nexport class RouteMetadata {\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n    /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */\n    apiName?: string;\n    /**\n     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded\n     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch\n     * without knowing the apiClass/methodName. Default false = JSON.\n     */\n    readonly formPost: boolean;\n    /**\n     * The @MaskLog field-mask spec for this route, or undefined when the method declared none. Read\n     * ONCE here at route-build time and handed to {@link LogApiCallImpl} via ApiMethodInfo, so the per-call\n     * log path pays for masking only on routes that opted in (the rest stay on plain JSON.stringify).\n     */\n    readonly mask?: MaskSpec;\n    /**\n     * True when @Endpoint(..., { rawBody: true }): the transport must retain the verbatim bytes +\n     * absolute url for the `@WpAuthWebhook` hook to verify a vendor signature over. Rides the route\n     * metadata for the same reason {@link formPost} does — the transport adapter decides how to read\n     * the body from the ROUTE, without knowing the apiClass/methodName.\n     */\n    readonly rawBody: boolean;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n        apiName?: string,\n        formPost: boolean = false,\n        mask?: MaskSpec,\n        rawBody: boolean = false,\n        /** Explicit path/query mappings, in API declaration order. */\n        readonly parameterBindings: readonly HttpParameterBinding[] = [],\n        /** The sole unannotated POST parameter, or undefined for a bodyless route. */\n        readonly bodyParameterIndex?: number,\n        /** Whether clients receive only the body or the complete status/header/body response. */\n        readonly responseType: EndpointResponseType = 'body',\n        /** Present only for `(ResponseStream) => Promise<RequestStream>` contracts. */\n        readonly streaming?: StreamingEndpointMetadata,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n        this.apiName = apiName;\n        this.formPost = formPost;\n        this.mask = mask;\n        this.rawBody = rawBody;\n        this.parameterBindings = parameterBindings;\n        this.bodyParameterIndex = bodyParameterIndex;\n        this.responseType = responseType;\n        this.streaming = streaming;\n    }\n}\n"]}
+{"version":3,"file":"RouteMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadata.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;GAQG;AACH,MAAa,aAAa;IAmDT;IAEA;IAEA;IAEA;IAxDb,UAAU,CAAS;IACnB,IAAI,CAAS;IACb,UAAU,CAAS;IACnB,mBAAmB,CAAU;IAC7B,QAAQ,CAAY;IACpB,wFAAwF;IACxF,OAAO,CAAU;IACjB;;;;OAIG;IACM,QAAQ,CAAU;IAC3B;;;;OAIG;IACM,IAAI,CAAY;IACzB;;;;;OAKG;IACM,OAAO,CAAU;IAC1B;;;;;;;;;;OAUG;IACM,UAAU,CAAU;IAE7B,YACI,UAAkB,EAClB,IAAY,EACZ,UAAkB,EAClB,mBAA4B,EAC5B,QAAmB,EACnB,OAAgB,EAChB,WAAoB,KAAK,EACzB,IAAe,EACf,UAAmB,KAAK;IACxB,8DAA8D;IACrD,oBAAqD,EAAE;IAChE,8EAA8E;IACrE,kBAA2B;IACpC,yFAAyF;IAChF,eAAqC,MAAM;IACpD,+EAA+E;IACtE,SAAqC,EAC9C,aAAsB,KAAK;QAPlB,sBAAiB,GAAjB,iBAAiB,CAAsC;QAEvD,uBAAkB,GAAlB,kBAAkB,CAAS;QAE3B,iBAAY,GAAZ,YAAY,CAA+B;QAE3C,cAAS,GAAT,SAAS,CAA4B;QAG9C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,mBAAmB,GAAG,mBAAmB,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;CACJ;AA3ED,sCA2EC","sourcesContent":["import { MaskSpec } from './LogFieldMask';\nimport { AuthMeta } from './auth-mode';\nimport { EndpointResponseType, HttpParameterBinding } from './HttpContract';\nimport { StreamingEndpointMetadata } from './StreamingContract';\n\n/**\n * Route metadata stored per-method at runtime.\n * Used internally by http-routing and http-client as the runtime representation\n * of a route. Constructed from @ApiPath + @Endpoint metadata by ProxyClient\n * and ApiRoutingFactory.\n *\n * Lives in its own file (one class per file) purely for file size, exactly as `api-kind.ts` and\n * `external-caller.ts` were split off `decorators.ts` before it. Nothing about its role changed.\n */\nexport class RouteMetadata {\n    httpMethod: string;\n    path: string;\n    methodName: string;\n    controllerClassName?: string;\n    authMeta?: AuthMeta;\n    /** The API contract class name (e.g. 'SaveApi') — distinct from the controller name. */\n    apiName?: string;\n    /**\n     * True when @Endpoint(..., { formPost: true }): the body is application/x-www-form-urlencoded\n     * (flat key→value), not JSON. Rides the route metadata so the per-route body parse can branch\n     * without knowing the apiClass/methodName. Default false = JSON.\n     */\n    readonly formPost: boolean;\n    /**\n     * The @MaskLog field-mask spec for this route, or undefined when the method declared none. Read\n     * ONCE here at route-build time and handed to {@link LogApiCallImpl} via ApiMethodInfo, so the per-call\n     * log path pays for masking only on routes that opted in (the rest stay on plain JSON.stringify).\n     */\n    readonly mask?: MaskSpec;\n    /**\n     * True when @Endpoint(..., { rawBody: true }): the transport must retain the verbatim bytes +\n     * absolute url for the `@WpAuthWebhook` hook to verify a vendor signature over. Rides the route\n     * metadata for the same reason {@link formPost} does — the transport adapter decides how to read\n     * the body from the ROUTE, without knowing the apiClass/methodName.\n     */\n    readonly rawBody: boolean;\n    /**\n     * True when @Endpoint(..., { background: true }): this route is plumbing the user did not ask\n     * for (a log shipper, a heartbeat, a telemetry flush). Rides the route metadata for the same\n     * reason {@link formPost} and {@link rawBody} do — each consumer branches on the ROUTE, without\n     * knowing the apiClass/methodName.\n     *\n     * Read by {@link LogApiCallImpl} (via ApiMethodInfo, exactly as {@link mask} is) so no\n     * `[API-*-req]`/`[API-*-resp-*]` line is emitted for the call, and readable from an app's\n     * `RequestLifecycleListener.onRequestStart/onRequestEnd` so a progress bar and any app-level RPC\n     * instrumentation can skip it too. Default false = an ordinary, fully-logged route.\n     */\n    readonly background: boolean;\n\n    constructor(\n        httpMethod: string,\n        path: string,\n        methodName: string,\n        controllerClassName?: string,\n        authMeta?: AuthMeta,\n        apiName?: string,\n        formPost: boolean = false,\n        mask?: MaskSpec,\n        rawBody: boolean = false,\n        /** Explicit path/query mappings, in API declaration order. */\n        readonly parameterBindings: readonly HttpParameterBinding[] = [],\n        /** The sole unannotated POST parameter, or undefined for a bodyless route. */\n        readonly bodyParameterIndex?: number,\n        /** Whether clients receive only the body or the complete status/header/body response. */\n        readonly responseType: EndpointResponseType = 'body',\n        /** Present only for `(ResponseStream) => Promise<RequestStream>` contracts. */\n        readonly streaming?: StreamingEndpointMetadata,\n        background: boolean = false,\n    ) {\n        this.httpMethod = httpMethod;\n        this.path = path;\n        this.methodName = methodName;\n        this.controllerClassName = controllerClassName;\n        this.authMeta = authMeta;\n        this.apiName = apiName;\n        this.formPost = formPost;\n        this.mask = mask;\n        this.rawBody = rawBody;\n        this.parameterBindings = parameterBindings;\n        this.bodyParameterIndex = bodyParameterIndex;\n        this.responseType = responseType;\n        this.streaming = streaming;\n        this.background = background;\n    }\n}\n"]}

package/src/http/RouteMetadataFactory.js

@@ -32,7 +32,7 @@ class RouteMetadataFactory {
         const bindings = declarations
             .map((declaration) => new HttpContract_1.HttpParameterBinding(declaration.index, declaration.source, declaration.wireName, this.valueType(parameterTypes[declaration.index])))
             .sort((a, b) => a.index - b.index);
-        return new RouteMetadata_1.RouteMetadata(httpMethod, fullPath, methodName, controllerClassName, (0, decorators_1.getAuthMeta)(apiClass, methodName), apiClass.name || 'UnknownApi', options.formPost === true, (0, decorators_1.getMaskSpec)(apiClass, methodName), options.rawBody === true, bindings, bodyParameterIndex, this.responseType(options.responseType, apiClass, methodName), streaming);
+        return new RouteMetadata_1.RouteMetadata(httpMethod, fullPath, methodName, controllerClassName, (0, decorators_1.getAuthMeta)(apiClass, methodName), apiClass.name || 'UnknownApi', options.formPost === true, (0, decorators_1.getMaskSpec)(apiClass, methodName), options.rawBody === true, bindings, bodyParameterIndex, this.responseType(options.responseType, apiClass, methodName), streaming, options.background === true);
     }
     // webpieces-disable no-function-outside-class -- private pure helper keeps the existing static metadata factory below the method-size limit
     static validateEndpointOptions(apiClass, methodName, httpMethod, formPost, rawBody) {

package/src/http/RouteMetadataFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteMetadataFactory.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadataFactory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    getApiPath,\n    getAuthMeta,\n    getEndpointOptions,\n    getEndpoints,\n    getMaskSpec,\n} from './decorators';\nimport { getHttpParameterDeclarations } from './http-parameter-decorators';\nimport {\n    ContractHttpMethod,\n    EndpointResponseType,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n    HttpParameterValueType,\n} from './HttpContract';\nimport { RouteMetadata } from './RouteMetadata';\nimport { getStreamingEndpoint } from './StreamingContract';\n\n/**\n * Build the one runtime route model consumed by incoming routing, in-process clients, and both\n * generated HTTP clients. Keeping this join/validation here prevents four subtly different\n * interpretations of the same decorators.\n */\nexport class RouteMetadataFactory {\n    // webpieces-disable no-function-outside-class -- deterministic decorator metadata factory shared by DI-free browser and server runtimes\n    static create(\n        apiClass: Function,\n        methodName: string,\n        controllerClassName?: string,\n    ): RouteMetadata {\n        const endpoints = getEndpoints(apiClass) ?? {};\n        const endpointPath = endpoints[methodName];\n        if (endpointPath === undefined) {\n            throw new Error(\n                `No @Endpoint metadata for ${apiClass.name || 'Unknown'}.${methodName}.`,\n            );\n        }\n        const fullPath = this.joinPath(getApiPath(apiClass) ?? '', endpointPath);\n        const options = getEndpointOptions(apiClass, methodName);\n        const streaming = getStreamingEndpoint(apiClass, methodName);\n        const httpMethod = this.httpMethod(options.httpMethod, apiClass, methodName);\n        this.validateEndpointOptions(\n            apiClass,\n            methodName,\n            httpMethod,\n            options.formPost,\n            options.rawBody,\n        );\n        const parameterTypes = this.parameterTypes(apiClass, methodName);\n        const declarations = getHttpParameterDeclarations(apiClass, methodName);\n        const bodyParameterIndex = streaming\n            ? this.validateStreamingParameters(\n                  apiClass,\n                  methodName,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              )\n            : this.validateParameters(\n                  apiClass,\n                  methodName,\n                  fullPath,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              );\n        const bindings = declarations\n            .map(\n                (declaration: HttpParameterDeclaration) =>\n                    new HttpParameterBinding(\n                        declaration.index,\n                        declaration.source,\n                        declaration.wireName,\n                        this.valueType(parameterTypes[declaration.index]),\n                    ),\n            )\n            .sort((a: HttpParameterBinding, b: HttpParameterBinding) => a.index - b.index);\n\n        return new RouteMetadata(\n            httpMethod,\n            fullPath,\n            methodName,\n            controllerClassName,\n            getAuthMeta(apiClass, methodName),\n            apiClass.name || 'UnknownApi',\n            options.formPost === true,\n            getMaskSpec(apiClass, methodName),\n            options.rawBody === true,\n            bindings,\n            bodyParameterIndex,\n            this.responseType(options.responseType, apiClass, methodName),\n            streaming,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper keeps the existing static metadata factory below the method-size limit\n    private static validateEndpointOptions(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        formPost?: boolean,\n        rawBody?: boolean,\n    ): void {\n        if (httpMethod === 'GET' && formPost === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare formPost:true because GET has no request body.`,\n            );\n        }\n        if (httpMethod === 'GET' && rawBody === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare rawBody:true because GET has no request body.`,\n            );\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure validator alongside existing contract validators\n    private static validateStreamingParameters(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        if (httpMethod !== 'POST') throw new Error(`${label} is streaming and must use POST.`);\n        if (declarations.length > 0)\n            throw new Error(`${label} is streaming and cannot declare path/query parameters.`);\n        if (parameterTypes.length !== 1)\n            throw new Error(`${label} must take exactly one ResponseStream parameter.`);\n        return undefined;\n    }\n\n    /**\n     * Refuse a contract in which two endpoints resolve to the same HTTP method + path.\n     *\n     * Empty paths are LEGAL (`@ApiPath('')` + `@Endpoint('', ...)` is how a contract says \"the whole\n     * destination arrives per call\"), so the thing actually worth rejecting is ambiguity: two methods\n     * that land on one route. On the server the second registration would silently shadow the first\n     * in the route map, and on the client both would dial the same URL — neither is ever what the\n     * author meant. Placeholder NAMES are ignored when comparing (`/a/{id}` and `/a/{key}` are the\n     * same route to a router), `''` and `'/'` compare equal (the server serves an empty path at the\n     * root), and the error names BOTH methods so the fix is obvious.\n     *\n     * Called by every transport that binds a whole contract (the generated clients and the server's\n     * route registration), so a duplicate dies at startup however the contract is consumed.\n     *\n     * @throws Error naming both colliding methods and the shared route.\n     */\n    // webpieces-disable no-function-outside-class -- deterministic contract validation shared by DI-free browser and server runtimes\n    static assertNoDuplicateRoutes(apiClass: Function): void {\n        const label = apiClass.name || 'Unknown';\n        const seen = new Map<string, string>();\n        for (const methodName of Object.keys(getEndpoints(apiClass) ?? {})) {\n            const route = this.create(apiClass, methodName);\n            // '' and '/' are one route to a server (every request path starts with '/').\n            const shape = (route.path === '' ? '/' : route.path).replace(/\\{[^{}]+\\}/g, '{}');\n            const key = `${route.httpMethod} ${shape}`;\n            const previous = seen.get(key);\n            if (previous !== undefined) {\n                throw new Error(\n                    `${label}.${previous} and ${label}.${methodName} both resolve to ` +\n                        `${route.httpMethod} '${route.path}'. Two endpoints of one contract cannot share ` +\n                        `an HTTP method + path; give one of them a distinct @Endpoint path or HTTP method.`,\n                );\n            }\n            seen.set(key, methodName);\n        }\n    }\n\n    /**\n     * Join `@ApiPath` and `@Endpoint` into the route path.\n     *\n     * Both empty joins to `''`, NOT `'/'`. A contract declaring `@ApiPath('')` + `@Endpoint('', ...)`\n     * is saying \"this route adds nothing to the base URL\", and a client whose base URL is a full\n     * destination (host + path + query) must send it byte for byte. Before #926 the client joined with\n     * plain concatenation (`'' + ''`), and forcing a `/` here broke exactly that (#944).\n     */\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static joinPath(basePath: string, endpointPath: string): string {\n        if (basePath === '' && endpointPath === '') return '';\n        const joined = `${basePath}/${endpointPath}`.replace(/\\/{2,}/g, '/');\n        return joined.startsWith('/') ? joined : `/${joined}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static httpMethod(\n        value: ContractHttpMethod | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): ContractHttpMethod {\n        const method = value ?? 'POST';\n        if (method === 'GET' || method === 'POST') return method;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported httpMethod '${String(method)}'; use GET or POST.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static responseType(\n        value: EndpointResponseType | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): EndpointResponseType {\n        const responseType = value ?? 'body';\n        if (responseType === 'body' || responseType === 'full') return responseType;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported responseType '${String(responseType)}'; use body or full.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- Reflect metadata lookup has no injectable dependency\n    private static parameterTypes(apiClass: Function, methodName: string): Function[] {\n        return Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName) ?? [];\n    }\n\n    // webpieces-disable no-function-outside-class -- private deterministic contract validation helper\n    private static validateParameters(\n        apiClass: Function,\n        methodName: string,\n        fullPath: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): number | undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        const placeholders = [...fullPath.matchAll(/\\{([^{}]+)\\}/g)].map(\n            (match: RegExpMatchArray) => match[1],\n        );\n        const pathNames = declarations\n            .filter((declaration: HttpParameterDeclaration) => declaration.source === 'path')\n            .map((declaration: HttpParameterDeclaration) => declaration.wireName);\n        for (const placeholder of new Set(placeholders)) {\n            if (!pathNames.includes(placeholder)) {\n                throw new Error(\n                    `${label} path '${fullPath}' contains {${placeholder}} but no @PathParam('${placeholder}') parameter.`,\n                );\n            }\n        }\n        for (const pathName of pathNames) {\n            if (!placeholders.includes(pathName)) {\n                throw new Error(\n                    `${label} declares @PathParam('${pathName}') but '${fullPath}' has no {${pathName}} placeholder.`,\n                );\n            }\n        }\n\n        const seenWire = new Set<string>();\n        const mappedIndexes = new Set<number>();\n        for (const declaration of declarations) {\n            const wireKey = `${declaration.source}:${declaration.wireName}`;\n            if (seenWire.has(wireKey)) {\n                throw new Error(`${label} maps '${wireKey}' more than once.`);\n            }\n            seenWire.add(wireKey);\n            mappedIndexes.add(declaration.index);\n        }\n\n        const declaredCount = Math.max(\n            parameterTypes.length,\n            declarations.reduce(\n                (highest: number, declaration: HttpParameterDeclaration) =>\n                    Math.max(highest, declaration.index + 1),\n                0,\n            ),\n        );\n        const unbound: number[] = [];\n        for (let index = 0; index < declaredCount; index++) {\n            if (!mappedIndexes.has(index)) unbound.push(index);\n        }\n        if (httpMethod === 'GET' && unbound.length > 0) {\n            throw new Error(\n                `${label} is GET, so every parameter must use @PathParam(...) or @QueryParam(...); argument ${unbound[0]} is unmapped.`,\n            );\n        }\n        if (unbound.length > 1) {\n            throw new Error(\n                `${label} has ${unbound.length} unmapped parameters. POST permits exactly one unannotated request body; map every other parameter explicitly.`,\n            );\n        }\n        return unbound[0];\n    }\n\n    // webpieces-disable no-function-outside-class -- private conversion of reflected constructors to wire types\n    private static valueType(type: Function | undefined): HttpParameterValueType {\n        if (type === String) return 'string';\n        if (type === Number) return 'number';\n        if (type === Boolean) return 'boolean';\n        if (type === Array) return 'array';\n        return 'unknown';\n    }\n}\n"]}
+{"version":3,"file":"RouteMetadataFactory.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/RouteMetadataFactory.ts"],"names":[],"mappings":";;;AAAA,6CAMsB;AACtB,2EAA2E;AAC3E,iDAMwB;AACxB,mDAAgD;AAChD,2DAA2D;AAE3D;;;;GAIG;AACH,MAAa,oBAAoB;IAC7B,wIAAwI;IACxI,MAAM,CAAC,MAAM,CACT,QAAkB,EAClB,UAAkB,EAClB,mBAA4B;QAE5B,MAAM,SAAS,GAAG,IAAA,yBAAY,EAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,YAAY,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACX,6BAA6B,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,GAAG,CAC3E,CAAC;QACN,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAA,uBAAU,EAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC;QACzE,MAAM,OAAO,GAAG,IAAA,+BAAkB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,IAAA,wCAAoB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7E,IAAI,CAAC,uBAAuB,CACxB,QAAQ,EACR,UAAU,EACV,UAAU,EACV,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,OAAO,CAClB,CAAC;QACF,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACjE,MAAM,YAAY,GAAG,IAAA,wDAA4B,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACxE,MAAM,kBAAkB,GAAG,SAAS;YAChC,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAC5B,QAAQ,EACR,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,CACf;YACH,CAAC,CAAC,IAAI,CAAC,kBAAkB,CACnB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,cAAc,EACd,YAAY,CACf,CAAC;QACR,MAAM,QAAQ,GAAG,YAAY;aACxB,GAAG,CACA,CAAC,WAAqC,EAAE,EAAE,CACtC,IAAI,mCAAoB,CACpB,WAAW,CAAC,KAAK,EACjB,WAAW,CAAC,MAAM,EAClB,WAAW,CAAC,QAAQ,EACpB,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CACpD,CACR;aACA,IAAI,CAAC,CAAC,CAAuB,EAAE,CAAuB,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAEnF,OAAO,IAAI,6BAAa,CACpB,UAAU,EACV,QAAQ,EACR,UAAU,EACV,mBAAmB,EACnB,IAAA,wBAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EACjC,QAAQ,CAAC,IAAI,IAAI,YAAY,EAC7B,OAAO,CAAC,QAAQ,KAAK,IAAI,EACzB,IAAA,wBAAW,EAAC,QAAQ,EAAE,UAAU,CAAC,EACjC,OAAO,CAAC,OAAO,KAAK,IAAI,EACxB,QAAQ,EACR,kBAAkB,EAClB,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,EAAE,UAAU,CAAC,EAC7D,SAAS,EACT,OAAO,CAAC,UAAU,KAAK,IAAI,CAC9B,CAAC;IACN,CAAC;IAED,4IAA4I;IACpI,MAAM,CAAC,uBAAuB,CAClC,QAAkB,EAClB,UAAkB,EAClB,UAA8B,EAC9B,QAAkB,EAClB,OAAiB;QAEjB,IAAI,UAAU,KAAK,KAAK,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,2EAA2E,CAC5G,CAAC;QACN,CAAC;QACD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,0EAA0E,CAC3G,CAAC;QACN,CAAC;IACL,CAAC;IAED,+GAA+G;IACvG,MAAM,CAAC,2BAA2B,CACtC,QAAkB,EAClB,UAAkB,EAClB,UAA8B,EAC9B,cAAmC,EACnC,YAAiD;QAEjD,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5D,IAAI,UAAU,KAAK,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAC;QACvF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,yDAAyD,CAAC,CAAC;QACvF,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,kDAAkD,CAAC,CAAC;QAChF,OAAO,SAAS,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,iIAAiI;IACjI,MAAM,CAAC,uBAAuB,CAAC,QAAkB;QAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;QACvC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,IAAA,yBAAY,EAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACjE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YAChD,6EAA6E;YAC7E,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;YAClF,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,EAAE,CAAC;YAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,IAAI,QAAQ,QAAQ,KAAK,IAAI,UAAU,mBAAmB;oBAC9D,GAAG,KAAK,CAAC,UAAU,KAAK,KAAK,CAAC,IAAI,gDAAgD;oBAClF,mFAAmF,CAC1F,CAAC;YACN,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,qGAAqG;IAC7F,MAAM,CAAC,QAAQ,CAAC,QAAgB,EAAE,YAAoB;QAC1D,IAAI,QAAQ,KAAK,EAAE,IAAI,YAAY,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QACtD,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,YAAY,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACrE,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,UAAU,CACrB,KAAqC,EACrC,QAAkB,EAClB,UAAkB;QAElB,MAAM,MAAM,GAAG,KAAK,IAAI,MAAM,CAAC;QAC/B,IAAI,MAAM,KAAK,KAAK,IAAI,MAAM,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QACzD,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,qCAAqC,MAAM,CAAC,MAAM,CAAC,qBAAqB,CACzG,CAAC;IACN,CAAC;IAED,qGAAqG;IAC7F,MAAM,CAAC,YAAY,CACvB,KAAuC,EACvC,QAAkB,EAClB,UAAkB;QAElB,MAAM,YAAY,GAAG,KAAK,IAAI,MAAM,CAAC;QACrC,IAAI,YAAY,KAAK,MAAM,IAAI,YAAY,KAAK,MAAM;YAAE,OAAO,YAAY,CAAC;QAC5E,MAAM,IAAI,KAAK,CACX,GAAG,QAAQ,CAAC,IAAI,IAAI,UAAU,uCAAuC,MAAM,CAAC,YAAY,CAAC,sBAAsB,CAClH,CAAC;IACN,CAAC;IAED,sGAAsG;IAC9F,MAAM,CAAC,cAAc,CAAC,QAAkB,EAAE,UAAkB;QAChE,OAAO,OAAO,CAAC,WAAW,CAAC,mBAAmB,EAAE,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;IAC1F,CAAC;IAED,kGAAkG;IAC1F,MAAM,CAAC,kBAAkB,CAC7B,QAAkB,EAClB,UAAkB,EAClB,QAAgB,EAChB,UAA8B,EAC9B,cAAmC,EACnC,YAAiD;QAEjD,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5D,MAAM,YAAY,GAAG,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,CAC5D,CAAC,KAAuB,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CACxC,CAAC;QACF,MAAM,SAAS,GAAG,YAAY;aACzB,MAAM,CAAC,CAAC,WAAqC,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,KAAK,MAAM,CAAC;aAChF,GAAG,CAAC,CAAC,WAAqC,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC1E,KAAK,MAAM,WAAW,IAAI,IAAI,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,UAAU,QAAQ,eAAe,WAAW,wBAAwB,WAAW,eAAe,CACzG,CAAC;YACN,CAAC;QACL,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,yBAAyB,QAAQ,WAAW,QAAQ,aAAa,QAAQ,gBAAgB,CACpG,CAAC;YACN,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;QACxC,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACrC,MAAM,OAAO,GAAG,GAAG,WAAW,CAAC,MAAM,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YAChE,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,UAAU,OAAO,mBAAmB,CAAC,CAAC;YAClE,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtB,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QAED,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAC1B,cAAc,CAAC,MAAM,EACrB,YAAY,CAAC,MAAM,CACf,CAAC,OAAe,EAAE,WAAqC,EAAE,EAAE,CACvD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,KAAK,GAAG,CAAC,CAAC,EAC5C,CAAC,CACJ,CACJ,CAAC;QACF,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC;YACjD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,sFAAsF,OAAO,CAAC,CAAC,CAAC,eAAe,CAC1H,CAAC;QACN,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACX,GAAG,KAAK,QAAQ,OAAO,CAAC,MAAM,gHAAgH,CACjJ,CAAC;QACN,CAAC;QACD,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IAED,4GAA4G;IACpG,MAAM,CAAC,SAAS,CAAC,IAA0B;QAC/C,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACrC,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,QAAQ,CAAC;QACrC,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,SAAS,CAAC;QACvC,IAAI,IAAI,KAAK,KAAK;YAAE,OAAO,OAAO,CAAC;QACnC,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ;AA5QD,oDA4QC","sourcesContent":["import {\n    getApiPath,\n    getAuthMeta,\n    getEndpointOptions,\n    getEndpoints,\n    getMaskSpec,\n} from './decorators';\nimport { getHttpParameterDeclarations } from './http-parameter-decorators';\nimport {\n    ContractHttpMethod,\n    EndpointResponseType,\n    HttpParameterBinding,\n    HttpParameterDeclaration,\n    HttpParameterValueType,\n} from './HttpContract';\nimport { RouteMetadata } from './RouteMetadata';\nimport { getStreamingEndpoint } from './StreamingContract';\n\n/**\n * Build the one runtime route model consumed by incoming routing, in-process clients, and both\n * generated HTTP clients. Keeping this join/validation here prevents four subtly different\n * interpretations of the same decorators.\n */\nexport class RouteMetadataFactory {\n    // webpieces-disable no-function-outside-class -- deterministic decorator metadata factory shared by DI-free browser and server runtimes\n    static create(\n        apiClass: Function,\n        methodName: string,\n        controllerClassName?: string,\n    ): RouteMetadata {\n        const endpoints = getEndpoints(apiClass) ?? {};\n        const endpointPath = endpoints[methodName];\n        if (endpointPath === undefined) {\n            throw new Error(\n                `No @Endpoint metadata for ${apiClass.name || 'Unknown'}.${methodName}.`,\n            );\n        }\n        const fullPath = this.joinPath(getApiPath(apiClass) ?? '', endpointPath);\n        const options = getEndpointOptions(apiClass, methodName);\n        const streaming = getStreamingEndpoint(apiClass, methodName);\n        const httpMethod = this.httpMethod(options.httpMethod, apiClass, methodName);\n        this.validateEndpointOptions(\n            apiClass,\n            methodName,\n            httpMethod,\n            options.formPost,\n            options.rawBody,\n        );\n        const parameterTypes = this.parameterTypes(apiClass, methodName);\n        const declarations = getHttpParameterDeclarations(apiClass, methodName);\n        const bodyParameterIndex = streaming\n            ? this.validateStreamingParameters(\n                  apiClass,\n                  methodName,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              )\n            : this.validateParameters(\n                  apiClass,\n                  methodName,\n                  fullPath,\n                  httpMethod,\n                  parameterTypes,\n                  declarations,\n              );\n        const bindings = declarations\n            .map(\n                (declaration: HttpParameterDeclaration) =>\n                    new HttpParameterBinding(\n                        declaration.index,\n                        declaration.source,\n                        declaration.wireName,\n                        this.valueType(parameterTypes[declaration.index]),\n                    ),\n            )\n            .sort((a: HttpParameterBinding, b: HttpParameterBinding) => a.index - b.index);\n\n        return new RouteMetadata(\n            httpMethod,\n            fullPath,\n            methodName,\n            controllerClassName,\n            getAuthMeta(apiClass, methodName),\n            apiClass.name || 'UnknownApi',\n            options.formPost === true,\n            getMaskSpec(apiClass, methodName),\n            options.rawBody === true,\n            bindings,\n            bodyParameterIndex,\n            this.responseType(options.responseType, apiClass, methodName),\n            streaming,\n            options.background === true,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper keeps the existing static metadata factory below the method-size limit\n    private static validateEndpointOptions(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        formPost?: boolean,\n        rawBody?: boolean,\n    ): void {\n        if (httpMethod === 'GET' && formPost === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare formPost:true because GET has no request body.`,\n            );\n        }\n        if (httpMethod === 'GET' && rawBody === true) {\n            throw new Error(\n                `${apiClass.name}.${methodName} is GET and cannot declare rawBody:true because GET has no request body.`,\n            );\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure validator alongside existing contract validators\n    private static validateStreamingParameters(\n        apiClass: Function,\n        methodName: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        if (httpMethod !== 'POST') throw new Error(`${label} is streaming and must use POST.`);\n        if (declarations.length > 0)\n            throw new Error(`${label} is streaming and cannot declare path/query parameters.`);\n        if (parameterTypes.length !== 1)\n            throw new Error(`${label} must take exactly one ResponseStream parameter.`);\n        return undefined;\n    }\n\n    /**\n     * Refuse a contract in which two endpoints resolve to the same HTTP method + path.\n     *\n     * Empty paths are LEGAL (`@ApiPath('')` + `@Endpoint('', ...)` is how a contract says \"the whole\n     * destination arrives per call\"), so the thing actually worth rejecting is ambiguity: two methods\n     * that land on one route. On the server the second registration would silently shadow the first\n     * in the route map, and on the client both would dial the same URL — neither is ever what the\n     * author meant. Placeholder NAMES are ignored when comparing (`/a/{id}` and `/a/{key}` are the\n     * same route to a router), `''` and `'/'` compare equal (the server serves an empty path at the\n     * root), and the error names BOTH methods so the fix is obvious.\n     *\n     * Called by every transport that binds a whole contract (the generated clients and the server's\n     * route registration), so a duplicate dies at startup however the contract is consumed.\n     *\n     * @throws Error naming both colliding methods and the shared route.\n     */\n    // webpieces-disable no-function-outside-class -- deterministic contract validation shared by DI-free browser and server runtimes\n    static assertNoDuplicateRoutes(apiClass: Function): void {\n        const label = apiClass.name || 'Unknown';\n        const seen = new Map<string, string>();\n        for (const methodName of Object.keys(getEndpoints(apiClass) ?? {})) {\n            const route = this.create(apiClass, methodName);\n            // '' and '/' are one route to a server (every request path starts with '/').\n            const shape = (route.path === '' ? '/' : route.path).replace(/\\{[^{}]+\\}/g, '{}');\n            const key = `${route.httpMethod} ${shape}`;\n            const previous = seen.get(key);\n            if (previous !== undefined) {\n                throw new Error(\n                    `${label}.${previous} and ${label}.${methodName} both resolve to ` +\n                        `${route.httpMethod} '${route.path}'. Two endpoints of one contract cannot share ` +\n                        `an HTTP method + path; give one of them a distinct @Endpoint path or HTTP method.`,\n                );\n            }\n            seen.set(key, methodName);\n        }\n    }\n\n    /**\n     * Join `@ApiPath` and `@Endpoint` into the route path.\n     *\n     * Both empty joins to `''`, NOT `'/'`. A contract declaring `@ApiPath('')` + `@Endpoint('', ...)`\n     * is saying \"this route adds nothing to the base URL\", and a client whose base URL is a full\n     * destination (host + path + query) must send it byte for byte. Before #926 the client joined with\n     * plain concatenation (`'' + ''`), and forcing a `/` here broke exactly that (#944).\n     */\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static joinPath(basePath: string, endpointPath: string): string {\n        if (basePath === '' && endpointPath === '') return '';\n        const joined = `${basePath}/${endpointPath}`.replace(/\\/{2,}/g, '/');\n        return joined.startsWith('/') ? joined : `/${joined}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static httpMethod(\n        value: ContractHttpMethod | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): ContractHttpMethod {\n        const method = value ?? 'POST';\n        if (method === 'GET' || method === 'POST') return method;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported httpMethod '${String(method)}'; use GET or POST.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- private pure helper for the static metadata factory\n    private static responseType(\n        value: EndpointResponseType | undefined,\n        apiClass: Function,\n        methodName: string,\n    ): EndpointResponseType {\n        const responseType = value ?? 'body';\n        if (responseType === 'body' || responseType === 'full') return responseType;\n        throw new Error(\n            `${apiClass.name}.${methodName} declares unsupported responseType '${String(responseType)}'; use body or full.`,\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- Reflect metadata lookup has no injectable dependency\n    private static parameterTypes(apiClass: Function, methodName: string): Function[] {\n        return Reflect.getMetadata('design:paramtypes', apiClass.prototype, methodName) ?? [];\n    }\n\n    // webpieces-disable no-function-outside-class -- private deterministic contract validation helper\n    private static validateParameters(\n        apiClass: Function,\n        methodName: string,\n        fullPath: string,\n        httpMethod: ContractHttpMethod,\n        parameterTypes: readonly Function[],\n        declarations: readonly HttpParameterDeclaration[],\n    ): number | undefined {\n        const label = `${apiClass.name || 'Unknown'}.${methodName}`;\n        const placeholders = [...fullPath.matchAll(/\\{([^{}]+)\\}/g)].map(\n            (match: RegExpMatchArray) => match[1],\n        );\n        const pathNames = declarations\n            .filter((declaration: HttpParameterDeclaration) => declaration.source === 'path')\n            .map((declaration: HttpParameterDeclaration) => declaration.wireName);\n        for (const placeholder of new Set(placeholders)) {\n            if (!pathNames.includes(placeholder)) {\n                throw new Error(\n                    `${label} path '${fullPath}' contains {${placeholder}} but no @PathParam('${placeholder}') parameter.`,\n                );\n            }\n        }\n        for (const pathName of pathNames) {\n            if (!placeholders.includes(pathName)) {\n                throw new Error(\n                    `${label} declares @PathParam('${pathName}') but '${fullPath}' has no {${pathName}} placeholder.`,\n                );\n            }\n        }\n\n        const seenWire = new Set<string>();\n        const mappedIndexes = new Set<number>();\n        for (const declaration of declarations) {\n            const wireKey = `${declaration.source}:${declaration.wireName}`;\n            if (seenWire.has(wireKey)) {\n                throw new Error(`${label} maps '${wireKey}' more than once.`);\n            }\n            seenWire.add(wireKey);\n            mappedIndexes.add(declaration.index);\n        }\n\n        const declaredCount = Math.max(\n            parameterTypes.length,\n            declarations.reduce(\n                (highest: number, declaration: HttpParameterDeclaration) =>\n                    Math.max(highest, declaration.index + 1),\n                0,\n            ),\n        );\n        const unbound: number[] = [];\n        for (let index = 0; index < declaredCount; index++) {\n            if (!mappedIndexes.has(index)) unbound.push(index);\n        }\n        if (httpMethod === 'GET' && unbound.length > 0) {\n            throw new Error(\n                `${label} is GET, so every parameter must use @PathParam(...) or @QueryParam(...); argument ${unbound[0]} is unmapped.`,\n            );\n        }\n        if (unbound.length > 1) {\n            throw new Error(\n                `${label} has ${unbound.length} unmapped parameters. POST permits exactly one unannotated request body; map every other parameter explicitly.`,\n            );\n        }\n        return unbound[0];\n    }\n\n    // webpieces-disable no-function-outside-class -- private conversion of reflected constructors to wire types\n    private static valueType(type: Function | undefined): HttpParameterValueType {\n        if (type === String) return 'string';\n        if (type === Number) return 'number';\n        if (type === Boolean) return 'boolean';\n        if (type === Array) return 'array';\n        return 'unknown';\n    }\n}\n"]}