@webpieces/cloudtasks-client 0.3.372 → 0.3.374

package/README.md

@@ -21,10 +21,11 @@ await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName: req.id
 
 - `ClientCloudTasksFactory.createPubSubClient(Api, TaskClientConfig)` — builds the enqueue proxy. It
   injects a `Provider<TaskProxyClient>` and calls `get()` per contract; `TaskProxyClient` is bound
-  TRANSIENT, so each client gets its own. The delivery URL is resolved at enqueue time from
-  `svcName` (same project + region as this container, so you maintain no URL table) unless you pass
-  an explicit `targetUrl`. `getCloudRunUrl` also honours a `CLOUD_RUN_URL_<UPPER_SNAKE_NAME>` env
-  override for local multi-service runs and integration tests
+  TRANSIENT, so each client gets its own. The delivery URL is resolved at enqueue time from `svcName`
+  via `resolveServiceUrl`: a `ClientRegistry` override wins, else on GCP it is derived from the Cloud
+  Run service name (same project + region, so you maintain no URL table), else (off-GCP, unregistered)
+  it throws. Register non-derivable URLs (localhost, cross-region, non-Cloud-Run) once at startup with
+  `ClientRegistry.addMapping(svcName, port)` / `addUrlMapping(svcName, url)`
 - An enqueue outside `RequestContext.run(...)` **throws**: a task with no caller trace is a bug
 - `CloudTaskScheduler` — `addToQueue` / `schedule` / `cancelJob`; carries scheduling
   options out-of-band so the contract signature stays identical on both sides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/cloudtasks-client",
-  "version": "0.3.372",
+  "version": "0.3.374",
   "description": "Cloud Tasks enqueue client generated from a shared @PubSub API contract (twin of http-client)",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -23,9 +23,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-context": "0.3.372",
-    "@webpieces/core-util": "0.3.372",
-    "@webpieces/gcp-identity": "0.3.372",
+    "@webpieces/core-context": "0.3.374",
+    "@webpieces/core-util": "0.3.374",
+    "@webpieces/gcp-identity": "0.3.374",
     "@google-cloud/tasks": "5.5.2",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"

package/src/TaskClientConfig.d.ts

@@ -7,46 +7,24 @@ export type ApiPrototype<T> = Function & {
  *
  * Collaborators (TaskInvoker, RequestContextHeaders) are NOT config: they are dependencies of
  * {@link ClientCloudTasksFactory} and shared by every client it builds. This is the fire-and-forget
- * twin of http-client-node's ClientConfig, and takes the same two fields.
+ * twin of http-client-node's ClientConfig, and takes the same single field.
  */
 export declare class TaskClientConfig {
     /**
-     * TYPICALLY the GCP Cloud Run service name — and it MUST be the Cloud Run service name
-     * when you do not supply a `targetUrl`, because we derive the URL from it.
-     *
-     * We lookup your service in the same project, same region, and form the url from the
-     * container information unless you pass in a targetUrl, so you do not have to maintain
-     * targetUrls. This works across your demo, qa, prod environments as long as each
-     * environment is in its own projectId, which is typical.
-     *
-     * When you DO supply a `targetUrl`, svcName is used only for logging, so any readable
-     * name works.
+     * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud
+     * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything
+     * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
+     * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.
      */
     readonly svcName: string;
-    /**
-     * Optional explicit base URL, for the cases lookup cannot describe: another region,
-     * another project, or a host that is not Cloud Run at all. It wins over `svcName`.
-     */
-    readonly targetUrl?: string | undefined;
     constructor(
     /**
-     * TYPICALLY the GCP Cloud Run service name — and it MUST be the Cloud Run service name
-     * when you do not supply a `targetUrl`, because we derive the URL from it.
-     *
-     * We lookup your service in the same project, same region, and form the url from the
-     * container information unless you pass in a targetUrl, so you do not have to maintain
-     * targetUrls. This works across your demo, qa, prod environments as long as each
-     * environment is in its own projectId, which is typical.
-     *
-     * When you DO supply a `targetUrl`, svcName is used only for logging, so any readable
-     * name works.
-     */
-    svcName: string, 
-    /**
-     * Optional explicit base URL, for the cases lookup cannot describe: another region,
-     * another project, or a host that is not Cloud Run at all. It wins over `svcName`.
+     * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud
+     * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything
+     * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
+     * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.
      */
-    targetUrl?: string | undefined);
+    svcName: string);
     /** Resolved per enqueue, not at construction — so building a client stays synchronous. */
-    resolveTargetUrl(): Promise<string>;
+    resolveUrl(): Promise<string>;
 }

