@faapi/faapi 1.0.0-canary.d7438c8 → 1.0.1-canary.218585b

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import * as node_http from 'node:http';
 import { Server, IncomingMessage, ServerResponse } from 'node:http';
 import { Socket } from 'node:net';
 import ts from 'typescript';
+import { WebSocket } from 'ws';
 
 /**
  * SSE（Server-Sent Events）支持
@@ -1122,6 +1123,181 @@ declare function createContext(request: Request, params: Record<string, string>,
  */
 declare function invokeHandler(handler: (...args: unknown[]) => unknown, ctx: FaapiContext, body?: unknown, middlewares?: FaapiMiddleware[], injectors?: InjectorMap): Promise<Response>;
 
+/**
+ * createTestServer 入参
+ *
+ * 业务方一行代码启动带 schema 校验的 E2E 测试服务器。
+ * 详见 src/testServer.md。
+ */
+interface TestServerOptions {
+    /** 项目根目录（路由源码所在，必填） */
+    rootDir: string;
+    patterns?: string[];
+    /**
+     * schema 产物输出目录（绝对路径或相对 rootDir）。
+     * 不传时自动 mkdtemp 生成临时目录，close() 时清理。
+     * 传值时 close() 仍会清理该目录。
+     */
+    dist?: string;
+    /** CORS 中间件配置，默认 false（禁用，避免污染断言） */
+    cors?: CorsOptions | boolean;
+    /** 安全头配置，默认 false */
+    helmet?: HelmetOptions | boolean;
+    /** 请求日志配置，默认 false（避免污染测试输出） */
+    logger?: LoggerOptions | boolean;
+    /** 全局中间件（外层洋葱） */
+    middlewares?: FaapiMiddleware[];
+    /** 全局注入器 */
+    injectors?: InjectorMap;
+    /** 请求错误钩子（在错误响应生成后调用，用于副作用） */
+    onError?: (error: unknown, ctx: FaapiContext) => Promise<void> | void;
+    /** 业务配置（注入到 ctx.config） */
+    config?: Record<string, unknown>;
+    /** 请求体大小限制（字节），默认 10MB */
+    bodyLimit?: number;
+}
+/**
+ * createTestServer 返回值
+ *
+ * 业务方通过 baseUrl 发 fetch 请求，close() 一行完成 teardown。
+ */
+interface TestServer {
+    /** Node.js HTTP Server 实例（已 listen） */
+    server: Server;
+    /** 形如 http://localhost:<随机端口> */
+    baseUrl: string;
+    /** 排序后的路由清单 */
+    routes: RouteManifest;
+    /** WebSocket 路由清单 */
+    wsRoutes: WsRouteManifest;
+    /** schema 临时目录绝对路径（业务方调试时可查看生成的 zod.js） */
+    schemaDist: string;
+    /**
+     * 关闭 server + 清理 schema 目录 + 清空 schema 模块缓存
+     *
+     * 内部顺序：
+     * 1. server.closeAllConnections?.()（Node 18+，强制断开 WS / 长连接）
+     * 2. server.close()
+     * 3. fs.rm(schemaDist, { recursive, force })
+     * 4. invalidateSchemaCache()
+     *
+     * 幂等：重复调用不会重复清理。
+     */
+    close(): Promise<void>;
+}
+/**
+ * 一键启动带 schema 校验的 E2E 测试服务器
+ *
+ * 内部流程：
+ * 1. scanRoutes 扫描路由
+ * 2. sortRoutes 排序
+ * 3. mkdtemp 创建临时 schema 目录（或用传入的 dist）
+ * 4. generateSchemaFiles 生成 zod.js
+ * 5. createServer 创建 server（默认禁用 CORS/Helmet/Logger，避免污染断言）
+ * 6. server.listen(0) 随机端口
+ * 7. 返回 TestServer
+ *
+ * 详见 src/testServer.md。
+ *
+ * @param options rootDir 必填，其余可选
+ * @returns TestServer 实例
+ */
+declare function createTestServer(options: TestServerOptions): Promise<TestServer>;
+
+/**
+ * WebSocket 测试客户端
+ *
+ * 公开导出 connectWs + MessageQueue + waitForWsOpen，业务方测试 WS 路由时
+ * 免去手写"消息竞态防护 + 三事件监听 + 端口拼接"样板代码。
+ *
+ * 详见 src/wsTestClient.md。
+ */
+/**
+ * connectWs 入参
+ */
+interface WsTestClientOptions {
+    /** 等待 open 的超时（ms），默认 2000 */
+    timeout?: number;
+    /** 握手请求头（如 authorization） */
+    headers?: Record<string, string>;
+    /** WS 子协议 */
+    protocols?: string | string[];
+}
+/**
+ * connectWs 返回值
+ *
+ * 业务方通过 ws.send() 发消息，queue.next() 取消息，close() 关闭。
+ */
+interface WsTestClient {
+    /** ws 库原生实例，业务方可直接 ws.send() / ws.close() */
+    ws: WebSocket;
+    /** 已开始缓冲的消息队列，调 next(timeout?) 取下一条 */
+    queue: MessageQueue;
+    /**
+     * 关闭 ws 并等待 'close' 事件
+     *
+     * 内部：
+     * 1. 若 ws 仍 OPEN/CLOSING，调 ws.close()
+     * 2. 等待 'close' 事件（超时 1000ms 强制 resolve）
+     *
+     * 幂等：重复调用不抛错。
+     */
+    close(): Promise<void>;
+}
+/**
+ * 消息队列：避免 once('message') 与服务端 onOpen 推送的竞态
+ *
+ * 服务端在 handleUpgrade 回调里同步触发 onOpen 并 send('connected')，
+ * 客户端 'open' 事件触发后到注册 once('message') 之间存在窗口，
+ * 若 'connected' 在此窗口内到达，once 会错过。
+ *
+ * 队列在创建 ws 时立即监听 'message'，按 FIFO 顺序消费。
+ */
+declare class MessageQueue {
+    private queue;
+    private waiters;
+    private listener;
+    constructor(ws: WebSocket);
+    /**
+     * 取下一条消息
+     *
+     * 队列有则立即 resolve，无则注册 waiter 等待下一条 'message' 事件。
+     * 超时未到 → reject('WebSocket message timeout')，waiter 被清理。
+     *
+     * @param timeout 超时毫秒，默认 2000
+     */
+    next(timeout?: number): Promise<string>;
+}
+/**
+ * Promise 化等待 ws 'open' 事件
+ *
+ * 同时监听 'open' / 'error' / 'close' 三事件，任一触发都清理 timer，
+ * 避免 timer 泄漏。
+ *
+ * @param ws WebSocket 实例
+ * @param timeout 超时毫秒，默认 2000
+ * @returns 'open' → resolve；'error' → reject(err)；'close' → reject；超时 → reject
+ */
+declare function waitForWsOpen(ws: WebSocket, timeout?: number): Promise<void>;
+/**
+ * 一键连接 WS server
+ *
+ * 内部流程：
+ * 1. baseUrl 协议转换（http → ws，https → wss）
+ * 2. new WebSocket(url, protocols, { headers })
+ * 3. 立即创建 MessageQueue（开始缓冲消息，避免竞态）
+ * 4. waitForWsOpen 等待连接建立（三事件监听 + 超时清理）
+ * 5. 返回 WsTestClient
+ *
+ * 连接失败（中间件拦截 / 路径未匹配 / 超时）→ reject。
+ *
+ * @param baseUrl createTestServer().baseUrl（http://...）
+ * @param pathname WS 路径，如 '/api/chat'，可含 query
+ * @param options timeout / headers / protocols
+ * @returns WsTestClient 实例
+ */
+declare function connectWs(baseUrl: string, pathname: string, options?: WsTestClientOptions): Promise<WsTestClient>;
+
 interface InjectOptions {
     method?: string;
     path?: string;
@@ -1215,4 +1391,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, collectRouteSchemaSources, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, loadEnv, logger, resolveTypeNode };
+export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MessageQueue, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TestServer, type TestServerOptions, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, type WsTestClient, type WsTestClientOptions, collectRouteSchemaSources, connectWs, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, createTestServer, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, loadEnv, logger, resolveTypeNode, waitForWsOpen };