@webpieces/cloudtasks-client 0.4.894 → 0.4.895

package/README.md

@@ -17,11 +17,11 @@ abstract class EmailApi {
 
 // build the client once (sync); 'email-svc' is the callee's Cloud Run service name
 const emailTasks = factory.createPubSubClient(EmailApi, new TaskClientConfig('email-svc'));
-// ...or pin a URL lookup cannot describe (other region/project); svcName stays the log name
-const other = factory.createPubSubClient(EmailApi, new TaskClientConfig('email-svc', 'https://email.eu.example'));
 
 // producer (inside a request → RequestContext active)
-await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName: req.id });
+await scheduler.addToQueue(() => emailTasks.sendEmail(req));                                        // retried, auto-named
+await scheduler.addToQueue(() => emailTasks.sendEmail(req), new ScheduleOptions(TaskName.dedup(req.id), 900));
+await scheduler.schedule(() => emailTasks.sendEmail(req), Date.now() + 60_000, new ScheduleOptions(TaskName.dedup(req.id)));
 ```
 
 - `ClientCloudTasksFactory.createPubSubClient(Api, TaskClientConfig)` — builds the enqueue proxy. It
@@ -35,13 +35,74 @@ await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName: req.id
 - 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
-- `TaskInvoker` (abstract token) with two impls:
-  - `GcpTaskInvoker` — real `@google-cloud/tasks` delivery (OIDC / shared-secret)
-  - `InMemoryTaskInvoker` — dispatches through the real server filter chain in-process
-    (tests + local dev, no GCP, production parity)
-
-Enqueue calls have a **30-second default timeout**. `CallRegistry` from `@webpieces/core-util` shares
-ALL, API and API-method timeout/strategy overrides with the HTTP clients. Any strategy replaces the
-entire timeout ladder; there is no default retry. These are **enqueue** retries, separate from queue
-delivery retries and task execution deadlines. A timed-out enqueue may still complete remotely;
-retry only with application-owned idempotency/deduplication. See [client timeouts](../../../docs/client-timeouts.md).
+- `TaskInvoker` (abstract token) with two impls, each making ONE attempt per call:
+  - `GcpTaskInvoker` — real `@google-cloud/tasks` 6.3.0 (google-gax 5) delivery (OIDC / shared-secret)
+  - `InMemoryTaskInvoker` — delivers over real HTTP to the target's filter chain (tests + local dev,
+    no GCP, production parity); ignores the customizer and gax, but still runs the same retry paths
+
+## Enqueue retries (this is ENQUEUE, not delivery)
+
+The `createTask` gRPC call is retried by webpieces' shared `RetryStrategy` — the same
+`CallRegistry.execute` the RPC clients use, with the enqueue transport default
+`RetryStrategy(5_000, 3, 500, 2, 4_000)`: 5 s per attempt, 3 retries, backoff 500 ms ×2 capped at
+4 s. Only a transient failure is retried (gRPC UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED →
+`GrpcErrorMapper`); giving up throws a 502 `ApiRetriesExhaustedError`. Each retried attempt logs
+`WARN [API-client-attempt-TRANSIENT]`. Delivery retries (Cloud Tasks re-POSTing the target) are the
+queue's `retryConfig` and are out of scope here.
+
+Retries are safe because every enqueue is NAMED ONCE, before the first attempt:
+
+| `ScheduleOptions.taskName` | name | a retry after a lost response |
+|---|---|---|
+| `TaskName.generated()` (default) | one UUID per logical enqueue | ALREADY_EXISTS → success |
+| `TaskName.dedup(key)` | your key (MessageSid, org+period, …): true dedup across callers | ALREADY_EXISTS → success |
+| `TaskName.serverAssigned()` | none — fastest `createTask` | may create a duplicate |
+
+ALREADY_EXISTS is success: `WARN [ENQUEUE-DEDUP]`, and the `JobReference` comes back with
+`alreadyExisted: true`. Delete any hand-rolled `isAlreadyExists` catch. A used name stays blocked
+for about an hour after its task runs or is deleted.
+
+## Three levels of Google settings
+
+```ts
+new ScheduleOptions(taskName, taskTimeoutSeconds?, customizeTask?, gax?)
+```
+
+- **`customizeTask`** (or `GcpTaskRegistry.setCustomizer(c, ...scope)`) — the Google
+  `ICreateTaskRequest`, run LAST on every attempt's freshly built request. Request only, never timing.
+  Call site wins over the registry (method → API → ALL).
+- **`gax`** (or `GcpTaskRegistry.setGax(options, ...scope)`) — `CallOptions` for the one `createTask`
+  RPC. **Set ⇒ you own timing:** no webpieces strategy, ONE attempt, `createTask(request, yourGax)`
+  as given, under a safety cap from `CallRegistry`'s timeout ladder (method → API → ALL → 30 s). Raise
+  the cap with `CallRegistry.setTimeout(60_000, EmailApi)` to give gax retries room. Exactly one retry
+  layer per enqueue — ours or gax's, never both.
+- **The client** — override `CloudTasksClientProvider` for channel/client settings:
+
+```ts
+class KeepaliveCloudTasks extends CloudTasksClientProvider {
+    override create(): CloudTasksClient {
+        return new CloudTasksClient({ 'grpc.keepalive_time_ms': 30_000 });
+    }
+}
+(await options.rebind(CloudTasksClientProvider)).to(KeepaliveCloudTasks).inSingletonScope();
+```
+
+Unbound, it is `new CloudTasksClient()` — nobody has to bind anything. (A provider class rather than
+an optional `CloudTasksClient` binding, because the app container's inversify `autobind` tries to
+construct any unbound class token, `@optional()` included, and fails on `CloudTasksClient`.)
+
+```ts
+// you own timing AND retries (gax retries UNAVAILABLE); raise the safety cap
+await scheduler.addToQueue(() => api.sendEmail(req),
+    new ScheduleOptions(TaskName.dedup(id), undefined, undefined, { timeout: 10_000, retry: { retryCodes: [14] } }));
+CallRegistry.setTimeout(60_000, EmailApi);
+
+// process-wide defaults, no call-site edits
+GcpTaskRegistry.setCustomizer((request) => { request.task!.dispatchDeadline = { seconds: 900 }; return request; }, 'ALL');
+CallRegistry.setStrategy(new RetryStrategy(2_000, 5, 200, 2, 2_000).run, WhatsAppProcessApi);  // tune OUR retries
+```
+
+`createTask`'s public promise exposes no `cancel()`; on the default path the gRPC deadline equals the
+attempt deadline, so gRPC cancels a hung RPC itself. See [client timeouts](../../../docs/client-timeouts.md).
+`GcpTaskInvoker.grpc.spec.ts` proves all of it against a local fake gRPC server with the real
+`CloudTasksClient`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/cloudtasks-client",
-  "version": "0.4.894",
+  "version": "0.4.895",
   "description": "Cloud Tasks enqueue client generated from a shared @PubSub API contract (twin of http-client)",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -23,11 +23,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-context": "0.4.894",
-    "@webpieces/core-util": "0.4.894",
-    "@webpieces/gcp-identity": "0.4.894",
-    "@google-cloud/tasks": "5.5.2",
+    "@webpieces/core-context": "0.4.895",
+    "@webpieces/core-util": "0.4.895",
+    "@webpieces/gcp-identity": "0.4.895",
+    "@google-cloud/tasks": "6.3.0",
+    "google-gax": "5.0.8",
     "inversify": "7.10.4",
     "reflect-metadata": "0.2.2"
+  },
+  "devDependencies": {
+    "@grpc/grpc-js": "1.14.4",
+    "@grpc/proto-loader": "0.8.1"
   }
 }

package/src/ClientCloudTasksFactory.d.ts

@@ -11,7 +11,7 @@ import { ApiPrototype, TaskClientConfig } from './TaskClientConfig';
  * ```typescript
  * // same project + region as this container; the URL is derived, you maintain nothing
  * const emailTasks = factory.createPubSubClient(EmailApi, new TaskClientConfig('email-svc'));