package/src/TaskClientConfig.js

@@ -7,36 +7,23 @@ const gcp_identity_1 = require("@webpieces/gcp-identity");
  *
  * Collaborators (TaskInvoker, RequestContextHeaders) are NOT config: they are dependencies of
  * {@link ClientCloudTasksFactory} and shared by every client it builds. This is the fire-and-forget
- * twin of http-client-node's ClientConfig, and takes the same two fields.
+ * twin of http-client-node's ClientConfig, and takes the same single field.
  */
 class TaskClientConfig {
     svcName;
-    targetUrl;
     constructor(
     /**
-     * TYPICALLY the GCP Cloud Run service name — and it MUST be the Cloud Run service name
-     * when you do not supply a `targetUrl`, because we derive the URL from it.
-     *
-     * We lookup your service in the same project, same region, and form the url from the
-     * container information unless you pass in a targetUrl, so you do not have to maintain
-     * targetUrls. This works across your demo, qa, prod environments as long as each
-     * environment is in its own projectId, which is typical.
-     *
-     * When you DO supply a `targetUrl`, svcName is used only for logging, so any readable
-     * name works.
+     * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud
+     * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything
+     * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run
+     * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.
      */
-    svcName, 
-    /**
-     * Optional explicit base URL, for the cases lookup cannot describe: another region,
-     * another project, or a host that is not Cloud Run at all. It wins over `svcName`.
-     */
-    targetUrl) {
+    svcName) {
         this.svcName = svcName;
-        this.targetUrl = targetUrl;
     }
     /** Resolved per enqueue, not at construction — so building a client stays synchronous. */
-    resolveTargetUrl() {
-        return (0, gcp_identity_1.resolveTargetUrl)(this.svcName, this.targetUrl);
+    resolveUrl() {
+        return (0, gcp_identity_1.resolveServiceUrl)(this.svcName);
     }
 }
 exports.TaskClientConfig = TaskClientConfig;

package/src/TaskClientConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskClientConfig.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskClientConfig.ts"],"names":[],"mappings":";;;AAAA,0DAA2D;AAK3D;;;;;;GAMG;AACH,MAAa,gBAAgB;IAcL;IAMA;IAnBpB;IACI;;;;;;;;;;;OAWG;IACa,OAAe;IAE/B;;;OAGG;IACa,SAAkB;QANlB,YAAO,GAAP,OAAO,CAAQ;QAMf,cAAS,GAAT,SAAS,CAAS;IACnC,CAAC;IAEJ,0FAA0F;IAC1F,gBAAgB;QACZ,OAAO,IAAA,+BAAgB,EAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC;CACJ;AA3BD,4CA2BC","sourcesContent":["import { resolveTargetUrl } from '@webpieces/gcp-identity';\n\n/** Constructor whose prototype is T (the abstract @PubSub API class). */\nexport type ApiPrototype<T> = Function & { prototype: T };\n\n/**\n * Per-client STATE for a Cloud Tasks enqueue client — nothing else.\n *\n * Collaborators (TaskInvoker, RequestContextHeaders) are NOT config: they are dependencies of\n * {@link ClientCloudTasksFactory} and shared by every client it builds. This is the fire-and-forget\n * twin of http-client-node's ClientConfig, and takes the same two fields.\n */\nexport class TaskClientConfig {\n    constructor(\n        /**\n         * TYPICALLY the GCP Cloud Run service name — and it MUST be the Cloud Run service name\n         * when you do not supply a `targetUrl`, because we derive the URL from it.\n         *\n         * We lookup your service in the same project, same region, and form the url from the\n         * container information unless you pass in a targetUrl, so you do not have to maintain\n         * targetUrls. This works across your demo, qa, prod environments as long as each\n         * environment is in its own projectId, which is typical.\n         *\n         * When you DO supply a `targetUrl`, svcName is used only for logging, so any readable\n         * name works.\n         */\n        public readonly svcName: string,\n\n        /**\n         * Optional explicit base URL, for the cases lookup cannot describe: another region,\n         * another project, or a host that is not Cloud Run at all. It wins over `svcName`.\n         */\n        public readonly targetUrl?: string,\n    ) {}\n\n    /** Resolved per enqueue, not at construction — so building a client stays synchronous. */\n    resolveTargetUrl(): Promise<string> {\n        return resolveTargetUrl(this.svcName, this.targetUrl);\n    }\n}\n"]}
+{"version":3,"file":"TaskClientConfig.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskClientConfig.ts"],"names":[],"mappings":";;;AAAA,0DAA4D;AAK5D;;;;;;GAMG;AACH,MAAa,gBAAgB;IAQL;IAPpB;IACI;;;;;OAKG;IACa,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAChC,CAAC;IAEJ,0FAA0F;IAC1F,UAAU;QACN,OAAO,IAAA,gCAAiB,EAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;CACJ;AAfD,4CAeC","sourcesContent":["import { resolveServiceUrl } from '@webpieces/gcp-identity';\n\n/** Constructor whose prototype is T (the abstract @PubSub API class). */\nexport type ApiPrototype<T> = Function & { prototype: T };\n\n/**\n * Per-client STATE for a Cloud Tasks enqueue client — nothing else.\n *\n * Collaborators (TaskInvoker, RequestContextHeaders) are NOT config: they are dependencies of\n * {@link ClientCloudTasksFactory} and shared by every client it builds. This is the fire-and-forget\n * twin of http-client-node's ClientConfig, and takes the same single field.\n */\nexport class TaskClientConfig {\n    constructor(\n        /**\n         * The service name. On GCP the URL is DERIVED from it (same project, same region — the Cloud\n         * Run service name, so you maintain no URL table), which works across demo/qa/prod. Anything\n         * the derivation cannot describe — a localhost port, another region/project, a non-Cloud-Run\n         * host — is a `ClientRegistry` mapping registered at startup, NOT a per-client URL.\n         */\n        public readonly svcName: string,\n    ) {}\n\n    /** Resolved per enqueue, not at construction — so building a client stays synchronous. */\n    resolveUrl(): Promise<string> {\n        return resolveServiceUrl(this.svcName);\n    }\n}\n"]}

