@faapi/faapi 6.3.0 → 6.4.0

package/dist/{routeTypes-CCveqSnY.d.ts → routeTypes-_17rXzal.d.ts}

@@ -22,14 +22,14 @@ declare function createTaskRegistry(): TaskRegistry;
  * run 执行包装、任务记录（list）；驱动层负责：入队存储、worker 消费、
  * 失败重试、停机 drain。换驱动 = 换存储，业务方写法不变。
  *
- * 内置 memory 驱动（memoryDriver.ts，进程内数组，零依赖）；
- * 外部驱动由独立子包提供：`@faapi/task-pgboss`（Postgres）、`@faapi/task-bullmq`（Redis），
- * 主包不依赖它们——按 config.task.driver 动态加载（loadTaskDriver.ts）。
+ * 框架不内置任何驱动实现：外部驱动由独立子包提供——`@faapi/task-pgboss`（Postgres）、
+ * `@faapi/task-bullmq`（Redis），主包不依赖它们——按 config.task.driver 动态加载
+ * （loadTaskDriver.ts）；无任务清单时用 idleTaskDriver 占位（enqueue 显式报错）。
  */
 
 /** 驱动层交付给语义层执行的单个任务 */
 interface TaskDriverJob {
-    /** 队列系统侧任务 id（memory 为 uuid；pg-boss/bullmq 为其自身 id） */
+    /** 队列系统侧任务 id（pg-boss/bullmq 为其自身 id；自定义驱动自行生成） */
     id: string;
     name: string;
     payload: unknown;
@@ -40,6 +40,28 @@ interface TaskDriverJob {
 }
 /** 语义层交给驱动层的执行函数（抛错 = 失败，由驱动按入队时的 retries 重试） */
 type TaskDriverProcess = (job: TaskDriverJob) => Promise<unknown>;
+/**
+ * 驱动侧任务查询记录（TaskDriver.list 的返回项）
+ *
+ * status 由子包从队列系统原生状态映射为 faapi 语义
+ * （pgboss：created→pending、active→running、completed→done、cancelled→cancelled；
+ * bullmq：waiting/delayed→pending、active→running、completed→done、failed→failed），
+ * 语义层零映射直接转 TaskJob。
+ */
+interface TaskDriverRecord {
+    id: string;
+    name: string;
+    payload: unknown;
+    status: TaskJobStatus;
+    attempts: number;
+    /** 执行返回值（已完成时） */
+    result?: unknown;
+    /** 失败/取消原因 */
+    error?: string;
+    createdAt: number;
+    /** 计划执行时间戳（延迟任务） */
+    runAt?: number;
+}
 /**
  * 任务队列驱动接口
  */
@@ -48,11 +70,15 @@ interface TaskDriver {
      * 入队一个任务，返回驱动侧任务 id
      *
      * @param opts.retries 失败重试次数（语义层从任务 meta 取，驱动负责执行重试策略）
+     * @param opts.dedupId 幂等键（可选）——同键任务在队列系统保留期内不重复入队。
+     *   pgboss 映射 send 自定义 id（驱动内做任意字符串 → 确定性 UUID 映射，冲突跳过）；
+     *   bullmq 映射 jobId。重复投递时返回已存在任务的 id。
      * @throws 驱动已停止 / 连接失败等
      */
     enqueue(name: string, payload: unknown, opts?: {
         delayMs?: number;
         retries?: number;
+        dedupId?: string;
     }): Promise<string>;
     /**
      * 注册某任务的消费 worker（幂等覆盖）。process 抛错 = 本次失败，驱动决定重试。
@@ -66,8 +92,59 @@ interface TaskDriver {
     stop(timeoutMs?: number): Promise<void>;
     /** 仅停止 worker 消费（不断开驱动连接），供 dev reloadTasks 重注册用；可选 */
     stopWorkers?(): Promise<void>;
+    /**
+     * 查询持久化队列任务（可选能力）
+     *
+     * 未实现时 TaskClient.listQueued 显式抛错。pg-boss v10 无批量列出 jobs 的公开 API，
+     * task-pgboss 未实现；BullMQ API 完整，task-bullmq 全支持。
+     * 不传 name 时列出本进程已创建队列/已知任务的范围由驱动自行定义。
+     */
+    list?(opts?: {
+        name?: string;
+        /** 按 faapi 语义状态过滤 */
+        state?: TaskJobStatus;
+        /** 返回条数上限（默认由驱动决定，建议 50） */
+        limit?: number;
+    }): Promise<TaskDriverRecord[]>;
+    /**
+     * 取消队列侧任务（可选能力）：等待/延迟中的不再执行。
+     * pgboss → boss.cancel（保留 cancelled 记录）；bullmq → job.remove()（记录随之移除）。
+     */
+    cancel?(name: string, id: string): Promise<void>;
+    /**
+     * 重试失败/取消的任务（可选能力）。
+     * pgboss → boss.resume（仅 cancelled）；bullmq → job.retry()（仅 failed）。
+     * 任务不存在 / 状态不允许时由驱动抛错。
+     */
+    retry?(name: string, id: string): Promise<void>;
 }
 
+/**
+ * 隔离执行器签名（taskQueue 按任务 meta.timeoutMs 调用；测试可注入 spy）
+ */
+type TaskWorkerRunner = typeof runTaskInWorker;
+interface TaskWorkerOptions {
+    /** 任务产物模块绝对路径（`<dist>/tasks/<dir>/task.js`） */
+    taskModulePath: string;
+    payload: unknown;
+    /** signal 由执行器构造（abort/terminate 时触发），宿主只传 config 与 job 信息 */
+    taskCtx: {
+        config: unknown;
+        job: {
+            id: string;
+            name: string;
+            attempt: number;
+        };
+    };
+    /** 单次执行超时（毫秒） */
+    timeoutMs: number;
+    /** 外部取消信号（驱动停机超时 abort）——abort 同样触发两段式取消 */
+    externalSignal?: AbortSignal;
+    /** 宽限期覆盖（默认 KILL_GRACE_MS）——测试注入短值用，业务不配置 */
+    killGraceMs?: number;
+}
+declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
+
 /**
  * 任务元信息（业务方在 task.ts 中 `export const task = {...}` 声明）
  *
@@ -78,6 +155,12 @@ interface FaapiTaskMeta {
     concurrency?: number;
     /** 失败重试次数（默认 0——失败即 failed，不重试） */
     retries?: number;
+    /**
+     * 单次执行超时（毫秒）。声明后该任务在独立 worker 线程执行，超时两段式取消
+     * （先 abort 信号宽限 5s，未退出 terminate 硬杀）——判定超时即执行真正终止。
+     * 未声明走进程内执行（零开销，但卡住时框架只能不再等待）。
+     */
+    timeoutMs?: number;
     /** cron 表达式（croner 语法，支持秒级）——到点自动入队空 payload */
     cron?: string;
 }