- * await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName });
+ * await scheduler.addToQueue(() => emailTasks.sendEmail(req), new ScheduleOptions(TaskName.dedup(id)));
  * ```
  *
  * Every client it builds gets its OWN {@link TaskProxyClient} from the injected

package/src/ClientCloudTasksFactory.js

@@ -27,7 +27,7 @@ const FRAMEWORK_INSPECTION_PROPERTIES = new Set([
  * ```typescript
  * // same project + region as this container; the URL is derived, you maintain nothing
  * const emailTasks = factory.createPubSubClient(EmailApi, new TaskClientConfig('email-svc'));
- * await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName });
+ * await scheduler.addToQueue(() => emailTasks.sendEmail(req), new ScheduleOptions(TaskName.dedup(id)));
  * ```
  *
  * Every client it builds gets its OWN {@link TaskProxyClient} from the injected

package/src/ClientCloudTasksFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientCloudTasksFactory.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/ClientCloudTasksFactory.ts"],"names":[],"mappings":";;;;AAAA,yCAAmC;AACnC,oDAAmE;AACnE,0DAAqG;AACrG,uDAAgF;AAGhF,iGAAiG;AACjG,6EAA6E;AAC7E,IAAA,oCAAqB,EAAC,4CAA0B,EAAE,iCAAe,CAAC,CAAC;AAEnE;;;GAGG;AACH,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAS;IACpD,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS;IAC3E,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU;CACrE,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAGI,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAEyB;IADzD,YACyD,uBAAkD;QAAlD,4BAAuB,GAAvB,uBAAuB,CAA2B;IACxG,CAAC;IAEJ,kFAAkF;IAClF,kBAAkB,CAAmB,QAAyB,EAAE,MAAwB;QACpF,8DAA8D;QAC9D,MAAM,WAAW,GAAG,IAAI,CAAC,uBAAuB,CAAC,GAAG,EAAE,CAAC;QACvD,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,IAAI,YAAY,CAAC;QAE9C,OAAO,IAAI,KAAK,CAAC,EAAO,EAAE;YACtB,oGAAoG;YACpG,GAAG,CAAC,MAAS,EAAE,IAAqB;gBAChC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,+BAA+B,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxE,OAAO,SAAS,CAAC;gBACrB,CAAC;gBACD,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjC,MAAM,IAAI,KAAK,CACX,wBAAwB,IAAI,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI;wBAClE,qDAAqD,CACxD,CAAC;gBACN,CAAC;gBACD,kFAAkF;gBAClF,gDAAgD;gBAChD,oFAAoF;gBACpF,MAAM,YAAY,GAAG,CAAC,UAAmB,EAAiB,EAAE;oBACxD,MAAM,QAAQ,GAAG,uBAAW,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;oBAClE,6EAA6E;oBAC7E,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,OAAgB,EAAE,EAAE;wBACpE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;wBAC3B,6GAA6G;wBAC7G,MAAM,OAAO,CAAC;oBAClB,CAAC,CAAC,CAAC;gBACP,CAAC,CAAC;gBACF,OAAO,YAAY,CAAC;YACxB,CAAC;SACJ,CAAC,CAAC;IACP,CAAC;CACJ,CAAA;AAxCY,0DAAuB;kCAAvB,uBAAuB;IAFnC,IAAA,0BAAc,GAAE;IAChB,IAAA,wCAAyB,GAAE;IAGnB,mBAAA,IAAA,kBAAM,EAAC,4CAA0B,CAAC,CAAA;6CAA2C,uBAAQ;GAFjF,uBAAuB,CAwCnC","sourcesContent":["import { inject } from 'inversify';\nimport { ApiCallSite, DocumentDesign } from '@webpieces/core-util';\nimport { Provider, bindFrameworkProvider, provideFrameworkSingleton } from '@webpieces/core-context';\nimport { TASK_PROXY_CLIENT_PROVIDER, TaskProxyClient } from './TaskProxyClient';\nimport { ApiPrototype, TaskClientConfig } from './TaskClientConfig';\n\n// Teach the container how to hand out fresh TaskProxyClients. TaskProxyClient is bound TRANSIENT\n// (@provideFrameworkTransient), so each provider.get() constructs a new one.\nbindFrameworkProvider(TASK_PROXY_CLIENT_PROVIDER, TaskProxyClient);\n\n/**\n * Properties DI frameworks / Promise checks / serializers probe on the proxy; return\n * undefined instead of treating them as endpoints. Mirrors http-client-core's buildClientProxy.\n */\nconst FRAMEWORK_INSPECTION_PROPERTIES = new Set<string>([\n    'constructor', 'prototype', '__proto__', 'name', 'then', 'catch', 'finally',\n    'toJSON', 'valueOf', 'toString', 'nodeType', 'tagName', '$$typeof',\n]);\n\n/**\n * ClientCloudTasksFactory - builds Cloud Tasks enqueue clients from a shared @PubSub API\n * contract. The fire-and-forget twin of http-client-node's ClientHttpFactory.\n *\n * Calling a method on the returned client ENQUEUES a task (it does not call remotely); the task\n * is later delivered to the same endpoint's controller through the full server filter chain.\n *\n * ```typescript\n * // same project + region as this container; the URL is derived, you maintain nothing\n * const emailTasks = factory.createPubSubClient(EmailApi, new TaskClientConfig('email-svc'));\n * await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName });\n * ```\n *\n * Every client it builds gets its OWN {@link TaskProxyClient} from the injected\n * `Provider<TaskProxyClient>` (bound transient), which `createPubSubClient` then `init`s for one\n * contract. Their collaborators (TaskInvoker, RequestContextHeaders) come from the container.\n *\n * Node-only, so the factory IS the inversify entry point. An enqueue outside\n * `RequestContext.run(...)` throws rather than silently dropping the caller's trace.\n */\n@DocumentDesign()\n@provideFrameworkSingleton()\nexport class ClientCloudTasksFactory {\n    constructor(\n        @inject(TASK_PROXY_CLIENT_PROVIDER) private readonly taskProxyClientProvider: Provider<TaskProxyClient>,\n    ) {}\n\n    /** Typed enqueue client for a @PubSub contract, delivered to `config.svcName`. */\n    createPubSubClient<T extends object>(apiClass: ApiPrototype<T>, config: TaskClientConfig): T {\n        // Fresh instance per contract — TaskProxyClient is transient.\n        const proxyClient = this.taskProxyClientProvider.get();\n        proxyClient.init(apiClass, config);\n        const apiName = apiClass.name || 'UnknownApi';\n\n        return new Proxy({} as T, {\n            // webpieces-disable no-any-unknown -- proxy get trap returns either an endpoint method or undefined\n            get(target: T, prop: string | symbol): unknown {\n                if (typeof prop !== 'string' || FRAMEWORK_INSPECTION_PROPERTIES.has(prop)) {\n                    return undefined;\n                }\n                if (!proxyClient.hasEndpoint(prop)) {\n                    throw new Error(\n                        `No @PubSub endpoint '${prop}' on ${apiClass.name || 'Unknown'}. ` +\n                        `Check for typos or a missing @Endpoint() decorator.`,\n                    );\n                }\n                // Same call-site capture as the HTTP clients (#1175): synchronous, trimmed to the\n                // caller, parked on the SAME rejected instance.\n                // webpieces-disable no-any-unknown -- request DTO type is erased at the proxy layer\n                const clientMethod = (requestDto: unknown): Promise<void> => {\n                    const callSite = ApiCallSite.capture(apiName, prop, clientMethod);\n                    // webpieces-disable no-any-unknown -- a rejection value is genuinely unknown\n                    return proxyClient.enqueue(prop, requestDto).catch((failure: unknown) => {\n                        callSite.attachTo(failure);\n                        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the caller's own failure unchanged\n                        throw failure;\n                    });\n                };\n                return clientMethod;\n            },\n        });\n    }\n}\n"]}
+{"version":3,"file":"ClientCloudTasksFactory.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/ClientCloudTasksFactory.ts"],"names":[],"mappings":";;;;AAAA,yCAAmC;AACnC,oDAAmE;AACnE,0DAAqG;AACrG,uDAAgF;AAGhF,iGAAiG;AACjG,6EAA6E;AAC7E,IAAA,oCAAqB,EAAC,4CAA0B,EAAE,iCAAe,CAAC,CAAC;AAEnE;;;GAGG;AACH,MAAM,+BAA+B,GAAG,IAAI,GAAG,CAAS;IACpD,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS;IAC3E,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU;CACrE,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAGI,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAEyB;IADzD,YACyD,uBAAkD;QAAlD,4BAAuB,GAAvB,uBAAuB,CAA2B;IACxG,CAAC;IAEJ,kFAAkF;IAClF,kBAAkB,CAAmB,QAAyB,EAAE,MAAwB;QACpF,8DAA8D;QAC9D,MAAM,WAAW,GAAG,IAAI,CAAC,uBAAuB,CAAC,GAAG,EAAE,CAAC;QACvD,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,IAAI,YAAY,CAAC;QAE9C,OAAO,IAAI,KAAK,CAAC,EAAO,EAAE;YACtB,oGAAoG;YACpG,GAAG,CAAC,MAAS,EAAE,IAAqB;gBAChC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,+BAA+B,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxE,OAAO,SAAS,CAAC;gBACrB,CAAC;gBACD,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjC,MAAM,IAAI,KAAK,CACX,wBAAwB,IAAI,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,IAAI;wBAClE,qDAAqD,CACxD,CAAC;gBACN,CAAC;gBACD,kFAAkF;gBAClF,gDAAgD;gBAChD,oFAAoF;gBACpF,MAAM,YAAY,GAAG,CAAC,UAAmB,EAAiB,EAAE;oBACxD,MAAM,QAAQ,GAAG,uBAAW,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;oBAClE,6EAA6E;oBAC7E,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,OAAgB,EAAE,EAAE;wBACpE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;wBAC3B,6GAA6G;wBAC7G,MAAM,OAAO,CAAC;oBAClB,CAAC,CAAC,CAAC;gBACP,CAAC,CAAC;gBACF,OAAO,YAAY,CAAC;YACxB,CAAC;SACJ,CAAC,CAAC;IACP,CAAC;CACJ,CAAA;AAxCY,0DAAuB;kCAAvB,uBAAuB;IAFnC,IAAA,0BAAc,GAAE;IAChB,IAAA,wCAAyB,GAAE;IAGnB,mBAAA,IAAA,kBAAM,EAAC,4CAA0B,CAAC,CAAA;6CAA2C,uBAAQ;GAFjF,uBAAuB,CAwCnC","sourcesContent":["import { inject } from 'inversify';\nimport { ApiCallSite, DocumentDesign } from '@webpieces/core-util';\nimport { Provider, bindFrameworkProvider, provideFrameworkSingleton } from '@webpieces/core-context';\nimport { TASK_PROXY_CLIENT_PROVIDER, TaskProxyClient } from './TaskProxyClient';\nimport { ApiPrototype, TaskClientConfig } from './TaskClientConfig';\n\n// Teach the container how to hand out fresh TaskProxyClients. TaskProxyClient is bound TRANSIENT\n// (@provideFrameworkTransient), so each provider.get() constructs a new one.\nbindFrameworkProvider(TASK_PROXY_CLIENT_PROVIDER, TaskProxyClient);\n\n/**\n * Properties DI frameworks / Promise checks / serializers probe on the proxy; return\n * undefined instead of treating them as endpoints. Mirrors http-client-core's buildClientProxy.\n */\nconst FRAMEWORK_INSPECTION_PROPERTIES = new Set<string>([\n    'constructor', 'prototype', '__proto__', 'name', 'then', 'catch', 'finally',\n    'toJSON', 'valueOf', 'toString', 'nodeType', 'tagName', '$$typeof',\n]);\n\n/**\n * ClientCloudTasksFactory - builds Cloud Tasks enqueue clients from a shared @PubSub API\n * contract. The fire-and-forget twin of http-client-node's ClientHttpFactory.\n *\n * Calling a method on the returned client ENQUEUES a task (it does not call remotely); the task\n * is later delivered to the same endpoint's controller through the full server filter chain.\n *\n * ```typescript\n * // same project + region as this container; the URL is derived, you maintain nothing\n * const emailTasks = factory.createPubSubClient(EmailApi, new TaskClientConfig('email-svc'));\n * await scheduler.addToQueue(() => emailTasks.sendEmail(req), new ScheduleOptions(TaskName.dedup(id)));\n * ```\n *\n * Every client it builds gets its OWN {@link TaskProxyClient} from the injected\n * `Provider<TaskProxyClient>` (bound transient), which `createPubSubClient` then `init`s for one\n * contract. Their collaborators (TaskInvoker, RequestContextHeaders) come from the container.\n *\n * Node-only, so the factory IS the inversify entry point. An enqueue outside\n * `RequestContext.run(...)` throws rather than silently dropping the caller's trace.\n */\n@DocumentDesign()\n@provideFrameworkSingleton()\nexport class ClientCloudTasksFactory {\n    constructor(\n        @inject(TASK_PROXY_CLIENT_PROVIDER) private readonly taskProxyClientProvider: Provider<TaskProxyClient>,\n    ) {}\n\n    /** Typed enqueue client for a @PubSub contract, delivered to `config.svcName`. */\n    createPubSubClient<T extends object>(apiClass: ApiPrototype<T>, config: TaskClientConfig): T {\n        // Fresh instance per contract — TaskProxyClient is transient.\n        const proxyClient = this.taskProxyClientProvider.get();\n        proxyClient.init(apiClass, config);\n        const apiName = apiClass.name || 'UnknownApi';\n\n        return new Proxy({} as T, {\n            // webpieces-disable no-any-unknown -- proxy get trap returns either an endpoint method or undefined\n            get(target: T, prop: string | symbol): unknown {\n                if (typeof prop !== 'string' || FRAMEWORK_INSPECTION_PROPERTIES.has(prop)) {\n                    return undefined;\n                }\n                if (!proxyClient.hasEndpoint(prop)) {\n                    throw new Error(\n                        `No @PubSub endpoint '${prop}' on ${apiClass.name || 'Unknown'}. ` +\n                        `Check for typos or a missing @Endpoint() decorator.`,\n                    );\n                }\n                // Same call-site capture as the HTTP clients (#1175): synchronous, trimmed to the\n                // caller, parked on the SAME rejected instance.\n                // webpieces-disable no-any-unknown -- request DTO type is erased at the proxy layer\n                const clientMethod = (requestDto: unknown): Promise<void> => {\n                    const callSite = ApiCallSite.capture(apiName, prop, clientMethod);\n                    // webpieces-disable no-any-unknown -- a rejection value is genuinely unknown\n                    return proxyClient.enqueue(prop, requestDto).catch((failure: unknown) => {\n                        callSite.attachTo(failure);\n                        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the caller's own failure unchanged\n                        throw failure;\n                    });\n                };\n                return clientMethod;\n            },\n        });\n    }\n}\n"]}