package/src/TaskProxyClient.d.ts

@@ -15,7 +15,7 @@ import { ApiPrototype, TaskClientConfig } from './TaskClientConfig';
  *
  * It owns:
  * - @ApiPath / @PubSub convention validation + the endpoint plans from the contract's decorators
- * - Resolving the callee's base URL (from svcName, or the explicit targetUrl)
+ * - Resolving the callee's base URL from svcName (ClientRegistry override, else GCP derivation)
  * - Context propagation onto the task headers (a credential is never a context key, so none can ride along)
  * - Handing a fully-built TaskRequest to the bound {@link TaskInvoker}
  */

package/src/TaskProxyClient.js

@@ -33,7 +33,7 @@ class EndpointPlan {
  *
  * It owns:
  * - @ApiPath / @PubSub convention validation + the endpoint plans from the contract's decorators
- * - Resolving the callee's base URL (from svcName, or the explicit targetUrl)
+ * - Resolving the callee's base URL from svcName (ClientRegistry override, else GCP derivation)
  * - Context propagation onto the task headers (a credential is never a context key, so none can ride along)
  * - Handing a fully-built TaskRequest to the bound {@link TaskInvoker}
  */
@@ -80,9 +80,9 @@ let TaskProxyClient = class TaskProxyClient {
                 'scheduler.addToQueue(() => taskClient.method(req), { dedupName }).');
         }
         // Resolved lazily (not at client construction) so building a client stays synchronous.
