@faapi/faapi 6.17.0 → 6.18.1

package/dist/{routeTypes-C7yHYxPg.d.ts → routeTypes-BAhPIzcG.d.ts}

@@ -183,8 +183,8 @@ 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），
+ * （bullmq：waiting/delayed→pending、active→running、completed→done、failed→failed；
+ * pg-boss v10 无批量列出 jobs 的公开 API，task-pgboss 未实现 list），
  * 语义层零映射直接转 TaskJob。
  */
 interface TaskDriverRecord {
@@ -212,12 +212,18 @@ interface TaskDriver {
      * @param opts.dedupId 幂等键（可选）——同键任务在队列系统保留期内不重复入队。
      *   pgboss 映射 send 自定义 id（驱动内做任意字符串 → 确定性 UUID 映射，冲突跳过）；
      *   bullmq 映射 jobId。重复投递时返回已存在任务的 id。
+     * @param opts.timeoutMs 任务执行超时毫秒（语义层从任务 meta 取）——驱动以此设置
+     *   队列系统的执行硬限（pgboss 映射 expireInSeconds），防止队列系统默认限值
+     *   （pg-boss DDL 15 分钟）强杀仍在运行的长任务后重试，导致同一任务两份并发执行
+     * @param opts.graceMs 超时取消宽限期毫秒（与 timeoutMs 配套，驱动计入执行硬限预算）
      * @throws 驱动已停止 / 连接失败等
      */
     enqueue(name: string, payload: unknown, opts?: {
         delayMs?: number;
         retries?: number;
         dedupId?: string;
+        timeoutMs?: number;
+        graceMs?: number;
     }): Promise<string>;
     /**
      * 注册某任务的消费 worker（幂等覆盖）。process 抛错 = 本次失败，驱动决定重试。
@@ -766,6 +772,8 @@ type TaskFailedHandler = (info: TaskFailedInfo) => Promise<void> | void;
  *   非 nginx 反代不识别该头，当普通自定义头透传）
  * - close 后再 send 静默忽略，避免 handler 异步流程中误写已关闭的流
  * - sendError 向流写入 event: error 后关闭，用于流式输出中报错的优雅终止
+ * - 背压：send/sendRaw 保持同步；desiredSize 暴露缓冲状态，waitForDrain() 供
+ *   生产循环在缓冲超水位时暂停（pull 钩子唤醒），防慢客户端内存无界增长
  *
  * 与 ctx 的集成：
  * - ctx.sse() 调用 createSseWriter()，并把 response 缓存到 ctx 内部字段
@@ -821,6 +829,22 @@ interface SseWriter {
     readonly closed: boolean;
     /** 客户端是否已断开（ReadableStream 被 cancel） */
     readonly aborted: boolean;
+    /**
+     * 流缓冲背压状态（透传 controller.desiredSize）
+     *
+     * `null` = 流已关闭/断开；`<= 0` 表示消费慢于生产（缓冲超过高水位），生产循环
+     * 应 `await waitForDrain()` 暂停，否则快生产者（LLM token 流）+ 慢客户端会让
+     * 缓冲无界增长。`send`/`sendRaw` 保持同步不抛，背压响应由调用方自决。
+     */
+    readonly desiredSize: number | null;
+    /**
+     * 等待流缓冲排空（背压感知）
+     *
+     * 缓冲低于高水位（desiredSize > 0）时立即返回；否则挂起直到消费者拉取使缓冲
+     * 排空（ReadableStream pull 钩子唤醒）、或流关闭/客户端断开（避免悬挂）。
+     * 典型用法见 runtime/sse.md「背压」章节。
+     */
+    waitForDrain(): Promise<void>;
     /** 对应的 HTTP Response（由框架使用，用户一般不需要直接访问） */
     readonly response: Response;
 }

package/dist/testing.d.ts

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