package/src/CloudTaskScheduler.d.ts

@@ -1,23 +1,45 @@
-import { TaskInvoker, JobReference } from './TaskTypes';
+import type { CallOptions } from 'google-gax';
+import { TaskInvoker, JobReference, TaskCustomizer } from './TaskTypes';
+import { TaskName } from './TaskName';
 /**
- * Options for a scheduled task. These are QUEUE/TRANSPORT knobs (dedup, deadline)
- * that belong on the enqueue CALL, never on the shared API method — the controller
- * implementing that method has no use for them. See CloudTaskScheduler's class doc
- * for the full rationale.
+ * Options for a scheduled task. These are QUEUE/TRANSPORT knobs (naming, deadline, the Google
+ * request, gax) that belong on the enqueue CALL, never on the shared API method — the controller
+ * implementing that method has no use for them. See CloudTaskScheduler's class doc for the full
+ * rationale.
+ *
+ * Three levels, three owners:
+ * - the `CloudTasksClient` (via an overridden `CloudTasksClientProvider`): the channel and client
+ *   defaults (keepalive, endpoint, clientConfig);
+ * - `gax` here, or `GcpTaskRegistry.setGax(...)`: how the ONE `createTask` RPC of this enqueue
+ *   behaves. Set ⇒ YOU own timing: no webpieces retries, one attempt, under a safety cap;
+ * - `customizeTask` here, or `GcpTaskRegistry.setCustomizer(...)`: the Google request itself.
  */
 export declare class ScheduleOptions {
-    /** Deterministic Cloud Task name → idempotent dedup (duplicate = ALREADY_EXISTS). */
-    dedupName?: string;
-    /** Per-task dispatch deadline in seconds. */
-    taskTimeoutSeconds?: number;
-    constructor(dedupName?: string, taskTimeoutSeconds?: number);
+    /** How the task is named. Default: one generated UUID per logical enqueue, reused on retry. */
+    readonly taskName: TaskName;
+    /** Per-task dispatch deadline in seconds (`task.dispatchDeadline`). */
+    readonly taskTimeoutSeconds?: number | undefined;
+    /** Changes the Google request on every attempt; NEVER gax. See {@link TaskCustomizer}. */
+    readonly customizeTask?: TaskCustomizer | undefined;
+    /** gax `CallOptions` for `createTask`. Set ⇒ you own timing/retries for this enqueue. */
+    readonly gax?: CallOptions | undefined;
+    constructor(
+    /** How the task is named. Default: one generated UUID per logical enqueue, reused on retry. */
+    taskName?: TaskName, 
+    /** Per-task dispatch deadline in seconds (`task.dispatchDeadline`). */
+    taskTimeoutSeconds?: number | undefined, 
+    /** Changes the Google request on every attempt; NEVER gax. See {@link TaskCustomizer}. */
+    customizeTask?: TaskCustomizer | undefined, 
+    /** gax `CallOptions` for `createTask`. Set ⇒ you own timing/retries for this enqueue. */
+    gax?: CallOptions | undefined);
 }
 /**
  * Schedules Cloud Tasks. You wrap an enqueue-client call in a lambda so the shared
  * contract's method signature stays `foo(req)` on both client and controller; the
  * scheduling options ride out-of-band in the schedule frame:
  *
- *   await scheduler.addToQueue(() => taskClient.sendEmail(req), { dedupName: id });
+ *   await scheduler.addToQueue(() => taskClient.sendEmail(req));
+ *   await scheduler.addToQueue(() => taskClient.sendEmail(req), new ScheduleOptions(TaskName.dedup(id), 900));
  *   await scheduler.schedule(() => taskClient.sendEmail(req), runAtEpochMs);
  *
  * Must be called inside an active RequestContext (a server request scope).
@@ -25,12 +47,12 @@ export declare class ScheduleOptions {
  * WHY scheduling options are here and NOT parameters on the API method
  * ------------------------------------------------------------------------
  * The enqueue client and the controller implement the SAME abstract API method
- * (`sendEmail(req): Promise<void>`). Scheduling options — `dedupName`, "run in the
+ * (`sendEmail(req): Promise<void>`). Scheduling options — the task name, "run in the
  * future", `taskTimeoutSeconds` — are QUEUE/TRANSPORT concerns, not part of the
  * business contract, so they must not appear on the method signature:
  *
  *  - They are meaningless on the SERVER side. The controller's `sendEmail` just does
- *    the work (send the email). It has no use for `dedupName` (a Cloud Tasks resource
+ *    the work (send the email). It has no use for a task name (a Cloud Tasks resource
  *    name), a future run-time (Cloud Tasks already delivered it), or a dispatch
  *    deadline. Putting them on the method would force the controller to accept and
  *    ignore transport metadata it can't act on.
@@ -56,5 +78,7 @@ export declare class CloudTaskScheduler {
     schedule(runnable: () => Promise<void>, epochMsToRunAt: number, opts?: ScheduleOptions): Promise<JobReference>;
     /** Cancel a previously scheduled task. */
     cancelJob(ref: JobReference): Promise<void>;
