@faapi/task-pgboss 0.0.0-canary.0 → 6.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 faapi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
 # @faapi/task-pgboss
 
-Placeholder package for Trusted Publisher setup. Real content published via CI from https://github.com/faapi/faapi.
+faapi 任务子系统的 **pg-boss 驱动**（PostgreSQL 持久化队列）。
+
+基于 PostgreSQL 的任务队列——任务不丢（持久化）、多实例天然防重跑（worker 领取制）、cron 重复投递由 pg-boss 消费语义兜底。复用业务方已有的 Postgres，不引入 Redis。
+
+## 安装
+
+```bash
+pnpm add @faapi/task-pgboss pgboss
+```
+
+## 使用
+
+任务定义不变（主包文件约定 `src/tasks/<name>/task.ts`），只切驱动：
+
+```ts
+// faapi.config.ts
+import type { FaapiConfig } from '@faapi/faapi';
+
+export default {
+  task: {
+    driver: 'pgboss',
+    pgboss: { connectionString: 'postgres://localhost:5432/app' }, // 透传给 new PgBoss(...)
+  },
+} satisfies FaapiConfig;
+```
+
+```ts
+// handler 里用法完全不变
+export function POST(body, tasks) {
+  return tasks.enqueue('send-email', { to: body.email });
+}
+```
+
+## 语义映射
+
+| faapi 驱动接口 | pg-boss |
+| --- | --- |
+| `enqueue(name, payload, { retries, delayMs })` | `boss.send(name, payload, { retryLimit, retryDelay: 1, retryBackoff: true, startAfter })` |
+| `startWorker(name, { concurrency, process })` | `boss.work(name, { batchSize: concurrency }, handler)` |
+| `stop(timeoutMs)` | 停 work + `boss.stop({ close: true, timeout })` |
+| `stopWorkers()` | `offWork()`（不断开连接，dev 热替换重注册用） |
+| 失败重试 | pg-boss 侧执行（retryLimit + retryBackoff 指数退避） |
+
+注意：pg-boss 不提供执行中任务的取消信号——`run` 的 `taskCtx.signal` 永不 abort，长任务请自行做超时控制。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { TaskDriver } from '@faapi/faapi';
+import PgBoss from 'pg-boss';
+
+/**
+ * pg-boss 驱动选项（透传给 PgBoss 构造函数）
+ *
+ * 常用：`connectionString`；其余见 pg-boss 文档（ConstructorOptions）。
+ */
+type PgBossDriverOptions = PgBoss.ConstructorOptions;
+declare function createPgBossDriver(options?: PgBossDriverOptions): TaskDriver;
+
+export { type PgBossDriverOptions, createPgBossDriver };

package/dist/index.js