@@ -92,6 +175,7 @@ interface TaskManifest {
     cron?: string;
     concurrency?: number;
     retries?: number;
+    timeoutMs?: number;
 }
 /**
  * 运行时任务元数据（faapi-tasks.js 水合到 TaskRegistry 后的形态，产物路径形式）
@@ -103,9 +187,15 @@ interface TaskMetadata {
     cron?: string;
     concurrency?: number;
     retries?: number;
+    timeoutMs?: number;
 }
-/** 任务记录状态 */
-type TaskJobStatus = 'pending' | 'running' | 'retry' | 'done' | 'failed';
+/**
+ * 任务记录状态
+ *
+ * cancelled = 执行被框架终止（超时两段式取消 / 停机取消），区别于 run 自身抛错的 failed；
+ * 驱动重试时记录回到 running 继续流转。
+ */
+type TaskJobStatus = 'pending' | 'running' | 'retry' | 'done' | 'failed' | 'cancelled';
 /**
  * 任务执行记录（内存快照）
  */
@@ -151,16 +241,42 @@ interface TaskClient {
     /**
      * 入队一个任务
      *
+     * @param opts.dedupId 幂等键（可选）——同键任务在队列系统保留期内不重复入队，
+     *   重复投递返回已存在任务 id（驱动语义见 driverTypes.md）；cron 投递自动携带
      * @returns 任务 id
      * @throws 任务不存在 / 队列已停止 / payload 校验失败（ValidationError）
      */
     enqueue(name: string, payload?: unknown, opts?: {
         delayMs?: number;
+        dedupId?: string;
     }): Promise<{
         id: string;
     }>;
-    /** 任务记录快照（可按任务名过滤） */
+    /** 任务记录快照（可按任务名过滤）——本进程内存活记录，不含其他实例/重启前历史 */
     list(name?: string): TaskJob[];
+    /**
+     * 持久化队列视图：驱动实现 `TaskDriver.list` 时返回队列侧任务（含其他实例的
+     * 与历史执行），并与本进程记录按 id 合并（本进程观测优先：status/attempts/
+     * result/error 以本进程为准）
+     *
+     * @throws 驱动未实现 TaskDriver.list（能力边界见 driverTypes.md——pgboss 未实现，
+     * 用 pg-boss 自身 API/SQL 旁路；BullMQ 全支持）
+     */
+    listQueued(name?: string): Promise<TaskJob[]>;
+    /**
+     * 取消队列侧任务：等待/延迟中的不再执行（语义随驱动——pgboss 保留 cancelled
+     * 记录，bullmq 为 job.remove 即移除）
+     *
+     * @throws 驱动未实现 TaskDriver.cancel
+     */
+    cancel(name: string, id: string): Promise<void>;
+    /**
+     * 重试队列侧失败/取消的任务（pgboss 仅 cancelled 可 resume；bullmq 仅 failed
+     * 可 retry；任务不存在/状态不允许由驱动抛错）
+     *
+     * @throws 驱动未实现 TaskDriver.retry
+     */
+    retry(name: string, id: string): Promise<void>;
 }
 /**
  * 任务队列（TaskClient + 生命周期控制，createAppBase 内部使用）
@@ -184,15 +300,40 @@ interface TaskQueueDeps {
     /** faapi.config.ts 全量配置，透传给 run 的 TaskContext.config */
     config?: unknown;
     /**
-     * 队列驱动（默认 memoryDriver——进程内数组，重启丢任务）
-     * 外部驱动：`@faapi/task-pgboss` / `@faapi/task-bullmq` 或自定义 TaskDriver 实例
+     * 队列驱动（必填）：`loadTaskDriver` 解析结果（pgboss/bullmq 子包驱动）
+     * 或自定义 TaskDriver 实例；无任务清单时由 createAppBase 传入 idleTaskDriver
      */
