@faapi/faapi 6.33.0 → 6.34.0

package/dist/cli/index.js

@@ -9548,6 +9548,53 @@ async function runTaskInWorker(options) {
     worker.on(
       "message",
       (msg) => {
+        if (msg?.type === "tasks-call") {
+          const { seq, method, args } = msg;
+          const reply = (body) => {
+            try {
+              worker.postMessage({ type: "tasks-result", seq, ...body });
+            } catch (err) {
+              try {
+                worker.postMessage({
+                  type: "tasks-result",
+                  seq,
+                  ok: false,
+                  error: {
+                    name: "Error",
+                    message: `taskCtx.tasks.${method} result is not cloneable: ${String(err)}`,
+                    stack: void 0,
+                    props: {}
+                  }
+                });
+              } catch {
+              }
+            }
+          };
+          if (!options.onTasksCall) {
+            reply({
+              ok: false,
+              error: {
+                name: "Error",
+                message: `taskCtx.tasks.${method} is unavailable: no host handler was provided for this execution`,
+                stack: void 0,
+                props: {}
+              }
+            });
+            return;
+          }
+          options.onTasksCall(method, args ?? []).then((value) => reply({ ok: true, value })).catch((err) => {
+            reply({
+              ok: false,
+              error: {
+                name: err instanceof Error ? err.name : "Error",
+                message: err instanceof Error ? err.message : String(err),
+                stack: err instanceof Error ? err.stack : void 0,
+                props: {}
+              }
+            });
+          });
+          return;
+        }
         if (phase === "grace") {
           if (msg?.type === "done") {
             finish(
@@ -9669,6 +9716,54 @@ function createTaskQueue(deps) {
       throw new Error(`[faapi] Unknown task "${name}". Registered tasks: ${known}`);
     }
   }
+  function assertGroupSupport() {
+    if (!driver.groups) {
+      throw new Error(
+        "[faapi] Task driver does not support group accounting (TaskDriver.groups is not implemented). Group enqueue/settle requires a driver that implements it \u2014 see driverTypes.md / taskGroups.md."
+      );
+    }
+  }
+  async function maybeFireCompletion(snap) {
+    if (!driver.groups) return;
+    if (!snap.onComplete || snap.completionEnqueued || snap.settled < snap.total) return;
+    const summary = {
+      groupId: snap.groupId,
+      task: snap.task,
+      total: snap.total,
+      done: snap.done,
+      failed: snap.failed,
+      cancelled: snap.cancelled,
+      settled: snap.settled
+    };
+    try {
+      await enqueueCore(snap.onComplete, summary, {
+        dedupId: GROUP_COMPLETION_DEDUP(snap.groupId)
+      });
+      await driver.groups.markCompletionEnqueued(snap.groupId);
+    } catch (err) {
+      console.error(
+        `[faapi] task group "${snap.groupId}" completion enqueue failed (group is settled; re-invoke enqueueGroup with the same groupId to re-arm the callback):`,
+        err
+      );
+    }
+  }
+  async function settleGroup(record, outcome, willRetry) {
+    const groupId = record.groupId;
+    if (!groupId || !driver.groups) return;
+    if (outcome !== "done" && willRetry) return;
+    try {
+      const snap = await driver.groups.settle(groupId, record.id, outcome);
+      if (outcome === "failed" && snap.onFailure === "fail-fast") {
+        await maybeFireCompletion(await driver.groups.cancelRemaining(groupId));
+      }
+      await maybeFireCompletion(snap);
+    } catch (err) {
+      console.error(
+        `[faapi] task group accounting failed for "${groupId}" (job ${record.id}, outcome ${outcome}):`,
+        err
+      );
+    }
+  }
   function snapshotRegistries() {
     return {
       agents: registriesView.agent.listAgents().map((core) => registriesView.agent.getAgentEntry(core.name)).filter((entry) => entry !== void 0),
@@ -9707,11 +9802,13 @@ function createTaskQueue(deps) {
       attempts: 0,
       createdAt: Date.now()
     };
+    if (job.groupId !== void 0) record.groupId = job.groupId;
     record.attempts = job.attempt;
     transitionStatus(record, "running");
     delete record.progress;
     record.error = void 0;
     records.set(job.id, record);
+    const willRetry = job.attempt <= (meta.retries ?? 0);
     try {
       let result;
       if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
@@ -9741,7 +9838,16 @@ function createTaskQueue(deps) {
           onProgress: (value) => {
             if (record.status === "running") record.progress = value;
           },
-          onLog: writeLogEntry
+          onLog: writeLogEntry,
+          // 隔离路径的 taskCtx.tasks 为 postMessage RPC 代理——宿主侧按方法名
+          // 分派到队列本体（与 ctx.tasks / app.tasks 同一实例），结果/错误按 seq 回传
+          onTasksCall: async (method, args) => {
+            if (!TASK_CLIENT_METHODS.has(method)) {
+              throw new Error(`[faapi] Unknown task client method "${method}"`);
+            }
+            const fn = queue[method];
+            return fn.apply(queue, args);
+          }
         });
       } else {
         let mod = moduleCache2.get(job.name);
@@ -9754,6 +9860,8 @@ function createTaskQueue(deps) {
         }
         const taskCtx = {
           signal: job.signal,
+          // 活引用：与 ctx.tasks / app.tasks 同一 app 实例队列
+          tasks: queue,
           config: deps.config,
           job: { id: job.id, name: job.name, attempt: job.attempt },
           registries: registriesView,
@@ -9771,19 +9879,22 @@ function createTaskQueue(deps) {
       transitionStatus(record, "done");
       record.result = result;
       evictFinishedRecords();
+      await settleGroup(record, "done", willRetry);
       return result;
     } catch (err) {
       const cancelled = err instanceof TaskCancelledError || job.signal.aborted;
-      transitionStatus(record, cancelled ? "cancelled" : "failed");
+      const outcome = cancelled ? "cancelled" : "failed";
+      transitionStatus(record, outcome);
       record.error = err instanceof Error ? err.message : String(err);
       evictFinishedRecords();
+      await settleGroup(record, outcome, willRetry);
       if (deps.onFailed) {
         void Promise.resolve().then(
           () => deps.onFailed({
             task: job.name,
             jobId: job.id,
             attempt: job.attempt,
-            willRetry: job.attempt <= (meta.retries ?? 0),
+            willRetry,
             cancelled,
             error: record.error
           })
@@ -9802,35 +9913,86 @@ function createTaskQueue(deps) {
       });
     }
   }
+  async function enqueueCore(name, payload, opts) {
+    if (stopped) {
+      throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
+    }
+    assertKnownTask(name);
+    const data = await validatePayload(name, payload);
+    const meta = registry.get(name);
+    const id = await driver.enqueue(name, data, {
+      delayMs: opts?.delayMs,
+      retries: meta.retries ?? 0,
+      dedupId: opts?.dedupId,
+      // 执行硬限预算透传驱动（pgboss 映射 expireInSeconds）：未声明 timeoutMs 时
+      // 两字段为 undefined，驱动用自身兜底
+      timeoutMs: meta.timeoutMs,
+      graceMs: meta.graceMs,
+      ...opts?.groupId !== void 0 ? { groupId: opts.groupId } : {}
+    });
+    if (!records.has(id)) {
+      records.set(id, {
+        id,
+        name,
+        payload: data,
+        status: "pending",
+        attempts: 0,
+        ...opts?.groupId !== void 0 ? { groupId: opts.groupId } : {},
+        createdAt: Date.now(),
+        ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+      });
+    }
+    return id;
+  }
   const queue = {
     async enqueue(name, payload = {}, opts) {
+      const id = await enqueueCore(name, payload, {
+        delayMs: opts?.delayMs,
+        dedupId: opts?.dedupId
+      });
+      return { id };
+    },
+    async enqueueGroup(name, payloads, opts) {
       if (stopped) {
         throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
       }
+      assertGroupSupport();
       assertKnownTask(name);
-      const data = await validatePayload(name, payload);
-      const meta = registry.get(name);
-      const id = await driver.enqueue(name, data, {
-        delayMs: opts?.delayMs,
-        retries: meta.retries ?? 0,
-        dedupId: opts?.dedupId,
-        // 执行硬限预算透传驱动（pgboss 映射 expireInSeconds）：未声明 timeoutMs 时
-        // 两字段为 undefined，驱动用自身兜底
-        timeoutMs: meta.timeoutMs,
-        graceMs: meta.graceMs
+      if (!Array.isArray(payloads) || payloads.length === 0) {
+        throw new Error(
+          "[faapi] enqueueGroup requires a non-empty payloads array \u2014 a group without members can never settle."
+        );
+      }
+      const onComplete = opts?.onComplete;
+      if (onComplete !== void 0) assertKnownTask(onComplete);
+      const onFailure = opts?.onFailure ?? "run-to-completion";
+      const validated = [];
+      for (const p of payloads) {
+        validated.push(await validatePayload(name, p));
+      }
+      const groupId = opts?.groupId ?? crypto.randomUUID();
+      await driver.groups.create({
+        id: groupId,
+        task: name,
+        total: validated.length,
+        ...onComplete !== void 0 ? { onComplete } : {},
+        onFailure
       });
-      if (!records.has(id)) {
-        records.set(id, {
-          id,
-          name,
-          payload: data,
-          status: "pending",
-          attempts: 0,
-          createdAt: Date.now(),
-          ...opts?.delayMs ? { runAt: Date.now() + opts.delayMs } : {}
+      const jobs = [];
+      for (let i = 0; i < validated.length; i++) {
+        const id = await enqueueCore(name, validated[i], {
+          delayMs: opts?.delayMs,
+          dedupId: GROUP_MEMBER_DEDUP(groupId, i + 1),
+          groupId
         });
+        jobs.push({ id });
       }
-      return { id };
+      await maybeFireCompletion(await driver.groups.get(groupId));
+      return { groupId, jobs };
+    },
+    async getGroup(groupId) {
+      assertGroupSupport();
+      return driver.groups.get(groupId);
     },
     list(name) {
       const snapshot = [];
@@ -9857,6 +10019,7 @@ function createTaskQueue(deps) {
           status: record.status,
           attempts: record.attempts,
           createdAt: record.createdAt,
+          ...record.groupId !== void 0 ? { groupId: record.groupId } : {},
           ...record.result !== void 0 ? { result: record.result } : {},
           ...record.error !== void 0 ? { error: record.error } : {},
           ...record.runAt !== void 0 ? { runAt: record.runAt } : {}
@@ -9876,8 +10039,11 @@ function createTaskQueue(deps) {
       }
       await driver.cancel(name, id);
       const record = records.get(id);
-      if (record) transitionStatus(record, "cancelled");
-      evictFinishedRecords();
+      if (record) {
+        transitionStatus(record, "cancelled");
+        evictFinishedRecords();
+        await settleGroup(record, "cancelled", false);
+      }
     },
     async retry(name, id) {
       if (!driver.retry) {
@@ -9887,7 +10053,18 @@ function createTaskQueue(deps) {
       }
       await driver.retry(name, id);
       const record = records.get(id);
-      if (record) transitionStatus(record, "pending");
+      if (record) {
+        const wasTerminal = TERMINAL_STATUSES.has(record.status);
+        transitionStatus(record, "pending");
+        if (wasTerminal && record.groupId && driver.groups) {
+          await driver.groups.unsettle(record.groupId, record.id).catch((err) => {
+            console.error(
+              `[faapi] task group unsettle failed for "${record.groupId}" (job ${record.id}):`,
+              err
+            );
+          });
+        }
+      }
     },
     async start() {
       if (stopped) {
@@ -9914,7 +10091,7 @@ function createTaskQueue(deps) {
   };
   return queue;
 }
-var TERMINAL_STATUSES, MAX_FINISHED_RECORDS;
+var TERMINAL_STATUSES, GROUP_MEMBER_DEDUP, GROUP_COMPLETION_DEDUP, TASK_CLIENT_METHODS, MAX_FINISHED_RECORDS;
 var init_taskQueue = __esm({
   "src/task/taskQueue.ts"() {
     "use strict";
@@ -9923,6 +10100,17 @@ var init_taskQueue = __esm({
     init_registries();
     init_logger();
     TERMINAL_STATUSES = /* @__PURE__ */ new Set(["done", "failed", "cancelled"]);
+    GROUP_MEMBER_DEDUP = (groupId, index) => `faapi-group:${groupId}:${index}`;
+    GROUP_COMPLETION_DEDUP = (groupId) => `faapi-group:${groupId}:complete`;
+    TASK_CLIENT_METHODS = /* @__PURE__ */ new Set([
+      "enqueue",
+      "enqueueGroup",
+      "list",
+      "listQueued",
+      "cancel",
+      "retry",
+      "getGroup"
+    ]);
     MAX_FINISHED_RECORDS = 1e3;
   }
 });