@webpieces/cloudtasks-client 0.3.269

package/README.md

@@ -0,0 +1,23 @@
+# @webpieces/cloudtasks-client
+
+The Cloud Tasks twin of `@webpieces/http-client`. A `@PubSub` API contract is shared
+by the enqueue client and the controller, exactly like RPC — calling a method on the
+client **enqueues a Cloud Task** that is later delivered (POST) to the SAME endpoint,
+where it runs through the full server filter chain.
+
+```ts
+// one shared contract
+@PubSub() @AuthOidc() @ApiPath('/email')
+abstract class EmailApi { @Endpoint('/send') sendEmail(r: SendEmailRequest): Promise<void> {…} }
+
+// producer (inside a request → RequestContext active)
+await scheduler.addToQueue(() => emailTasks.sendEmail(req), { dedupName: req.id });
+```
+
+- `createTaskClient(Api, TaskClientConfig)` / `TaskClientCreator` — the enqueue proxy
+- `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)

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@webpieces/cloudtasks-client",
+  "version": "0.3.269",
+  "description": "Cloud Tasks enqueue client generated from a shared @PubSub API contract (twin of http-client)",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "author": "Dean Hiller",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deanhiller/webpieces-ts.git",
+    "directory": "packages/cloud/cloudtasks-client"
+  },
+  "keywords": [
+    "webpieces",
+    "gcp",
+    "cloud-tasks",
+    "pubsub",
+    "queue"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@webpieces/core-context": "0.3.269",
+    "@webpieces/core-util": "0.3.269",
+    "@webpieces/gcp-identity": "0.3.269",
+    "@google-cloud/tasks": "5.5.2",
+    "inversify": "7.10.4",
+    "reflect-metadata": "0.2.2"
+  }
+}

package/src/CloudTaskScheduler.d.ts

@@ -0,0 +1,60 @@
+import { TaskInvoker, JobReference } from './TaskTypes';
+/**
+ * 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.
+ */
+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);
+}
+/**
+ * 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.schedule(() => taskClient.sendEmail(req), runAtEpochMs);
+ *
+ * Must be called inside an active RequestContext (a server request scope).
+ *
+ * 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
+ * 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
+ *    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.
+ *  - They vary per CALL SITE, not per method. The same `sendEmail` might be enqueued
+ *    plain in one place, deduped in another, and scheduled for later in a third. That
+ *    is a property of THIS enqueue, not of the API — so it belongs on the enqueue
+ *    call (the scheduler), exactly like Cloud Tasks itself separates the task's
+ *    schedule/dedup/deadline from the HTTP body it delivers.
+ *  - Symmetry with RPC: an http-client RPC call is `foo(req)` with no transport knobs
+ *    in the contract; the async (queue) client keeps that same clean contract and
+ *    moves the queue knobs to the scheduler wrapper.
+ *
+ * So the rule is: the API method is `method(req)` on BOTH sides forever; anything
+ * queue-shaped (dedup, delay, timeout, cancel) lives on CloudTaskScheduler /
+ * ScheduleOptions here, never on the API.
+ */
+export declare class CloudTaskScheduler {
+    private readonly invoker;
+    constructor(invoker: TaskInvoker);
+    /** Enqueue a task to run as soon as possible. Returns its JobReference. */
+    addToQueue(runnable: () => Promise<void>, opts?: ScheduleOptions): Promise<JobReference>;
+    /** Enqueue a task to run at an absolute epoch-millis time. Returns its JobReference. */
+    schedule(runnable: () => Promise<void>, epochMsToRunAt: number, opts?: ScheduleOptions): Promise<JobReference>;
+    /** Cancel a previously scheduled task. */
+    cancelJob(ref: JobReference): Promise<void>;
+    private runWithFrame;
+}

package/src/CloudTaskScheduler.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudTaskScheduler = exports.ScheduleOptions = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+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 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.
+ */
+class ScheduleOptions {
+    /** Deterministic Cloud Task name → idempotent dedup (duplicate = ALREADY_EXISTS). */
+    dedupName;
+    /** Per-task dispatch deadline in seconds. */
+    taskTimeoutSeconds;
+    constructor(dedupName, taskTimeoutSeconds) {
+        this.dedupName = dedupName;
+        this.taskTimeoutSeconds = taskTimeoutSeconds;
+    }
+}
+exports.ScheduleOptions = ScheduleOptions;
+/**
+ * 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.schedule(() => taskClient.sendEmail(req), runAtEpochMs);
+ *
+ * Must be called inside an active RequestContext (a server request scope).
+ *
+ * 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
+ * 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
+ *    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.
+ *  - They vary per CALL SITE, not per method. The same `sendEmail` might be enqueued
+ *    plain in one place, deduped in another, and scheduled for later in a third. That
+ *    is a property of THIS enqueue, not of the API — so it belongs on the enqueue
+ *    call (the scheduler), exactly like Cloud Tasks itself separates the task's
+ *    schedule/dedup/deadline from the HTTP body it delivers.
+ *  - Symmetry with RPC: an http-client RPC call is `foo(req)` with no transport knobs
+ *    in the contract; the async (queue) client keeps that same clean contract and
+ *    moves the queue knobs to the scheduler wrapper.
+ *
+ * So the rule is: the API method is `method(req)` on BOTH sides forever; anything
+ * queue-shaped (dedup, delay, timeout, cancel) lives on CloudTaskScheduler /
+ * ScheduleOptions here, never on the API.
+ */
+let CloudTaskScheduler = class CloudTaskScheduler {
+    invoker;
+    constructor(invoker) {
+        this.invoker = invoker;
+    }
+    /** 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);
+    }
+    /** 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);
+    }
+    /** Cancel a previously scheduled task. */
+    async cancelJob(ref) {
+        await this.invoker.delete(ref);
+    }
+    async runWithFrame(info, runnable) {
+        if (!core_context_2.RequestContext.isActive()) {
+            throw new Error('CloudTaskScheduler must run inside a RequestContext (a server request scope).');
+        }
+        const frame = new ScheduleContext_1.ScheduleFrame(info);
+        (0, ScheduleContext_1.setScheduleFrame)(frame);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- always clear the frame; the runnable's error propagates unchanged
+        try {
+            await runnable();
+        }
+        finally {
+            (0, ScheduleContext_1.clearScheduleFrame)();
+        }
+        if (!frame.jobRef) {
+            throw new Error('CloudTaskScheduler runnable did not enqueue a task — the lambda must call ' +
+                'a task-client method exactly once.');
+        }
+        log.debug(`scheduled task ${frame.jobRef.taskId}`);
+        return frame.jobRef;
+    }
+};
+exports.CloudTaskScheduler = CloudTaskScheduler;
+exports.CloudTaskScheduler = CloudTaskScheduler = tslib_1.__decorate([
+    (0, core_context_1.provideSingleton)(),
+    (0, inversify_1.injectable)(),
+    tslib_1.__param(0, (0, inversify_1.inject)(TaskTypes_1.TaskInvoker)),
+    tslib_1.__metadata("design:paramtypes", [TaskTypes_1.TaskInvoker])
+], CloudTaskScheduler);
+//# sourceMappingURL=CloudTaskScheduler.js.map

package/src/CloudTaskScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudTaskScheduler.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/CloudTaskScheduler.ts"],"names":[],"mappings":";;;;AAAA,yCAA+C;AAC/C,0DAA2D;AAC3D,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;AAGI,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;IAF9B,IAAA,+BAAgB,GAAE;IAClB,IAAA,sBAAU,GAAE;IAGJ,mBAAA,IAAA,kBAAM,EAAC,uBAAW,CAAC,CAAA;6CAA2B,uBAAW;GAFrD,kBAAkB,CAwD9B","sourcesContent":["import { inject, injectable } from 'inversify';\nimport { provideSingleton } 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@provideSingleton()\n@injectable()\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"]}

package/src/GcpTaskInvoker.d.ts

@@ -0,0 +1,15 @@
+import { TaskInvoker, TaskRequest, JobReference } from './TaskTypes';
+/**
+ * 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).
+ */
+export declare class GcpTaskInvoker extends TaskInvoker {
+    private readonly client;
+    enqueue(request: TaskRequest): Promise<JobReference>;
+    delete(ref: JobReference): Promise<void>;
+    private buildTask;
+    private applyAuth;
+}

package/src/GcpTaskInvoker.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GcpTaskInvoker = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const tasks_1 = require("@google-cloud/tasks");
+const core_context_1 = require("@webpieces/core-context");
+const gcp_identity_1 = require("@webpieces/gcp-identity");
+const core_util_1 = require("@webpieces/core-util");
+const TaskTypes_1 = require("./TaskTypes");
+const log = core_util_1.LogManager.getLogger('GcpTaskInvoker');
+/**
+ * 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).
+ */
+let GcpTaskInvoker = class GcpTaskInvoker extends TaskTypes_1.TaskInvoker {
+    client = new tasks_1.CloudTasksClient();
+    async enqueue(request) {
+        const projectId = await (0, gcp_identity_1.getProjectId)();
+        const region = await (0, gcp_identity_1.getRegion)();
+        const parent = this.client.queuePath(projectId, region, request.queueName);
+        const task = await this.buildTask(request, parent);
+        const result = await this.client.createTask({ parent: parent, task: task });
+        const created = result[0];
+        const name = created.name ?? request.scheduleInfo.dedupName ?? 'unknown';
+        log.info(`enqueued cloud task ${name}`);
+        return new TaskTypes_1.JobReference(name);
+    }
+    async delete(ref) {
+        await this.client.deleteTask({ name: ref.taskId });
+    }
+    async buildTask(request, parent) {
+        const headers = new Map(request.contextHeaders);
+        headers.set('content-type', 'application/json');
+        const httpRequest = {
+            httpMethod: 'POST',
+            url: request.targetUrl + request.path,
+            headers: Object.fromEntries(headers),
+            body: Buffer.from(JSON.stringify(request.body ?? {}), 'utf8').toString('base64'),
+        };
+        await this.applyAuth(request, httpRequest, headers);
+        const task = { httpRequest: httpRequest };
+        if (request.scheduleInfo.dedupName) {
+            task.name = `${parent}/tasks/${request.scheduleInfo.dedupName}`;
+        }
+        if (request.scheduleInfo.epochMsToRunAt) {
+            task.scheduleTime = { seconds: Math.floor(request.scheduleInfo.epochMsToRunAt / 1000) };
+        }
+        if (request.scheduleInfo.taskTimeoutSeconds) {
+            task.dispatchDeadline = { seconds: request.scheduleInfo.taskTimeoutSeconds };
+        }
+        return task;
+    }
+    async applyAuth(request, httpRequest, headers) {
+        const mode = request.authMode;
+        if (mode.kind === 'oidc') {
+            httpRequest.oidcToken = {
+                serviceAccountEmail: await (0, gcp_identity_1.getRuntimeServiceAccountEmail)(),
+                audience: request.targetUrl,
+            };
+            return;
+        }
+        if (mode.kind === 'shared-secret') {
+            const secret = process.env[mode.secretEnv];
+            if (secret) {
+                headers.set('x-webpieces-shared-secret', secret);
+                httpRequest.headers = Object.fromEntries(headers);
+            }
+        }
+    }
+};
+exports.GcpTaskInvoker = GcpTaskInvoker;
+exports.GcpTaskInvoker = GcpTaskInvoker = tslib_1.__decorate([
+    (0, core_context_1.provideSingleton)(),
+    (0, inversify_1.injectable)()
+], GcpTaskInvoker);
+//# sourceMappingURL=GcpTaskInvoker.js.map

package/src/GcpTaskInvoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GcpTaskInvoker.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/GcpTaskInvoker.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable } from 'inversify';\nimport { CloudTasksClient, protos } from '@google-cloud/tasks';\nimport { provideSingleton } from '@webpieces/core-context';\nimport {\n    getProjectId,\n    getRegion,\n    getRuntimeServiceAccountEmail,\n} from '@webpieces/gcp-identity';\nimport { LogManager } from '@webpieces/core-util';\nimport { TaskInvoker, TaskRequest, JobReference } from './TaskTypes';\n\nconst log = LogManager.getLogger('GcpTaskInvoker');\n\ntype ITask = protos.google.cloud.tasks.v2.ITask;\n\n/**\n * TaskInvoker that enqueues to Google Cloud Tasks (`@google-cloud/tasks`). Builds an\n * HTTP-target task delivered as POST to `targetUrl + path`, authenticated per the\n * endpoint's auth mode (OIDC token minted as this service's runtime SA, or a\n * shared-secret header). The task name is derived from the dedup name for idempotency\n * (a duplicate enqueue is rejected ALREADY_EXISTS = idempotent success upstream).\n */\n@provideSingleton()\n@injectable()\nexport class GcpTaskInvoker extends TaskInvoker {\n    private readonly client = new CloudTasksClient();\n\n    override async enqueue(request: TaskRequest): Promise<JobReference> {\n        const projectId = await getProjectId();\n        const region = await getRegion();\n        const parent = this.client.queuePath(projectId, region, request.queueName);\n\n        const task = await this.buildTask(request, parent);\n        const result = await this.client.createTask({ parent: parent, task: task });\n        const created = result[0];\n        const name = created.name ?? request.scheduleInfo.dedupName ?? 'unknown';\n        log.info(`enqueued cloud task ${name}`);\n        return new JobReference(name);\n    }\n\n    override async delete(ref: JobReference): Promise<void> {\n        await this.client.deleteTask({ name: ref.taskId });\n    }\n\n    private async buildTask(request: TaskRequest, parent: string): Promise<ITask> {\n        const headers = new Map<string, string>(request.contextHeaders);\n        headers.set('content-type', 'application/json');\n\n        const httpRequest: protos.google.cloud.tasks.v2.IHttpRequest = {\n            httpMethod: 'POST',\n            url: request.targetUrl + request.path,\n            headers: Object.fromEntries(headers),\n            body: Buffer.from(JSON.stringify(request.body ?? {}), 'utf8').toString('base64'),\n        };\n        await this.applyAuth(request, httpRequest, headers);\n\n        const task: ITask = { httpRequest: httpRequest };\n        if (request.scheduleInfo.dedupName) {\n            task.name = `${parent}/tasks/${request.scheduleInfo.dedupName}`;\n        }\n        if (request.scheduleInfo.epochMsToRunAt) {\n            task.scheduleTime = { seconds: Math.floor(request.scheduleInfo.epochMsToRunAt / 1000) };\n        }\n        if (request.scheduleInfo.taskTimeoutSeconds) {\n            task.dispatchDeadline = { seconds: request.scheduleInfo.taskTimeoutSeconds };\n        }\n        return task;\n    }\n\n    private async applyAuth(\n        request: TaskRequest,\n        httpRequest: protos.google.cloud.tasks.v2.IHttpRequest,\n        headers: Map<string, string>,\n    ): Promise<void> {\n        const mode = request.authMode;\n        if (mode.kind === 'oidc') {\n            httpRequest.oidcToken = {\n                serviceAccountEmail: await getRuntimeServiceAccountEmail(),\n                audience: request.targetUrl,\n            };\n            return;\n        }\n        if (mode.kind === 'shared-secret') {\n            const secret = process.env[mode.secretEnv];\n            if (secret) {\n                headers.set('x-webpieces-shared-secret', secret);\n                httpRequest.headers = Object.fromEntries(headers);\n            }\n        }\n    }\n}\n"]}

package/src/InMemoryTaskInvoker.d.ts

@@ -0,0 +1,32 @@
+import { TaskInvoker, TaskRequest, JobReference } from './TaskTypes';
+/**
+ * TaskInvoker for tests + local dev — the in-memory-queue twin of GcpTaskInvoker
+ * (a TypeScript port of webpieces-java's LocalRemoteInvoker).
+ *
+ * Instead of enqueuing to Google Cloud Tasks, it drops the delivery onto an in-process
+ * timer queue and returns IMMEDIATELY (breaking from the caller, exactly like handing a
+ * task to Cloud Tasks). The queued job then delivers the task the SAME way real Cloud
+ * Tasks does: a plain HTTP POST to `targetUrl + path` with the JSON body and the
+ * synthesized delivery auth (OIDC bearer / shared-secret). It does NOT invoke the server
+ * in-process — the target may be a different process entirely — so the request travels
+ * over real HTTP (e.g. http://localhost:{port}/queue/path) and is served by the target's
+ * real routing + filter chain, giving production parity without GCP.
+ *
+ * Bind it (via appOverrides) in place of GcpTaskInvoker:
+ *   bind(TaskInvoker).to(InMemoryTaskInvoker)
+ */
+export declare class InMemoryTaskInvoker extends TaskInvoker {
+    private counter;
+    /** Scheduled (not-yet-delivered) jobs, so delete() can cancel them. */
+    private readonly pending;
+    enqueue(request: TaskRequest): Promise<JobReference>;
+    delete(ref: JobReference): Promise<void>;
+    /** ms until the scheduled run time (0 = as soon as possible / already due). */
+    private computeDelayMs;
+    /** Deliver the queued task over real HTTP, mirroring Cloud Tasks' HTTP callback. */
+    private deliver;
+    /** content-type + propagated context headers + synthesized delivery credential. */
+    private buildHeaders;
+    /** Synthesize the delivery credential Cloud Tasks would attach, per the auth mode. */
+    private attachAuth;
+}

package/src/InMemoryTaskInvoker.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryTaskInvoker = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const core_context_1 = require("@webpieces/core-context");
+const gcp_identity_1 = require("@webpieces/gcp-identity");
+const core_util_1 = require("@webpieces/core-util");
+const TaskTypes_1 = require("./TaskTypes");
+const log = core_util_1.LogManager.getLogger('InMemoryTaskInvoker');
+/**
+ * TaskInvoker for tests + local dev — the in-memory-queue twin of GcpTaskInvoker
+ * (a TypeScript port of webpieces-java's LocalRemoteInvoker).
+ *
+ * Instead of enqueuing to Google Cloud Tasks, it drops the delivery onto an in-process
+ * timer queue and returns IMMEDIATELY (breaking from the caller, exactly like handing a
+ * task to Cloud Tasks). The queued job then delivers the task the SAME way real Cloud
+ * Tasks does: a plain HTTP POST to `targetUrl + path` with the JSON body and the
+ * synthesized delivery auth (OIDC bearer / shared-secret). It does NOT invoke the server
+ * in-process — the target may be a different process entirely — so the request travels
+ * over real HTTP (e.g. http://localhost:{port}/queue/path) and is served by the target's
+ * real routing + filter chain, giving production parity without GCP.
+ *
+ * Bind it (via appOverrides) in place of GcpTaskInvoker:
+ *   bind(TaskInvoker).to(InMemoryTaskInvoker)
+ */
+let InMemoryTaskInvoker = class InMemoryTaskInvoker extends TaskTypes_1.TaskInvoker {
+    counter = 0;
+    /** Scheduled (not-yet-delivered) jobs, so delete() can cancel them. */
+    pending = new Map();
+    async enqueue(request) {
+        this.counter += 1;
+        const taskId = request.scheduleInfo.dedupName ?? `inmem-${request.queueName}-${this.counter}`;
+        const delayMs = this.computeDelayMs(request.scheduleInfo.epochMsToRunAt);
+        // Break from the caller: queue the HTTP delivery and return the reference NOW.
+        const timer = setTimeout(() => {
+            this.pending.delete(taskId);
+            void this.deliver(request, taskId);
+        }, delayMs);
+        // A queued task must not keep the process alive on its own.
+        timer.unref?.();
+        this.pending.set(taskId, timer);
+        log.debug(`queued local task ${taskId} -> ${request.targetUrl}${request.path} (delay ${delayMs}ms)`);
+        return new TaskTypes_1.JobReference(taskId);
+    }
+    async delete(ref) {
+        const timer = this.pending.get(ref.taskId);
+        if (timer) {
+            clearTimeout(timer);
+            this.pending.delete(ref.taskId);
+        }
+    }
+    /** ms until the scheduled run time (0 = as soon as possible / already due). */
+    computeDelayMs(epochMsToRunAt) {
+        if (epochMsToRunAt === undefined) {
+            return 0;
+        }
+        const delay = epochMsToRunAt - Date.now();
+        return delay > 0 ? delay : 0;
+    }
+    /** Deliver the queued task over real HTTP, mirroring Cloud Tasks' HTTP callback. */
+    async deliver(request, taskId) {
+        const url = `${request.targetUrl}${request.path}`;
+        const headers = await this.buildHeaders(request);
+        log.info(`delivering local task ${taskId}: POST ${url}`);
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- detached queue job: log delivery failure, never crash the queue
+        try {
+            // webpieces-disable no-fetch -- in-memory queue delivers over real HTTP like Cloud Tasks (no server to invoke in-process)
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: headers,
+                body: JSON.stringify(request.body ?? {}),
+            });
+            if (!response.ok) {
+                log.error(`local task ${taskId} delivery to ${url} failed: HTTP ${response.status}`);
+                return;
+            }
+            log.debug(`local task ${taskId} delivered: HTTP ${response.status}`);
+        }
+        catch (err) {
+            const error = (0, core_util_1.toError)(err);
+            log.error(`local task ${taskId} delivery to ${url} threw: ${error.message}`);
+        }
+    }
+    /** content-type + propagated context headers + synthesized delivery credential. */
+    async buildHeaders(request) {
+        const headers = { 'content-type': 'application/json' };
+        for (const entry of request.contextHeaders.entries()) {
+            headers[entry[0]] = entry[1];
+        }
+        await this.attachAuth(request, headers);
+        return headers;
+    }
+    /** Synthesize the delivery credential Cloud Tasks would attach, per the auth mode. */
+    async attachAuth(request, headers) {
+        const mode = request.authMode;
+        if (mode.kind === 'oidc') {
+            headers['authorization'] = `Bearer ${await (0, gcp_identity_1.mintIdToken)(request.targetUrl)}`;
+            return;
+        }
+        if (mode.kind === 'shared-secret') {
+            const secret = process.env[mode.secretEnv];
+            if (secret) {
+                headers['x-webpieces-shared-secret'] = secret;
+            }
+        }
+        // public / jwt → no service credential is synthesized.
+    }
+};
+exports.InMemoryTaskInvoker = InMemoryTaskInvoker;
+exports.InMemoryTaskInvoker = InMemoryTaskInvoker = tslib_1.__decorate([
+    (0, core_context_1.provideSingleton)(),
+    (0, inversify_1.injectable)()
+], InMemoryTaskInvoker);
+//# sourceMappingURL=InMemoryTaskInvoker.js.map

package/src/InMemoryTaskInvoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryTaskInvoker.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/InMemoryTaskInvoker.ts"],"names":[],"mappings":"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","sourcesContent":["import { injectable } from 'inversify';\nimport { provideSingleton } from '@webpieces/core-context';\nimport { mintIdToken } from '@webpieces/gcp-identity';\nimport { LogManager, toError } from '@webpieces/core-util';\nimport { TaskInvoker, TaskRequest, JobReference } from './TaskTypes';\n\nconst log = LogManager.getLogger('InMemoryTaskInvoker');\n\n/**\n * TaskInvoker for tests + local dev — the in-memory-queue twin of GcpTaskInvoker\n * (a TypeScript port of webpieces-java's LocalRemoteInvoker).\n *\n * Instead of enqueuing to Google Cloud Tasks, it drops the delivery onto an in-process\n * timer queue and returns IMMEDIATELY (breaking from the caller, exactly like handing a\n * task to Cloud Tasks). The queued job then delivers the task the SAME way real Cloud\n * Tasks does: a plain HTTP POST to `targetUrl + path` with the JSON body and the\n * synthesized delivery auth (OIDC bearer / shared-secret). It does NOT invoke the server\n * in-process — the target may be a different process entirely — so the request travels\n * over real HTTP (e.g. http://localhost:{port}/queue/path) and is served by the target's\n * real routing + filter chain, giving production parity without GCP.\n *\n * Bind it (via appOverrides) in place of GcpTaskInvoker:\n *   bind(TaskInvoker).to(InMemoryTaskInvoker)\n */\n@provideSingleton()\n@injectable()\nexport class InMemoryTaskInvoker extends TaskInvoker {\n    private counter = 0;\n    /** Scheduled (not-yet-delivered) jobs, so delete() can cancel them. */\n    private readonly pending = new Map<string, ReturnType<typeof setTimeout>>();\n\n    override async enqueue(request: TaskRequest): Promise<JobReference> {\n        this.counter += 1;\n        const taskId = request.scheduleInfo.dedupName ?? `inmem-${request.queueName}-${this.counter}`;\n        const delayMs = this.computeDelayMs(request.scheduleInfo.epochMsToRunAt);\n\n        // Break from the caller: queue the HTTP delivery and return the reference NOW.\n        const timer = setTimeout(() => {\n            this.pending.delete(taskId);\n            void this.deliver(request, taskId);\n        }, delayMs);\n        // A queued task must not keep the process alive on its own.\n        timer.unref?.();\n        this.pending.set(taskId, timer);\n\n        log.debug(`queued local task ${taskId} -> ${request.targetUrl}${request.path} (delay ${delayMs}ms)`);\n        return new JobReference(taskId);\n    }\n\n    override async delete(ref: JobReference): Promise<void> {\n        const timer = this.pending.get(ref.taskId);\n        if (timer) {\n            clearTimeout(timer);\n            this.pending.delete(ref.taskId);\n        }\n    }\n\n    /** ms until the scheduled run time (0 = as soon as possible / already due). */\n    private computeDelayMs(epochMsToRunAt?: number): number {\n        if (epochMsToRunAt === undefined) {\n            return 0;\n        }\n        const delay = epochMsToRunAt - Date.now();\n        return delay > 0 ? delay : 0;\n    }\n\n    /** Deliver the queued task over real HTTP, mirroring Cloud Tasks' HTTP callback. */\n    private async deliver(request: TaskRequest, taskId: string): Promise<void> {\n        const url = `${request.targetUrl}${request.path}`;\n        const headers = await this.buildHeaders(request);\n        log.info(`delivering local task ${taskId}: POST ${url}`);\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- detached queue job: log delivery failure, never crash the queue\n        try {\n            // webpieces-disable no-fetch -- in-memory queue delivers over real HTTP like Cloud Tasks (no server to invoke in-process)\n            const response = await fetch(url, {\n                method: 'POST',\n                headers: headers,\n                body: JSON.stringify(request.body ?? {}),\n            });\n            if (!response.ok) {\n                log.error(`local task ${taskId} delivery to ${url} failed: HTTP ${response.status}`);\n                return;\n            }\n            log.debug(`local task ${taskId} delivered: HTTP ${response.status}`);\n        } catch (err: unknown) {\n            const error = toError(err);\n            log.error(`local task ${taskId} delivery to ${url} threw: ${error.message}`);\n        }\n    }\n\n    /** content-type + propagated context headers + synthesized delivery credential. */\n    private async buildHeaders(request: TaskRequest): Promise<Record<string, string>> {\n        const headers: Record<string, string> = { 'content-type': 'application/json' };\n        for (const entry of request.contextHeaders.entries()) {\n            headers[entry[0]] = entry[1];\n        }\n        await this.attachAuth(request, headers);\n        return headers;\n    }\n\n    /** Synthesize the delivery credential Cloud Tasks would attach, per the auth mode. */\n    private async attachAuth(request: TaskRequest, headers: Record<string, string>): Promise<void> {\n        const mode = request.authMode;\n        if (mode.kind === 'oidc') {\n            headers['authorization'] = `Bearer ${await mintIdToken(request.targetUrl)}`;\n            return;\n        }\n        if (mode.kind === 'shared-secret') {\n            const secret = process.env[mode.secretEnv];\n            if (secret) {\n                headers['x-webpieces-shared-secret'] = secret;\n            }\n        }\n        // public / jwt → no service credential is synthesized.\n    }\n}\n"]}

package/src/ScheduleContext.d.ts

@@ -0,0 +1,18 @@
+import { ScheduleInfo, JobReference } from './TaskTypes';
+/**
+ * The scheduler→proxy bridge for the current async scope. The CloudTaskScheduler
+ * sets a frame around a runnable; the enqueue proxy reads its ScheduleInfo and, after
+ * enqueuing, writes back the JobReference. Stored in the request's AsyncLocalStorage
+ * frame so it never leaks across requests.
+ */
+export declare class ScheduleFrame {
+    info: ScheduleInfo;
+    jobRef?: JobReference;
+    constructor(info: ScheduleInfo);
+}
+/** Install a schedule frame for the current scope (called by the scheduler). */
+export declare function setScheduleFrame(frame: ScheduleFrame): void;
+/** The active schedule frame, or undefined if no scheduler lambda is running. */
+export declare function currentScheduleFrame(): ScheduleFrame | undefined;
+/** Remove the schedule frame (called by the scheduler in a finally). */
+export declare function clearScheduleFrame(): void;

package/src/ScheduleContext.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScheduleFrame = void 0;
+exports.setScheduleFrame = setScheduleFrame;
+exports.currentScheduleFrame = currentScheduleFrame;
+exports.clearScheduleFrame = clearScheduleFrame;
+const core_context_1 = require("@webpieces/core-context");
+/**
+ * The scheduler→proxy bridge for the current async scope. The CloudTaskScheduler
+ * sets a frame around a runnable; the enqueue proxy reads its ScheduleInfo and, after
+ * enqueuing, writes back the JobReference. Stored in the request's AsyncLocalStorage
+ * frame so it never leaks across requests.
+ */
+class ScheduleFrame {
+    info;
+    jobRef;
+    constructor(info) {
+        this.info = info;
+    }
+}
+exports.ScheduleFrame = ScheduleFrame;
+/** Non-transferrable context key for the active schedule frame. */
+const SCHEDULE_FRAME_KEY = '__webpieces_schedule_frame';
+/** Install a schedule frame for the current scope (called by the scheduler). */
+function setScheduleFrame(frame) {
+    core_context_1.RequestContext.put(SCHEDULE_FRAME_KEY, frame);
+}
+/** The active schedule frame, or undefined if no scheduler lambda is running. */
+function currentScheduleFrame() {
+    return core_context_1.RequestContext.get(SCHEDULE_FRAME_KEY);
+}
+/** Remove the schedule frame (called by the scheduler in a finally). */
+function clearScheduleFrame() {
+    core_context_1.RequestContext.remove(SCHEDULE_FRAME_KEY);
+}
+//# sourceMappingURL=ScheduleContext.js.map

package/src/ScheduleContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleContext.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/ScheduleContext.ts"],"names":[],"mappings":";;;AAsBA,4CAEC;AAGD,oDAEC;AAGD,gDAEC;AAlCD,0DAAyD;AAGzD;;;;;GAKG;AACH,MAAa,aAAa;IACtB,IAAI,CAAe;IACnB,MAAM,CAAgB;IAEtB,YAAY,IAAkB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ;AAPD,sCAOC;AAED,mEAAmE;AACnE,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAExD,gFAAgF;AAChF,SAAgB,gBAAgB,CAAC,KAAoB;IACjD,6BAAc,CAAC,GAAG,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,iFAAiF;AACjF,SAAgB,oBAAoB;IAChC,OAAO,6BAAc,CAAC,GAAG,CAAgB,kBAAkB,CAAC,CAAC;AACjE,CAAC;AAED,wEAAwE;AACxE,SAAgB,kBAAkB;IAC9B,6BAAc,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["import { RequestContext } from '@webpieces/core-context';\nimport { ScheduleInfo, JobReference } from './TaskTypes';\n\n/**\n * The scheduler→proxy bridge for the current async scope. The CloudTaskScheduler\n * sets a frame around a runnable; the enqueue proxy reads its ScheduleInfo and, after\n * enqueuing, writes back the JobReference. Stored in the request's AsyncLocalStorage\n * frame so it never leaks across requests.\n */\nexport class ScheduleFrame {\n    info: ScheduleInfo;\n    jobRef?: JobReference;\n\n    constructor(info: ScheduleInfo) {\n        this.info = info;\n    }\n}\n\n/** Non-transferrable context key for the active schedule frame. */\nconst SCHEDULE_FRAME_KEY = '__webpieces_schedule_frame';\n\n/** Install a schedule frame for the current scope (called by the scheduler). */\nexport function setScheduleFrame(frame: ScheduleFrame): void {\n    RequestContext.put(SCHEDULE_FRAME_KEY, frame);\n}\n\n/** The active schedule frame, or undefined if no scheduler lambda is running. */\nexport function currentScheduleFrame(): ScheduleFrame | undefined {\n    return RequestContext.get<ScheduleFrame>(SCHEDULE_FRAME_KEY);\n}\n\n/** Remove the schedule frame (called by the scheduler in a finally). */\nexport function clearScheduleFrame(): void {\n    RequestContext.remove(SCHEDULE_FRAME_KEY);\n}\n"]}

package/src/TaskClientCreator.d.ts

@@ -0,0 +1,24 @@
+import { HeaderRegistry } from '@webpieces/core-util';
+import { TaskInvoker } from './TaskTypes';
+/** Constructor whose prototype is T (the abstract @PubSub API class). */
+type ApiPrototype<T> = Function & {
+    prototype: T;
+};
+/**
+ * Injectable factory for Cloud Tasks enqueue clients — the twin of http-client's
+ * RpcClientCreator. Resolves the bound TaskInvoker + a context-propagating ContextMgr
+ * so a service just asks for a typed client:
+ *
+ *   const emailTasks = creator.createClientOnService(EmailApi, 'email-svc'); // self/other svc
+ */
+export declare class TaskClientCreator {
+    private readonly invoker;
+    private readonly registry;
+    constructor(invoker: TaskInvoker, registry: HeaderRegistry);
+    /** Enqueue client whose delivery URL is another Cloud Run service (by name). */
+    createClientOnService<T extends object>(apiClass: ApiPrototype<T>, serviceName: string): T;
+    /** Enqueue client whose delivery URL is a fixed base URL. */
+    createClientOnUrl<T extends object>(apiClass: ApiPrototype<T>, url: string): T;
+    private buildContextMgr;
+}
+export {};

package/src/TaskClientCreator.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskClientCreator = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const core_context_1 = require("@webpieces/core-context");
+const core_util_1 = require("@webpieces/core-util");
+const gcp_identity_1 = require("@webpieces/gcp-identity");
+const TaskTypes_1 = require("./TaskTypes");
+const TaskClientFactory_1 = require("./TaskClientFactory");
+/**
+ * Injectable factory for Cloud Tasks enqueue clients — the twin of http-client's
+ * RpcClientCreator. Resolves the bound TaskInvoker + a context-propagating ContextMgr
+ * so a service just asks for a typed client:
+ *
+ *   const emailTasks = creator.createClientOnService(EmailApi, 'email-svc'); // self/other svc
+ */
+let TaskClientCreator = class TaskClientCreator {
+    invoker;
+    registry;
+    constructor(invoker, registry) {
+        this.invoker = invoker;
+        this.registry = registry;
+    }
+    /** Enqueue client whose delivery URL is another Cloud Run service (by name). */
+    createClientOnService(apiClass, serviceName) {
+        const config = new TaskClientFactory_1.TaskClientConfig(() => (0, gcp_identity_1.getCloudRunUrl)(serviceName), this.invoker, this.buildContextMgr());
+        return (0, TaskClientFactory_1.createTaskClient)(apiClass, config);
+    }
+    /** Enqueue client whose delivery URL is a fixed base URL. */
+    createClientOnUrl(apiClass, url) {
+        const config = new TaskClientFactory_1.TaskClientConfig(url, this.invoker, this.buildContextMgr());
+        return (0, TaskClientFactory_1.createTaskClient)(apiClass, config);
+    }
+    buildContextMgr() {
+        return new core_context_1.ContextMgr(new core_context_1.RequestContextReader(), this.registry);
+    }
+};
+exports.TaskClientCreator = TaskClientCreator;
+exports.TaskClientCreator = TaskClientCreator = tslib_1.__decorate([
+    (0, core_context_1.provideSingleton)(),
+    (0, inversify_1.injectable)(),
+    tslib_1.__param(0, (0, inversify_1.inject)(TaskTypes_1.TaskInvoker)),
+    tslib_1.__param(1, (0, inversify_1.inject)(core_util_1.HeaderRegistry)),
+    tslib_1.__metadata("design:paramtypes", [TaskTypes_1.TaskInvoker,
+        core_util_1.HeaderRegistry])
+], TaskClientCreator);
+//# sourceMappingURL=TaskClientCreator.js.map

package/src/TaskClientCreator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskClientCreator.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskClientCreator.ts"],"names":[],"mappings":";;;;AAAA,yCAA+C;AAC/C,0DAA6F;AAC7F,oDAAsD;AACtD,0DAAyD;AACzD,2CAA0C;AAC1C,2DAAyE;AAKzE;;;;;;GAMG;AAGI,IAAM,iBAAiB,GAAvB,MAAM,iBAAiB;IAEgB;IACG;IAF7C,YAC0C,OAAoB,EACjB,QAAwB;QAD3B,YAAO,GAAP,OAAO,CAAa;QACjB,aAAQ,GAAR,QAAQ,CAAgB;IAClE,CAAC;IAEJ,gFAAgF;IAChF,qBAAqB,CAAmB,QAAyB,EAAE,WAAmB;QAClF,MAAM,MAAM,GAAG,IAAI,oCAAgB,CAC/B,GAAG,EAAE,CAAC,IAAA,6BAAc,EAAC,WAAW,CAAC,EACjC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,eAAe,EAAE,CACzB,CAAC;QACF,OAAO,IAAA,oCAAgB,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,6DAA6D;IAC7D,iBAAiB,CAAmB,QAAyB,EAAE,GAAW;QACtE,MAAM,MAAM,GAAG,IAAI,oCAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QAC/E,OAAO,IAAA,oCAAgB,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAEO,eAAe;QACnB,OAAO,IAAI,yBAAU,CAAC,IAAI,mCAAoB,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrE,CAAC;CACJ,CAAA;AAzBY,8CAAiB;4BAAjB,iBAAiB;IAF7B,IAAA,+BAAgB,GAAE;IAClB,IAAA,sBAAU,GAAE;IAGJ,mBAAA,IAAA,kBAAM,EAAC,uBAAW,CAAC,CAAA;IACnB,mBAAA,IAAA,kBAAM,EAAC,0BAAc,CAAC,CAAA;6CADwB,uBAAW;QACP,0BAAc;GAH5D,iBAAiB,CAyB7B","sourcesContent":["import { inject, injectable } from 'inversify';\nimport { provideSingleton, RequestContextReader, ContextMgr } from '@webpieces/core-context';\nimport { HeaderRegistry } from '@webpieces/core-util';\nimport { getCloudRunUrl } from '@webpieces/gcp-identity';\nimport { TaskInvoker } from './TaskTypes';\nimport { createTaskClient, TaskClientConfig } from './TaskClientFactory';\n\n/** Constructor whose prototype is T (the abstract @PubSub API class). */\ntype ApiPrototype<T> = Function & { prototype: T };\n\n/**\n * Injectable factory for Cloud Tasks enqueue clients — the twin of http-client's\n * RpcClientCreator. Resolves the bound TaskInvoker + a context-propagating ContextMgr\n * so a service just asks for a typed client:\n *\n *   const emailTasks = creator.createClientOnService(EmailApi, 'email-svc'); // self/other svc\n */\n@provideSingleton()\n@injectable()\nexport class TaskClientCreator {\n    constructor(\n        @inject(TaskInvoker) private readonly invoker: TaskInvoker,\n        @inject(HeaderRegistry) private readonly registry: HeaderRegistry,\n    ) {}\n\n    /** Enqueue client whose delivery URL is another Cloud Run service (by name). */\n    createClientOnService<T extends object>(apiClass: ApiPrototype<T>, serviceName: string): T {\n        const config = new TaskClientConfig(\n            () => getCloudRunUrl(serviceName),\n            this.invoker,\n            this.buildContextMgr(),\n        );\n        return createTaskClient(apiClass, config);\n    }\n\n    /** Enqueue client whose delivery URL is a fixed base URL. */\n    createClientOnUrl<T extends object>(apiClass: ApiPrototype<T>, url: string): T {\n        const config = new TaskClientConfig(url, this.invoker, this.buildContextMgr());\n        return createTaskClient(apiClass, config);\n    }\n\n    private buildContextMgr(): ContextMgr {\n        return new ContextMgr(new RequestContextReader(), this.registry);\n    }\n}\n"]}

package/src/TaskClientFactory.d.ts

@@ -0,0 +1,27 @@
+import { ContextMgr } from '@webpieces/core-context';
+import { TaskInvoker } from './TaskTypes';
+/** Constructor whose prototype is T (the abstract API class). */
+type ApiPrototype<T> = Function & {
+    prototype: T;
+};
+/** Configuration for an enqueue client. */
+export declare class TaskClientConfig {
+    /** Callee base URL, or an async resolver (e.g. getCloudRunUrl(serviceName)). */
+    targetUrl: string | (() => Promise<string>);
+    /** The transport that enqueues the task (GcpTaskInvoker / InMemoryTaskInvoker). */
+    invoker: TaskInvoker;
+    /** Optional context propagation (txId/requestId/tenant…) onto the task headers. */
+    contextMgr?: ContextMgr;
+    constructor(targetUrl: string | (() => Promise<string>), invoker: TaskInvoker, contextMgr?: ContextMgr);
+}
+/**
+ * Create a Cloud Tasks enqueue client from a shared @PubSub API contract. Calling a
+ * method ENQUEUES a task (it does not call remotely); the task is later delivered to
+ * the same endpoint's controller through the full server filter chain.
+ *
+ * Must be called inside a CloudTaskScheduler lambda (which supplies the ScheduleInfo)
+ * within an active RequestContext, e.g.:
+ *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });
+ */
+export declare function createTaskClient<T extends object>(apiClass: ApiPrototype<T>, config: TaskClientConfig): T;
+export {};

package/src/TaskClientFactory.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskClientConfig = void 0;
+exports.createTaskClient = createTaskClient;
+const core_util_1 = require("@webpieces/core-util");
+const core_util_2 = require("@webpieces/core-util");
+const TaskTypes_1 = require("./TaskTypes");
+const ScheduleContext_1 = require("./ScheduleContext");
+const log = core_util_2.LogManager.getLogger('TaskClientFactory');
+/**
+ * Auth headers are NEVER propagated from the caller's context onto an enqueued task:
+ * the caller's inbound user JWT / secret must not leak to an internal service, and
+ * the invoker mints fresh delivery auth (OIDC / shared-secret) per the endpoint's mode.
+ */
+const AUTH_HEADER_NAMES = new Set(['authorization', 'x-webpieces-shared-secret']);
+/**
+ * Properties DI frameworks / Promise checks / serializers probe on the proxy; return
+ * undefined instead of treating them as endpoints. Mirrors http-client's ClientFactory.
+ */
+const FRAMEWORK_INSPECTION_PROPERTIES = new Set([
+    'constructor', 'prototype', '__proto__', 'name', 'then', 'catch', 'finally',
+    'toJSON', 'valueOf', 'toString', 'nodeType', 'tagName', '$$typeof',
+]);
+/** Configuration for an enqueue client. */
+class TaskClientConfig {
+    /** Callee base URL, or an async resolver (e.g. getCloudRunUrl(serviceName)). */
+    targetUrl;
+    /** The transport that enqueues the task (GcpTaskInvoker / InMemoryTaskInvoker). */
+    invoker;
+    /** Optional context propagation (txId/requestId/tenant…) onto the task headers. */
+    contextMgr;
+    constructor(targetUrl, invoker, contextMgr) {
+        this.targetUrl = targetUrl;
+        this.invoker = invoker;
+        this.contextMgr = contextMgr;
+    }
+}
+exports.TaskClientConfig = TaskClientConfig;
+/** Per-endpoint routing plan resolved once from the contract's decorators. */
+class EndpointPlan {
+    path;
+    queueName;
+    authMode;
+    constructor(path, queueName, authMode) {
+        this.path = path;
+        this.queueName = queueName;
+        this.authMode = authMode;
+    }
+}
+/**
+ * Create a Cloud Tasks enqueue client from a shared @PubSub API contract. Calling a
+ * method ENQUEUES a task (it does not call remotely); the task is later delivered to
+ * the same endpoint's controller through the full server filter chain.
+ *
+ * Must be called inside a CloudTaskScheduler lambda (which supplies the ScheduleInfo)
+ * within an active RequestContext, e.g.:
+ *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });
+ */
+function createTaskClient(apiClass, config) {
+    if (!(0, core_util_1.isApiPath)(apiClass)) {
+        throw new Error(`Class ${apiClass.name || 'Unknown'} must be decorated with @ApiPath()`);
+    }
+    (0, core_util_1.assertPubSubConventions)(apiClass);
+    (0, core_util_1.assertEveryEndpointHasAuthMode)(apiClass);
+    const basePath = (0, core_util_1.getApiPath)(apiClass) ?? '';
+    const endpoints = (0, core_util_1.getEndpoints)(apiClass) ?? {};
+    const plans = buildPlans(apiClass, basePath, endpoints);
+    return new Proxy({}, {
+        // webpieces-disable no-any-unknown -- proxy get trap returns either a method or undefined
+        get(_target, prop) {
+            if (typeof prop !== 'string' || FRAMEWORK_INSPECTION_PROPERTIES.has(prop)) {
+                return undefined;
+            }
+            const plan = plans.get(prop);
+            if (!plan) {
+                throw new Error(`No @PubSub endpoint '${prop}' on ${apiClass.name || 'Unknown'}. ` +
+                    `Check for typos or a missing @Endpoint() decorator.`);
+            }
+            // webpieces-disable no-any-unknown -- request DTO type is erased at the proxy layer
+            return (requestDto) => enqueue(config, plan, requestDto);
+        },
+    });
+}
+function buildPlans(apiClass, basePath, endpoints) {
+    const plans = new Map();
+    for (const methodName of Object.keys(endpoints)) {
+        const authMode = (0, core_util_1.getAuthMode)(apiClass, methodName);
+        if (!authMode) {
+            throw new Error(`Endpoint '${methodName}' on ${apiClass.name} has no auth mode`);
+        }
+        const plan = new EndpointPlan(basePath + endpoints[methodName], (0, core_util_1.getQueueName)(apiClass, methodName), authMode);
+        plans.set(methodName, plan);
+    }
+    return plans;
+}
+async function enqueue(config, plan, 
+// webpieces-disable no-any-unknown -- request DTO type is erased at the proxy layer
+requestDto) {
+    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 }).');
+    }
+    const targetUrl = typeof config.targetUrl === 'string'
+        ? config.targetUrl
+        : await config.targetUrl();
+    const contextHeaders = buildContextHeaders(config.contextMgr);
+    const request = new TaskTypes_1.TaskRequest(targetUrl, plan.path, plan.queueName, requestDto, contextHeaders, plan.authMode, frame.info ?? new TaskTypes_1.ScheduleInfo());
+    log.debug(`enqueue task ${plan.queueName} -> ${targetUrl}${plan.path}`);
+    frame.jobRef = await config.invoker.enqueue(request);
+}
+function buildContextHeaders(contextMgr) {
+    const headers = new Map();
+    if (!contextMgr) {
+        return headers;
+    }
+    for (const entry of contextMgr.buildOutboundHeaders().entries()) {
+        if (!AUTH_HEADER_NAMES.has(entry[0].toLowerCase())) {
+            headers.set(entry[0], entry[1]);
+        }
+    }
+    return headers;
+}
+//# sourceMappingURL=TaskClientFactory.js.map

package/src/TaskClientFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskClientFactory.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskClientFactory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    isApiPath,\n    getApiPath,\n    getEndpoints,\n    getAuthMode,\n    getQueueName,\n    assertPubSubConventions,\n    assertEveryEndpointHasAuthMode,\n    AuthMode,\n} from '@webpieces/core-util';\nimport { ContextMgr } from '@webpieces/core-context';\nimport { LogManager } from '@webpieces/core-util';\nimport { TaskInvoker, TaskRequest, ScheduleInfo } from './TaskTypes';\nimport { currentScheduleFrame } from './ScheduleContext';\n\nconst log = LogManager.getLogger('TaskClientFactory');\n\n/** Constructor whose prototype is T (the abstract API class). */\ntype ApiPrototype<T> = Function & { prototype: T };\n\n/**\n * Auth headers are NEVER propagated from the caller's context onto an enqueued task:\n * the caller's inbound user JWT / secret must not leak to an internal service, and\n * the invoker mints fresh delivery auth (OIDC / shared-secret) per the endpoint's mode.\n */\nconst AUTH_HEADER_NAMES = new Set<string>(['authorization', 'x-webpieces-shared-secret']);\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's ClientFactory.\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/** Configuration for an enqueue client. */\nexport class TaskClientConfig {\n    /** Callee base URL, or an async resolver (e.g. getCloudRunUrl(serviceName)). */\n    targetUrl: string | (() => Promise<string>);\n    /** The transport that enqueues the task (GcpTaskInvoker / InMemoryTaskInvoker). */\n    invoker: TaskInvoker;\n    /** Optional context propagation (txId/requestId/tenant…) onto the task headers. */\n    contextMgr?: ContextMgr;\n\n    constructor(\n        targetUrl: string | (() => Promise<string>),\n        invoker: TaskInvoker,\n        contextMgr?: ContextMgr,\n    ) {\n        this.targetUrl = targetUrl;\n        this.invoker = invoker;\n        this.contextMgr = contextMgr;\n    }\n}\n\n/** Per-endpoint routing plan resolved once from the contract's decorators. */\nclass EndpointPlan {\n    path: string;\n    queueName: string;\n    authMode: AuthMode;\n\n    constructor(path: string, queueName: string, authMode: AuthMode) {\n        this.path = path;\n        this.queueName = queueName;\n        this.authMode = authMode;\n    }\n}\n\n/**\n * Create a Cloud Tasks enqueue client from a shared @PubSub API contract. Calling a\n * method 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 * Must be called inside a CloudTaskScheduler lambda (which supplies the ScheduleInfo)\n * within an active RequestContext, e.g.:\n *   scheduler.addToQueue(() => taskClient.foo(req), { dedupName });\n */\nexport function createTaskClient<T extends object>(\n    apiClass: ApiPrototype<T>,\n    config: TaskClientConfig,\n): T {\n    if (!isApiPath(apiClass)) {\n        throw new Error(`Class ${apiClass.name || 'Unknown'} must be decorated with @ApiPath()`);\n    }\n    assertPubSubConventions(apiClass);\n    assertEveryEndpointHasAuthMode(apiClass);\n\n    const basePath = getApiPath(apiClass) ?? '';\n    const endpoints = getEndpoints(apiClass) ?? {};\n    const plans = buildPlans(apiClass, basePath, endpoints);\n\n    return new Proxy({} as T, {\n        // webpieces-disable no-any-unknown -- proxy get trap returns either a 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            const plan = plans.get(prop);\n            if (!plan) {\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            // webpieces-disable no-any-unknown -- request DTO type is erased at the proxy layer\n            return (requestDto: unknown): Promise<void> => enqueue(config, plan, requestDto);\n        },\n    });\n}\n\nfunction buildPlans(\n    apiClass: Function,\n    basePath: string,\n    endpoints: Record<string, string>,\n): Map<string, EndpointPlan> {\n    const plans = new Map<string, EndpointPlan>();\n    for (const methodName of Object.keys(endpoints)) {\n        const authMode = getAuthMode(apiClass, methodName);\n        if (!authMode) {\n            throw new Error(`Endpoint '${methodName}' on ${apiClass.name} has no auth mode`);\n        }\n        const plan = new EndpointPlan(\n            basePath + endpoints[methodName],\n            getQueueName(apiClass, methodName),\n            authMode,\n        );\n        plans.set(methodName, plan);\n    }\n    return plans;\n}\n\nasync function enqueue(\n    config: TaskClientConfig,\n    plan: EndpointPlan,\n    // webpieces-disable no-any-unknown -- request DTO type is erased at the proxy layer\n    requestDto: unknown,\n): Promise<void> {\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    const targetUrl = typeof config.targetUrl === 'string'\n        ? config.targetUrl\n        : await config.targetUrl();\n\n    const contextHeaders = buildContextHeaders(config.contextMgr);\n\n    const request = new TaskRequest(\n        targetUrl,\n        plan.path,\n        plan.queueName,\n        requestDto,\n        contextHeaders,\n        plan.authMode,\n        frame.info ?? new ScheduleInfo(),\n    );\n\n    log.debug(`enqueue task ${plan.queueName} -> ${targetUrl}${plan.path}`);\n    frame.jobRef = await config.invoker.enqueue(request);\n}\n\nfunction buildContextHeaders(contextMgr?: ContextMgr): Map<string, string> {\n    const headers = new Map<string, string>();\n    if (!contextMgr) {\n        return headers;\n    }\n    for (const entry of contextMgr.buildOutboundHeaders().entries()) {\n        if (!AUTH_HEADER_NAMES.has(entry[0].toLowerCase())) {\n            headers.set(entry[0], entry[1]);\n        }\n    }\n    return headers;\n}\n"]}

package/src/TaskTypes.d.ts

@@ -0,0 +1,55 @@
+import { AuthMode } from '@webpieces/core-util';
+/**
+ * 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 {
+    /** Absolute epoch-millis to run at; omitted = run as soon as possible. */
+    epochMsToRunAt?: number;
+    /** Per-task dispatch deadline in seconds. */
+    taskTimeoutSeconds?: number;
+    /**
+     * Deterministic dedup name → the Cloud Task resource name. A second enqueue with
+     * the same name is rejected ALREADY_EXISTS (treated as success = idempotent).
+     */
+    dedupName?: string;
+    constructor(epochMsToRunAt?: number, taskTimeoutSeconds?: number, dedupName?: string);
+}
+/** Handle to an enqueued task (its Cloud Tasks id), returned by the scheduler. */
+export declare class JobReference {
+    taskId: string;
+    constructor(taskId: string);
+}
+/**
+ * Everything an invoker needs to enqueue one task. Built by the enqueue proxy from
+ * the shared @PubSub contract's decorators + the ambient RequestContext.
+ */
+export declare class TaskRequest {
+    /** 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 (dedup name, run-at, timeout). */
+    scheduleInfo: ScheduleInfo;
+    constructor(targetUrl: string, path: string, queueName: string, body: unknown, contextHeaders: Map<string, string>, authMode: AuthMode, scheduleInfo: ScheduleInfo);
+}
+/**
+ * The transport that actually enqueues a task. Abstract class so it doubles as the
+ * inversify DI token (inject by type, no Symbol). Bind GcpTaskInvoker in prod or
+ * 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.
+ */
+export declare abstract class TaskInvoker {
+    abstract enqueue(request: TaskRequest): Promise<JobReference>;
+    abstract delete(ref: JobReference): Promise<void>;
+}

package/src/TaskTypes.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskInvoker = exports.TaskRequest = exports.JobReference = exports.ScheduleInfo = void 0;
+/**
+ * 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.
+ */
+class ScheduleInfo {
+    /** Absolute epoch-millis to run at; omitted = run as soon as possible. */
+    epochMsToRunAt;
+    /** Per-task dispatch deadline in seconds. */
+    taskTimeoutSeconds;
+    /**
+     * Deterministic dedup name → the Cloud Task resource name. A second enqueue with
+     * the same name is rejected ALREADY_EXISTS (treated as success = idempotent).
+     */
+    dedupName;
+    constructor(epochMsToRunAt, taskTimeoutSeconds, dedupName) {
+        this.epochMsToRunAt = epochMsToRunAt;
+        this.taskTimeoutSeconds = taskTimeoutSeconds;
+        this.dedupName = dedupName;
+    }
+}
+exports.ScheduleInfo = ScheduleInfo;
+/** Handle to an enqueued task (its Cloud Tasks id), returned by the scheduler. */
+class JobReference {
+    taskId;
+    constructor(taskId) {
+        this.taskId = taskId;
+    }
+}
+exports.JobReference = JobReference;
+/**
+ * Everything an invoker needs to enqueue one task. Built by the enqueue proxy from
+ * the shared @PubSub contract's decorators + the ambient RequestContext.
+ */
+class TaskRequest {
+    /** Callee base URL (e.g. https://email-svc-123.us-central1.run.app). */
+    targetUrl;
+    /** Endpoint path the task is delivered to (basePath + endpoint, e.g. /email/send). */
+    path;
+    /** Cloud Tasks queue name (getQueueName: @Queue override or `${Api}-${method}`). */
+    queueName;
+    /** The request DTO (serialized to the POST body on delivery). */
+    // webpieces-disable no-any-unknown -- request DTO type is erased at the task boundary
+    body;
+    /** Context headers to propagate (txId/requestId/tenant…), already resolved. */
+    contextHeaders;
+    /** The endpoint's auth mode — how the invoker authenticates delivery. */
+    authMode;
+    /** Scheduling options (dedup name, run-at, timeout). */
+    scheduleInfo;
+    constructor(targetUrl, path, queueName, 
+    // webpieces-disable no-any-unknown -- request DTO type is erased at the task boundary
+    body, contextHeaders, authMode, scheduleInfo) {
+        this.targetUrl = targetUrl;
+        this.path = path;
+        this.queueName = queueName;
+        this.body = body;
+        this.contextHeaders = contextHeaders;
+        this.authMode = authMode;
+        this.scheduleInfo = scheduleInfo;
+    }
+}
+exports.TaskRequest = TaskRequest;
+/**
+ * The transport that actually enqueues a task. Abstract class so it doubles as the
+ * inversify DI token (inject by type, no Symbol). Bind GcpTaskInvoker in prod or
+ * 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.
+ */
+class TaskInvoker {
+}
+exports.TaskInvoker = TaskInvoker;
+//# sourceMappingURL=TaskTypes.js.map

package/src/TaskTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaskTypes.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/TaskTypes.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACH,MAAa,YAAY;IACrB,0EAA0E;IAC1E,cAAc,CAAU;IACxB,6CAA6C;IAC7C,kBAAkB,CAAU;IAC5B;;;OAGG;IACH,SAAS,CAAU;IAEnB,YAAY,cAAuB,EAAE,kBAA2B,EAAE,SAAkB;QAChF,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ;AAhBD,oCAgBC;AAED,kFAAkF;AAClF,MAAa,YAAY;IACrB,MAAM,CAAS;IAEf,YAAY,MAAc;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;CACJ;AAND,oCAMC;AAED;;;GAGG;AACH,MAAa,WAAW;IACpB,wEAAwE;IACxE,SAAS,CAAS;IAClB,sFAAsF;IACtF,IAAI,CAAS;IACb,oFAAoF;IACpF,SAAS,CAAS;IAClB,iEAAiE;IACjE,sFAAsF;IACtF,IAAI,CAAU;IACd,+EAA+E;IAC/E,cAAc,CAAsB;IACpC,yEAAyE;IACzE,QAAQ,CAAW;IACnB,wDAAwD;IACxD,YAAY,CAAe;IAE3B,YACI,SAAiB,EACjB,IAAY,EACZ,SAAiB;IACjB,sFAAsF;IACtF,IAAa,EACb,cAAmC,EACnC,QAAkB,EAClB,YAA0B;QAE1B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACrC,CAAC;CACJ;AAnCD,kCAmCC;AAED;;;;;;GAMG;AACH,MAAsB,WAAW;CAGhC;AAHD,kCAGC","sourcesContent":["import { AuthMode } from '@webpieces/core-util';\n\n/**\n * Scheduling options for an enqueued task. Travels out-of-band (via the scheduler\n * frame in RequestContext) so the shared API method signature stays `foo(req)` on\n * both the client and the controller.\n */\nexport class ScheduleInfo {\n    /** Absolute epoch-millis to run at; omitted = run as soon as possible. */\n    epochMsToRunAt?: number;\n    /** Per-task dispatch deadline in seconds. */\n    taskTimeoutSeconds?: number;\n    /**\n     * Deterministic dedup name → the Cloud Task resource name. A second enqueue with\n     * the same name is rejected ALREADY_EXISTS (treated as success = idempotent).\n     */\n    dedupName?: string;\n\n    constructor(epochMsToRunAt?: number, taskTimeoutSeconds?: number, dedupName?: string) {\n        this.epochMsToRunAt = epochMsToRunAt;\n        this.taskTimeoutSeconds = taskTimeoutSeconds;\n        this.dedupName = dedupName;\n    }\n}\n\n/** Handle to an enqueued task (its Cloud Tasks id), returned by the scheduler. */\nexport class JobReference {\n    taskId: string;\n\n    constructor(taskId: string) {\n        this.taskId = taskId;\n    }\n}\n\n/**\n * Everything an invoker needs to enqueue one task. Built by the enqueue proxy from\n * the shared @PubSub contract's decorators + the ambient RequestContext.\n */\nexport class TaskRequest {\n    /** Callee base URL (e.g. https://email-svc-123.us-central1.run.app). */\n    targetUrl: string;\n    /** Endpoint path the task is delivered to (basePath + endpoint, e.g. /email/send). */\n    path: string;\n    /** Cloud Tasks queue name (getQueueName: @Queue override or `${Api}-${method}`). */\n    queueName: string;\n    /** The request DTO (serialized to the POST body on delivery). */\n    // webpieces-disable no-any-unknown -- request DTO type is erased at the task boundary\n    body: unknown;\n    /** Context headers to propagate (txId/requestId/tenant…), already resolved. */\n    contextHeaders: Map<string, string>;\n    /** The endpoint's auth mode — how the invoker authenticates delivery. */\n    authMode: AuthMode;\n    /** Scheduling options (dedup name, run-at, timeout). */\n    scheduleInfo: ScheduleInfo;\n\n    constructor(\n        targetUrl: string,\n        path: string,\n        queueName: string,\n        // webpieces-disable no-any-unknown -- request DTO type is erased at the task boundary\n        body: unknown,\n        contextHeaders: Map<string, string>,\n        authMode: AuthMode,\n        scheduleInfo: ScheduleInfo,\n    ) {\n        this.targetUrl = targetUrl;\n        this.path = path;\n        this.queueName = queueName;\n        this.body = body;\n        this.contextHeaders = contextHeaders;\n        this.authMode = authMode;\n        this.scheduleInfo = scheduleInfo;\n    }\n}\n\n/**\n * The transport that actually enqueues a task. Abstract class so it doubles as the\n * inversify DI token (inject by type, no Symbol). Bind GcpTaskInvoker in prod or\n * InMemoryTaskInvoker in tests/local dev. Both deliver a task the same way — a plain\n * HTTP POST to `targetUrl + path` — GcpTaskInvoker via Google Cloud Tasks, and\n * InMemoryTaskInvoker via an in-process queue that fetches the target directly.\n */\nexport abstract class TaskInvoker {\n    abstract enqueue(request: TaskRequest): Promise<JobReference>;\n    abstract delete(ref: JobReference): Promise<void>;\n}\n"]}

package/src/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @webpieces/cloudtasks-client
+ *
+ * Cloud Tasks enqueue client generated from a shared @PubSub API contract — the
+ * fire-and-forget twin of @webpieces/http-client. The client and the controller
+ * share ONE abstract API class; calling a method enqueues a task that is later
+ * delivered to the same endpoint through the full server filter chain.
+ */
+export { ScheduleInfo, JobReference, TaskRequest, TaskInvoker, } from './TaskTypes';
+export { createTaskClient, TaskClientConfig } from './TaskClientFactory';
+export { TaskClientCreator } from './TaskClientCreator';
+export { CloudTaskScheduler, ScheduleOptions } from './CloudTaskScheduler';
+export { InMemoryTaskInvoker } from './InMemoryTaskInvoker';
+export { GcpTaskInvoker } from './GcpTaskInvoker';
+export { ScheduleFrame, setScheduleFrame, currentScheduleFrame, clearScheduleFrame, } from './ScheduleContext';

package/src/index.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * @webpieces/cloudtasks-client
+ *
+ * Cloud Tasks enqueue client generated from a shared @PubSub API contract — the
+ * fire-and-forget twin of @webpieces/http-client. The client and the controller
+ * share ONE abstract API class; calling a method enqueues a task that is later
+ * delivered to the same endpoint through the full server filter chain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearScheduleFrame = exports.currentScheduleFrame = exports.setScheduleFrame = exports.ScheduleFrame = exports.GcpTaskInvoker = exports.InMemoryTaskInvoker = exports.ScheduleOptions = exports.CloudTaskScheduler = exports.TaskClientCreator = exports.TaskClientConfig = exports.createTaskClient = exports.TaskInvoker = exports.TaskRequest = exports.JobReference = exports.ScheduleInfo = void 0;
+var TaskTypes_1 = require("./TaskTypes");
+Object.defineProperty(exports, "ScheduleInfo", { enumerable: true, get: function () { return TaskTypes_1.ScheduleInfo; } });
+Object.defineProperty(exports, "JobReference", { enumerable: true, get: function () { return TaskTypes_1.JobReference; } });
+Object.defineProperty(exports, "TaskRequest", { enumerable: true, get: function () { return TaskTypes_1.TaskRequest; } });
+Object.defineProperty(exports, "TaskInvoker", { enumerable: true, get: function () { return TaskTypes_1.TaskInvoker; } });
+var TaskClientFactory_1 = require("./TaskClientFactory");
+Object.defineProperty(exports, "createTaskClient", { enumerable: true, get: function () { return TaskClientFactory_1.createTaskClient; } });
+Object.defineProperty(exports, "TaskClientConfig", { enumerable: true, get: function () { return TaskClientFactory_1.TaskClientConfig; } });
+var TaskClientCreator_1 = require("./TaskClientCreator");
+Object.defineProperty(exports, "TaskClientCreator", { enumerable: true, get: function () { return TaskClientCreator_1.TaskClientCreator; } });
+var CloudTaskScheduler_1 = require("./CloudTaskScheduler");
+Object.defineProperty(exports, "CloudTaskScheduler", { enumerable: true, get: function () { return CloudTaskScheduler_1.CloudTaskScheduler; } });
+Object.defineProperty(exports, "ScheduleOptions", { enumerable: true, get: function () { return CloudTaskScheduler_1.ScheduleOptions; } });
+// The two task transports (local HTTP-queue + remote GCP), both delivering over real HTTP.
+var InMemoryTaskInvoker_1 = require("./InMemoryTaskInvoker");
+Object.defineProperty(exports, "InMemoryTaskInvoker", { enumerable: true, get: function () { return InMemoryTaskInvoker_1.InMemoryTaskInvoker; } });
+var GcpTaskInvoker_1 = require("./GcpTaskInvoker");
+Object.defineProperty(exports, "GcpTaskInvoker", { enumerable: true, get: function () { return GcpTaskInvoker_1.GcpTaskInvoker; } });
+// NOTE: ServiceAuthFilter (server-side delivery-auth Filter) lives in @webpieces/http-server —
+// a client library has no server filters / routing machinery.
+var ScheduleContext_1 = require("./ScheduleContext");
+Object.defineProperty(exports, "ScheduleFrame", { enumerable: true, get: function () { return ScheduleContext_1.ScheduleFrame; } });
+Object.defineProperty(exports, "setScheduleFrame", { enumerable: true, get: function () { return ScheduleContext_1.setScheduleFrame; } });
+Object.defineProperty(exports, "currentScheduleFrame", { enumerable: true, get: function () { return ScheduleContext_1.currentScheduleFrame; } });
+Object.defineProperty(exports, "clearScheduleFrame", { enumerable: true, get: function () { return ScheduleContext_1.clearScheduleFrame; } });
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/cloud/cloudtasks-client/src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,yCAKqB;AAJjB,yGAAA,YAAY,OAAA;AACZ,yGAAA,YAAY,OAAA;AACZ,wGAAA,WAAW,OAAA;AACX,wGAAA,WAAW,OAAA;AAEf,yDAAyE;AAAhE,qHAAA,gBAAgB,OAAA;AAAE,qHAAA,gBAAgB,OAAA;AAC3C,yDAAwD;AAA/C,sHAAA,iBAAiB,OAAA;AAC1B,2DAA2E;AAAlE,wHAAA,kBAAkB,OAAA;AAAE,qHAAA,eAAe,OAAA;AAC5C,2FAA2F;AAC3F,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAC5B,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AACvB,+FAA+F;AAC/F,8DAA8D;AAC9D,qDAK2B;AAJvB,gHAAA,aAAa,OAAA;AACb,mHAAA,gBAAgB,OAAA;AAChB,uHAAA,oBAAoB,OAAA;AACpB,qHAAA,kBAAkB,OAAA","sourcesContent":["/**\n * @webpieces/cloudtasks-client\n *\n * Cloud Tasks enqueue client generated from a shared @PubSub API contract — the\n * fire-and-forget twin of @webpieces/http-client. The client and the controller\n * share ONE abstract API class; calling a method enqueues a task that is later\n * delivered to the same endpoint through the full server filter chain.\n */\n\nexport {\n    ScheduleInfo,\n    JobReference,\n    TaskRequest,\n    TaskInvoker,\n} from './TaskTypes';\nexport { createTaskClient, TaskClientConfig } from './TaskClientFactory';\nexport { TaskClientCreator } from './TaskClientCreator';\nexport { CloudTaskScheduler, ScheduleOptions } from './CloudTaskScheduler';\n// The two task transports (local HTTP-queue + remote GCP), both delivering over real HTTP.\nexport { InMemoryTaskInvoker } from './InMemoryTaskInvoker';\nexport { GcpTaskInvoker } from './GcpTaskInvoker';\n// NOTE: ServiceAuthFilter (server-side delivery-auth Filter) lives in @webpieces/http-server —\n// a client library has no server filters / routing machinery.\nexport {\n    ScheduleFrame,\n    setScheduleFrame,\n    currentScheduleFrame,\n    clearScheduleFrame,\n} from './ScheduleContext';\n"]}