-    driver?: TaskDriver;
+    driver: TaskDriver;
     /** 任务模块加载器（默认：import 产物路径） */
     loadTaskModule?: (filePath: string) => Promise<TaskModule>;
     /** payload schema 加载器（默认：import 任务目录 zod.js，取首个 `*Schema` 导出） */
     loadPayloadSchema?: (filePath: string) => Promise<unknown>;
+    /**
+     * 隔离执行器（默认 runTaskInWorker）——任务声明 timeoutMs 时由语义层调用，
+     * 独立 worker 线程执行 + 超时两段式取消；测试注入 spy 验证执行路径路由
+     */
+    runIsolated?: TaskWorkerRunner;
+    /**
+     * 执行失败/取消钩子（config.task.onFailed）——每次 process 抛错后触发
+     * （含将重试的失败）；用于告警/死信上报等副作用，自身抛错被忽略
+     */
+    onFailed?: TaskFailedHandler;
+}
+/**
+ * 任务失败信息（onFailed 钩子参数）
+ *
+ * willRetry 按任务 meta.retries 推算（attempt <= retries 时驱动会重试）；
+ * cancelled = 执行被框架终止（超时终止/停机取消），与 run 自身失败区分。
+ */
+interface TaskFailedInfo {
+    task: string;
+    jobId: string;
+    attempt: number;
+    willRetry: boolean;
+    cancelled: boolean;
+    error: string;
 }
+type TaskFailedHandler = (info: TaskFailedInfo) => Promise<void> | void;
 
 /**
  * SSE（Server-Sent Events）支持
@@ -919,4 +1060,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { type AppRegistries as A, type TaskDriverProcess as B, type CorsOptions as C, type TaskJob as D, type TaskJobStatus as E, type FaapiContext as F, type TaskMetadata as G, type HelmetOptions as H, type InjectorMap as I, type TaskModule as J, type ToolCore as K, type LoggerOptions as L, type ToolPathMeta as M, type ToolRegistry as N, cors as O, createAppRegistries as P, createTaskRegistry as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, helmet as U, logger as V, type WsRouteManifest as W, type FaapiMiddleware as a, type TaskQueueDeps as b, type TaskQueue as c, type TaskDriver as d, type TaskRegistry as e, type TaskManifest as f, type ToolMetadata as g, type AgentCore as h, type AgentMetadata as i, type AgentHandleFactory as j, type AgentHandleStore as k, type AgentPathMeta as l, type AgentRegistry as m, type AgentToolDescriptor as n, type FaapiContextConfig as o, type FaapiTaskMeta as p, type FailOptions as q, type Injector as r, type RouteInfo as s, type RouteInputSchema as t, type RouteOutputSchema as u, type RouteParamSchema as v, type SseEvent as w, type SseWriter as x, type TaskContext as y, type TaskDriverJob as z };
+export { type AppRegistries as A, type TaskDriverJob as B, type CorsOptions as C, type TaskDriverProcess as D, type TaskDriverRecord as E, type FaapiContext as F, type TaskFailedInfo as G, type HelmetOptions as H, type InjectorMap as I, type TaskJob as J, type TaskJobStatus as K, type LoggerOptions as L, type TaskMetadata as M, type TaskModule as N, type ToolCore as O, type ToolPathMeta as P, type ToolRegistry as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, cors as U, createAppRegistries as V, type WsRouteManifest as W, createTaskRegistry as X, helmet as Y, logger as Z, type FaapiMiddleware as a, type TaskFailedHandler as b, type TaskQueueDeps as c, type TaskQueue as d, type TaskDriver as e, type TaskRegistry as f, type TaskManifest as g, type ToolMetadata as h, type AgentCore as i, type AgentMetadata as j, type AgentHandleFactory as k, type AgentHandleStore as l, type AgentPathMeta as m, type AgentRegistry as n, type AgentToolDescriptor as o, type FaapiContextConfig as p, type FaapiTaskMeta as q, type FailOptions as r, type Injector as s, type RouteInfo as t, type RouteInputSchema as u, type RouteOutputSchema as v, type RouteParamSchema as w, type SseEvent as x, type SseWriter as y, type TaskContext as z };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-CCveqSnY.js';
+import { F as FaapiContext, a as FaapiMiddleware, I as InjectorMap, R as RouteManifest, W as WsRouteManifest, C as CorsOptions, H as HelmetOptions, L as LoggerOptions } from './routeTypes-_17rXzal.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faapi/faapi",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "函数即接口 - Function as API",
   "type": "module",
   "main": "./dist/index.js",