-        // Every metadata read beneath resolveTargetUrl is memoized process-wide, so only the
+        // Every metadata read beneath resolveServiceUrl is memoized process-wide, so only the
         // first enqueue in the process pays a lookup.
-        const targetUrl = await this.config.resolveTargetUrl();
+        const targetUrl = await this.config.resolveUrl();
         const request = new TaskTypes_1.TaskRequest(targetUrl, plan.path, plan.queueName, requestDto, this.buildContextHeaders(), plan.authMode, frame.info ?? new TaskTypes_1.ScheduleInfo());
         // svcName, not the URL, is the stable name across demo/qa/prod.
         log.debug(`enqueue task ${plan.queueName} -> ${this.config.svcName}${plan.path}`);

package/src/TaskProxyClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskProxyClient.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, injectable } from 'inversify';\nimport {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMode,\n    getQueueName,\n    assertPubSubConventions,\n    assertEveryEndpointHasAuthMode,\n    AuthMode,\n    LogManager,\n} from '@webpieces/core-util';\nimport {\n    RequestContextHeaders,\n    provideFrameworkTransient,\n} from '@webpieces/core-context';\nimport { TaskInvoker, TaskRequest, ScheduleInfo } from './TaskTypes';\nimport { currentScheduleFrame } from './ScheduleContext';\nimport { ApiPrototype, TaskClientConfig } from './TaskClientConfig';\n\nconst log = LogManager.getLogger('TaskProxyClient');\n\n/** Per-endpoint routing plan resolved once from the contract's decorators. */\nclass EndpointPlan {\n    path: string;\n    queueName: string;\n    authMode: AuthMode;\n\n    constructor(path: string, queueName: string, authMode: AuthMode) {\n        this.path = path;\n        this.queueName = queueName;\n        this.authMode = authMode;\n    }\n}\n\n/**\n * TaskProxyClient - the enqueue engine behind one @PubSub API contract's client proxy.\n *\n * The fire-and-forget twin of http-client-core's ProxyClient, and TWO-PHASE for the same reason:\n * its COLLABORATORS (invoker, headers) come from the container, while the PER-CLIENT state (which\n * contract, which target) arrives on {@link init}. That is what lets {@link ClientCloudTasksFactory}\n * hold a `Provider<TaskProxyClient>` and hand out a fresh, independently-configured client per\n * contract.\n *\n * Calling an endpoint ENQUEUES a task (it does not call remotely); the task is later delivered to\n * the same endpoint's controller through the full server filter chain.\n *\n * It owns:\n * - @ApiPath / @PubSub convention validation + the endpoint plans from the contract's decorators\n * - Resolving the callee's base URL (from svcName, or the explicit targetUrl)\n * - Context propagation onto the task headers (a credential is never a context key, so none can ride along)\n * - Handing a fully-built TaskRequest to the bound {@link TaskInvoker}\n */\n@provideFrameworkTransient()\n@injectable()\nexport class TaskProxyClient {\n    // Assigned by init(), which the factory calls immediately after construction.\n    private plans!: Map<string, EndpointPlan>;\n    private apiName!: string;\n    private config!: TaskClientConfig;\n\n    constructor(\n        @inject(TaskInvoker) private readonly invoker: TaskInvoker,\n        @inject(RequestContextHeaders) private readonly headers: RequestContextHeaders,\n    ) {}\n\n    /** Bind this client to one @PubSub contract + target. */\n    init(apiClass: ApiPrototype<object>, config: TaskClientConfig): void {\n        if (!isApiPath(apiClass)) {\n            throw new Error(`Class ${apiClass.name || 'Unknown'} must be decorated with @ApiPath()`);\n        }\n        assertPubSubConventions(apiClass);\n        assertEveryEndpointHasAuthMode(apiClass);\n\n        this.config = config;\n        this.apiName = apiClass.name || 'UnknownApi';\n        this.plans = this.buildPlans(apiClass);\n    }\n\n    /** Check whether the contract declares a @PubSub endpoint with this method name. */\n    hasEndpoint(methodName: string): boolean {\n        return this.plans.has(methodName);\n    }\n\n    /**\n     * Enqueue one task for the named endpoint. Must run inside a CloudTaskScheduler lambda\n     * (which supplies the ScheduleInfo) within an active RequestContext, e.g.:\n     *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });\n     */\n    // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n    async enqueue(methodName: string, requestDto: unknown): Promise<void> {\n        const plan = this.plans.get(methodName);\n        if (!plan) {\n            throw new Error(`No @PubSub endpoint '${methodName}' on ${this.apiName}`);\n        }\n\n        const frame = currentScheduleFrame();\n        if (!frame) {\n            throw new Error(\n                'Cloud task enqueue must run inside a CloudTaskScheduler lambda, e.g. ' +\n                'scheduler.addToQueue(() => taskClient.method(req), { dedupName }).',\n            );\n        }\n\n        // Resolved lazily (not at client construction) so building a client stays synchronous.\n        // Every metadata read beneath resolveTargetUrl is memoized process-wide, so only the\n        // first enqueue in the process pays a lookup.\n        const targetUrl = await this.config.resolveTargetUrl();\n\n        const request = new TaskRequest(\n            targetUrl,\n            plan.path,\n            plan.queueName,\n            requestDto,\n            this.buildContextHeaders(),\n            plan.authMode,\n            frame.info ?? new ScheduleInfo(),\n        );\n\n        // svcName, not the URL, is the stable name across demo/qa/prod.\n        log.debug(`enqueue task ${plan.queueName} -> ${this.config.svcName}${plan.path}`);\n        frame.jobRef = await this.invoker.enqueue(request);\n    }\n\n    /** Endpoint name -> its resolved path / queue / auth mode, read once from the decorators. */\n    private buildPlans(apiClass: ApiPrototype<object>): Map<string, EndpointPlan> {\n        const basePath = getApiPath(apiClass) ?? '';\n        const endpoints = getEndpoints(apiClass) ?? {};\n        const plans = new Map<string, EndpointPlan>();\n\n        for (const methodName of Object.keys(endpoints)) {\n            const authMode = getAuthMode(apiClass, methodName);\n            if (!authMode) {\n                throw new Error(`Endpoint '${methodName}' on ${this.apiName} has no auth mode`);\n            }\n            const plan = new EndpointPlan(\n                basePath + endpoints[methodName],\n                getQueueName(apiClass, methodName),\n                authMode,\n            );\n            plans.set(methodName, plan);\n        }\n        return plans;\n    }\n\n    /**\n     * Every transferred context key (txId/requestId/tenant…), request-id chained.\n     * Throws if there is no active RequestContext — an enqueue with no trace is a bug.\n     *\n     * No credential can appear here: `authorization` is read off the inbound HttpRequest and is not\n     * a ContextKey, so it never enters the RequestContext to be transferred. The invoker mints the\n     * task's own delivery auth per the endpoint's @AuthOidc / @AuthSharedSecret mode.\n     */\n    private buildContextHeaders(): Map<string, string> {\n        return this.headers.buildOutboundHeaders();\n    }\n}\n\n/**\n * DI token for the `Provider<TaskProxyClient>` that hands out enqueue clients — one per @PubSub\n * contract. `Provider<T>` is erased at runtime, so it cannot be its own token; this Symbol names T.\n *\n * Because TaskProxyClient is bound TRANSIENT, every `get()` constructs a new one. (Were it bound\n * `@provideFrameworkSingleton`, the very same Provider would hand back one lazily-created instance\n * instead — the provider caches nothing, so the target's scope decides.)\n */\n// webpieces-disable no-symbol-di-tokens -- Provider<T> is erased at runtime; the Symbol names T\nexport const TASK_PROXY_CLIENT_PROVIDER = Symbol.for('Provider<TaskProxyClient>');\n"]}
+{"version":3,"file":"TaskProxyClient.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskProxyClient.ts"],"names":[],"mappings":"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","sourcesContent":["import { inject, injectable } from 'inversify';\nimport {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMode,\n    getQueueName,\n    assertPubSubConventions,\n    assertEveryEndpointHasAuthMode,\n    AuthMode,\n    LogManager,\n} from '@webpieces/core-util';\nimport {\n    RequestContextHeaders,\n    provideFrameworkTransient,\n} from '@webpieces/core-context';\nimport { TaskInvoker, TaskRequest, ScheduleInfo } from './TaskTypes';\nimport { currentScheduleFrame } from './ScheduleContext';\nimport { ApiPrototype, TaskClientConfig } from './TaskClientConfig';\n\nconst log = LogManager.getLogger('TaskProxyClient');\n\n/** Per-endpoint routing plan resolved once from the contract's decorators. */\nclass EndpointPlan {\n    path: string;\n    queueName: string;\n    authMode: AuthMode;\n\n    constructor(path: string, queueName: string, authMode: AuthMode) {\n        this.path = path;\n        this.queueName = queueName;\n        this.authMode = authMode;\n    }\n}\n\n/**\n * TaskProxyClient - the enqueue engine behind one @PubSub API contract's client proxy.\n *\n * The fire-and-forget twin of http-client-core's ProxyClient, and TWO-PHASE for the same reason:\n * its COLLABORATORS (invoker, headers) come from the container, while the PER-CLIENT state (which\n * contract, which target) arrives on {@link init}. That is what lets {@link ClientCloudTasksFactory}\n * hold a `Provider<TaskProxyClient>` and hand out a fresh, independently-configured client per\n * contract.\n *\n * Calling an endpoint ENQUEUES a task (it does not call remotely); the task is later delivered to\n * the same endpoint's controller through the full server filter chain.\n *\n * It owns:\n * - @ApiPath / @PubSub convention validation + the endpoint plans from the contract's decorators\n * - Resolving the callee's base URL from svcName (ClientRegistry override, else GCP derivation)\n * - Context propagation onto the task headers (a credential is never a context key, so none can ride along)\n * - Handing a fully-built TaskRequest to the bound {@link TaskInvoker}\n */\n@provideFrameworkTransient()\n@injectable()\nexport class TaskProxyClient {\n    // Assigned by init(), which the factory calls immediately after construction.\n    private plans!: Map<string, EndpointPlan>;\n    private apiName!: string;\n    private config!: TaskClientConfig;\n\n    constructor(\n        @inject(TaskInvoker) private readonly invoker: TaskInvoker,\n        @inject(RequestContextHeaders) private readonly headers: RequestContextHeaders,\n    ) {}\n\n    /** Bind this client to one @PubSub contract + target. */\n    init(apiClass: ApiPrototype<object>, config: TaskClientConfig): void {\n        if (!isApiPath(apiClass)) {\n            throw new Error(`Class ${apiClass.name || 'Unknown'} must be decorated with @ApiPath()`);\n        }\n        assertPubSubConventions(apiClass);\n        assertEveryEndpointHasAuthMode(apiClass);\n\n        this.config = config;\n        this.apiName = apiClass.name || 'UnknownApi';\n        this.plans = this.buildPlans(apiClass);\n    }\n\n    /** Check whether the contract declares a @PubSub endpoint with this method name. */\n    hasEndpoint(methodName: string): boolean {\n        return this.plans.has(methodName);\n    }\n\n    /**\n     * Enqueue one task for the named endpoint. Must run inside a CloudTaskScheduler lambda\n     * (which supplies the ScheduleInfo) within an active RequestContext, e.g.:\n     *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });\n     */\n    // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n    async enqueue(methodName: string, requestDto: unknown): Promise<void> {\n        const plan = this.plans.get(methodName);\n        if (!plan) {\n            throw new Error(`No @PubSub endpoint '${methodName}' on ${this.apiName}`);\n        }\n\n        const frame = currentScheduleFrame();\n        if (!frame) {\n            throw new Error(\n                'Cloud task enqueue must run inside a CloudTaskScheduler lambda, e.g. ' +\n                'scheduler.addToQueue(() => taskClient.method(req), { dedupName }).',\n            );\n        }\n\n        // Resolved lazily (not at client construction) so building a client stays synchronous.\n        // Every metadata read beneath resolveServiceUrl is memoized process-wide, so only the\n        // first enqueue in the process pays a lookup.\n        const targetUrl = await this.config.resolveUrl();\n\n        const request = new TaskRequest(\n            targetUrl,\n            plan.path,\n            plan.queueName,\n            requestDto,\n            this.buildContextHeaders(),\n            plan.authMode,\n            frame.info ?? new ScheduleInfo(),\n        );\n\n        // svcName, not the URL, is the stable name across demo/qa/prod.\n        log.debug(`enqueue task ${plan.queueName} -> ${this.config.svcName}${plan.path}`);\n        frame.jobRef = await this.invoker.enqueue(request);\n    }\n\n    /** Endpoint name -> its resolved path / queue / auth mode, read once from the decorators. */\n    private buildPlans(apiClass: ApiPrototype<object>): Map<string, EndpointPlan> {\n        const basePath = getApiPath(apiClass) ?? '';\n        const endpoints = getEndpoints(apiClass) ?? {};\n        const plans = new Map<string, EndpointPlan>();\n\n        for (const methodName of Object.keys(endpoints)) {\n            const authMode = getAuthMode(apiClass, methodName);\n            if (!authMode) {\n                throw new Error(`Endpoint '${methodName}' on ${this.apiName} has no auth mode`);\n            }\n            const plan = new EndpointPlan(\n                basePath + endpoints[methodName],\n                getQueueName(apiClass, methodName),\n                authMode,\n            );\n            plans.set(methodName, plan);\n        }\n        return plans;\n    }\n\n    /**\n     * Every transferred context key (txId/requestId/tenant…), request-id chained.\n     * Throws if there is no active RequestContext — an enqueue with no trace is a bug.\n     *\n     * No credential can appear here: `authorization` is read off the inbound HttpRequest and is not\n     * a ContextKey, so it never enters the RequestContext to be transferred. The invoker mints the\n     * task's own delivery auth per the endpoint's @AuthOidc / @AuthSharedSecret mode.\n     */\n    private buildContextHeaders(): Map<string, string> {\n        return this.headers.buildOutboundHeaders();\n    }\n}\n\n/**\n * DI token for the `Provider<TaskProxyClient>` that hands out enqueue clients — one per @PubSub\n * contract. `Provider<T>` is erased at runtime, so it cannot be its own token; this Symbol names T.\n *\n * Because TaskProxyClient is bound TRANSIENT, every `get()` constructs a new one. (Were it bound\n * `@provideFrameworkSingleton`, the very same Provider would hand back one lazily-created instance\n * instead — the provider caches nothing, so the target's scope decides.)\n */\n// webpieces-disable no-symbol-di-tokens -- Provider<T> is erased at runtime; the Symbol names T\nexport const TASK_PROXY_CLIENT_PROVIDER = Symbol.for('Provider<TaskProxyClient>');\n"]}