@dangao/bun-server 2.1.0 → 2.3.0

package/src/ai/service.ts

@@ -120,7 +120,7 @@ export class AiService {
     const timeout = this.options.timeout ?? 30000;
 
     if (!fallback) {
-      return this.withTimeout(this.getProvider(targetName).complete(request), timeout, targetName);
+      return this.withTimeout(this.getProvider(targetName).complete(request), timeout, targetName, request.signal);
     }
 
     // Fallback chain: try target first, then others in order
@@ -134,7 +134,7 @@ export class AiService {
       try {
         const provider = this.providers.get(name);
         if (!provider) continue;
-        return await this.withTimeout(provider.complete({ ...request, provider: name }), timeout, name);
+        return await this.withTimeout(provider.complete({ ...request, provider: name }), timeout, name, request.signal);
       } catch (err) {
         errors.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
       }
@@ -143,12 +143,24 @@ export class AiService {
     throw new AiAllProvidersFailed(errors);
   }
 
-  private withTimeout<T>(promise: Promise<T>, ms: number, providerName: string): Promise<T> {
+  private withTimeout<T>(promise: Promise<T>, ms: number, providerName: string, signal?: AbortSignal): Promise<T> {
     return new Promise<T>((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(signal.reason ?? new Error('Aborted'));
+        return;
+      }
+
       const timer = setTimeout(() => reject(new AiTimeoutError(providerName, ms)), ms);
+
+      const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal!.reason ?? new Error('Aborted'));
+      };
+      signal?.addEventListener('abort', onAbort, { once: true });
+
       promise.then(
-        (val) => { clearTimeout(timer); resolve(val); },
-        (err) => { clearTimeout(timer); reject(err); },
+        (val) => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); resolve(val); },
+        (err) => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); reject(err); },
       );
     });
   }

package/src/ai/types.ts

@@ -45,6 +45,11 @@ export interface AiRequest {
   tools?: AiToolDefinition[];
   /** Provider name override */
   provider?: string;
+  /**
+   * Abort signal — pass `ctx.signal` to cascade client disconnection
+   * to the upstream AI API, stopping token consumption immediately.
+   */
+  signal?: AbortSignal;
 }
 
 /**

package/src/core/application.ts

@@ -61,6 +61,24 @@ export interface ApplicationOptions {
    * 框架内部会自动转换为 Bun.serve 的秒单位
    */
   idleTimeout?: number;
