@webpieces/cloudtasks-client 0.4.893 → 0.4.895

package/src/TaskName.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskName = void 0;
+const crypto_1 = require("crypto");
+/** How a {@link TaskName} picks the Cloud Task id. */
+var TaskNameMode;
+(function (TaskNameMode) {
+    TaskNameMode["DEDUP"] = "dedup";
+    TaskNameMode["GENERATED"] = "generated";
+    TaskNameMode["SERVER_ASSIGNED"] = "server-assigned";
+})(TaskNameMode || (TaskNameMode = {}));
+/**
+ * How an enqueue names its Cloud Task — the id after `.../queues/<queue>/tasks/`.
+ *
+ * The name is resolved ONCE per logical enqueue (in `TaskProxyClient.enqueue`, before any attempt),
+ * so every retry of that enqueue carries the SAME name. That is what makes the enqueue retry safe: an
+ * attempt whose response was lost but whose task landed makes the retry answer ALREADY_EXISTS, which
+ * is reported as success (`JobReference.alreadyExisted`), not as a second task.
+ *
+ * - {@link TaskName.generated} — the DEFAULT. One fresh UUID per logical enqueue, reused on every retry.
+ * - {@link TaskName.dedup} — the CALLER's key: true dedup across callers and processes (a Twilio
+ *   MessageSid, `org + period`, ...). A used name stays blocked for about an hour after its task runs
+ *   or is deleted.
+ * - {@link TaskName.serverAssigned} — no name: the fastest `createTask` (Google documents that named
+ *   tasks add enqueue latency), at the price that a retry after a lost response may create a duplicate.
+ */
+class TaskName {
+    mode;
+    id;
+    /** Cloud Tasks task ids: letters, digits, hyphens and underscores, at most 500 characters. */
+    static VALID_ID = /^[A-Za-z0-9_-]{1,500}$/;
+    constructor(mode, id) {
+        this.mode = mode;
+        this.id = id;
+    }
+    /** The caller's own dedup key, used verbatim as the task id. */
+    // webpieces-disable no-function-outside-class -- named constructor of this value type
+    static dedup(name) {
+        if (!TaskName.VALID_ID.test(name)) {
+            throw new RangeError(`TaskName.dedup('${name}') is not a valid Cloud Tasks task id: use only letters, ` +
+                'digits, hyphens and underscores, at most 500 characters.');
+        }
+        return new TaskName(TaskNameMode.DEDUP, name);
+    }
+    /** The default: a fresh UUID for this logical enqueue, shared by every retry of it. */
+    // webpieces-disable no-function-outside-class -- named constructor of this value type
+    static generated() {
+        return new TaskName(TaskNameMode.GENERATED);
+    }
+    /** No name: Cloud Tasks assigns one. Fastest; a retry after a lost response may duplicate. */
+    // webpieces-disable no-function-outside-class -- named constructor of this value type
+    static serverAssigned() {
+        return new TaskName(TaskNameMode.SERVER_ASSIGNED);
+    }
+    /**
+     * The task id to send, or `undefined` for a server-assigned name. Call ONCE per logical
+     * enqueue: a generated name is a new UUID on every call.
+     */
+    resolve() {
+        switch (this.mode) {
+            case TaskNameMode.DEDUP:
+                return this.id;
+            case TaskNameMode.GENERATED:
+                return (0, crypto_1.randomUUID)();
+            case TaskNameMode.SERVER_ASSIGNED:
+                return undefined;
+        }
+    }
+}
+exports.TaskName = TaskName;
+//# sourceMappingURL=TaskName.js.map

