@dangao/bun-server 2.2.0 → 3.0.0

package/src/config/service.ts

@@ -1,4 +1,5 @@
 import type { ConfigFileFormat } from './types';
+import { getRuntime } from '../platform/runtime';
 
 /**
  * 配置服务
@@ -7,16 +8,16 @@ import type { ConfigFileFormat } from './types';
 export class ConfigService<TConfig extends Record<string, unknown> = Record<string, unknown>> {
   /**
    * 解析配置内容，按 JSON -> JSONC -> JSON5 顺序自动尝试
-   * 利用 Bun 1.3.6+ 的 Bun.JSONC 和 Bun 1.3.7+ 的 Bun.JSON5
    * @param content - 配置文本内容
    * @param format - 强制指定格式（可选），省略则自动检测
    */
   public static parseConfigContent(content: string, format?: ConfigFileFormat): unknown {
+    const parser = getRuntime().parser;
     if (format === 'jsonc') {
-      return Bun.JSONC.parse(content);
+      return parser.parseJSONC(content);
     }
     if (format === 'json5') {
-      return Bun.JSON5.parse(content);
+      return parser.parseJSON5(content);
     }
     if (format === 'json') {
       return JSON.parse(content);
@@ -26,9 +27,9 @@ export class ConfigService<TConfig extends Record<string, unknown> = Record<stri
       return JSON.parse(content);
     } catch (_error) {
       try {
-        return Bun.JSONC.parse(content);
+        return parser.parseJSONC(content);
       } catch (_innerError) {
-        return Bun.JSON5.parse(content);
+        return parser.parseJSON5(content);
       }
     }
   }