+
+  /**
+   * SSE 保活配置
+   *
+   * 框架自动检测 `Content-Type: text/event-stream` 的响应，
+   * 对该请求禁用 Bun TCP 空闲超时（`server.timeout(req, 0)`），
+   * 并按配置间隔向客户端发送 SSE 注释心跳（`: keepalive\n\n`）。
+   *
+   * 心跳可防止中间代理（nginx / 云 LB）因空闲而断开连接。
+   *
+   * @default `{ enabled: true, intervalMs: 15000 }`
+   */
+  sseKeepAlive?: {
+    /** 是否启用，默认 true */
+    enabled?: boolean;
+    /** 心跳间隔（毫秒），默认 15000 */
+    intervalMs?: number;
+  };
 }
 
 /**
@@ -150,6 +168,7 @@ export class Application {
       hostname: finalHostname,
       reusePort: this.options.reusePort,
       idleTimeout: this.options.idleTimeout,
+      sseKeepAlive: this.options.sseKeepAlive,
       fetch: this.handleRequest.bind(this),
       websocketRegistry: this.websocketRegistry,
       gracefulShutdownTimeout: this.options.gracefulShutdownTimeout,
@@ -324,6 +343,7 @@ export class Application {
    */
   private async handleRequest(context: Context): Promise<Response> {
     const logger = LoggerManager.getLogger();
+    const moduleRegistry = ModuleRegistry.getInstance();
     logger.debug('[Request] Incoming', {
       method: context.method,
       path: context.path,
@@ -332,34 +352,46 @@ export class Application {
 
     // 使用 AsyncLocalStorage 包裹请求处理，确保所有中间件和控制器都在请求上下文中执行
     return await contextStore.run(context, async () => {
-      // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
-      // 这样可以确保 Request.body 流只读取一次
-      if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
-        await context.getBody();
-      }
+      try {
+        // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
+        // 这样可以确保 Request.body 流只读取一次
+        if (['POST', 'PUT', 'PATCH'].includes(context.method)) {
+          await context.getBody();
+        }
 
-      // 先通过路由解析出处理器信息，便于安全中间件等基于路由元数据做决策
-      const registry = RouteRegistry.getInstance();
-      const router = registry.getRouter();
+        // 先通过路由解析出处理器信息，便于安全中间件等基于路由元数据做决策
+        const registry = RouteRegistry.getInstance();
+        const router = registry.getRouter();
 
-      // 预解析路由，仅设置上下文信息，不执行处理器
-      await router.preHandle(context);
+        // 预解析路由，仅设置上下文信息，不执行处理器
+        await router.preHandle(context);
 
-      // 再进入中间件管道，由中间件（如安全过滤器）根据 routeHandler 和 Auth 元数据做校验，
-      // 最后再由路由真正执行控制器方法
-      return await this.middlewarePipeline.run(context, async () => {
-        const response = await router.handle(context);
-        if (response) {
-          return response;
-        }
+        // 再进入中间件管道，由中间件（如安全过滤器）根据 routeHandler 和 Auth 元数据做校验，
+        // 最后再由路由真正执行控制器方法
+        return await this.middlewarePipeline.run(context, async () => {
+          const response = await router.handle(context);
+          if (response) {
+            return response;
+          }
 
-        logger.debug('[Router] No route matched', {
-          method: context.method,
-          path: context.path,
+          logger.debug('[Router] No route matched', {
+            method: context.method,
+            path: context.path,
+          });
+          context.setStatus(404);
+          return context.createErrorResponse({ error: 'Not Found' });
         });
-        context.setStatus(404);
-        return context.createErrorResponse({ error: 'Not Found' });
-      });
+      } finally {
+        try {
+          await moduleRegistry.disposeScopedInstances(context);
+        } catch (error) {
+          logger.warn('[Application] Failed to dispose scoped instances', {
+            path: context.path,
+            method: context.method,
+            errorMessage: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
     });
   }
 

package/src/core/context.ts

@@ -74,6 +74,12 @@ export class Context {
    */
   private _bodyParsed: boolean = false;
 
+  /**
+   * 客户端断连信号
+   * 当客户端主动关闭连接时 abort，可用于级联取消内部请求
+   */
+  public readonly signal: AbortSignal;
+
   public constructor(request: Request) {
     this.request = request;
     this.url = new URL(request.url);
@@ -82,6 +88,7 @@ export class Context {
     this.query = this.url.searchParams;
     this.headers = request.headers;
     this.responseHeaders = new Headers();
+    this.signal = request.signal;
   }
 
   /**

package/src/core/server.ts

@@ -47,6 +47,15 @@ export interface ServerOptions {
    * 框架内部会转换为 Bun.serve 所需的秒
    */
   idleTimeout?: number;
+
+  /**
+   * SSE 保活配置
+   * @see ApplicationOptions.sseKeepAlive
+   */
+  sseKeepAlive?: {
+    enabled?: boolean;
+    intervalMs?: number;
+  };
 }
 
 /**
@@ -81,9 +90,44 @@ export class BunServer {
     this.shutdownPromise = undefined;
     this.shutdownResolve = undefined;
 
+    const sseKeepAlive = this.options.sseKeepAlive;
+    const sseHeartbeatEnabled = sseKeepAlive?.enabled !== false;
+    const sseHeartbeatIntervalMs = sseKeepAlive?.intervalMs ?? 15_000;
+
+    const postProcessSse = (
+      response: Response,
+      request: Request,
+      bunServer: Server<WebSocketConnectionData>,
+    ): Response => {
+      const ct = response.headers.get('content-type');
+      if (!ct?.includes('text/event-stream')) {
+        return response;
+      }
+
+      // SSE detected — always disable Bun TCP idle timeout for this connection
+      bunServer.timeout(request, 0);
+
+      if (sseHeartbeatEnabled && response.body) {
+        return BunServer.wrapSseWithHeartbeat(
+          response,
+          sseHeartbeatIntervalMs,
+          request.signal,
+        );
+      }
+
+      return response;
+    };
+
+    const decrementAndMaybeShutdown = () => {
+      this.activeRequests--;
+      if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
+        this.shutdownResolve();
+      }
+    };
+
     const fetchHandler = (
       request: Request,
-      server: Server<WebSocketConnectionData>,
+      bunServer: Server<WebSocketConnectionData>,
     ): Response | Promise<Response> | undefined => {
       if (this.isShuttingDown) {
         return new Response("Server is shutting down", { status: 503 });
@@ -101,7 +145,7 @@ export class BunServer {
         }
         const context = new Context(request);
         const queryParams = new URLSearchParams(url.searchParams);
-        const upgraded = server.upgrade(request, {
+        const upgraded = bunServer.upgrade(request, {
           data: {
             path: url.pathname,
             query: queryParams,
@@ -120,24 +164,17 @@ export class BunServer {
       const responsePromise = this.options.fetch(context);
 
       if (responsePromise instanceof Promise) {
-        responsePromise
-          .finally(() => {
-            this.activeRequests--;
-            if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
-              this.shutdownResolve();
-            }
-          })
-          .catch(() => {
-            // errors handled by middleware pipeline
-          });
-      } else {
-        this.activeRequests--;
-        if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
-          this.shutdownResolve();
-        }
+        const processed = responsePromise.then(
+          (response) => postProcessSse(response, request, bunServer),
+        );
+        processed
+          .finally(decrementAndMaybeShutdown)
+          .catch(() => { /* errors handled by middleware pipeline */ });
+        return processed;
       }
 
-      return responsePromise;
+      decrementAndMaybeShutdown();
+      return postProcessSse(responsePromise, request, bunServer);
     };
 
     const websocketHandlers = {
@@ -296,4 +333,70 @@ export class BunServer {
   public getHostname(): string | undefined {
     return this.options.hostname;
   }
+
+  /**
+   * 将 SSE Response 的 body 包裹一层心跳注入流。
+   *
+   * 原始流的数据原样透传；在数据间隙中按 intervalMs 发送
+   * SSE 注释帧 `: keepalive\n\n`（客户端会忽略注释帧）。
+   *
+   * 当 signal abort / 原始流结束 / 客户端断连时自动清理定时器。
+   */
+  private static wrapSseWithHeartbeat(
+    original: Response,
+    intervalMs: number,
+    signal: AbortSignal,
+  ): Response {
+    const encoder = new TextEncoder();
+    const keepaliveChunk = encoder.encode(': keepalive\n\n');
+    const originalBody = original.body!;
+    let heartbeat: ReturnType<typeof setInterval> | undefined;
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+
+    const wrapped = new ReadableStream<Uint8Array>({
+      start(controller) {
+        reader = originalBody.getReader() as ReadableStreamDefaultReader<Uint8Array>;
+
+        heartbeat = setInterval(() => {
+          try {
+            controller.enqueue(keepaliveChunk);
+          } catch {
+            clearInterval(heartbeat);
+            heartbeat = undefined;
+          }
+        }, intervalMs);
+
+        const onAbort = () => {
+          if (heartbeat) { clearInterval(heartbeat); heartbeat = undefined; }
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+
+        const pump = async () => {
+          try {
+            while (true) {
+              const { done, value } = await reader!.read();
+              if (done) break;
+              controller.enqueue(value);
+            }
+            controller.close();
+          } catch (err) {
+            try { controller.error(err); } catch { /* already closed */ }
+          } finally {
+            if (heartbeat) { clearInterval(heartbeat); heartbeat = undefined; }
+            signal.removeEventListener('abort', onAbort);
+          }
+        };
+        pump();
+      },
+      cancel() {
+        if (heartbeat) { clearInterval(heartbeat); heartbeat = undefined; }
+        reader?.cancel();
+      },
+    });
+
+    return new Response(wrapped, {
+      status: original.status,
+      headers: original.headers,
+    });
+  }
 }

package/src/di/container.ts

@@ -14,6 +14,13 @@ import {
 import { LoggerManager } from "@dangao/logsmith";
 import type { Constructor } from "@/core/types";
 import { contextStore } from "../core/context-service";
+import {
+  callComponentBeforeCreate,
+  callOnAfterCreate,
+  callOnBeforeDestroy,
+  callOnModuleDestroy,
+  callOnAfterDestroy,
+} from "./lifecycle";
 
 /**
  * 依赖注入容器
@@ -365,6 +372,7 @@ export class Container {
    * @returns 实例
    */
   private instantiate<T>(constructor: Constructor<T>): T {
+    callComponentBeforeCreate(constructor);
     const plan = this.getDependencyPlan(constructor);
 
     let instance: T;
@@ -379,7 +387,9 @@ export class Container {
     }
 
     // 应用后处理器
-    return this.applyPostProcessors(instance, constructor);
+    const processed = this.applyPostProcessors(instance, constructor);
+    callOnAfterCreate(processed);
+    return processed;
   }
 
   /**
@@ -409,6 +419,50 @@ export class Container {
     // scopedInstances 使用 WeakMap，当 Context 对象被 GC 时会自动清理
   }
 
+  /**
+   * 获取指定请求上下文下的 scoped 实例
+   * @param context - 请求上下文对象
+   * @returns 去重后的 scoped 实例列表
+   */
+  public getScopedInstances(context: object): unknown[] {
+    const scopedMap = this.scopedInstances.get(context);
+    if (!scopedMap || scopedMap.size === 0) {
+      return [];
+    }
+    const seen = new Set<unknown>();
+    const instances: unknown[] = [];
+    for (const instance of scopedMap.values()) {
+      if (!seen.has(instance)) {
+        seen.add(instance);
+        instances.push(instance);
+      }
+    }
+    return instances;
+  }
+
+  /**
+   * 清理指定请求上下文的 scoped 实例缓存
+   * @param context - 请求上下文对象
+   */
+  public clearScopedInstances(context: object): void {
+    this.scopedInstances.delete(context);
+  }
+
+  /**
+   * 触发指定请求上下文下 scoped 实例的销毁钩子并清理缓存
+   * @param context - 请求上下文对象
+   */
+  public async disposeScopedInstances(context: object): Promise<void> {
+    const instances = this.getScopedInstances(context);
+    if (instances.length === 0) {
+      return;
+    }
+    await callOnBeforeDestroy(instances);
+    await callOnModuleDestroy(instances);
+    await callOnAfterDestroy(instances);
+    this.clearScopedInstances(context);
+  }
+
   /**
    * 检查是否已注册
    * @param token - 提供者标识符

package/src/di/lifecycle.ts

@@ -30,6 +30,38 @@ export interface OnApplicationShutdown {
   onApplicationShutdown(signal?: string): Promise<void> | void;
 }
 
+/**
+ * 组件创建前钩子（静态类方法）
+ * 在实例化前调用，适用于 Controller / Injectable 类
+ */
+export type ComponentClassBeforeCreate = {
+  onBeforeCreate(): void;
+};
+
+/**
+ * 组件创建后钩子（实例）
+ * 在实例化并完成后处理后调用
+ */
+export interface OnAfterCreate {
+  onAfterCreate(): void;
+}
+
+/**
+ * 组件销毁前钩子（实例）
+ * 在 onModuleDestroy 之前调用（反向顺序）
+ */
+export interface OnBeforeDestroy {
+  onBeforeDestroy(): Promise<void> | void;
+}
+
+/**
+ * 组件销毁后钩子（实例）
+ * 在 onModuleDestroy 之后调用（反向顺序）
+ */
+export interface OnAfterDestroy {
+  onAfterDestroy(): Promise<void> | void;
+}
+
 export function hasOnModuleInit(instance: unknown): instance is OnModuleInit {
   return (
     instance !== null &&
@@ -70,6 +102,64 @@ export function hasOnApplicationShutdown(instance: unknown): instance is OnAppli
   );
 }
 
+export function hasComponentBeforeCreate(target: unknown): target is ComponentClassBeforeCreate {
+  return (
+    target !== null &&
+    target !== undefined &&
+    typeof target === 'function' &&
+    'onBeforeCreate' in target &&
+    typeof (target as ComponentClassBeforeCreate).onBeforeCreate === 'function'
+  );
+}
+
+export function hasOnAfterCreate(instance: unknown): instance is OnAfterCreate {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onAfterCreate' in instance &&
+    typeof (instance as OnAfterCreate).onAfterCreate === 'function'
+  );
+}
+
+export function hasOnBeforeDestroy(instance: unknown): instance is OnBeforeDestroy {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onBeforeDestroy' in instance &&
+    typeof (instance as OnBeforeDestroy).onBeforeDestroy === 'function'
+  );
+}
+
+export function hasOnAfterDestroy(instance: unknown): instance is OnAfterDestroy {
+  return (
+    instance !== null &&
+    instance !== undefined &&
+    typeof instance === 'object' &&
+    'onAfterDestroy' in instance &&
+    typeof (instance as OnAfterDestroy).onAfterDestroy === 'function'
+  );
+}
+
+/**
+ * 调用组件类静态 onBeforeCreate
+ */
+export function callComponentBeforeCreate(target: unknown): void {
+  if (hasComponentBeforeCreate(target)) {
+    target.onBeforeCreate();
+  }
+}
+
+/**
+ * 调用组件实例 onAfterCreate
+ */
+export function callOnAfterCreate(instance: unknown): void {
+  if (hasOnAfterCreate(instance)) {
+    instance.onAfterCreate();
+  }
+}
+
 /**
  * 按顺序调用 onModuleInit
  */
@@ -115,3 +205,27 @@ export async function callOnApplicationShutdown(instances: unknown[], signal?: s
     }
   }
 }
+
+/**
+ * 按反向顺序调用 onBeforeDestroy
+ */
+export async function callOnBeforeDestroy(instances: unknown[]): Promise<void> {
+  for (let i = instances.length - 1; i >= 0; i--) {
+    const instance = instances[i];
+    if (hasOnBeforeDestroy(instance)) {
+      await instance.onBeforeDestroy();
+    }
+  }
+}
+
+/**
+ * 按反向顺序调用 onAfterDestroy
+ */
+export async function callOnAfterDestroy(instances: unknown[]): Promise<void> {
+  for (let i = instances.length - 1; i >= 0; i--) {
+    const instance = instances[i];
+    if (hasOnAfterDestroy(instance)) {
+      await instance.onAfterDestroy();
+    }
+  }
+}

package/src/di/module-registry.ts

@@ -11,6 +11,8 @@ import {
   callOnModuleDestroy,
   callOnApplicationBootstrap,
   callOnApplicationShutdown,
+  callOnBeforeDestroy,
+  callOnAfterDestroy,
 } from './lifecycle';
 
 interface ModuleRef {
@@ -225,9 +227,9 @@ export class ModuleRegistry {
   }
 
   /**
-   * 解析所有模块中的 provider 实例，用于生命周期钩子调用
+   * 解析所有模块中的组件实例（providers + controllers），用于生命周期钩子调用
    */
-  public resolveAllProviderInstances(): unknown[] {
+  public resolveAllComponentInstances(): unknown[] {
     const instances: unknown[] = [];
     const seen = new Set<unknown>();
     for (const [, ref] of this.moduleRefs) {
@@ -262,42 +264,88 @@ export class ModuleRegistry {
           // skip providers that can't be resolved (e.g. pending async providers)
         }
       }
+      for (const controller of ref.metadata.controllers) {
+        try {
+          const instance = ref.container.resolve(controller);
+          if (!seen.has(instance)) {
+            seen.add(instance);
+            instances.push(instance);
+          }
+        } catch (_error) {
+          // skip controllers that can't be resolved
+        }
+      }
     }
     return instances;
   }
 
   /**
-   * 调用所有 provider 的 onModuleInit 钩子
+   * 调用所有组件（providers + controllers）的 onModuleInit 钩子
    */
   public async callModuleInitHooks(): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
     await callOnModuleInit(instances);
   }
 
   /**
-   * 调用所有 provider 的 onApplicationBootstrap 钩子
+   * 调用所有组件（providers + controllers）的 onApplicationBootstrap 钩子
    */
   public async callBootstrapHooks(): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
     await callOnApplicationBootstrap(instances);
   }
 
   /**
-   * 调用所有 provider 的 onModuleDestroy 钩子
+   * 调用所有组件（providers + controllers）的 onModuleDestroy 钩子
    */
   public async callModuleDestroyHooks(): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
+    await callOnBeforeDestroy(instances);
     await callOnModuleDestroy(instances);
+    await callOnAfterDestroy(instances);
   }
 
   /**
-   * 调用所有 provider 的 onApplicationShutdown 钩子
+   * 调用所有组件（providers + controllers）的 onApplicationShutdown 钩子
    */
   public async callShutdownHooks(signal?: string): Promise<void> {
-    const instances = this.resolveAllProviderInstances();
+    const instances = this.resolveAllComponentInstances();
     await callOnApplicationShutdown(instances, signal);
   }
 
+  /**
+   * 调用当前请求上下文下 scoped 组件的销毁钩子并清理缓存
+   */
+  public async disposeScopedInstances(context: object): Promise<void> {
+    const containers: Container[] = [];
+    if (this.rootContainer) {
+      containers.push(this.rootContainer);
+    }
+    containers.push(...this.getAllModuleContainers());
+
+    const instances: unknown[] = [];
+    const seen = new Set<unknown>();
+    for (const container of containers) {
+      const scopedInstances = container.getScopedInstances(context);
+      for (const instance of scopedInstances) {
+        if (!seen.has(instance)) {
+          seen.add(instance);
+          instances.push(instance);
+        }
+      }
+    }
+
+    if (instances.length > 0) {
+      await callOnBeforeDestroy(instances);
+      await callOnModuleDestroy(instances);
+      await callOnAfterDestroy(instances);
+    }
+
+    for (const container of containers) {
+      container.clearScopedInstances(context);
+    }
+  }
+
   private registerExport(parentContainer: Container, moduleRef: ModuleRef, token: ProviderToken): void {
     if (!moduleRef.container.isRegistered(token)) {
       throw new Error(