@@ -0,0 +1,139 @@
+// src/index.ts
+import { createHash } from "crypto";
+import PgBoss from "pg-boss";
+function dedupIdToUuid(dedupId) {
+  const h = createHash("sha1").update(dedupId).digest("hex");
+  return [
+    h.slice(0, 8),
+    h.slice(8, 12),
+    `5${h.slice(13, 16)}`,
+    // version 5
+    `${(parseInt(h.slice(16, 17), 16) & 3 | 8).toString(16)}${h.slice(17, 20)}`,
+    // variant
+    h.slice(20, 32)
+  ].join("-");
+}
+function createPgBossDriver(options = {}) {
+  let boss = null;
+  let stopped = false;
+  const workerIds = /* @__PURE__ */ new Map();
+  const inflight = /* @__PURE__ */ new Map();
+  async function ensureBoss() {
+    if (!boss) {
+      boss = new PgBoss(options);
+      await boss.start();
+    }
+    return boss;
+  }
+  return {
+    async enqueue(name, payload, opts) {
+      if (stopped) {
+        throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+      }
+      const b = await ensureBoss();
+      const sendOptions = {
+        retryLimit: opts?.retries ?? 0,
+        retryDelay: 1,
+        // 秒；配合 retryBackoff 指数退避
+        retryBackoff: true,
+        ...opts?.dedupId ? { id: dedupIdToUuid(opts.dedupId) } : {},
+        ...opts?.delayMs ? { startAfter: new Date(Date.now() + opts.delayMs) } : {}
+      };
+      const id = await b.send(name, payload, sendOptions);
+      if (!id) {
+        if (opts?.dedupId) {
+          return dedupIdToUuid(opts.dedupId);
+        }
+        throw new Error(`[faapi] pg-boss send failed for task "${name}"`);
+      }
+      return id;
+    },
+    async startWorker(name, workerOpts) {
+      const b = await ensureBoss();
+      const process = workerOpts.process;
+      const existing = workerIds.get(name);
+      if (existing) {
+        await b.offWork(existing);
+      }
+      const workerId = await b.work(
+        name,
+        { batchSize: workerOpts.concurrency, includeMetadata: true },
+        async (jobs) => {
+          for (const job of jobs) {
+            const attempt = job.retryCount + 1;
+            const controller = new AbortController();
+            inflight.set(job.id, controller);
+            try {
+              await process({
+                id: job.id,
+                name,
+                payload: job.data,
+                attempt,
+                signal: controller.signal
+              });
+            } finally {
+              inflight.delete(job.id);
+            }
+          }
+        }
+      );
+      workerIds.set(name, workerId);
+    },
+    async stop(timeoutMs = 1e4) {
+      stopped = true;
+      const abortTimer = setTimeout(() => {
+        for (const controller of inflight.values()) controller.abort();
+      }, timeoutMs);
+      try {
+        const b = boss;
+        if (b) {
+          for (const workerId of workerIds.values()) {
+            await b.offWork(workerId).catch(() => {
+            });
+          }
+          workerIds.clear();
+          await b.stop({ close: true, graceful: true, timeout: Math.floor(timeoutMs / 1e3) });
+          boss = null;
+        }
+      } finally {
+        clearTimeout(abortTimer);
+        for (const controller of inflight.values()) controller.abort();
+        inflight.clear();
+      }
+    },
+    async stopWorkers() {
+      const b = boss;
+      if (b) {
+        for (const workerId of workerIds.values()) {
+          await b.offWork(workerId).catch(() => {
+          });
+        }
+      }
+      workerIds.clear();
+    },
+    async cancel(name, id) {
+      if (stopped) {
+        throw new Error(
+          "[faapi] Task queue is stopped and no longer accepts management operations"
+        );
+      }
+      const b = await ensureBoss();
+      await b.cancel(name, id);
+    },
+    async retry(name, id) {
+      if (stopped) {
+        throw new Error(
+          "[faapi] Task queue is stopped and no longer accepts management operations"
+        );
+      }
+      const b = await ensureBoss();
+      await b.resume(name, id);
+    }
+    // list 未实现：pg-boss v10 无批量列出 jobs 的公开 API（getJobById/getQueueSize 只能单查/计数），
+    // 不硬造内部 SQL 依赖——语义层 listQueued 显式抛错，管理走 pg-boss 自身 API/SQL
+  };
+}
+export {
+  createPgBossDriver
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport type { TaskDriver, TaskDriverProcess } from '@faapi/faapi';\nimport PgBoss from 'pg-boss';\n\n/**\n * pg-boss 驱动选项（透传给 PgBoss 构造函数）\n *\n * 常用：`connectionString`；其余见 pg-boss 文档（ConstructorOptions）。\n */\nexport type PgBossDriverOptions = PgBoss.ConstructorOptions;\n\n/**\n * faapi 任务队列 pg-boss 驱动（PostgreSQL 持久化队列）\n *\n * 与 faapi 主包 `config.task.driver: 'pgboss'` 配合使用：\n *\n * ```ts\n * // faapi.config.ts\n * export default {\n *   task: {\n *     driver: 'pgboss',\n *     pgboss: { connectionString: 'postgres://localhost:5432/app' },\n *   },\n * } satisfies FaapiConfig;\n * ```\n *\n * 语义映射（详见包根 README）：\n * - `enqueue` → `boss.send(name, payload, { retryLimit, retryDelay, retryBackoff, startAfter })`\n * - `startWorker` → `boss.work(name, { batchSize: concurrency, includeMetadata: true }, handler)`\n * - `stop` → `offWork` + `boss.stop({ close: true, graceful: true, timeout })`；超时后 abort 在跑任务的 signal\n * - 重试 → pg-boss 侧执行（retryLimit + retryBackoff 指数退避）\n */\n/**\n * dedupId → 确定性 UUID：pg-boss 的 send 自定义 id 要求 UUID 格式（SQL 侧 cast），\n * 任意字符串键经 SHA-1 映射为合法 UUID——同键必同 UUID（幂等），不同键碰撞可忽略\n */\nfunction dedupIdToUuid(dedupId: string): string {\n  const h = createHash('sha1').update(dedupId).digest('hex');\n  return [\n    h.slice(0, 8),\n    h.slice(8, 12),\n    `5${h.slice(13, 16)}`, // version 5\n    `${((parseInt(h.slice(16, 17), 16) & 0x3) | 0x8).toString(16)}${h.slice(17, 20)}`, // variant\n    h.slice(20, 32),\n  ].join('-');\n}\n\nexport function createPgBossDriver(options: PgBossDriverOptions = {}): TaskDriver {\n  let boss: PgBoss | null = null;\n  let stopped = false;\n  /** 已创建的 pg-boss worker id（stopWorkers 时 offWork） */\n  const workerIds = new Map<string, string>();\n  /** 在跑任务的取消控制器（stop 超时 abort——run 监听 signal 可尽快退出） */\n  const inflight = new Map<string, AbortController>();\n\n  async function ensureBoss(): Promise<PgBoss> {\n    if (!boss) {\n      boss = new PgBoss(options);\n      // pg-boss 惰性连接：start 后才连库；驱动在首次 enqueue/startWorker 前建立\n      await boss.start();\n    }\n    return boss;\n  }\n\n  return {\n    async enqueue(name, payload, opts) {\n      if (stopped) {\n        throw new Error('[faapi] Task queue is stopped and no longer accepts jobs');\n      }\n      const b = await ensureBoss();\n      const sendOptions: PgBoss.SendOptions = {\n        retryLimit: opts?.retries ?? 0,\n        retryDelay: 1, // 秒；配合 retryBackoff 指数退避\n        retryBackoff: true,\n        ...(opts?.dedupId ? { id: dedupIdToUuid(opts.dedupId) } : {}),\n        ...(opts?.delayMs ? { startAfter: new Date(Date.now() + opts.delayMs) } : {}),\n      };\n      // pg-boss data 形参为 object——基础类型 payload（cron 空任务等）按 JSON 语义透传\n      const id = await b.send(name, payload as object, sendOptions);\n      if (!id) {\n        // dedupId 幂等投递：同键已存在（主键冲突 DO NOTHING → send 返回 null），\n        // 返回已存在任务的确定性 id；无 dedupId 的失败投递才是异常\n        if (opts?.dedupId) {\n          return dedupIdToUuid(opts.dedupId);\n        }\n        throw new Error(`[faapi] pg-boss send failed for task \"${name}\"`);\n      }\n      return id;\n    },\n\n    async startWorker(name, workerOpts) {\n      const b = await ensureBoss();\n      const process: TaskDriverProcess = workerOpts.process;\n      // 二次注册（reload 场景）先 offWork 旧 worker\n      const existing = workerIds.get(name);\n      if (existing) {\n        await b.offWork(existing);\n      }\n      const workerId = await b.work<unknown>(\n        name,\n        { batchSize: workerOpts.concurrency, includeMetadata: true },\n        async (jobs) => {\n          for (const job of jobs) {\n            // retryCount 从 0 起（首次执行为 0）→ faapi attempt 从 1 起\n            const attempt = job.retryCount + 1;\n            // 信号由驱动自管：stop 超时 abort（pg-boss 自身不提供执行中任务的取消能力）\n            const controller = new AbortController();\n            inflight.set(job.id, controller);\n            try {\n              await process({\n                id: job.id,\n                name,\n                payload: job.data,\n                attempt,\n                signal: controller.signal,\n              });\n            } finally {\n              inflight.delete(job.id);\n            }\n          }\n          // handler 正常返回 = 本批全部完成；抛错 = 整批失败由 pg-boss 按 retryLimit 重试\n        },\n      );\n      workerIds.set(name, workerId);\n    },\n\n    async stop(timeoutMs = 10_000) {\n      stopped = true;\n      // 等待超时到点 abort 在跑任务（run 监听 signal 尽快退出）；等待结束后兜底 abort 残留\n      const abortTimer = setTimeout(() => {\n        for (const controller of inflight.values()) controller.abort();\n      }, timeoutMs);\n      try {\n        const b = boss;\n        if (b) {\n          for (const workerId of workerIds.values()) {\n            await b.offWork(workerId).catch(() => {});\n          }\n          workerIds.clear();\n          // graceful: 等 in-flight 任务完成；timeout 秒后强制处置\n          await b.stop({ close: true, graceful: true, timeout: Math.floor(timeoutMs / 1000) });\n          boss = null;\n        }\n      } finally {\n        clearTimeout(abortTimer);\n        for (const controller of inflight.values()) controller.abort();\n        inflight.clear();\n      }\n    },\n\n    async stopWorkers() {\n      const b = boss;\n      if (b) {\n        for (const workerId of workerIds.values()) {\n          await b.offWork(workerId).catch(() => {});\n        }\n      }\n      workerIds.clear();\n    },\n\n    async cancel(name, id) {\n      if (stopped) {\n        throw new Error(\n          '[faapi] Task queue is stopped and no longer accepts management operations',\n        );\n      }\n      const b = await ensureBoss();\n      await b.cancel(name, id);\n    },\n\n    async retry(name, id) {\n      if (stopped) {\n        throw new Error(\n          '[faapi] Task queue is stopped and no longer accepts management operations',\n        );\n      }\n      const b = await ensureBoss();\n      // pg-boss v10 语义：resume 恢复 cancelled 任务；failed 任务无原生重试 API\n      await b.resume(name, id);\n    },\n    // list 未实现：pg-boss v10 无批量列出 jobs 的公开 API（getJobById/getQueueSize 只能单查/计数），\n    // 不硬造内部 SQL 依赖——语义层 listQueued 显式抛错，管理走 pg-boss 自身 API/SQL\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,11 +1,60 @@
 {
   "name": "@faapi/task-pgboss",
-  "version": "0.0.0-canary.0",
-  "description": "Placeholder for Trusted Publisher setup. Real content published via CI from https://github.com/faapi/faapi.",
+  "version": "6.4.0",
+  "description": "pg-boss task queue driver for faapi — persistent queue on PostgreSQL",
   "type": "module",
-  "main": "./index.js",
-  "files": [],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "pg-boss": "^10.1.5",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11",
+    "@faapi/faapi": "6.4.0"
+  },
+  "peerDependencies": {
+    "pg-boss": "^10.0.0",
+    "@faapi/faapi": "^6.4.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faapi/faapi.git",
+    "directory": "packages/task-pgboss"
+  },
+  "bugs": {
+    "url": "https://github.com/faapi/faapi/issues"
+  },
+  "keywords": [
+    "faapi",
+    "task-queue",
+    "pg-boss",
+    "postgres",
+    "driver"
+  ],
+  "sideEffects": false,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json"
   }
-}
+}