@faapi/faapi 6.3.0 → 6.4.1

package/dist/index.js

@@ -1941,131 +1941,161 @@ var PayloadTooLargeError = class extends FaapiError {
   }
 };
 
-// src/task/memoryDriver.ts
-import { randomUUID } from "crypto";
-var RETRY_BASE_DELAY_MS = 500;
-var RETRY_MAX_DELAY_MS = 3e4;
-function createMemoryDriver() {
-  const jobs = /* @__PURE__ */ new Map();
-  const pendingByTask = /* @__PURE__ */ new Map();
-  const runningCount = /* @__PURE__ */ new Map();
-  const workers = /* @__PURE__ */ new Map();
-  let stopped = false;
-  function pump() {
-    if (stopped) return;
-    for (const [name, worker] of workers) {
-      const queue = pendingByTask.get(name);
-      if (!queue || queue.length === 0) continue;
-      let running = runningCount.get(name) ?? 0;
-      while (running < worker.concurrency && queue.length > 0) {
-        const head = jobs.get(queue[0]);
-        if (!head) {
-          queue.shift();
-          continue;
-        }
-        if (head.runAt > Date.now()) break;
-        queue.shift();
-        running += 1;
-        runningCount.set(name, running);
-        void dispatch(name, worker, head);
-      }
-      if (running === 0) runningCount.delete(name);
-      else runningCount.set(name, running);
-    }
+// src/task/taskWorker.ts
+import { Worker } from "worker_threads";
+import { pathToFileURL } from "url";
+var KILL_GRACE_MS = 5e3;
+var TaskCancelledError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TaskCancelledError";
   }
-  async function dispatch(name, worker, job) {
-    job.attempts += 1;
-    const driverJob = {
-      id: job.id,
-      name,
-      payload: job.payload,
-      attempt: job.attempts,
-      signal: job.controller.signal
-    };
+};
+function safeConfig(config) {
+  if (config === void 0 || config === null) return config;
+  try {
+    structuredClone(config);
+    return config;
+  } catch {
+  }
+  try {
+    return JSON.parse(JSON.stringify(config));
+  } catch {
+    return void 0;
+  }
+}
+function buildWrapperSource(moduleUrl) {
+  return `
+import { parentPort } from 'node:worker_threads';
+import * as mod from '${moduleUrl}';
+
+const run = mod.run;
+if (typeof run !== 'function') {
+  parentPort.postMessage({ type: 'error', message: 'Task module has no run export' });
+} else {
+  let controller = null;
+  parentPort.on('message', async (msg) => {
+    if (msg?.type === 'abort') {
+      controller?.abort(new Error(msg.reason));
+      return;
+    }
+    if (msg?.type !== 'run') return;
+    controller = new AbortController();
+    const { payload, taskCtx } = msg;
     try {
-      await worker.process(driverJob);
+      const result = await run(payload, { ...taskCtx, signal: controller.signal });
+      parentPort.postMessage({ type: 'done', result });
     } catch (err) {
-      if (job.attempts <= job.retries) {
-        const delay = Math.min(RETRY_BASE_DELAY_MS * 2 ** (job.attempts - 1), RETRY_MAX_DELAY_MS);
-        job.runAt = Date.now() + delay;
-        job.timer = setTimeout(() => {
-          job.timer = void 0;
-          pendingByTask.get(name)?.push(job.id);
-          pump();
-        }, delay);
-      }
-      void err;
-    } finally {
-      const running = (runningCount.get(name) ?? 1) - 1;
-      if (running <= 0) runningCount.delete(name);
-      else runningCount.set(name, running);
-      pump();
+      parentPort.postMessage({
+        type: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      });
     }
-  }
-  return {
-    async enqueue(name, payload, opts) {
-      if (stopped) {
-        throw new Error("[faapi] Task queue is stopped and no longer accepts jobs");
-      }
-      const id = randomUUID();
-      const job = {
-        id,
-        payload,
-        retries: opts?.retries ?? 0,
-        runAt: opts?.delayMs ? Date.now() + opts.delayMs : Date.now(),
-        attempts: 0,
-        controller: new AbortController()
-      };
-      jobs.set(id, job);
-      if (job.runAt > Date.now()) {
-        job.timer = setTimeout(() => {
-          job.timer = void 0;
-          pendingByTask.get(name)?.push(id);
-          pump();
-        }, job.runAt - Date.now());
+  });
+}
+`;
+}
+async function runTaskInWorker(options) {
+  const { taskModulePath, payload, taskCtx, timeoutMs, externalSignal } = options;
+  const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
+  const moduleUrl = pathToFileURL(taskModulePath).href;
+  const wrapperUrl = new URL(
+    `data:text/javascript,${encodeURIComponent(buildWrapperSource(moduleUrl))}`
+  );
+  return new Promise((resolve, reject) => {
+    let worker;
+    try {
+      worker = new Worker(wrapperUrl);
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let phase = "running";
+    let cancelReason = "";
+    let graceTimer;
+    const finish = (settle) => {
+      if (phase === "settled") return;
+      phase = "settled";
+      clearTimeout(timeoutTimer);
+      if (graceTimer) clearTimeout(graceTimer);
+      externalSignal?.removeEventListener("abort", onExternalAbort);
+      void worker.terminate();
+      settle();
+    };
+    const startCancel = (reason) => {
+      if (phase !== "running") return;
+      phase = "grace";
+      cancelReason = reason;
+      worker.postMessage({ type: "abort", reason });
+      graceTimer = setTimeout(() => {
+        finish(
+          () => reject(new TaskCancelledError(`Task "${taskCtx.job.name}" ${reason} and was terminated`))
+        );
+      }, killGraceMs);
+    };
+    const onExternalAbort = () => startCancel("cancelled (driver stop timeout)");
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        onExternalAbort();
       } else {
-        let q = pendingByTask.get(name);
-        if (!q) {
-          q = [];
-          pendingByTask.set(name, q);
-        }
-        q.push(id);
-        pump();
+        externalSignal.addEventListener("abort", onExternalAbort, { once: true });
       }
-      return id;
-    },
-    startWorker(name, opts) {
-      workers.set(name, opts);
-      pump();
-    },
-    async stop(timeoutMs = 1e4) {
-      stopped = true;
-      for (const job of jobs.values()) {
-        if (job.timer) {
-          clearTimeout(job.timer);
-          job.timer = void 0;
+    }
+    const timeoutTimer = setTimeout(
+      () => startCancel(`timed out after ${timeoutMs}ms`),
+      timeoutMs
+    );
+    worker.on("message", (msg) => {
+      if (phase === "grace") {
+        if (msg?.type === "done") {
+          finish(
+            () => reject(
+              new TaskCancelledError(
+                `Task "${taskCtx.job.name}" ${cancelReason} (task completed after the timeout)`
+              )
+            )
+          );
+        } else if (msg?.type === "error") {
+          finish(() => reject(new TaskCancelledError(msg.message ?? cancelReason)));
         }
+        return;
       }
-      const start = Date.now();
-      while (Date.now() - start < timeoutMs) {
-        const total = Array.from(runningCount.values()).reduce((sum, n) => sum + n, 0);
-        if (total === 0) return;
-        await new Promise((r) => setTimeout(r, 10));
+      if (phase !== "running") return;
+      if (msg?.type === "done") {
+        finish(() => resolve(msg.result));
+      } else if (msg?.type === "error") {
+        finish(() => reject(new Error(msg.message ?? "task worker error")));
       }
-      for (const job of jobs.values()) {
-        job.controller.abort();
+    });
+    worker.on("error", (err) => {
+      finish(() => reject(err));
+    });
+    worker.on("exit", (code) => {
+      if (phase === "grace") {
+        finish(() => reject(new TaskCancelledError(`Task "${taskCtx.job.name}" ${cancelReason}`)));
+      } else if (phase === "running") {
+        finish(() => reject(new Error(`Task worker exited unexpectedly (code ${code})`)));
       }
-    },
-    async stopWorkers() {
-      workers.clear();
+    });
+    try {
+      worker.postMessage({
+        type: "run",
+        payload,
+        taskCtx: { config: safeConfig(taskCtx.config), job: taskCtx.job }
+      });
+    } catch (err) {
+      finish(
+        () => reject(
+          new Error(`Task "${taskCtx.job.name}" payload/config is not cloneable: ${String(err)}`)
+        )
+      );
     }
-  };
+  });
 }
 
 // src/task/taskQueue.ts
 function createTaskQueue(deps) {
-  const { registry, rootDir } = deps;
-  const driver = deps.driver ?? createMemoryDriver();
+  const { registry, rootDir, driver } = deps;
   const records = /* @__PURE__ */ new Map();
   const moduleCache2 = /* @__PURE__ */ new Map();
   const schemaCache = /* @__PURE__ */ new Map();
@@ -2126,26 +2156,54 @@ function createTaskQueue(deps) {
     record.error = void 0;
     records.set(job.id, record);
     try {
-      let mod = moduleCache2.get(job.name);
-      if (!mod) {
-        mod = await loadTaskModule(path3.resolve(rootDir, meta.filePath));
-        moduleCache2.set(job.name, mod);
-      }
-      if (typeof mod.run !== "function") {
-        throw new Error(`Task "${job.name}" module has no run export`);
+      let result;
+      if (meta.timeoutMs !== void 0 && meta.timeoutMs > 0) {
+        result = await (deps.runIsolated ?? runTaskInWorker)({
+          taskModulePath: path3.resolve(rootDir, meta.filePath),
+          payload: job.payload,
+          taskCtx: {
+            config: deps.config,
+            job: { id: job.id, name: job.name, attempt: job.attempt }
+          },
+          timeoutMs: meta.timeoutMs,
+          externalSignal: job.signal
+        });
+      } else {
+        let mod = moduleCache2.get(job.name);
+        if (!mod) {
+          mod = await loadTaskModule(path3.resolve(rootDir, meta.filePath));
+          moduleCache2.set(job.name, mod);
+        }
+        if (typeof mod.run !== "function") {
+          throw new Error(`Task "${job.name}" module has no run export`);
+        }
+        const taskCtx = {
+          signal: job.signal,
+          config: deps.config,
+          job: { id: job.id, name: job.name, attempt: job.attempt }
+        };
+        result = await mod.run(job.payload, taskCtx);
       }
-      const taskCtx = {
-        signal: job.signal,
-        config: deps.config,
-        job: { id: job.id, name: job.name, attempt: job.attempt }
-      };
-      const result = await mod.run(job.payload, taskCtx);
       record.status = "done";
       record.result = result;
       return result;
     } catch (err) {
-      record.status = "failed";
+      const cancelled = err instanceof TaskCancelledError || job.signal.aborted;
+      record.status = cancelled ? "cancelled" : "failed";
       record.error = err instanceof Error ? err.message : String(err);
+      if (deps.onFailed) {
+        void Promise.resolve().then(
+          () => deps.onFailed({
+            task: job.name,
+            jobId: job.id,
+            attempt: job.attempt,
+            willRetry: job.attempt <= (meta.retries ?? 0),
+            cancelled,
+            error: record.error
+          })
+        ).catch(() => {
+        });
+      }
       throw err;
     }
   }
@@ -2167,7 +2225,8 @@ function createTaskQueue(deps) {
       const meta = registry.get(name);
       const id = await driver.enqueue(name, data, {
         delayMs: opts?.delayMs,
-        retries: meta.retries ?? 0
+        retries: meta.retries ?? 0,
+        dedupId: opts?.dedupId
       });
       if (!records.has(id)) {
         records.set(id, {
@@ -2190,6 +2249,54 @@ function createTaskQueue(deps) {
       }
       return snapshot;
     },
+    async listQueued(name) {
+      if (!driver.list) {
+        throw new Error(
+          "[faapi] Task driver does not support listing queued tasks (TaskDriver.list is not implemented). Use the queue system's own management tools, or see driverTypes.md for per-driver capability."
+        );
+      }
+      const queued = await driver.list({ name, limit: 50 });
+      const merged = /* @__PURE__ */ new Map();
+      for (const record of queued) {
+        if (name !== void 0 && record.name !== name) continue;
+        merged.set(record.id, {
+          id: record.id,
+          name: record.name,
+          payload: record.payload,
+          status: record.status,
+          attempts: record.attempts,
+          createdAt: record.createdAt,
+          ...record.result !== void 0 ? { result: record.result } : {},
+          ...record.error !== void 0 ? { error: record.error } : {},
+          ...record.runAt !== void 0 ? { runAt: record.runAt } : {}
+        });
+      }
+      for (const local of records.values()) {
+        if (name !== void 0 && local.name !== name) continue;
+        merged.set(local.id, { ...local });
+      }
+      return [...merged.values()];
+    },
+    async cancel(name, id) {
+      if (!driver.cancel) {
+        throw new Error(
+          "[faapi] Task driver does not support cancelling tasks (TaskDriver.cancel is not implemented)."
+        );
+      }
+      await driver.cancel(name, id);
+      const record = records.get(id);
+      if (record) record.status = "cancelled";
+    },
+    async retry(name, id) {
+      if (!driver.retry) {
+        throw new Error(
+          "[faapi] Task driver does not support retrying tasks (TaskDriver.retry is not implemented)."
+        );
+      }
+      await driver.retry(name, id);
+      const record = records.get(id);
+      if (record) record.status = "pending";
+    },
     async start() {
       if (stopped) {
         throw new Error("[faapi] Task queue is stopped and cannot be restarted");
@@ -2218,15 +2325,22 @@ function createTaskQueue(deps) {
 
 // src/task/loadTaskDriver.ts
 async function loadTaskDriver(driver, driverOptions) {
-  if (driver === void 0 || driver === "memory") {
-    return createMemoryDriver();
+  if (driver === void 0) {
+    throw new Error(
+      "[faapi] config.task.driver is required when tasks are defined. Install @faapi/task-pgboss or @faapi/task-bullmq and set `task.driver` to 'pgboss' or 'bullmq' (or pass a TaskDriver instance)."
+    );
+  }
+  if (driver === "memory") {
+    throw new Error(
+      "[faapi] The built-in memory task driver has been removed. Migrate to a persistent driver: install @faapi/task-pgboss or @faapi/task-bullmq and set `task.driver` to 'pgboss' or 'bullmq'."
+    );
   }
   if (typeof driver === "object") {
     return driver;
   }
   if (driver !== "pgboss" && driver !== "bullmq") {
     throw new Error(
-      `[faapi] Unknown task driver "${driver}". Supported: 'memory' (default), 'pgboss', 'bullmq', or a TaskDriver instance.`
+      `[faapi] Unknown task driver "${driver}". Supported: 'pgboss', 'bullmq', or a TaskDriver instance.`
     );
   }
   const specifier = `@faapi/task-${driver}`;
@@ -2260,13 +2374,17 @@ function createCronScheduler(registry, enqueue) {
       this.stop();
       for (const task of registry.list()) {
         if (!task.cron) continue;
-        schedules.push(
-          new Cron(task.cron, () => {
-            void Promise.resolve().then(() => enqueue(task.name)).catch((err) => {
-              console.error(`[faapi] Cron enqueue failed for task "${task.name}":`, err);
-            });
-          })
-        );
+        const schedule = new Cron(task.cron, () => {
+          const runAt = schedule.currentRun();
+          void Promise.resolve().then(
+            () => enqueue(task.name, {
+              dedupId: runAt ? `cron:${task.name}:${runAt.toISOString()}` : void 0
+            })
+          ).catch((err) => {
+            console.error(`[faapi] Cron enqueue failed for task "${task.name}":`, err);
+          });
+        });
+        schedules.push(schedule);
       }
     },
     stop() {
@@ -2287,6 +2405,7 @@ var TASK_FILENAME = "task.ts";
 var CRON_RE = /(?:^|\n)\s*cron:\s*['"`]([^'"`\n]+)['"`]/;
 var CONCURRENCY_RE = /(?:^|\n)\s*concurrency:\s*(\d+)/;
 var RETRIES_RE = /(?:^|\n)\s*retries:\s*(\d+)/;
+var TIMEOUT_MS_RE = /(?:^|\n)\s*timeoutMs:\s*(\d+)/;
 function filePathToTaskName(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   const match = normalized.match(/(?:^|\/)tasks\/(.+)\/task\.ts$/);
@@ -2323,9 +2442,11 @@ async function scanTasks(rootDir, patterns) {
     const cron = CRON_RE.exec(source)?.[1];
     const concurrency = CONCURRENCY_RE.exec(source)?.[1];
     const retries = RETRIES_RE.exec(source)?.[1];
+    const timeoutMs = TIMEOUT_MS_RE.exec(source)?.[1];
     if (cron !== void 0) manifest.cron = cron;
     if (concurrency !== void 0) manifest.concurrency = Number(concurrency);
     if (retries !== void 0) manifest.retries = Number(retries);
+    if (timeoutMs !== void 0) manifest.timeoutMs = Number(timeoutMs);
     tasks.push(manifest);
   }
   return tasks;
@@ -2389,7 +2510,7 @@ function resolveExport(module, exportName) {
 }
 
 // src/utils/importWithCacheBust.ts
-import { pathToFileURL } from "url";
+import { pathToFileURL as pathToFileURL2 } from "url";
 var loadTs;
 function setLoadTimestamp(ts11) {
   loadTs = ts11;
@@ -2403,13 +2524,13 @@ async function importWithCacheBust(filePath, bustViteCache = false) {
   const importActual = getVitestImportActual();
   if (importActual) {
     if (bustViteCache) {
-      let url2 = pathToFileURL(filePath).href;
+      let url2 = pathToFileURL2(filePath).href;
       url2 += `?t=${Date.now()}`;
       return await import(url2);
     }
     return await importActual(filePath);
   }
-  let url = pathToFileURL(filePath).href;
+  let url = pathToFileURL2(filePath).href;
   if (loadTs !== void 0) {
     url += `?t=${loadTs}`;
   }
@@ -5891,7 +6012,8 @@ function serializeTasks(tasks, dist = "dist") {
     filePath: toProdFilePath(t.filePath, dist),
     ...t.cron !== void 0 ? { cron: t.cron } : {},
     ...t.concurrency !== void 0 ? { concurrency: t.concurrency } : {},
-    ...t.retries !== void 0 ? { retries: t.retries } : {}
+    ...t.retries !== void 0 ? { retries: t.retries } : {},
+    ...t.timeoutMs !== void 0 ? { timeoutMs: t.timeoutMs } : {}
   }));
 }
 async function writeTasksModule(manifest, outputPath) {
@@ -5906,7 +6028,8 @@ function hydrateTasks(manifest) {
     filePath: t.filePath,
     cron: t.cron ?? void 0,
     concurrency: t.concurrency ?? void 0,
-    retries: t.retries ?? void 0
+    retries: t.retries ?? void 0,
+    timeoutMs: t.timeoutMs ?? void 0
   }));
 }
 function collectTaskSchemaSources(tasks, rootDir) {
@@ -6034,10 +6157,29 @@ async function generateTaskArtifacts(manifests, rootDir, dist) {
   return hydrateTasks(serialized);
 }
 
+// src/task/idleTaskDriver.ts
+function createIdleTaskDriver() {
+  return {
+    enqueue() {
+      return Promise.reject(
+        new Error(
+          "[faapi] New task(s) were registered without a queue driver. Set config.task.driver to 'pgboss' or 'bullmq' (install the matching @faapi/task-* package) and restart the server."
+        )
+      );
+    },
+    startWorker() {
+    },
+    async stop() {
+    },
+    async stopWorkers() {
+    }
+  };
+}
+
 // src/cli/loadPlugins.ts
 import path22 from "path";
 import fs17 from "fs";
-import { pathToFileURL as pathToFileURL2 } from "url";
+import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/compileConfig.ts
 import path21 from "path";
@@ -6172,7 +6314,7 @@ async function importPluginModule(specifier, baseDir, dist) {
   const sourcePath = resolveLocalPluginSource(specifier, baseDir);
   const productPath = sourcePath && distDir ? mirrorProductPath(sourcePath, baseDir, distDir) : null;
   if (productPath !== null && fs17.existsSync(productPath) && (sourcePath === null || !isSourceNewer(sourcePath, productPath))) {
-    return import(pathToFileURL2(productPath).href);
+    return import(pathToFileURL3(productPath).href);
   }
   if (sourcePath && TS_EXTS.test(sourcePath)) {
     if (!isDevOnDemandEnabled() || !distDir) {
@@ -6187,11 +6329,11 @@ async function importPluginModule(specifier, baseDir, dist) {
       await compileProjectModules([sourcePath], baseDir, dist);
     }
     if (productPath && fs17.existsSync(productPath)) {
-      return import(pathToFileURL2(productPath).href);
+      return import(pathToFileURL3(productPath).href);
     }
   }
   if (sourcePath && JS_EXTS.test(sourcePath)) {
-    return import(pathToFileURL2(sourcePath).href);
+    return import(pathToFileURL3(sourcePath).href);
   }
   const candidates = [
     `${specifier}.ts`,
@@ -6250,10 +6392,8 @@ async function loadAndHydrateAgents(rootDir, dist, registries = defaultRegistrie
 }
 function getTaskDriverOptions(config) {
   if (!config?.task) return void 0;
-  const taskConfig = config.task;
-  const driver = taskConfig.driver;
-  if (driver === "pgboss") return taskConfig.pgboss;
-  if (driver === "bullmq") return taskConfig.bullmq;
+  if (config.task.driver === "pgboss") return config.task.pgboss;
+  if (config.task.driver === "bullmq") return config.task.bullmq;
   return void 0;
 }
 async function loadAndHydrateTasks(rootDir, dist, registries = defaultRegistries) {
@@ -6350,16 +6490,17 @@ async function createAppBase(options) {
   const tools = await loadAndHydrateTools(rootDir, dist, registries);
   const agents = await loadAndHydrateAgents(rootDir, dist, registries);
   const taskMetas = await loadAndHydrateTasks(rootDir, dist, registries);
-  const taskDriver = await loadTaskDriver(config?.task?.driver, getTaskDriverOptions(config));
+  const taskDriver = taskMetas.length ? await loadTaskDriver(config?.task?.driver, getTaskDriverOptions(config)) : createIdleTaskDriver();
   const taskQueue = createTaskQueue({
     registry: registries.task,
     rootDir,
     config,
-    driver: taskDriver
+    driver: taskDriver,
+    onFailed: config?.task?.onFailed
   });
   const cronScheduler = createCronScheduler(
     registries.task,
-    (name) => taskQueue.enqueue(name)
+    (name, opts) => taskQueue.enqueue(name, void 0, opts)
   );
   const taskEnabled = process.env.FAAPI_TASKS_DISABLED === "1" ? false : config?.task?.enabled ?? true;
   const stopTaskRuntime = async () => {
@@ -6367,7 +6508,7 @@ async function createAppBase(options) {
     await taskQueue.stop(config?.task?.shutdownTimeoutMs ?? 1e4);
   };
   if (taskEnabled) {
-    taskQueue.start();
+    await taskQueue.start();
     cronScheduler.start();
   }
   registries.taskHandle.register(() => taskQueue);
@@ -7034,7 +7175,6 @@ export {
   createAppRegistries,
   createCronScheduler,
   createDevApp,
-  createMemoryDriver,
   createProdApp,
   createProgram,
   createPrograms,