+    /** No options = a generated name, no deadline, no customizer, webpieces-owned timing. */
+    private infoFor;
     private runWithFrame;
 }

package/src/CloudTaskScheduler.js

@@ -7,22 +7,40 @@ const core_context_1 = require("@webpieces/core-context");
 const core_context_2 = require("@webpieces/core-context");
 const core_util_1 = require("@webpieces/core-util");
 const TaskTypes_1 = require("./TaskTypes");
+const TaskName_1 = require("./TaskName");
 const ScheduleContext_1 = require("./ScheduleContext");
 const log = core_util_1.LogManager.getLogger('CloudTaskScheduler');
 /**
- * Options for a scheduled task. These are QUEUE/TRANSPORT knobs (dedup, deadline)
- * that belong on the enqueue CALL, never on the shared API method — the controller
- * implementing that method has no use for them. See CloudTaskScheduler's class doc
- * for the full rationale.
+ * Options for a scheduled task. These are QUEUE/TRANSPORT knobs (naming, deadline, the Google
+ * request, gax) that belong on the enqueue CALL, never on the shared API method — the controller
+ * implementing that method has no use for them. See CloudTaskScheduler's class doc for the full
+ * rationale.
+ *
+ * Three levels, three owners:
+ * - the `CloudTasksClient` (via an overridden `CloudTasksClientProvider`): the channel and client
+ *   defaults (keepalive, endpoint, clientConfig);
+ * - `gax` here, or `GcpTaskRegistry.setGax(...)`: how the ONE `createTask` RPC of this enqueue
+ *   behaves. Set ⇒ YOU own timing: no webpieces retries, one attempt, under a safety cap;
+ * - `customizeTask` here, or `GcpTaskRegistry.setCustomizer(...)`: the Google request itself.
  */
 class ScheduleOptions {
-    /** Deterministic Cloud Task name → idempotent dedup (duplicate = ALREADY_EXISTS). */
-    dedupName;
-    /** Per-task dispatch deadline in seconds. */
+    taskName;
     taskTimeoutSeconds;
-    constructor(dedupName, taskTimeoutSeconds) {
-        this.dedupName = dedupName;
+    customizeTask;
+    gax;
+    constructor(
+    /** How the task is named. Default: one generated UUID per logical enqueue, reused on retry. */
+    taskName = TaskName_1.TaskName.generated(), 
+    /** Per-task dispatch deadline in seconds (`task.dispatchDeadline`). */
+    taskTimeoutSeconds, 
+    /** Changes the Google request on every attempt; NEVER gax. See {@link TaskCustomizer}. */
+    customizeTask, 
+    /** gax `CallOptions` for `createTask`. Set ⇒ you own timing/retries for this enqueue. */
+    gax) {
+        this.taskName = taskName;
         this.taskTimeoutSeconds = taskTimeoutSeconds;
+        this.customizeTask = customizeTask;
+        this.gax = gax;
     }
 }
 exports.ScheduleOptions = ScheduleOptions;
@@ -31,7 +49,8 @@ exports.ScheduleOptions = ScheduleOptions;
  * contract's method signature stays `foo(req)` on both client and controller; the
  * scheduling options ride out-of-band in the schedule frame:
  *
- *   await scheduler.addToQueue(() => taskClient.sendEmail(req), { dedupName: id });
+ *   await scheduler.addToQueue(() => taskClient.sendEmail(req));
+ *   await scheduler.addToQueue(() => taskClient.sendEmail(req), new ScheduleOptions(TaskName.dedup(id), 900));
  *   await scheduler.schedule(() => taskClient.sendEmail(req), runAtEpochMs);
  *
  * Must be called inside an active RequestContext (a server request scope).
@@ -39,12 +58,12 @@ exports.ScheduleOptions = ScheduleOptions;
  * WHY scheduling options are here and NOT parameters on the API method
  * ------------------------------------------------------------------------
  * The enqueue client and the controller implement the SAME abstract API method
- * (`sendEmail(req): Promise<void>`). Scheduling options — `dedupName`, "run in the
+ * (`sendEmail(req): Promise<void>`). Scheduling options — the task name, "run in the
  * future", `taskTimeoutSeconds` — are QUEUE/TRANSPORT concerns, not part of the
  * business contract, so they must not appear on the method signature:
  *
  *  - They are meaningless on the SERVER side. The controller's `sendEmail` just does
- *    the work (send the email). It has no use for `dedupName` (a Cloud Tasks resource
+ *    the work (send the email). It has no use for a task name (a Cloud Tasks resource
  *    name), a future run-time (Cloud Tasks already delivered it), or a dispatch
  *    deadline. Putting them on the method would force the controller to accept and
  *    ignore transport metadata it can't act on.
@@ -68,16 +87,21 @@ let CloudTaskScheduler = class CloudTaskScheduler {
     }
     /** Enqueue a task to run as soon as possible. Returns its JobReference. */
     async addToQueue(runnable, opts) {
-        return this.runWithFrame(new TaskTypes_1.ScheduleInfo(undefined, opts?.taskTimeoutSeconds, opts?.dedupName), runnable);
+        return this.runWithFrame(this.infoFor(undefined, opts), runnable);
     }
     /** Enqueue a task to run at an absolute epoch-millis time. Returns its JobReference. */
     async schedule(runnable, epochMsToRunAt, opts) {
-        return this.runWithFrame(new TaskTypes_1.ScheduleInfo(epochMsToRunAt, opts?.taskTimeoutSeconds, opts?.dedupName), runnable);
+        return this.runWithFrame(this.infoFor(epochMsToRunAt, opts), runnable);
     }
     /** Cancel a previously scheduled task. */
     async cancelJob(ref) {
         await this.invoker.delete(ref);
     }
+    /** No options = a generated name, no deadline, no customizer, webpieces-owned timing. */
+    infoFor(epochMsToRunAt, opts) {
+        const options = opts ?? new ScheduleOptions();
+        return new TaskTypes_1.ScheduleInfo(options.taskName, epochMsToRunAt, options.taskTimeoutSeconds, options.customizeTask, options.gax);
+    }
     async runWithFrame(info, runnable) {
         if (!core_context_2.RequestContext.isActive()) {
             throw new Error('CloudTaskScheduler must run inside a RequestContext (a server request scope).');

package/src/CloudTaskScheduler.js.map

@@ -1 +1 @@
-{"version":3,"file":"CloudTaskScheduler.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/CloudTaskScheduler.ts"],"names":[],"mappings":";;;;AAAA,yCAAmC;AACnC,0DAAoE;AACpE,0DAAyD;AACzD,oDAAkD;AAClD,2CAAsE;AACtE,uDAAwF;AAExF,MAAM,GAAG,GAAG,sBAAU,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,MAAa,eAAe;IACxB,qFAAqF;IACrF,SAAS,CAAU;IACnB,6CAA6C;IAC7C,kBAAkB,CAAU;IAE5B,YAAY,SAAkB,EAAE,kBAA2B;QACvD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IACjD,CAAC;CACJ;AAVD,0CAUC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;IAEe;IAD1C,YAC0C,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAC3D,CAAC;IAEJ,2EAA2E;IAC3E,KAAK,CAAC,UAAU,CAAC,QAA6B,EAAE,IAAsB;QAClE,OAAO,IAAI,CAAC,YAAY,CACpB,IAAI,wBAAY,CAAC,SAAS,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,CAAC,EACtE,QAAQ,CACX,CAAC;IACN,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,QAAQ,CACV,QAA6B,EAC7B,cAAsB,EACtB,IAAsB;QAEtB,OAAO,IAAI,CAAC,YAAY,CACpB,IAAI,wBAAY,CAAC,cAAc,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,CAAC,EAC3E,QAAQ,CACX,CAAC;IACN,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,SAAS,CAAC,GAAiB;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAEO,KAAK,CAAC,YAAY,CACtB,IAAkB,EAClB,QAA6B;QAE7B,IAAI,CAAC,6BAAc,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACX,+EAA+E,CAClF,CAAC;QACN,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,+BAAa,CAAC,IAAI,CAAC,CAAC;QACtC,IAAA,kCAAgB,EAAC,KAAK,CAAC,CAAC;QACxB,mIAAmI;QACnI,IAAI,CAAC;YACD,MAAM,QAAQ,EAAE,CAAC;QACrB,CAAC;gBAAS,CAAC;YACP,IAAA,oCAAkB,GAAE,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACX,4EAA4E;gBAC5E,oCAAoC,CACvC,CAAC;QACN,CAAC;QACD,GAAG,CAAC,KAAK,CAAC,kBAAkB,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,MAAM,CAAC;IACxB,CAAC;CACJ,CAAA;AAxDY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,wCAAyB,GAAE;IAGnB,mBAAA,IAAA,kBAAM,EAAC,uBAAW,CAAC,CAAA;6CAA2B,uBAAW;GAFrD,kBAAkB,CAwD9B","sourcesContent":["import { inject } from 'inversify';\nimport { provideFrameworkSingleton } from '@webpieces/core-context';\nimport { RequestContext } from '@webpieces/core-context';\nimport { LogManager } from '@webpieces/core-util';\nimport { TaskInvoker, JobReference, ScheduleInfo } from './TaskTypes';\nimport { ScheduleFrame, setScheduleFrame, clearScheduleFrame } from './ScheduleContext';\n\nconst log = LogManager.getLogger('CloudTaskScheduler');\n\n/**\n * Options for a scheduled task. These are QUEUE/TRANSPORT knobs (dedup, deadline)\n * that belong on the enqueue CALL, never on the shared API method — the controller\n * implementing that method has no use for them. See CloudTaskScheduler's class doc\n * for the full rationale.\n */\nexport class ScheduleOptions {\n    /** Deterministic Cloud Task name → idempotent dedup (duplicate = ALREADY_EXISTS). */\n    dedupName?: string;\n    /** Per-task dispatch deadline in seconds. */\n    taskTimeoutSeconds?: number;\n\n    constructor(dedupName?: string, taskTimeoutSeconds?: number) {\n        this.dedupName = dedupName;\n        this.taskTimeoutSeconds = taskTimeoutSeconds;\n    }\n}\n\n/**\n * Schedules Cloud Tasks. You wrap an enqueue-client call in a lambda so the shared\n * contract's method signature stays `foo(req)` on both client and controller; the\n * scheduling options ride out-of-band in the schedule frame:\n *\n *   await scheduler.addToQueue(() => taskClient.sendEmail(req), { dedupName: id });\n *   await scheduler.schedule(() => taskClient.sendEmail(req), runAtEpochMs);\n *\n * Must be called inside an active RequestContext (a server request scope).\n *\n * WHY scheduling options are here and NOT parameters on the API method\n * ------------------------------------------------------------------------\n * The enqueue client and the controller implement the SAME abstract API method\n * (`sendEmail(req): Promise<void>`). Scheduling options — `dedupName`, \"run in the\n * future\", `taskTimeoutSeconds` — are QUEUE/TRANSPORT concerns, not part of the\n * business contract, so they must not appear on the method signature:\n *\n *  - They are meaningless on the SERVER side. The controller's `sendEmail` just does\n *    the work (send the email). It has no use for `dedupName` (a Cloud Tasks resource\n *    name), a future run-time (Cloud Tasks already delivered it), or a dispatch\n *    deadline. Putting them on the method would force the controller to accept and\n *    ignore transport metadata it can't act on.\n *  - They vary per CALL SITE, not per method. The same `sendEmail` might be enqueued\n *    plain in one place, deduped in another, and scheduled for later in a third. That\n *    is a property of THIS enqueue, not of the API — so it belongs on the enqueue\n *    call (the scheduler), exactly like Cloud Tasks itself separates the task's\n *    schedule/dedup/deadline from the HTTP body it delivers.\n *  - Symmetry with RPC: an http-client RPC call is `foo(req)` with no transport knobs\n *    in the contract; the async (queue) client keeps that same clean contract and\n *    moves the queue knobs to the scheduler wrapper.\n *\n * So the rule is: the API method is `method(req)` on BOTH sides forever; anything\n * queue-shaped (dedup, delay, timeout, cancel) lives on CloudTaskScheduler /\n * ScheduleOptions here, never on the API.\n */\n@provideFrameworkSingleton()\nexport class CloudTaskScheduler {\n    constructor(\n        @inject(TaskInvoker) private readonly invoker: TaskInvoker,\n    ) {}\n\n    /** Enqueue a task to run as soon as possible. Returns its JobReference. */\n    async addToQueue(runnable: () => Promise<void>, opts?: ScheduleOptions): Promise<JobReference> {\n        return this.runWithFrame(\n            new ScheduleInfo(undefined, opts?.taskTimeoutSeconds, opts?.dedupName),\n            runnable,\n        );\n    }\n\n    /** Enqueue a task to run at an absolute epoch-millis time. Returns its JobReference. */\n    async schedule(\n        runnable: () => Promise<void>,\n        epochMsToRunAt: number,\n        opts?: ScheduleOptions,\n    ): Promise<JobReference> {\n        return this.runWithFrame(\n            new ScheduleInfo(epochMsToRunAt, opts?.taskTimeoutSeconds, opts?.dedupName),\n            runnable,\n        );\n    }\n\n    /** Cancel a previously scheduled task. */\n    async cancelJob(ref: JobReference): Promise<void> {\n        await this.invoker.delete(ref);\n    }\n\n    private async runWithFrame(\n        info: ScheduleInfo,\n        runnable: () => Promise<void>,\n    ): Promise<JobReference> {\n        if (!RequestContext.isActive()) {\n            throw new Error(\n                'CloudTaskScheduler must run inside a RequestContext (a server request scope).',\n            );\n        }\n        const frame = new ScheduleFrame(info);\n        setScheduleFrame(frame);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- always clear the frame; the runnable's error propagates unchanged\n        try {\n            await runnable();\n        } finally {\n            clearScheduleFrame();\n        }\n        if (!frame.jobRef) {\n            throw new Error(\n                'CloudTaskScheduler runnable did not enqueue a task — the lambda must call ' +\n                'a task-client method exactly once.',\n            );\n        }\n        log.debug(`scheduled task ${frame.jobRef.taskId}`);\n        return frame.jobRef;\n    }\n}\n"]}
+{"version":3,"file":"CloudTaskScheduler.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/CloudTaskScheduler.ts"],"names":[],"mappings":";;;;AAAA,yCAAmC;AACnC,0DAAoE;AACpE,0DAAyD;AACzD,oDAAkD;AAElD,2CAAsF;AACtF,yCAAsC;AACtC,uDAAwF;AAExF,MAAM,GAAG,GAAG,sBAAU,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAa,eAAe;IAGX;IAEA;IAEA;IAEA;IARb;IACI,+FAA+F;IACtF,WAAqB,mBAAQ,CAAC,SAAS,EAAE;IAClD,uEAAuE;IAC9D,kBAA2B;IACpC,0FAA0F;IACjF,aAA8B;IACvC,yFAAyF;IAChF,GAAiB;QANjB,aAAQ,GAAR,QAAQ,CAAiC;QAEzC,uBAAkB,GAAlB,kBAAkB,CAAS;QAE3B,kBAAa,GAAb,aAAa,CAAiB;QAE9B,QAAG,GAAH,GAAG,CAAc;IAC3B,CAAC;CACP;AAXD,0CAWC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEI,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;IAEe;IAD1C,YAC0C,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAC3D,CAAC;IAEJ,2EAA2E;IAC3E,KAAK,CAAC,UAAU,CAAC,QAA6B,EAAE,IAAsB;QAClE,OAAO,IAAI,CAAC,YAAY,CACpB,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,EAC7B,QAAQ,CACX,CAAC;IACN,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,QAAQ,CACV,QAA6B,EAC7B,cAAsB,EACtB,IAAsB;QAEtB,OAAO,IAAI,CAAC,YAAY,CACpB,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,EAClC,QAAQ,CACX,CAAC;IACN,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,SAAS,CAAC,GAAiB;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,yFAAyF;IACjF,OAAO,CAAC,cAAkC,EAAE,IAAiC;QACjF,MAAM,OAAO,GAAG,IAAI,IAAI,IAAI,eAAe,EAAE,CAAC;QAC9C,OAAO,IAAI,wBAAY,CACnB,OAAO,CAAC,QAAQ,EAChB,cAAc,EACd,OAAO,CAAC,kBAAkB,EAC1B,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,GAAG,CACd,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,YAAY,CACtB,IAAkB,EAClB,QAA6B;QAE7B,IAAI,CAAC,6BAAc,CAAC,QAAQ,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACX,+EAA+E,CAClF,CAAC;QACN,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,+BAAa,CAAC,IAAI,CAAC,CAAC;QACtC,IAAA,kCAAgB,EAAC,KAAK,CAAC,CAAC;QACxB,mIAAmI;QACnI,IAAI,CAAC;YACD,MAAM,QAAQ,EAAE,CAAC;QACrB,CAAC;gBAAS,CAAC;YACP,IAAA,oCAAkB,GAAE,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACX,4EAA4E;gBAC5E,oCAAoC,CACvC,CAAC;QACN,CAAC;QACD,GAAG,CAAC,KAAK,CAAC,kBAAkB,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC,MAAM,CAAC;IACxB,CAAC;CACJ,CAAA;AApEY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,wCAAyB,GAAE;IAGnB,mBAAA,IAAA,kBAAM,EAAC,uBAAW,CAAC,CAAA;6CAA2B,uBAAW;GAFrD,kBAAkB,CAoE9B","sourcesContent":["import { inject } from 'inversify';\nimport { provideFrameworkSingleton } from '@webpieces/core-context';\nimport { RequestContext } from '@webpieces/core-context';\nimport { LogManager } from '@webpieces/core-util';\nimport type { CallOptions } from 'google-gax';\nimport { TaskInvoker, JobReference, ScheduleInfo, TaskCustomizer } from './TaskTypes';\nimport { TaskName } from './TaskName';\nimport { ScheduleFrame, setScheduleFrame, clearScheduleFrame } from './ScheduleContext';\n\nconst log = LogManager.getLogger('CloudTaskScheduler');\n\n/**\n * Options for a scheduled task. These are QUEUE/TRANSPORT knobs (naming, deadline, the Google\n * request, gax) that belong on the enqueue CALL, never on the shared API method — the controller\n * implementing that method has no use for them. See CloudTaskScheduler's class doc for the full\n * rationale.\n *\n * Three levels, three owners:\n * - the `CloudTasksClient` (via an overridden `CloudTasksClientProvider`): the channel and client\n *   defaults (keepalive, endpoint, clientConfig);\n * - `gax` here, or `GcpTaskRegistry.setGax(...)`: how the ONE `createTask` RPC of this enqueue\n *   behaves. Set ⇒ YOU own timing: no webpieces retries, one attempt, under a safety cap;\n * - `customizeTask` here, or `GcpTaskRegistry.setCustomizer(...)`: the Google request itself.\n */\nexport class ScheduleOptions {\n    constructor(\n        /** How the task is named. Default: one generated UUID per logical enqueue, reused on retry. */\n        readonly taskName: TaskName = TaskName.generated(),\n        /** Per-task dispatch deadline in seconds (`task.dispatchDeadline`). */\n        readonly taskTimeoutSeconds?: number,\n        /** Changes the Google request on every attempt; NEVER gax. See {@link TaskCustomizer}. */\n        readonly customizeTask?: TaskCustomizer,\n        /** gax `CallOptions` for `createTask`. Set ⇒ you own timing/retries for this enqueue. */\n        readonly gax?: CallOptions,\n    ) {}\n}\n\n/**\n * Schedules Cloud Tasks. You wrap an enqueue-client call in a lambda so the shared\n * contract's method signature stays `foo(req)` on both client and controller; the\n * scheduling options ride out-of-band in the schedule frame:\n *\n *   await scheduler.addToQueue(() => taskClient.sendEmail(req));\n *   await scheduler.addToQueue(() => taskClient.sendEmail(req), new ScheduleOptions(TaskName.dedup(id), 900));\n *   await scheduler.schedule(() => taskClient.sendEmail(req), runAtEpochMs);\n *\n * Must be called inside an active RequestContext (a server request scope).\n *\n * WHY scheduling options are here and NOT parameters on the API method\n * ------------------------------------------------------------------------\n * The enqueue client and the controller implement the SAME abstract API method\n * (`sendEmail(req): Promise<void>`). Scheduling options — the task name, \"run in the\n * future\", `taskTimeoutSeconds` — are QUEUE/TRANSPORT concerns, not part of the\n * business contract, so they must not appear on the method signature:\n *\n *  - They are meaningless on the SERVER side. The controller's `sendEmail` just does\n *    the work (send the email). It has no use for a task name (a Cloud Tasks resource\n *    name), a future run-time (Cloud Tasks already delivered it), or a dispatch\n *    deadline. Putting them on the method would force the controller to accept and\n *    ignore transport metadata it can't act on.\n *  - They vary per CALL SITE, not per method. The same `sendEmail` might be enqueued\n *    plain in one place, deduped in another, and scheduled for later in a third. That\n *    is a property of THIS enqueue, not of the API — so it belongs on the enqueue\n *    call (the scheduler), exactly like Cloud Tasks itself separates the task's\n *    schedule/dedup/deadline from the HTTP body it delivers.\n *  - Symmetry with RPC: an http-client RPC call is `foo(req)` with no transport knobs\n *    in the contract; the async (queue) client keeps that same clean contract and\n *    moves the queue knobs to the scheduler wrapper.\n *\n * So the rule is: the API method is `method(req)` on BOTH sides forever; anything\n * queue-shaped (dedup, delay, timeout, cancel) lives on CloudTaskScheduler /\n * ScheduleOptions here, never on the API.\n */\n@provideFrameworkSingleton()\nexport class CloudTaskScheduler {\n    constructor(\n        @inject(TaskInvoker) private readonly invoker: TaskInvoker,\n    ) {}\n\n    /** Enqueue a task to run as soon as possible. Returns its JobReference. */\n    async addToQueue(runnable: () => Promise<void>, opts?: ScheduleOptions): Promise<JobReference> {\n        return this.runWithFrame(\n            this.infoFor(undefined, opts),\n            runnable,\n        );\n    }\n\n    /** Enqueue a task to run at an absolute epoch-millis time. Returns its JobReference. */\n    async schedule(\n        runnable: () => Promise<void>,\n        epochMsToRunAt: number,\n        opts?: ScheduleOptions,\n    ): Promise<JobReference> {\n        return this.runWithFrame(\n            this.infoFor(epochMsToRunAt, opts),\n            runnable,\n        );\n    }\n\n    /** Cancel a previously scheduled task. */\n    async cancelJob(ref: JobReference): Promise<void> {\n        await this.invoker.delete(ref);\n    }\n\n    /** No options = a generated name, no deadline, no customizer, webpieces-owned timing. */\n    private infoFor(epochMsToRunAt: number | undefined, opts: ScheduleOptions | undefined): ScheduleInfo {\n        const options = opts ?? new ScheduleOptions();\n        return new ScheduleInfo(\n            options.taskName,\n            epochMsToRunAt,\n            options.taskTimeoutSeconds,\n            options.customizeTask,\n            options.gax,\n        );\n    }\n\n    private async runWithFrame(\n        info: ScheduleInfo,\n        runnable: () => Promise<void>,\n    ): Promise<JobReference> {\n        if (!RequestContext.isActive()) {\n            throw new Error(\n                'CloudTaskScheduler must run inside a RequestContext (a server request scope).',\n            );\n        }\n        const frame = new ScheduleFrame(info);\n        setScheduleFrame(frame);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- always clear the frame; the runnable's error propagates unchanged\n        try {\n            await runnable();\n        } finally {\n            clearScheduleFrame();\n        }\n        if (!frame.jobRef) {\n            throw new Error(\n                'CloudTaskScheduler runnable did not enqueue a task — the lambda must call ' +\n                'a task-client method exactly once.',\n            );\n        }\n        log.debug(`scheduled task ${frame.jobRef.taskId}`);\n        return frame.jobRef;\n    }\n}\n"]}

package/src/CloudTasksClientProvider.d.ts

@@ -0,0 +1,29 @@
+import { CloudTasksClient } from '@google-cloud/tasks';
+/**
+ * Builds the ONE `CloudTasksClient` that `GcpTaskInvoker` enqueues through — the place for
+ * process-wide CLIENT settings: the gRPC channel (keepalive), the endpoint, `clientConfig`.
+ *
+ * The default builds `new CloudTasksClient()`, exactly what `GcpTaskInvoker` always did, so nobody has
+ * to bind anything. An app that needs client-level settings overrides it at startup:
+ *
+ * ```ts
+ * class KeepaliveCloudTasks extends CloudTasksClientProvider {
+ *     override create(): CloudTasksClient {
+ *         return new CloudTasksClient({ 'grpc.keepalive_time_ms': 30_000 });
+ *     }
+ * }
+ * (await options.rebind(CloudTasksClientProvider)).to(KeepaliveCloudTasks).inSingletonScope();
+ * ```
+ *
+ * Why a provider class and not an optional `CloudTasksClient` binding: the app container is created
+ * with inversify `autobind`, which auto-constructs ANY unbound class token — `@optional()` included —
+ * and `CloudTasksClient` has no injectable metadata, so resolving it unbound throws
+ * ("CloudTasksClient constructor requires at least 2 arguments"). A provider that is always bound
+ * keeps the same contract — optional to override, today's client by default — with nothing to throw.
+ *
+ * Per-CALL settings are not here: gax `CallOptions` belong on `ScheduleOptions.gax` /
+ * `GcpTaskRegistry.setGax`, and the Google request on a `TaskCustomizer`.
+ */
+export declare class CloudTasksClientProvider {
+    create(): CloudTasksClient;
+}

package/src/CloudTasksClientProvider.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudTasksClientProvider = void 0;
+const tslib_1 = require("tslib");
+const tasks_1 = require("@google-cloud/tasks");
+const core_context_1 = require("@webpieces/core-context");
+/**
+ * Builds the ONE `CloudTasksClient` that `GcpTaskInvoker` enqueues through — the place for
+ * process-wide CLIENT settings: the gRPC channel (keepalive), the endpoint, `clientConfig`.
+ *
+ * The default builds `new CloudTasksClient()`, exactly what `GcpTaskInvoker` always did, so nobody has
+ * to bind anything. An app that needs client-level settings overrides it at startup:
+ *
+ * ```ts
+ * class KeepaliveCloudTasks extends CloudTasksClientProvider {
+ *     override create(): CloudTasksClient {
+ *         return new CloudTasksClient({ 'grpc.keepalive_time_ms': 30_000 });
+ *     }
+ * }
+ * (await options.rebind(CloudTasksClientProvider)).to(KeepaliveCloudTasks).inSingletonScope();
+ * ```
+ *
+ * Why a provider class and not an optional `CloudTasksClient` binding: the app container is created
+ * with inversify `autobind`, which auto-constructs ANY unbound class token — `@optional()` included —
+ * and `CloudTasksClient` has no injectable metadata, so resolving it unbound throws
+ * ("CloudTasksClient constructor requires at least 2 arguments"). A provider that is always bound
+ * keeps the same contract — optional to override, today's client by default — with nothing to throw.
+ *
+ * Per-CALL settings are not here: gax `CallOptions` belong on `ScheduleOptions.gax` /
+ * `GcpTaskRegistry.setGax`, and the Google request on a `TaskCustomizer`.
+ */
+let CloudTasksClientProvider = class CloudTasksClientProvider {
+    create() {
+        return new tasks_1.CloudTasksClient();
+    }
+};
+exports.CloudTasksClientProvider = CloudTasksClientProvider;
+exports.CloudTasksClientProvider = CloudTasksClientProvider = tslib_1.__decorate([
+    (0, core_context_1.provideFrameworkSingleton)()
+], CloudTasksClientProvider);
+//# sourceMappingURL=CloudTasksClientProvider.js.map

package/src/CloudTasksClientProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudTasksClientProvider.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/CloudTasksClientProvider.ts"],"names":[],"mappings":";;;;AAAA,+CAAuD;AACvD,0DAAoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEI,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;IACjC,MAAM;QACF,OAAO,IAAI,wBAAgB,EAAE,CAAC;IAClC,CAAC;CACJ,CAAA;AAJY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,wCAAyB,GAAE;GACf,wBAAwB,CAIpC","sourcesContent":["import { CloudTasksClient } from '@google-cloud/tasks';\nimport { provideFrameworkSingleton } from '@webpieces/core-context';\n\n/**\n * Builds the ONE `CloudTasksClient` that `GcpTaskInvoker` enqueues through — the place for\n * process-wide CLIENT settings: the gRPC channel (keepalive), the endpoint, `clientConfig`.\n *\n * The default builds `new CloudTasksClient()`, exactly what `GcpTaskInvoker` always did, so nobody has\n * to bind anything. An app that needs client-level settings overrides it at startup:\n *\n * ```ts\n * class KeepaliveCloudTasks extends CloudTasksClientProvider {\n *     override create(): CloudTasksClient {\n *         return new CloudTasksClient({ 'grpc.keepalive_time_ms': 30_000 });\n *     }\n * }\n * (await options.rebind(CloudTasksClientProvider)).to(KeepaliveCloudTasks).inSingletonScope();\n * ```\n *\n * Why a provider class and not an optional `CloudTasksClient` binding: the app container is created\n * with inversify `autobind`, which auto-constructs ANY unbound class token — `@optional()` included —\n * and `CloudTasksClient` has no injectable metadata, so resolving it unbound throws\n * (\"CloudTasksClient constructor requires at least 2 arguments\"). A provider that is always bound\n * keeps the same contract — optional to override, today's client by default — with nothing to throw.\n *\n * Per-CALL settings are not here: gax `CallOptions` belong on `ScheduleOptions.gax` /\n * `GcpTaskRegistry.setGax`, and the Google request on a `TaskCustomizer`.\n */\n@provideFrameworkSingleton()\nexport class CloudTasksClientProvider {\n    create(): CloudTasksClient {\n        return new CloudTasksClient();\n    }\n}\n"]}

package/src/GcpTaskInvoker.d.ts

@@ -1,20 +1,43 @@
 import { AuthMeta, AuthMode } from '@webpieces/core-util';
 import { Secrets } from '@webpieces/core-util';
 import { TaskInvoker, TaskRequest, JobReference } from './TaskTypes';
+import { CloudTasksClientProvider } from './CloudTasksClientProvider';
 /**
  * TaskInvoker that enqueues to Google Cloud Tasks (`@google-cloud/tasks`). Builds an
  * HTTP-target task delivered as POST to `targetUrl + path`, authenticated per the
  * endpoint's auth mode (OIDC token minted as this service's runtime SA, or a
- * shared-secret header). The task name is derived from the dedup name for idempotency
- * (a duplicate enqueue is rejected ALREADY_EXISTS = idempotent success upstream).
+ * shared-secret header).
+ *
+ * ONE attempt per call, never a retry of its own:
+ * - it builds a FRESH `ICreateTaskRequest` (gax mutates what it is handed), names the task with the
+ *   id `TaskProxyClient` resolved once for the whole logical enqueue, then applies the effective
+ *   {@link TaskCustomizer} last;
+ * - it sends `createTask(request, { timeout: timeoutMs })` — a real gRPC deadline per attempt, and no
+ *   gax retry — unless the caller owns timing (`plan.gax` set), in which case it sends a shallow copy
+ *   of the caller's `CallOptions`, untouched;
+ * - it maps the gRPC failure with {@link GrpcErrorMapper}: ALREADY_EXISTS becomes
+ *   `TaskAlreadyExistsError` (success, upstream), UNAVAILABLE / DEADLINE_EXCEEDED /
+ *   RESOURCE_EXHAUSTED become transient webpieces errors that `RetryStrategy` retries.
+ *
+ * Cancellation: the gRPC deadline IS the attempt deadline, so on Path A gRPC itself cancels the RPC
+ * at the same moment `CallDeadline` gives up on it. `createTask`'s public promise carries no
+ * `cancel()` (the client chains `.then` on gax's cancellable promise, which drops it), so the abort
+ * signal is checked before sending rather than wired to a cancel.
  */
 export declare class GcpTaskInvoker extends TaskInvoker {
     private readonly secrets?;
     private readonly client;
-    constructor(secrets?: Secrets | undefined);
+    private readonly grpcErrorMapper;
+    constructor(clientProvider: CloudTasksClientProvider, secrets?: Secrets | undefined);
     selectAuthentication(meta: AuthMeta): AuthMode;
-    enqueue(request: TaskRequest): Promise<JobReference>;
+    enqueue(request: TaskRequest, timeoutMs: number, signal: AbortSignal): Promise<JobReference>;
     delete(ref: JobReference): Promise<void>;
+    /**
+     * A NEW object on every attempt. webpieces owns timing → `{ timeout }` only: a real gRPC deadline
+     * and no gax retry loop. The caller owns timing → a shallow copy of their options, so gax's own
+     * mutation (`otherArgs.headers`) never lands on an object the caller may reuse.
+     */
+    private callOptions;
     private buildTask;
     private applyAuth;
 }