@faapi/faapi 6.21.0 → 6.22.0

package/dist/{routeTypes-gyz4PMh7.d.ts → routeTypes-CXWkRx4W.d.ts}

@@ -762,7 +762,7 @@ type TaskFailedHandler = (info: TaskFailedInfo) => Promise<void> | void;
  *
  * 核心导出：
  * - `encodeSseEvent(event)`：把 SSE 事件对象编码为符合 HTML5 SSE 规范的字符串
- * - `createSseWriter()`：创建一个 SseWriter，封装 ReadableStream + Response，提供 send/close/sendError API
+ * - `createSseWriter()`：创建一个 SseWriter，封装 ReadableStream + Response，提供 send/close/onClose/sendError API
  * - `SseWriter`：writer 类型，ctx.sse() 返回此类型
  *
  * 设计要点：
@@ -803,6 +803,20 @@ interface SseEvent {
     /** 注释行（以 : 开头），用于 keep-alive 心跳 */
     comment?: string;
 }
+/**
+ * ctx.sse() 的选项
+ */
+interface SseOptions {
+    /**
+     * 声明流生命周期独立于 handler 返回（长连接订阅模式）
+     *
+     * `true` 时 handler 返回后框架不自动 close——handler 只负责把连接挂到推送源
+     * （事件总线、change stream），注册完立即返回，连接长存直到显式 close()、
+     * 客户端断开或 handler 抛错兜底。清理推送源用 `onClose(callback)`。
+     * 默认 false（handler 返回时框架自动 close 兜底）。
+     */
+    keepOpen?: boolean;
+}
 /**
  * SSE writer：封装流式推送 API
  *
@@ -827,10 +841,20 @@ interface SseWriter {
     sendError(error: unknown): void;
     /** 关闭流（多次调用安全） */
     close(): void;
+    /**
+     * 注册流结束回调
+     *
+     * 显式 close、框架兜底 close、客户端断开、sendError 任一路径结束流时恰好触发
+     * 一次（多个回调按注册顺序执行，回调自身抛错被忽略）；注册时流已结束则立即触发。
+     * keepOpen 模式下用于退订/清理推送源，防止客户端断开后订阅随重连累积泄漏。
+     */
+    onClose(callback: () => void): void;
     /** 流是否已关闭（handler 主动 close 或框架自动 close） */
     readonly closed: boolean;
     /** 客户端是否已断开（ReadableStream 被 cancel） */
     readonly aborted: boolean;
+    /** 创建时是否声明了 `{ keepOpen: true }`（handler 返回后框架不自动 close） */
+    readonly keepOpen: boolean;
     /**
      * 流缓冲背压状态（透传 controller.desiredSize）
      *
@@ -1061,8 +1085,12 @@ interface FaapiContext {
      *   sse.close();
      * }
      * ```
+     *
+     * @param options `{ keepOpen: true }` 声明流生命周期独立于 handler 返回（长连接
+     *   订阅模式）：handler 返回后框架不自动 close，连接长存直到显式 close()、客户端
+     *   断开或 handler 抛错兜底；清理推送源用 `writer.onClose(callback)`。默认 false。
      */