@@ -38,7 +39,7 @@ export class ConfigService<TConfig extends Record<string, unknown> = Record<stri
    * @param filePath - 配置文件路径（.json / .jsonc / .json5）
    */
   public static async loadConfigFile(filePath: string): Promise<Record<string, unknown>> {
-    const file = Bun.file(filePath);
+    const file = getRuntime().fs.file(filePath);
     const content = await file.text();
 
     let format: ConfigFileFormat | undefined;

package/src/core/application.ts

@@ -21,6 +21,8 @@ import { LoggerManager } from '@dangao/logsmith';
 import { EventModule } from '../events/event-module';
 import { AsyncProviderRegistry } from '../di/async-module';
 import { ServiceRegistryModule } from '../microservice/service-registry/service-registry-module';
+import type { PlatformEngine } from '../platform/types';
+import { initRuntime } from '../platform/runtime';
 
 /**
  * 应用配置选项
@@ -61,6 +63,37 @@ 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;
+  };
+
+  /**
+   * 运行时平台选择
+   *
+   * 优先级（从高到低）：
+   * 1. 此字段（构造函数选项）
+   * 2. CLI 参数 `--platform=node`
+   * 3. 环境变量 `BUN_SERVER_PLATFORM=node`
+   * 4. 自动检测（有 Bun 全局对象则使用 bun，否则使用 node）
+   *
+   * @default 自动检测
+   */
+  platform?: PlatformEngine;
 }
 
 /**
@@ -76,6 +109,9 @@ export class Application {
   private signalHandlersInstalled: boolean = false;
 
   public constructor(options: ApplicationOptions = {}) {
+    // Initialize platform runtime first — must be the very first operation
+    initRuntime(options.platform);
+
     this.options = options;
     this.middlewarePipeline = new MiddlewarePipeline([createErrorHandlingMiddleware()]);
     this.websocketRegistry = WebSocketGatewayRegistry.getInstance();
@@ -150,13 +186,14 @@ 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,
     };
 
     this.server = new BunServer(serverOptions);
-    this.server.start();
+    await this.server.start();
 
     // 安装信号处理器（如果启用）
     if (this.options.enableSignalHandlers !== false) {

package/src/core/cluster.ts

@@ -1,8 +1,9 @@
-import { spawn } from 'bun';
 import { LoggerManager } from '@dangao/logsmith';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { mkdirSync, rmSync, existsSync } from 'fs';
+import type { IServerHandle, IChildProcess } from '../platform/types';
+import { getRuntime } from '../platform/runtime';
 
 /**
  * 集群模式
@@ -38,12 +39,12 @@ export interface ClusterOptions {
  */
 export class ClusterManager {
   private readonly workerCount: number;
-  private readonly workers: ReturnType<typeof spawn>[] = [];
+  private readonly workers: IChildProcess[] = [];
   private readonly scriptPath: string;
   private readonly port: number;
   private readonly hostname?: string;
   private readonly mode: 'reusePort' | 'proxy';
-  private proxyServer?: ReturnType<typeof Bun.serve>;
+  private proxyServer?: IServerHandle;
   private socketPaths: string[] = [];
   private roundRobinIndex = 0;
   private socketDir?: string;
@@ -145,8 +146,8 @@ export class ClusterManager {
     this.monitorReusePortWorkers();
   }
 
-  private spawnReusePortWorker(index: number): ReturnType<typeof spawn> {
-    return spawn({
+  private spawnReusePortWorker(index: number): IChildProcess {
+    return getRuntime().process.spawn({
       cmd: ['bun', 'run', this.scriptPath],
       env: {
         ...process.env,
@@ -197,7 +198,7 @@ export class ClusterManager {
     }
 
     await this.waitForWorkerSockets();
-    this.startProxyServer();
+    await this.startProxyServer();
 
     logger.info(
       `[Cluster] ${this.workerCount} workers ready (proxy mode, unix sockets)`,
@@ -206,8 +207,8 @@ export class ClusterManager {
     this.monitorProxyWorkers();
   }
 
-  private spawnProxyWorker(index: number, socketPath: string): ReturnType<typeof spawn> {
-    return spawn({
+  private spawnProxyWorker(index: number, socketPath: string): IChildProcess {
+    return getRuntime().process.spawn({
       cmd: ['bun', 'run', this.scriptPath],
       env: {
         ...process.env,
@@ -239,11 +240,11 @@ export class ClusterManager {
 
       if (allReady) {
         // Give workers a moment to finish bind+listen after file creation
-        await Bun.sleep(200);
+        await getRuntime().process.sleep(200);
         return;
       }
 
-      await Bun.sleep(100);
+      await getRuntime().process.sleep(100);
     }
 
     const ready = this.socketPaths.filter((p) => existsSync(p)).length;
@@ -252,11 +253,11 @@ export class ClusterManager {
     );
   }
 
-  private startProxyServer(): void {
+  private async startProxyServer(): Promise<void> {
     const sockets = this.socketPaths;
     const count = sockets.length;
 
-    this.proxyServer = Bun.serve({
+    this.proxyServer = await getRuntime().http.serve({
       port: this.port,
       hostname: this.hostname,
       fetch: async (req) => {
@@ -269,6 +270,7 @@ export class ClusterManager {
             headers: req.headers,
             body: req.body,
             redirect: 'manual',
+            // @ts-ignore — unix fetch is Bun-specific; Node fallback skips this
             unix: socketPath,
           });
         } catch (_error) {
@@ -296,11 +298,11 @@ export class ClusterManager {
           const deadline = Date.now() + 15_000;
           while (Date.now() < deadline) {
             if (existsSync(socketPath)) {
-              await Bun.sleep(200);
+              await getRuntime().process.sleep(200);
               logger.info(`[Cluster] Worker ${index} restarted (unix socket)`);
               return;
             }
-            await Bun.sleep(100);
+            await getRuntime().process.sleep(100);
           }
 
           logger.error(`[Cluster] Worker ${index} failed to restart within 15s`);

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

@@ -1,8 +1,9 @@
-import type { Server } from "bun";
 import { Context } from "./context";
 import { LoggerManager } from "@dangao/logsmith";
 import type { WebSocketGatewayRegistry } from "../websocket/registry";
 import type { WebSocketConnectionData } from "../websocket/registry";
+import type { IServerHandle, IWebSocket } from "../platform/types";
+import { getRuntime } from "../platform/runtime";
 
 /**
  * 服务器配置选项
@@ -44,17 +45,26 @@ export interface ServerOptions {
 
   /**
    * 连接空闲超时时间（毫秒）
-   * 框架内部会转换为 Bun.serve 所需的秒
+   * Bun 平台下自动转换为秒单位；Node.js 平台下静默忽略
    */
   idleTimeout?: number;
+
+  /**
+   * SSE 保活配置
+   * @see ApplicationOptions.sseKeepAlive
+   */
+  sseKeepAlive?: {
+    enabled?: boolean;
+    intervalMs?: number;
+  };
 }
 
 /**
  * 服务器封装类
- * 基于 Bun.serve() 构建
+ * 基于平台适配层构建，支持 Bun 和 Node.js
  */
 export class BunServer {
-  private server?: Server<WebSocketConnectionData>;
+  private server?: IServerHandle;
   private readonly options: ServerOptions;
   private activeRequests: number = 0;
   private isShuttingDown: boolean = false;
@@ -68,7 +78,7 @@ export class BunServer {
   /**
    * 启动服务器
    */
-  public start(): void {
+  public async start(): Promise<void> {
     if (this.server) {
       throw new Error("Server is already running");
     }
@@ -81,10 +91,45 @@ 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,
+      serverHandle: IServerHandle,
+    ): Response => {
+      const ct = response.headers.get('content-type');
+      if (!ct?.includes('text/event-stream')) {
+        return response;
+      }
+
+      // SSE detected — disable idle timeout for this connection (Bun-only, no-op on Node)
+      serverHandle.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>,
-    ): Response | Promise<Response> | undefined => {
+      serverHandle: IServerHandle,
+    ): Response | Promise<Response | undefined> | undefined => {
       if (this.isShuttingDown) {
         return new Response("Server is shutting down", { status: 503 });
       }
@@ -101,7 +146,7 @@ export class BunServer {
         }
         const context = new Context(request);
         const queryParams = new URLSearchParams(url.searchParams);
-        const upgraded = server.upgrade(request, {
+        const upgraded = serverHandle.upgrade?.(request, {
           data: {
             path: url.pathname,
             query: queryParams,
@@ -120,57 +165,55 @@ 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, serverHandle),
+        );
+        processed
+          .finally(decrementAndMaybeShutdown)
+          .catch(() => { /* errors handled by middleware pipeline */ });
+        return processed;
       }
 
-      return responsePromise;
+      decrementAndMaybeShutdown();
+      return postProcessSse(responsePromise, request, serverHandle);
     };
 
-    const websocketHandlers = {
-      open: async (ws: import("bun").ServerWebSocket<WebSocketConnectionData>) => {
-        await this.options.websocketRegistry?.handleOpen(ws);
-      },
-      message: async (ws: import("bun").ServerWebSocket<WebSocketConnectionData>, message: string | Buffer) => {
-        await this.options.websocketRegistry?.handleMessage(ws, message);
-      },
-      close: async (ws: import("bun").ServerWebSocket<WebSocketConnectionData>, code: number, reason: string) => {
-        await this.options.websocketRegistry?.handleClose(ws, code, reason);
-      },
-    };
+    const websocketHandlers = this.options.websocketRegistry
+      ? {
+          open: async (ws: IWebSocket<WebSocketConnectionData>) => {
+            await this.options.websocketRegistry?.handleOpen(ws);
+          },
+          message: async (ws: IWebSocket<WebSocketConnectionData>, message: string | Buffer) => {
+            await this.options.websocketRegistry?.handleMessage(ws, message);
+          },
+          close: async (ws: IWebSocket<WebSocketConnectionData>, code: number, reason: string) => {
+            await this.options.websocketRegistry?.handleClose(ws, code, reason);
+          },
+        }
+      : undefined;
 
+    const runtime = getRuntime();
     const socketFile = process.env.CLUSTER_SOCKET_FILE;
 
     if (socketFile) {
       // Unix socket mode for cluster proxy workers
-      this.server = Bun.serve({
+      this.server = await runtime.http.serve({
         unix: socketFile,
         fetch: fetchHandler,
         websocket: websocketHandlers,
       });
       logger.info(`Server started at unix://${socketFile}`);
     } else {
-      this.server = Bun.serve({
+      const idleTimeoutSec =
+        typeof this.options.idleTimeout === 'number'
+          ? Math.max(0, Math.ceil(this.options.idleTimeout / 1000))
+          : undefined;
+
+      this.server = await runtime.http.serve({
         port: this.options.port ?? 3000,
         hostname: this.options.hostname,
         reusePort: this.options.reusePort,
-        idleTimeout:
-          typeof this.options.idleTimeout === 'number'
-            ? Math.max(0, Math.ceil(this.options.idleTimeout / 1000))
-            : undefined,
+        idleTimeout: idleTimeoutSec,
         fetch: fetchHandler,
         websocket: websocketHandlers,
       });
@@ -181,7 +224,7 @@ export class BunServer {
       // In proxy cluster mode (TCP fallback), report port to master
       const portFile = process.env.CLUSTER_PORT_FILE;
       if (portFile) {
-        Bun.write(portFile, String(port));
+        runtime.fs.write(portFile, String(port));
       }
     }
   }
@@ -264,16 +307,23 @@ export class BunServer {
   }
 
   /**
-   * 获取服务器实例
-   * @returns Bun Server 实例
+   * 获取平台中立的服务器句柄（推荐）
    */
-  public getServer(): Server<WebSocketConnectionData> | undefined {
+  public getServer(): IServerHandle | undefined {
     return this.server;
   }
 
+  /**
+   * 获取底层原生服务器实例（不推荐，类型为 unknown）
+   * - Bun 平台：Bun.Server<WebSocketConnectionData>
+   * - Node.js 平台：node:http.Server
+   */
+  public getNativeServer(): unknown {
+    return this.server?.getNative();
+  }
+
   /**
    * 检查服务器是否运行中
-   * @returns 是否运行中
    */
   public isRunning(): boolean {
     return this.server !== undefined;
@@ -296,4 +346,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/dashboard/controller.ts

@@ -4,6 +4,7 @@ import { createDashboardHTML } from './ui';
 import { ControllerRegistry } from '../controller/controller';
 import { HEALTH_INDICATORS_TOKEN } from '../health/types';
 import type { HealthIndicator } from '../health/types';
+import { getRuntime } from '../platform/runtime';
 
 /**
  * Dashboard 服务
@@ -122,7 +123,7 @@ export class DashboardService {
         heapTotal: mem.heapTotal,
       },
       platform: process.platform,
-      bunVersion: typeof Bun !== 'undefined' ? Bun.version : undefined,
+      bunVersion: getRuntime().engine === 'bun' && typeof Bun !== 'undefined' ? Bun.version : undefined,
     };
     return new Response(JSON.stringify(data), {
       headers: { 'Content-Type': 'application/json; charset=utf-8' },
@@ -166,7 +167,7 @@ export class DashboardService {
           headers: { 'Content-Type': 'application/json; charset=utf-8' },
         });
       }
-      const html = Bun.markdown.html(body.content, { headings: true });
+      const html = getRuntime().parser.renderMarkdown(body.content);
       return new Response(JSON.stringify({ html }), {
         headers: { 'Content-Type': 'application/json; charset=utf-8' },
       });

package/src/database/connection-pool.ts

@@ -3,6 +3,7 @@ import type {
   DatabaseConfig,
   DatabaseType,
 } from './types';
+import { getRuntime } from '../platform/runtime';
 
 /**
  * 连接池中的连接项
@@ -175,19 +176,22 @@ export class ConnectionPool {
   }
 
   /**
-   * 创建 SQLite 连接
+   * 创建 SQLite 连接（自动感知运行时）
    */
   private async createSqliteConnection(
     config: { path: string },
   ): Promise<unknown> {
-    // 使用 Bun 原生 SQLite API
-    const { Database } = await import('bun:sqlite');
-    const db = new Database(config.path);
-    return db;
+    if (getRuntime().engine === 'bun') {
+      const { Database } = await import('bun:sqlite');
+      return new Database(config.path);
+    }
+    // Node.js：使用 better-sqlite3
+    const BetterSqlite3 = require('better-sqlite3') as typeof import('better-sqlite3');
+    return BetterSqlite3(config.path);
   }
 
   /**
-   * 创建 PostgreSQL 连接（使用 Bun.SQL）
+   * 创建 PostgreSQL 连接（自动感知运行时）
    */
   private async createPostgresConnection(
     config: {
@@ -199,18 +203,18 @@ export class ConnectionPool {
       ssl?: boolean;
     },
   ): Promise<unknown> {
-    // 使用 Bun.SQL API
-    // Bun.SQL 支持 postgres:// URL
     const url = `postgres://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}`;
-    const { SQL } = await import('bun');
-    return new SQL(url, {
-      max: 1, // 单个连接（连接池会在外部管理）
-      tls: config.ssl ?? false,
-    });
+    if (getRuntime().engine === 'bun') {
+      const { SQL } = await import('bun');
+      return new SQL(url, { max: 1, tls: config.ssl ?? false });
+    }
+    // Node.js：使用 postgres 包
+    const postgres = require('postgres') as typeof import('postgres');
+    return postgres(url, { max: 1, ssl: config.ssl ? 'require' : false });
   }
 
   /**
-   * 创建 MySQL 连接（使用 Bun.SQL）
+   * 创建 MySQL 连接（自动感知运行时）
    */
   private async createMysqlConnection(
     config: {
@@ -221,13 +225,21 @@ export class ConnectionPool {
       password: string;
     },
   ): Promise<unknown> {
-    // 使用 Bun.SQL API
-    // Bun.SQL 支持 mysql:// URL
-    const url = `mysql://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}`;
-    const { SQL } = await import('bun');
-    return new SQL(url, {
-      max: 1, // 单个连接（连接池会在外部管理）
+    if (getRuntime().engine === 'bun') {
+      const url = `mysql://${config.user}:${config.password}@${config.host}:${config.port}/${config.database}`;
+      const { SQL } = await import('bun');
+      return new SQL(url, { max: 1 });
+    }
+    // Node.js：使用 mysql2 包
+    const mysql2 = require('mysql2/promise') as typeof import('mysql2/promise');
+    const conn = await mysql2.createConnection({
+      host: config.host,
+      port: config.port,
+      database: config.database,
+      user: config.user,
+      password: config.password,
     });
+    return conn;
   }
 
   /**

package/src/database/database-module.ts

@@ -185,7 +185,7 @@ export class DatabaseModule {
         tenantId: selected.tenantId,
         lazyReserve: async () => {
           if (!reserved) {
-            reserved = await sql.reserve();
+            reserved = await (sql as any).reserve();
             session.reserved = reserved;
           }
           return reserved;