package/src/TaskName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskName.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskName.ts"],"names":[],"mappings":";;;AAAA,mCAAoC;AAEpC,sDAAsD;AACtD,IAAK,YAIJ;AAJD,WAAK,YAAY;IACb,+BAAe,CAAA;IACf,uCAAuB,CAAA;IACvB,mDAAmC,CAAA;AACvC,CAAC,EAJI,YAAY,KAAZ,YAAY,QAIhB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAa,QAAQ;IAKI;IACA;IALrB,8FAA8F;IACtF,MAAM,CAAU,QAAQ,GAAG,wBAAwB,CAAC;IAE5D,YACqB,IAAkB,EAClB,EAAW;QADX,SAAI,GAAJ,IAAI,CAAc;QAClB,OAAE,GAAF,EAAE,CAAS;IAC7B,CAAC;IAEJ,gEAAgE;IAChE,sFAAsF;IACtF,MAAM,CAAC,KAAK,CAAC,IAAY;QACrB,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,UAAU,CAChB,mBAAmB,IAAI,2DAA2D;gBAC9E,0DAA0D,CACjE,CAAC;QACN,CAAC;QACD,OAAO,IAAI,QAAQ,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,uFAAuF;IACvF,sFAAsF;IACtF,MAAM,CAAC,SAAS;QACZ,OAAO,IAAI,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IAChD,CAAC;IAED,8FAA8F;IAC9F,sFAAsF;IACtF,MAAM,CAAC,cAAc;QACjB,OAAO,IAAI,QAAQ,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,OAAO;QACH,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,YAAY,CAAC,KAAK;gBACnB,OAAO,IAAI,CAAC,EAAE,CAAC;YACnB,KAAK,YAAY,CAAC,SAAS;gBACvB,OAAO,IAAA,mBAAU,GAAE,CAAC;YACxB,KAAK,YAAY,CAAC,eAAe;gBAC7B,OAAO,SAAS,CAAC;QACzB,CAAC;IACL,CAAC;;AA9CL,4BA+CC","sourcesContent":["import { randomUUID } from 'crypto';\n\n/** How a {@link TaskName} picks the Cloud Task id. */\nenum TaskNameMode {\n    DEDUP = 'dedup',\n    GENERATED = 'generated',\n    SERVER_ASSIGNED = 'server-assigned',\n}\n\n/**\n * How an enqueue names its Cloud Task — the id after `.../queues/<queue>/tasks/`.\n *\n * The name is resolved ONCE per logical enqueue (in `TaskProxyClient.enqueue`, before any attempt),\n * so every retry of that enqueue carries the SAME name. That is what makes the enqueue retry safe: an\n * attempt whose response was lost but whose task landed makes the retry answer ALREADY_EXISTS, which\n * is reported as success (`JobReference.alreadyExisted`), not as a second task.\n *\n * - {@link TaskName.generated} — the DEFAULT. One fresh UUID per logical enqueue, reused on every retry.\n * - {@link TaskName.dedup} — the CALLER's key: true dedup across callers and processes (a Twilio\n *   MessageSid, `org + period`, ...). A used name stays blocked for about an hour after its task runs\n *   or is deleted.\n * - {@link TaskName.serverAssigned} — no name: the fastest `createTask` (Google documents that named\n *   tasks add enqueue latency), at the price that a retry after a lost response may create a duplicate.\n */\nexport class TaskName {\n    /** Cloud Tasks task ids: letters, digits, hyphens and underscores, at most 500 characters. */\n    private static readonly VALID_ID = /^[A-Za-z0-9_-]{1,500}$/;\n\n    private constructor(\n        private readonly mode: TaskNameMode,\n        private readonly id?: string,\n    ) {}\n\n    /** The caller's own dedup key, used verbatim as the task id. */\n    // webpieces-disable no-function-outside-class -- named constructor of this value type\n    static dedup(name: string): TaskName {\n        if (!TaskName.VALID_ID.test(name)) {\n            throw new RangeError(\n                `TaskName.dedup('${name}') is not a valid Cloud Tasks task id: use only letters, ` +\n                    'digits, hyphens and underscores, at most 500 characters.',\n            );\n        }\n        return new TaskName(TaskNameMode.DEDUP, name);\n    }\n\n    /** The default: a fresh UUID for this logical enqueue, shared by every retry of it. */\n    // webpieces-disable no-function-outside-class -- named constructor of this value type\n    static generated(): TaskName {\n        return new TaskName(TaskNameMode.GENERATED);\n    }\n\n    /** No name: Cloud Tasks assigns one. Fastest; a retry after a lost response may duplicate. */\n    // webpieces-disable no-function-outside-class -- named constructor of this value type\n    static serverAssigned(): TaskName {\n        return new TaskName(TaskNameMode.SERVER_ASSIGNED);\n    }\n\n    /**\n     * The task id to send, or `undefined` for a server-assigned name. Call ONCE per logical\n     * enqueue: a generated name is a new UUID on every call.\n     */\n    resolve(): string | undefined {\n        switch (this.mode) {\n            case TaskNameMode.DEDUP:\n                return this.id;\n            case TaskNameMode.GENERATED:\n                return randomUUID();\n            case TaskNameMode.SERVER_ASSIGNED:\n                return undefined;\n        }\n    }\n}\n"]}

package/src/TaskProxyClient.d.ts

@@ -1,3 +1,4 @@
+import { TransportDefault } from '@webpieces/core-util';
 import { RequestContextHeaders } from '@webpieces/core-context';
 import { TaskInvoker } from './TaskTypes';
 import { ApiPrototype, TaskClientConfig } from './TaskClientConfig';
@@ -23,6 +24,15 @@ import { ApiPrototype, TaskClientConfig } from './TaskClientConfig';
 export declare class TaskProxyClient {
     private readonly invoker;
     private readonly headers;
+    /**
+     * The enqueue transport's default for `CallRegistry.execute` (Path A): 30 s if a caller only
+     * registers a strategy-free timeout ladder, otherwise webpieces' shared `RetryStrategy` — 5 s per
+     * attempt, 3 retries, backoff 500 ms x2 capped at 4 s. RPC passes `new TransportDefault(30_000)`
+     * (no retry); this is the ONLY place the two transports differ.
+     */
+    static readonly ENQUEUE_TRANSPORT_DEFAULT: TransportDefault;
+    /** Path B's safety cap when no timeout is registered: caller-owned gax timing still ends. */
+    static readonly ENQUEUE_SAFETY_CAP_MS = 30000;
     private plans;
     private apiName;
     private apiClass;
@@ -43,9 +53,30 @@ export declare class TaskProxyClient {
     /**
      * Enqueue one task for the named endpoint. Must run inside a CloudTaskScheduler lambda
      * (which supplies the ScheduleInfo) within an active RequestContext, e.g.:
-     *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });
+     *   scheduler.addToQueue(() => taskClient.foo(req), new ScheduleOptions(TaskName.dedup(id)));
+     *
+     * Before any attempt it resolves, ONCE: the task name (so every attempt carries the same one),
+     * and the effective customizer and gax options (call site, else `GcpTaskRegistry` method -> API
+     * -> ALL). Then exactly ONE retry layer runs:
+     *
+     * - **Path A, no gax — webpieces owns timing.** `CallRegistry.execute` with
+     *   {@link TaskProxyClient.ENQUEUE_TRANSPORT_DEFAULT}: a registered strategy (method -> API -> ALL), else a
+     *   registered timeout, else `RetryStrategy(5_000, 3, 500, 2, 4_000)`. Each attempt sends
+     *   `createTask(request, { timeout: attemptMs })`.
+     * - **Path B, gax set — you own timing.** No strategy lookup and ONE attempt, sending
+     *   `createTask(request, yourGax)` under a safety cap from the timeout ladder (method -> API ->
+     *   ALL -> 30 s) so a hung channel cannot block forever.
+     *
+     * Either way the endpoint reports `WRITE_IDEMPOTENT`: one name for every attempt makes a repeat
+     * safe (delivery is at-least-once anyway, and `TaskName.serverAssigned()` accepts duplicates).
+     * A `TaskAlreadyExistsError` is caught HERE, above the retry layer: `WARN [ENQUEUE-DEDUP]`, then
+     * success with `JobReference.alreadyExisted = true`.
      */
     enqueue(methodName: string, requestDto: unknown): Promise<void>;
+    /** ALREADY_EXISTS is the task the caller asked for, already there: success, logged once. */
+    private dedupAware;
+    /** ONE enqueue attempt: a fresh TaskRequest, handed to the bound invoker. */
+    private attempt;
     /** Endpoint name -> its resolved path / queue / auth mode, read once from the decorators. */
     private buildPlans;
     /**

package/src/TaskProxyClient.js

@@ -1,4 +1,5 @@
 "use strict";
+var TaskProxyClient_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TASK_PROXY_CLIENT_PROVIDER = exports.TaskProxyClient = void 0;
 const tslib_1 = require("tslib");
@@ -6,6 +7,8 @@ const inversify_1 = require("inversify");
 const core_util_1 = require("@webpieces/core-util");
 const core_context_1 = require("@webpieces/core-context");
 const TaskTypes_1 = require("./TaskTypes");
+const TaskAlreadyExistsError_1 = require("./TaskAlreadyExistsError");
+const GcpTaskRegistry_1 = require("./GcpTaskRegistry");
 const ScheduleContext_1 = require("./ScheduleContext");
 const log = core_util_1.LogManager.getLogger('TaskProxyClient');
 /** Per-endpoint routing plan resolved once from the contract's decorators. */
@@ -16,13 +19,10 @@ class EndpointPlan {
     /** @MaskLog spec for this endpoint's request DTO, read once here so the enqueue log path masks
      *  a secret on the task payload without a per-enqueue reflection hit. Undefined = log verbatim. */
     mask;
-    /** The endpoint's declared @Endpoint operation; an enqueue deadline reports it on its timeout. */
-    operation;
-    constructor(path, queueName, authMode, operation, mask) {
+    constructor(path, queueName, authMode, mask) {
         this.path = path;
         this.queueName = queueName;
         this.authMode = authMode;
-        this.operation = operation;
         this.mask = mask;
     }
 }
@@ -46,8 +46,18 @@ class EndpointPlan {
  * - Handing a fully-built TaskRequest to the bound {@link TaskInvoker}
  */
 let TaskProxyClient = class TaskProxyClient {
+    static { TaskProxyClient_1 = this; }
     invoker;
     headers;
+    /**
+     * The enqueue transport's default for `CallRegistry.execute` (Path A): 30 s if a caller only
+     * registers a strategy-free timeout ladder, otherwise webpieces' shared `RetryStrategy` — 5 s per
+     * attempt, 3 retries, backoff 500 ms x2 capped at 4 s. RPC passes `new TransportDefault(30_000)`
+     * (no retry); this is the ONLY place the two transports differ.
+     */
+    static ENQUEUE_TRANSPORT_DEFAULT = new core_util_1.TransportDefault(30_000, new core_util_1.RetryStrategy(5_000, 3, 500, 2, 4_000).run);
+    /** Path B's safety cap when no timeout is registered: caller-owned gax timing still ends. */
+    static ENQUEUE_SAFETY_CAP_MS = 30_000;
     // Assigned by init(), which the factory calls immediately after construction.
     plans;
     apiName;
@@ -85,7 +95,24 @@ let TaskProxyClient = class TaskProxyClient {
     /**
      * Enqueue one task for the named endpoint. Must run inside a CloudTaskScheduler lambda
      * (which supplies the ScheduleInfo) within an active RequestContext, e.g.:
-     *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });
+     *   scheduler.addToQueue(() => taskClient.foo(req), new ScheduleOptions(TaskName.dedup(id)));
+     *
+     * Before any attempt it resolves, ONCE: the task name (so every attempt carries the same one),
+     * and the effective customizer and gax options (call site, else `GcpTaskRegistry` method -> API
+     * -> ALL). Then exactly ONE retry layer runs:
+     *
+     * - **Path A, no gax — webpieces owns timing.** `CallRegistry.execute` with
+     *   {@link TaskProxyClient.ENQUEUE_TRANSPORT_DEFAULT}: a registered strategy (method -> API -> ALL), else a
+     *   registered timeout, else `RetryStrategy(5_000, 3, 500, 2, 4_000)`. Each attempt sends
+     *   `createTask(request, { timeout: attemptMs })`.
+     * - **Path B, gax set — you own timing.** No strategy lookup and ONE attempt, sending
+     *   `createTask(request, yourGax)` under a safety cap from the timeout ladder (method -> API ->
+     *   ALL -> 30 s) so a hung channel cannot block forever.
+     *
+     * Either way the endpoint reports `WRITE_IDEMPOTENT`: one name for every attempt makes a repeat
+     * safe (delivery is at-least-once anyway, and `TaskName.serverAssigned()` accepts duplicates).
+     * A `TaskAlreadyExistsError` is caught HERE, above the retry layer: `WARN [ENQUEUE-DEDUP]`, then
+     * success with `JobReference.alreadyExisted = true`.
      */
     // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary
     async enqueue(methodName, requestDto) {
@@ -96,35 +123,58 @@ let TaskProxyClient = class TaskProxyClient {
         const frame = (0, ScheduleContext_1.currentScheduleFrame)();
         if (!frame) {
             throw new Error('Cloud task enqueue must run inside a CloudTaskScheduler lambda, e.g. ' +
-                'scheduler.addToQueue(() => taskClient.method(req), { dedupName }).');
+                'scheduler.addToQueue(() => taskClient.method(req), new ScheduleOptions(TaskName.dedup(id))).');
         }
+        const enqueuePlan = new TaskTypes_1.EnqueuePlan(frame.info.taskName.resolve(), frame.info.customizeTask ?? GcpTaskRegistry_1.GcpTaskRegistry.customizerFor(this.apiClass, methodName), frame.info.gax ?? GcpTaskRegistry_1.GcpTaskRegistry.gaxFor(this.apiClass, methodName));
         // Route through LogApiCall exactly like ProxyClient does for http. TaskProxyClient.enqueue is
         // the ONE seam above BOTH GcpTaskInvoker (prod) and InMemoryTaskInvoker (localhost) — whichever
         // TaskInvoker is bound, this method sits above it — so the enqueue edge gets structured
-        // `jsonPayload.api.*` logging (and, once recording is unified at LogApiCall, is recorded)
-        // uniformly, without touching either invoker impl.
+        // `jsonPayload.api.*` logging uniformly, without touching either invoker impl.
         const info = new core_util_1.ApiMethodInfo('client', this.apiName, methodName, undefined, plan.mask);
         await this.logApiCall.execute(info, requestDto, async () => {
-            const callContext = new core_util_1.CallContext(this.apiName, methodName, plan.operation);
-            const jobRef = await core_util_1.CallRegistry.execute(this.apiClass, callContext, (timeoutMs) => core_util_1.CallDeadline.run(timeoutMs, callContext, async (signal) => {
-                // Resolved lazily (not at client construction) so building a client stays synchronous.
-                // Every metadata read beneath resolveUrl is memoized process-wide, so only the first
-                // enqueue in the process pays a lookup.
-                const targetUrl = await this.config.resolveUrl();
-                core_util_1.CallDeadline.throwIfAborted(signal);
-                const request = new TaskTypes_1.TaskRequest(targetUrl, plan.path, plan.queueName, requestDto, this.buildContextHeaders(plan.authMode), 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}`);
-                return this.invoker.enqueue(request);
-            }), 30_000);
+            const callContext = new core_util_1.CallContext(this.apiName, methodName, core_util_1.WRITE_IDEMPOTENT);
+            const attempt = (timeoutMs) => core_util_1.CallDeadline.run(timeoutMs, callContext, (signal) => this.attempt(plan, enqueuePlan, frame.info, requestDto, timeoutMs, signal));
             // Only the winning attempt may publish the reference. A late enqueue cannot overwrite it.
-            frame.jobRef = jobRef;
-            // Fire-and-forget: the enqueue ack is not a meaningful response. Return a non-null value so
-            // LogApiCall's null-response guard passes; a recorded test asserts the enqueued REQUEST
-            // (payload), never this ack.
-            return frame.jobRef ?? { enqueued: true };
+            frame.jobRef = await this.dedupAware(methodName, () => enqueuePlan.gax === undefined
+                ? core_util_1.CallRegistry.execute(this.apiClass, callContext, attempt, TaskProxyClient_1.ENQUEUE_TRANSPORT_DEFAULT)
+                : attempt(core_util_1.CallRegistry.resolveTimeout(this.apiClass, methodName, TaskProxyClient_1.ENQUEUE_SAFETY_CAP_MS)));
+            // Fire-and-forget: the enqueue ack is not a meaningful response, but it is non-null so
+            // LogApiCall's null-response guard passes; a recorded test asserts the enqueued REQUEST.
+            return frame.jobRef;
         });
     }
+    /** ALREADY_EXISTS is the task the caller asked for, already there: success, logged once. */
+    async dedupAware(methodName, enqueue) {
+        // webpieces-disable no-unmanaged-exceptions -- ALREADY_EXISTS is success; everything else propagates unchanged
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return await enqueue();
+        }
+        catch (err) {
+            const error = (0, core_util_1.toError)(err);
+            if (!(error instanceof TaskAlreadyExistsError_1.TaskAlreadyExistsError)) {
+                // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the enqueue's own failure unchanged
+                throw err;
+            }
+            log.warn(`[ENQUEUE-DEDUP] ${this.apiName}.${methodName} task ${error.taskName} already exists ` +
+                '(a retry whose earlier attempt landed, or a dedup name reused) — treated as success');
+            return new TaskTypes_1.JobReference(error.taskName, true);
+        }
+    }
+    /** ONE enqueue attempt: a fresh TaskRequest, handed to the bound invoker. */
+    async attempt(plan, enqueuePlan, scheduleInfo, 
+    // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary
+    requestDto, timeoutMs, signal) {
+        // Resolved lazily (not at client construction) so building a client stays synchronous.
+        // Every metadata read beneath resolveUrl is memoized process-wide, so only the first
+        // enqueue in the process pays a lookup.
+        const targetUrl = await this.config.resolveUrl();
+        core_util_1.CallDeadline.throwIfAborted(signal);
+        const request = new TaskTypes_1.TaskRequest(targetUrl, plan.path, plan.queueName, requestDto, this.buildContextHeaders(plan.authMode), plan.authMode, scheduleInfo, enqueuePlan);
+        // svcName, not the URL, is the stable name across demo/qa/prod.
+        log.debug(`enqueue task ${plan.queueName} -> ${this.config.svcName}${plan.path}`);
+        return this.invoker.enqueue(request, timeoutMs, signal);
+    }
     /** Endpoint name -> its resolved path / queue / auth mode, read once from the decorators. */
     buildPlans(apiClass) {
         const basePath = (0, core_util_1.getApiPath)(apiClass) ?? '';
@@ -136,7 +186,7 @@ let TaskProxyClient = class TaskProxyClient {
             if (!authMode) {
                 throw new Error(`Endpoint '${methodName}' on ${this.apiName} has no auth mode`);
             }
-            const plan = new EndpointPlan(basePath + endpoints[methodName], (0, core_util_1.getQueueName)(apiClass, methodName), authMode, (0, core_util_1.getEndpointOperation)(apiClass, methodName), (0, core_util_1.getMaskSpec)(apiClass, methodName));
+            const plan = new EndpointPlan(basePath + endpoints[methodName], (0, core_util_1.getQueueName)(apiClass, methodName), authMode, (0, core_util_1.getMaskSpec)(apiClass, methodName));
             plans.set(methodName, plan);
         }
         return plans;
@@ -162,7 +212,7 @@ let TaskProxyClient = class TaskProxyClient {
     }
 };
 exports.TaskProxyClient = TaskProxyClient;
-exports.TaskProxyClient = TaskProxyClient = tslib_1.__decorate([
+exports.TaskProxyClient = TaskProxyClient = TaskProxyClient_1 = tslib_1.__decorate([
     (0, core_context_1.provideFrameworkTransient)(),
     tslib_1.__param(0, (0, inversify_1.inject)(TaskTypes_1.TaskInvoker)),
     tslib_1.__param(1, (0, inversify_1.inject)(core_context_1.RequestContextHeaders)),

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 } from 'inversify';\nimport {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMeta,\n    getQueueName,\n    getMaskSpec,\n    assertPubSubConventions,\n    assertEveryEndpointHasAuthMode,\n    assertNotInternalApi,\n    AuthMode,\n    DestinationTrust,\n    MaskSpec,\n    LogManager,\n    LogApiCallImpl,\n    ApiMethodInfo,\n    CallRegistry,\n    CallDeadline,\n    CallContext,\n    getEndpointOperation,\n} from '@webpieces/core-util';\nimport type { EndpointOperation } from '@webpieces/core-util';\nimport {\n    RequestContextApiCallContext,\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    /** @MaskLog spec for this endpoint's request DTO, read once here so the enqueue log path masks\n     *  a secret on the task payload without a per-enqueue reflection hit. Undefined = log verbatim. */\n    mask?: MaskSpec;\n    /** The endpoint's declared @Endpoint operation; an enqueue deadline reports it on its timeout. */\n    operation: EndpointOperation;\n\n    constructor(\n        path: string,\n        queueName: string,\n        authMode: AuthMode,\n        operation: EndpointOperation,\n        mask?: MaskSpec,\n    ) {\n        this.path = path;\n        this.queueName = queueName;\n        this.authMode = authMode;\n        this.operation = operation;\n        this.mask = mask;\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 through `ClientRegistry.resolve` — the SAME chain the\n *   RPC client runs: a registered mapping, else the installed deriver, else throw\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()\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 apiClass!: ApiPrototype<object>;\n    private config!: TaskClientConfig;\n\n    /**\n     * The api-call log seam, built around this node-only package's OWN RequestContext-backed\n     * ApiCallContext. Constructed here rather than installed at startup, so a plain NestJS/Express\n     * host needs no webpieces STARTUP INSTALL to enqueue — it only has to run the call inside a\n     * `RequestContext.run(...)` scope, which such a host already opens per request. That is the defect\n     * that made every enqueue throw `ApiCallContext is not installed`.\n     */\n    private readonly logApiCall = new LogApiCallImpl(new RequestContextApiCallContext());\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        assertNotInternalApi(apiClass, 'Cloud Tasks client');\n        if (!isApiPath(apiClass)) {\n            throw new Error(\n                `Class ${apiClass.name || 'Unknown'} must be decorated with @ApiPath()`,\n            );\n        }\n        assertPubSubConventions(apiClass);\n        assertEveryEndpointHasAuthMode(apiClass);\n\n        this.config = config;\n        this.apiClass = apiClass;\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        // Route through LogApiCall exactly like ProxyClient does for http. TaskProxyClient.enqueue is\n        // the ONE seam above BOTH GcpTaskInvoker (prod) and InMemoryTaskInvoker (localhost) — whichever\n        // TaskInvoker is bound, this method sits above it — so the enqueue edge gets structured\n        // `jsonPayload.api.*` logging (and, once recording is unified at LogApiCall, is recorded)\n        // uniformly, without touching either invoker impl.\n        const info = new ApiMethodInfo('client', this.apiName, methodName, undefined, plan.mask);\n        await this.logApiCall.execute(info, requestDto, async () => {\n            const callContext = new CallContext(this.apiName, methodName, plan.operation);\n            const jobRef = await CallRegistry.execute(\n                this.apiClass,\n                callContext,\n                (timeoutMs: number) =>\n                    CallDeadline.run(timeoutMs, callContext, async (signal: AbortSignal) => {\n                        // Resolved lazily (not at client construction) so building a client stays synchronous.\n                        // Every metadata read beneath resolveUrl is memoized process-wide, so only the first\n                        // enqueue in the process pays a lookup.\n                        const targetUrl = await this.config.resolveUrl();\n                        CallDeadline.throwIfAborted(signal);\n\n                        const request = new TaskRequest(\n                            targetUrl,\n                            plan.path,\n                            plan.queueName,\n                            requestDto,\n                            this.buildContextHeaders(plan.authMode),\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(\n                            `enqueue task ${plan.queueName} -> ${this.config.svcName}${plan.path}`,\n                        );\n                        return this.invoker.enqueue(request);\n                    }),\n                30_000,\n            );\n            // Only the winning attempt may publish the reference. A late enqueue cannot overwrite it.\n            frame.jobRef = jobRef;\n\n            // Fire-and-forget: the enqueue ack is not a meaningful response. Return a non-null value so\n            // LogApiCall's null-response guard passes; a recorded test asserts the enqueued REQUEST\n            // (payload), never this ack.\n            return frame.jobRef ?? { enqueued: true };\n        });\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 authMeta = getAuthMeta(apiClass, methodName);\n            const authMode = authMeta ? this.invoker.selectAuthentication(authMeta) : undefined;\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                getEndpointOperation(apiClass, methodName),\n                getMaskSpec(apiClass, methodName),\n            );\n            plans.set(methodName, plan);\n        }\n        return plans;\n    }\n\n    /**\n     * Every transferred context key (txId/requestId/tenant…) the DELIVERY endpoint may receive,\n     * request-id chained. Throws if there is no active RequestContext — an enqueue with no trace is\n     * 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 oidc(...) / sharedSecret(...) mode.\n     *\n     * TRUSTED keys DO flow on this path, and that is the point of deriving {@link DestinationTrust}\n     * from `plan.authMode` rather than hardcoding it: a task is delivered under the OIDC token the\n     * invoker mints, so the delivery endpoint authenticates its caller and its AuthFilter admits the\n     * userId/orgId we vouched for. A @PubSub endpoint declared @WpAuthPublic or jwt() would not, and it\n     * correctly stops receiving them — the enqueue keeps working, minus context the callee would\n     * have 401'd on.\n     */\n    private buildContextHeaders(authMode: AuthMode): Map<string, string> {\n        return this.headers.buildOutboundHeaders(DestinationTrust.forAuthMode(authMode));\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 } from 'inversify';\nimport {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMeta,\n    getQueueName,\n    getMaskSpec,\n    assertPubSubConventions,\n    assertEveryEndpointHasAuthMode,\n    assertNotInternalApi,\n    AuthMode,\n    DestinationTrust,\n    MaskSpec,\n    LogManager,\n    LogApiCallImpl,\n    ApiMethodInfo,\n    CallRegistry,\n    CallDeadline,\n    CallContext,\n    RetryStrategy,\n    TransportDefault,\n    WRITE_IDEMPOTENT,\n    toError,\n} from '@webpieces/core-util';\nimport {\n    RequestContextApiCallContext,\n    RequestContextHeaders,\n    provideFrameworkTransient,\n} from '@webpieces/core-context';\nimport { TaskInvoker, TaskRequest, ScheduleInfo, EnqueuePlan, JobReference } from './TaskTypes';\nimport { TaskAlreadyExistsError } from './TaskAlreadyExistsError';\nimport { GcpTaskRegistry } from './GcpTaskRegistry';\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    /** @MaskLog spec for this endpoint's request DTO, read once here so the enqueue log path masks\n     *  a secret on the task payload without a per-enqueue reflection hit. Undefined = log verbatim. */\n    mask?: MaskSpec;\n\n    constructor(path: string, queueName: string, authMode: AuthMode, mask?: MaskSpec) {\n        this.path = path;\n        this.queueName = queueName;\n        this.authMode = authMode;\n        this.mask = mask;\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 through `ClientRegistry.resolve` — the SAME chain the\n *   RPC client runs: a registered mapping, else the installed deriver, else throw\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()\nexport class TaskProxyClient {\n    /**\n     * The enqueue transport's default for `CallRegistry.execute` (Path A): 30 s if a caller only\n     * registers a strategy-free timeout ladder, otherwise webpieces' shared `RetryStrategy` — 5 s per\n     * attempt, 3 retries, backoff 500 ms x2 capped at 4 s. RPC passes `new TransportDefault(30_000)`\n     * (no retry); this is the ONLY place the two transports differ.\n     */\n    static readonly ENQUEUE_TRANSPORT_DEFAULT = new TransportDefault(\n        30_000,\n        new RetryStrategy(5_000, 3, 500, 2, 4_000).run,\n    );\n\n    /** Path B's safety cap when no timeout is registered: caller-owned gax timing still ends. */\n    static readonly ENQUEUE_SAFETY_CAP_MS = 30_000;\n\n    // Assigned by init(), which the factory calls immediately after construction.\n    private plans!: Map<string, EndpointPlan>;\n    private apiName!: string;\n    private apiClass!: ApiPrototype<object>;\n    private config!: TaskClientConfig;\n\n    /**\n     * The api-call log seam, built around this node-only package's OWN RequestContext-backed\n     * ApiCallContext. Constructed here rather than installed at startup, so a plain NestJS/Express\n     * host needs no webpieces STARTUP INSTALL to enqueue — it only has to run the call inside a\n     * `RequestContext.run(...)` scope, which such a host already opens per request. That is the defect\n     * that made every enqueue throw `ApiCallContext is not installed`.\n     */\n    private readonly logApiCall = new LogApiCallImpl(new RequestContextApiCallContext());\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        assertNotInternalApi(apiClass, 'Cloud Tasks client');\n        if (!isApiPath(apiClass)) {\n            throw new Error(\n                `Class ${apiClass.name || 'Unknown'} must be decorated with @ApiPath()`,\n            );\n        }\n        assertPubSubConventions(apiClass);\n        assertEveryEndpointHasAuthMode(apiClass);\n\n        this.config = config;\n        this.apiClass = apiClass;\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), new ScheduleOptions(TaskName.dedup(id)));\n     *\n     * Before any attempt it resolves, ONCE: the task name (so every attempt carries the same one),\n     * and the effective customizer and gax options (call site, else `GcpTaskRegistry` method -> API\n     * -> ALL). Then exactly ONE retry layer runs:\n     *\n     * - **Path A, no gax — webpieces owns timing.** `CallRegistry.execute` with\n     *   {@link TaskProxyClient.ENQUEUE_TRANSPORT_DEFAULT}: a registered strategy (method -> API -> ALL), else a\n     *   registered timeout, else `RetryStrategy(5_000, 3, 500, 2, 4_000)`. Each attempt sends\n     *   `createTask(request, { timeout: attemptMs })`.\n     * - **Path B, gax set — you own timing.** No strategy lookup and ONE attempt, sending\n     *   `createTask(request, yourGax)` under a safety cap from the timeout ladder (method -> API ->\n     *   ALL -> 30 s) so a hung channel cannot block forever.\n     *\n     * Either way the endpoint reports `WRITE_IDEMPOTENT`: one name for every attempt makes a repeat\n     * safe (delivery is at-least-once anyway, and `TaskName.serverAssigned()` accepts duplicates).\n     * A `TaskAlreadyExistsError` is caught HERE, above the retry layer: `WARN [ENQUEUE-DEDUP]`, then\n     * success with `JobReference.alreadyExisted = true`.\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), new ScheduleOptions(TaskName.dedup(id))).',\n            );\n        }\n        const enqueuePlan = new EnqueuePlan(\n            frame.info.taskName.resolve(),\n            frame.info.customizeTask ?? GcpTaskRegistry.customizerFor(this.apiClass, methodName),\n            frame.info.gax ?? GcpTaskRegistry.gaxFor(this.apiClass, methodName),\n        );\n\n        // Route through LogApiCall exactly like ProxyClient does for http. TaskProxyClient.enqueue is\n        // the ONE seam above BOTH GcpTaskInvoker (prod) and InMemoryTaskInvoker (localhost) — whichever\n        // TaskInvoker is bound, this method sits above it — so the enqueue edge gets structured\n        // `jsonPayload.api.*` logging uniformly, without touching either invoker impl.\n        const info = new ApiMethodInfo('client', this.apiName, methodName, undefined, plan.mask);\n        await this.logApiCall.execute(info, requestDto, async () => {\n            const callContext = new CallContext(this.apiName, methodName, WRITE_IDEMPOTENT);\n            const attempt = (timeoutMs: number): Promise<JobReference> =>\n                CallDeadline.run(timeoutMs, callContext, (signal: AbortSignal) =>\n                    this.attempt(plan, enqueuePlan, frame.info, requestDto, timeoutMs, signal),\n                );\n            // Only the winning attempt may publish the reference. A late enqueue cannot overwrite it.\n            frame.jobRef = await this.dedupAware(methodName, () =>\n                enqueuePlan.gax === undefined\n                    ? CallRegistry.execute(this.apiClass, callContext, attempt, TaskProxyClient.ENQUEUE_TRANSPORT_DEFAULT)\n                    : attempt(CallRegistry.resolveTimeout(this.apiClass, methodName, TaskProxyClient.ENQUEUE_SAFETY_CAP_MS)),\n            );\n            // Fire-and-forget: the enqueue ack is not a meaningful response, but it is non-null so\n            // LogApiCall's null-response guard passes; a recorded test asserts the enqueued REQUEST.\n            return frame.jobRef;\n        });\n    }\n\n    /** ALREADY_EXISTS is the task the caller asked for, already there: success, logged once. */\n    private async dedupAware(\n        methodName: string,\n        enqueue: () => Promise<JobReference>,\n    ): Promise<JobReference> {\n        // webpieces-disable no-unmanaged-exceptions -- ALREADY_EXISTS is success; everything else propagates unchanged\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await enqueue();\n        } catch (err: unknown) {\n            const error = toError(err);\n            if (!(error instanceof TaskAlreadyExistsError)) {\n                // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the enqueue's own failure unchanged\n                throw err;\n            }\n            log.warn(\n                `[ENQUEUE-DEDUP] ${this.apiName}.${methodName} task ${error.taskName} already exists ` +\n                    '(a retry whose earlier attempt landed, or a dedup name reused) — treated as success',\n            );\n            return new JobReference(error.taskName, true);\n        }\n    }\n\n    /** ONE enqueue attempt: a fresh TaskRequest, handed to the bound invoker. */\n    private async attempt(\n        plan: EndpointPlan,\n        enqueuePlan: EnqueuePlan,\n        scheduleInfo: ScheduleInfo,\n        // webpieces-disable no-any-unknown -- the request DTO's type is erased at the proxy boundary\n        requestDto: unknown,\n        timeoutMs: number,\n        signal: AbortSignal,\n    ): Promise<JobReference> {\n        // Resolved lazily (not at client construction) so building a client stays synchronous.\n        // Every metadata read beneath resolveUrl is memoized process-wide, so only the first\n        // enqueue in the process pays a lookup.\n        const targetUrl = await this.config.resolveUrl();\n        CallDeadline.throwIfAborted(signal);\n\n        const request = new TaskRequest(\n            targetUrl,\n            plan.path,\n            plan.queueName,\n            requestDto,\n            this.buildContextHeaders(plan.authMode),\n            plan.authMode,\n            scheduleInfo,\n            enqueuePlan,\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        return this.invoker.enqueue(request, timeoutMs, signal);\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 authMeta = getAuthMeta(apiClass, methodName);\n            const authMode = authMeta ? this.invoker.selectAuthentication(authMeta) : undefined;\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                getMaskSpec(apiClass, methodName),\n            );\n            plans.set(methodName, plan);\n        }\n        return plans;\n    }\n\n    /**\n     * Every transferred context key (txId/requestId/tenant…) the DELIVERY endpoint may receive,\n     * request-id chained. Throws if there is no active RequestContext — an enqueue with no trace is\n     * 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 oidc(...) / sharedSecret(...) mode.\n     *\n     * TRUSTED keys DO flow on this path, and that is the point of deriving {@link DestinationTrust}\n     * from `plan.authMode` rather than hardcoding it: a task is delivered under the OIDC token the\n     * invoker mints, so the delivery endpoint authenticates its caller and its AuthFilter admits the\n     * userId/orgId we vouched for. A @PubSub endpoint declared @WpAuthPublic or jwt() would not, and it\n     * correctly stops receiving them — the enqueue keeps working, minus context the callee would\n     * have 401'd on.\n     */\n    private buildContextHeaders(authMode: AuthMode): Map<string, string> {\n        return this.headers.buildOutboundHeaders(DestinationTrust.forAuthMode(authMode));\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"]}

package/src/TaskTypes.d.ts

@@ -1,25 +1,82 @@
-import { AuthMode } from '@webpieces/core-util';
+import { AuthMeta, AuthMode } from '@webpieces/core-util';
+import type { protos } from '@google-cloud/tasks';
+import type { CallOptions } from 'google-gax';
+import { TaskName } from './TaskName';
+/** The Google `CreateTask` request: `{ parent, task }`, built by webpieces on every attempt. */
+export type ICreateTaskRequest = protos.google.cloud.tasks.v2.ICreateTaskRequest;
+/**
+ * Changes the Google request of ONE enqueue attempt. It runs on every attempt, LAST, on a freshly
+ * built `ICreateTaskRequest` (url, body, headers, auth, name, scheduleTime and dispatchDeadline are
+ * already set) and returns the request to send — the same object mutated, or a new one.
+ *
+ * It is Google-request-only and never touches timing: gax `CallOptions` are
+ * `ScheduleOptions.gax` / `GcpTaskRegistry.setGax`. If it changes `task.name`, it must stay under the
+ * same queue path and return the same name on every attempt, or webpieces' own retries can create
+ * duplicates. The in-memory invoker has no Google request and ignores it.
+ */
+export type TaskCustomizer = (request: ICreateTaskRequest) => ICreateTaskRequest;
 /**
  * Scheduling options for an enqueued task. Travels out-of-band (via the scheduler
  * frame in RequestContext) so the shared API method signature stays `foo(req)` on
  * both the client and the controller.
  */
 export declare class ScheduleInfo {
+    /** How the task is named; resolved ONCE per logical enqueue by `TaskProxyClient`. */
+    readonly taskName: TaskName;
+    /** Absolute epoch-millis to run at; omitted = run as soon as possible. */
+    readonly epochMsToRunAt?: number | undefined;
+    /** Per-task dispatch deadline in seconds (`task.dispatchDeadline`). */
+    readonly taskTimeoutSeconds?: number | undefined;
+    /** The call site's {@link TaskCustomizer}; wins over `GcpTaskRegistry.setCustomizer`. */
+    readonly customizeTask?: TaskCustomizer | undefined;
+    /** The call site's gax `CallOptions`; set ⇒ the caller owns timing for this enqueue. */
+    readonly gax?: CallOptions | undefined;
+    constructor(
+    /** How the task is named; resolved ONCE per logical enqueue by `TaskProxyClient`. */
+    taskName: TaskName, 
     /** Absolute epoch-millis to run at; omitted = run as soon as possible. */
-    epochMsToRunAt?: number;
-    /** Per-task dispatch deadline in seconds. */
-    taskTimeoutSeconds?: number;
+    epochMsToRunAt?: number | undefined, 
+    /** Per-task dispatch deadline in seconds (`task.dispatchDeadline`). */
+    taskTimeoutSeconds?: number | undefined, 
+    /** The call site's {@link TaskCustomizer}; wins over `GcpTaskRegistry.setCustomizer`. */
+    customizeTask?: TaskCustomizer | undefined, 
+    /** The call site's gax `CallOptions`; set ⇒ the caller owns timing for this enqueue. */
+    gax?: CallOptions | undefined);
+}
+/** Handle to an enqueued task (its Cloud Tasks name), returned by the scheduler. */
+export declare class JobReference {
+    /** The task's full resource name (`projects/.../tasks/<id>`), or the in-memory task id. */
+    readonly taskId: string;
     /**
-     * Deterministic dedup name → the Cloud Task resource name. A second enqueue with
-     * the same name is rejected ALREADY_EXISTS (treated as success = idempotent).
+     * True when the task already existed (ALREADY_EXISTS): a retry whose earlier attempt landed,
+     * or a `TaskName.dedup` collision. Reported as success, never as an error.
      */
-    dedupName?: string;
-    constructor(epochMsToRunAt?: number, taskTimeoutSeconds?: number, dedupName?: string);
+    readonly alreadyExisted: boolean;
+    constructor(
+    /** The task's full resource name (`projects/.../tasks/<id>`), or the in-memory task id. */
+    taskId: string, 
+    /**
+     * True when the task already existed (ALREADY_EXISTS): a retry whose earlier attempt landed,
+     * or a `TaskName.dedup` collision. Reported as success, never as an error.
+     */
+    alreadyExisted: boolean);
 }
-/** Handle to an enqueued task (its Cloud Tasks id), returned by the scheduler. */
-export declare class JobReference {
-    taskId: string;
-    constructor(taskId: string);
+/**
+ * What `TaskProxyClient` resolved ONCE for a logical enqueue, before any attempt: the task id every
+ * attempt carries, and the EFFECTIVE customizer and gax options (call site, else `GcpTaskRegistry`
+ * method -> API -> ALL).
+ */
+export declare class EnqueuePlan {
+    /** The task id (not the full path); undefined = let Cloud Tasks assign one. */
+    readonly taskId: string | undefined;
+    readonly customizeTask?: TaskCustomizer | undefined;
+    /** Set ⇒ the caller owns timing: one attempt, `createTask(request, gax)` as given. */
+    readonly gax?: CallOptions | undefined;
+    constructor(
+    /** The task id (not the full path); undefined = let Cloud Tasks assign one. */
+    taskId: string | undefined, customizeTask?: TaskCustomizer | undefined, 
+    /** Set ⇒ the caller owns timing: one attempt, `createTask(request, gax)` as given. */
+    gax?: CallOptions | undefined);
 }
 /**
  * Everything an invoker needs to enqueue one task. Built by the enqueue proxy from
@@ -27,20 +84,38 @@ export declare class JobReference {
  */
 export declare class TaskRequest {
     /** Callee base URL (e.g. https://email-svc-123.us-central1.run.app). */
-    targetUrl: string;
+    readonly targetUrl: string;
     /** Endpoint path the task is delivered to (basePath + endpoint, e.g. /email/send). */
-    path: string;
+    readonly path: string;
     /** Cloud Tasks queue name (getQueueName: @Queue override or `${Api}-${method}`). */
-    queueName: string;
+    readonly queueName: string;
     /** The request DTO (serialized to the POST body on delivery). */
-    body: unknown;
+    readonly body: unknown;
     /** Context headers to propagate (txId/requestId/tenant…), already resolved. */
-    contextHeaders: Map<string, string>;
+    readonly contextHeaders: Map<string, string>;
     /** The endpoint's auth mode — how the invoker authenticates delivery. */
-    authMode: AuthMode;
-    /** Scheduling options (dedup name, run-at, timeout). */
-    scheduleInfo: ScheduleInfo;
-    constructor(targetUrl: string, path: string, queueName: string, body: unknown, contextHeaders: Map<string, string>, authMode: AuthMode, scheduleInfo: ScheduleInfo);
+    readonly authMode: AuthMode;
+    /** Scheduling options (run-at, dispatch deadline). */
+    readonly scheduleInfo: ScheduleInfo;
+    /** The resolved name, customizer and gax for this logical enqueue. */
+    readonly plan: EnqueuePlan;
+    constructor(
+    /** Callee base URL (e.g. https://email-svc-123.us-central1.run.app). */
+    targetUrl: string, 
+    /** Endpoint path the task is delivered to (basePath + endpoint, e.g. /email/send). */
+    path: string, 
+    /** Cloud Tasks queue name (getQueueName: @Queue override or `${Api}-${method}`). */
+    queueName: string, 
+    /** The request DTO (serialized to the POST body on delivery). */
+    body: unknown, 
+    /** Context headers to propagate (txId/requestId/tenant…), already resolved. */
+    contextHeaders: Map<string, string>, 
+    /** The endpoint's auth mode — how the invoker authenticates delivery. */
+    authMode: AuthMode, 
+    /** Scheduling options (run-at, dispatch deadline). */
+    scheduleInfo: ScheduleInfo, 
+    /** The resolved name, customizer and gax for this logical enqueue. */
+    plan: EnqueuePlan);
 }
 /**
  * The transport that actually enqueues a task. Abstract class so it doubles as the
@@ -48,9 +123,21 @@ export declare class TaskRequest {
  * InMemoryTaskInvoker in tests/local dev. Both deliver a task the same way — a plain
  * HTTP POST to `targetUrl + path` — GcpTaskInvoker via Google Cloud Tasks, and
  * InMemoryTaskInvoker via an in-process queue that fetches the target directly.
+ *
+ * An invoker performs ONE attempt and never retries: retries belong to `CallRegistry` (webpieces'
+ * `RetryStrategy` by default) or, when `plan.gax` is set, to gax. It throws
+ * `TaskAlreadyExistsError` for a name that already exists.
  */
 export declare abstract class TaskInvoker {
-    selectAuthentication(meta: import('@webpieces/core-util').AuthMeta): AuthMode;
-    abstract enqueue(request: TaskRequest): Promise<JobReference>;
+    selectAuthentication(meta: AuthMeta): AuthMode;
+    /**
+     * Enqueue ONE attempt.
+     *
+     * @param request - the task, including the resolved {@link EnqueuePlan}
+     * @param timeoutMs - this attempt's deadline (webpieces' attempt timeout, or the safety cap when
+     *   the caller owns timing); the GCP invoker sends it as the gRPC deadline
+     * @param signal - aborted when the attempt's deadline fires
+     */
+    abstract enqueue(request: TaskRequest, timeoutMs: number, signal: AbortSignal): Promise<JobReference>;
     abstract delete(ref: JobReference): Promise<void>;
 }