@faapi/task-pgboss 6.4.0 → 6.5.0

package/README.md

@@ -37,13 +37,13 @@ export function POST(body, tasks) {
 
 | 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)` |
+| `enqueue(name, payload, { retries, delayMs })` | 幂等 `createQueue(name)`（每任务名每进程一次，缓存短路）→ `boss.send(name, payload, { retryLimit, retryDelay: 1, retryBackoff: true, startAfter })` |
+| `startWorker(name, { concurrency, process })` | 幂等 `createQueue(name)` → `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，长任务请自行做超时控制。
+注意：pg-boss v10 不再隐式建队列（`send()` 对未创建队列静默返回 null）——驱动在投递/注册 worker 前自动幂等建队列，业务方无需预建；pg-boss 也不提供执行中任务的取消信号——`run` 的 `taskCtx.signal` 永不 abort，长任务请自行做超时控制。
 
 ## License
 

package/dist/index.js

@@ -18,12 +18,36 @@ function createPgBossDriver(options = {}) {
   let stopped = false;
   const workerIds = /* @__PURE__ */ new Map();
   const inflight = /* @__PURE__ */ new Map();
+  const ensuredQueues = /* @__PURE__ */ new Set();
+  const ensuring = /* @__PURE__ */ new Map();
+  let bossStarting = null;
   async function ensureBoss() {
-    if (!boss) {
-      boss = new PgBoss(options);
-      await boss.start();
+    if (boss) return boss;
+    if (!bossStarting) {
+      bossStarting = (async () => {
+        const b = new PgBoss(options);
+        await b.start();
+        boss = b;
+        return b;
+      })();
+      void bossStarting.catch(() => {
+        bossStarting = null;
+      });
     }
-    return boss;
+    return bossStarting;
+  }
+  async function ensureQueue(b, name) {
+    if (ensuredQueues.has(name)) return;
+    const pending = ensuring.get(name);
+    if (pending) return pending;
+    const promise = (async () => {
+      await b.createQueue(name);
+      ensuredQueues.add(name);
+    })().finally(() => {
+      ensuring.delete(name);
+    });
+    ensuring.set(name, promise);
+    return promise;
   }
   return {
     async enqueue(name, payload, opts) {
@@ -31,6 +55,7 @@ function createPgBossDriver(options = {}) {
         throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
       }
       const b = await ensureBoss();
+      await ensureQueue(b, name);
       const sendOptions = {
         retryLimit: opts?.retries ?? 0,
         retryDelay: 1,
@@ -50,6 +75,7 @@ function createPgBossDriver(options = {}) {
     },
     async startWorker(name, workerOpts) {
       const b = await ensureBoss();
+      await ensureQueue(b, name);
       const process = workerOpts.process;
       const existing = workerIds.get(name);
       if (existing) {
@@ -86,6 +112,7 @@ function createPgBossDriver(options = {}) {
       }, timeoutMs);
       try {
         const b = boss;
+        bossStarting = null;
         if (b) {
           for (const workerId of workerIds.values()) {
             await b.offWork(workerId).catch(() => {

package/dist/index.js.map

@@ -1 +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":[]}
+{"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` → 幂等 ensureQueue + `boss.send(name, payload, { retryLimit, retryDelay, retryBackoff, startAfter })`\n * - `startWorker` → 幂等 ensureQueue + `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  /** 已建队列名缓存（每任务名每进程一次真实 createQueue，之后短路） */\n  const ensuredQueues = new Set<string>();\n  /** 并发首次投递同名任务的 in-flight 去重 */\n  const ensuring = new Map<string, Promise<void>>();\n  /** boss.start() in-flight 共享 promise（并发首调等待同一次建连，不出现半启动实例） */\n  let bossStarting: Promise<PgBoss> | null = null;\n\n  async function ensureBoss(): Promise<PgBoss> {\n    if (boss) return boss;\n    if (!bossStarting) {\n      bossStarting = (async () => {\n        const b = new PgBoss(options);\n        // pg-boss 惰性连接：start 后才连库；驱动在首次 enqueue/startWorker 前建立。\n        // start 完成前实例不外借——pre-open 的 executeSql 静默 no-op（返回 undefined），\n        // 建连中并发调用会在半启动实例上跑 SQL\n        await b.start();\n        boss = b;\n        return b;\n      })();\n      // start 失败清空 in-flight：下次调用重新建连（坏实例不入缓存）\n      void bossStarting.catch(() => {\n        bossStarting = null;\n      });\n    }\n    return bossStarting;\n  }\n\n  /**\n   * pg-boss v10 不再隐式建队列（v9 行为）：send() 的 INSERT JOIN queue 对未创建队列\n   * 静默返回 null，work() 只注册进程内轮询器同样不建队列——投递/注册 worker 前先建队列。\n   * create_queue plpgsql 幂等（INSERT ON CONFLICT DO NOTHING，已存在直接返回），\n   * 重复/并发调用安全；失败不入缓存，下次投递重试。\n   */\n  async function ensureQueue(b: PgBoss, name: string): Promise<void> {\n    if (ensuredQueues.has(name)) return;\n    const pending = ensuring.get(name);\n    if (pending) return pending;\n    const promise = (async () => {\n      await b.createQueue(name);\n      ensuredQueues.add(name);\n    })().finally(() => {\n      ensuring.delete(name);\n    });\n    ensuring.set(name, promise);\n    return promise;\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      await ensureQueue(b, name);\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      await ensureQueue(b, name);\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        bossStarting = null; // 停机后 ensureBoss 不再复用旧实例/旧建连 promise\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,6 +1,6 @@
 {
   "name": "@faapi/task-pgboss",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "pg-boss task queue driver for faapi — persistent queue on PostgreSQL",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,11 +24,11 @@
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.11",
-    "@faapi/faapi": "6.4.0"
+    "@faapi/faapi": "6.5.0"
   },
   "peerDependencies": {
     "pg-boss": "^10.0.0",
-    "@faapi/faapi": "^6.4.0"
+    "@faapi/faapi": "^6.5.0"
   },
   "license": "MIT",
   "repository": {