-    sse(): SseWriter;
+    sse(options?: SseOptions): SseWriter;
     /**
      * 显式包装成功响应(返回 Response 对象)
      *
@@ -1313,4 +1341,4 @@ interface RouteInfo {
     output: RouteOutputSchema | null;
 }
 
-export { type ToolRegistry as $, type AppRegistries as A, type RouteOutputSchema as B, type CorsOptions as C, type RouteParamSchema as D, type SseEvent as E, type FaapiMiddleware as F, type SseWriter as G, type HelmetOptions as H, type InjectorMap as I, type TaskContext as J, type TaskDriverJob as K, type LogConfig as L, type TaskDriverProcess as M, type TaskDriverRecord as N, type TaskFailedInfo as O, type TaskJob as P, type TaskJobStatus as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type TaskMetadata as U, type TaskModule as V, type WsRouteManifest as W, type TaskRegistriesSnapshot as X, type TaskRegistriesView as Y, type ToolCore as Z, type ToolPathMeta as _, type FaapiContext as a, cors as a0, createAppRegistries as a1, createTaskRegistriesView as a2, createTaskRegistry as a3, helmet as a4, 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 CreateLoggerOptions as k, type Logger as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type FaapiContextConfig as r, type FaapiTaskMeta as s, type FailOptions as t, type Injector as u, type LogEntry as v, type LogLevel as w, type LogSink as x, type RouteInfo as y, type RouteInputSchema as z };
+export { type ToolPathMeta as $, type AppRegistries as A, type RouteOutputSchema as B, type CorsOptions as C, type RouteParamSchema as D, type SseEvent as E, type FaapiMiddleware as F, type SseOptions as G, type HelmetOptions as H, type InjectorMap as I, type SseWriter as J, type TaskContext as K, type LogConfig as L, type TaskDriverJob as M, type TaskDriverProcess as N, type TaskDriverRecord as O, type TaskFailedInfo as P, type TaskJob as Q, type RouteManifest as R, type SkillRegistry as S, type TaskClient as T, type TaskJobStatus as U, type TaskMetadata as V, type WsRouteManifest as W, type TaskModule as X, type TaskRegistriesSnapshot as Y, type TaskRegistriesView as Z, type ToolCore as _, type FaapiContext as a, type ToolRegistry as a0, cors as a1, createAppRegistries as a2, createTaskRegistriesView as a3, createTaskRegistry as a4, helmet as a5, 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 CreateLoggerOptions as k, type Logger as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type FaapiContextConfig as r, type FaapiTaskMeta as s, type FailOptions as t, type Injector as u, type LogEntry as v, type LogLevel as w, type LogSink as x, type RouteInfo as y, type RouteInputSchema as z };

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-gyz4PMh7.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-CXWkRx4W.js';
 import { Server } from 'node:http';
 import { WebSocket } from 'ws';
 

package/dist/testing.js

@@ -155,13 +155,28 @@ function encodeSseEvent(event) {
   return out;
 }
 function createSseWriter(options = {}) {
-  const { onFirstWrite } = options;
+  const { onFirstWrite, keepOpen = false } = options;
   const encoder = new TextEncoder();
   let controller = null;
   let closed = false;
   let aborted = false;
   let firstWriteTriggered = false;
   let drainWaiters = [];
+  let closeCallbacks = [];
+  let closeCallbacksFired = false;
+  const safeRunCallback = (callback) => {
+    try {
+      callback();
+    } catch {
+    }
+  };
+  const runCloseCallbacks = () => {
+    if (closeCallbacksFired) return;
+    closeCallbacksFired = true;
+    const callbacks = closeCallbacks;
+    closeCallbacks = [];
+    for (const callback of callbacks) safeRunCallback(callback);
+  };
   const resolveDrainWaiters = () => {
     const waiters = drainWaiters;
     drainWaiters = [];
@@ -185,6 +200,7 @@ function createSseWriter(options = {}) {
         aborted = true;
         closed = true;
         controller = null;
+        runCloseCallbacks();
         resolveDrainWaiters();
       }
     },
@@ -227,6 +243,7 @@ function createSseWriter(options = {}) {
     close() {
       if (closed) return;
       closed = true;
+      runCloseCallbacks();
       resolveDrainWaiters();
       if (controller) {
         try {
@@ -236,6 +253,13 @@ function createSseWriter(options = {}) {
         controller = null;
       }
     },
+    onClose(callback) {
+      if (closeCallbacksFired) {
+        safeRunCallback(callback);
+        return;
+      }
+      closeCallbacks.push(callback);
+    },
     get closed() {
       return closed;
     },
@@ -252,6 +276,9 @@ function createSseWriter(options = {}) {
     get aborted() {
       return aborted;
     },
+    get keepOpen() {
+      return keepOpen;
+    },
     get response() {
       return response;
     }
@@ -633,10 +660,15 @@ function createContextFromUrl(request, url, params, config = {}, ip = "", regist
      * 接入底层连接——流式期间字节即产即达（见 createServer.md「SSE 提前接管」）。
      * 无钩子场景（app.inject / 测试直调 invokeHandler）回落为 handler 返回后交出。
      *
+     * `{ keepOpen: true }` 声明流生命周期独立于 handler 返回：handler 返回后框架
+     * 不自动 close（长连接订阅模式，清理推送源用 writer.onClose）；handler 抛错
+     * 的兜底 close 不受影响。详见 runtime/sse.md「长连接订阅模式」。
+     *
      * 与 ctx.json / ctx.html 互斥：一个 handler 只能用一种响应方式。
      */
-    sse() {
+    sse(options) {
       const writer = createSseWriter({
+        keepOpen: options?.keepOpen,
         onFirstWrite: (response) => {
           ctx.__earlyRespond?.(response);
         }
@@ -1265,7 +1297,7 @@ async function invokeHandler(handler, ctx, body, middlewares, injectors) {
   const pickSseAndAutoClose = () => {
     const sseWriter = ctx.__sseWriter;
     if (!sseWriter) return null;
-    if (!sseWriter.closed && !sseWriter.aborted) {
+    if (!sseWriter.keepOpen && !sseWriter.closed && !sseWriter.aborted) {
       sseWriter.close();
     }
     return mergeMeta(sseWriter.response, meta);