@dangao/bun-server 2.3.0 → 3.0.0

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,7 +45,7 @@ export interface ServerOptions {
 
   /**
    * 连接空闲超时时间（毫秒）
-   * 框架内部会转换为 Bun.serve 所需的秒
+   * Bun 平台下自动转换为秒单位；Node.js 平台下静默忽略
    */
   idleTimeout?: number;
 
@@ -60,10 +61,10 @@ export interface ServerOptions {
 
 /**
  * 服务器封装类
- * 基于 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;
@@ -77,7 +78,7 @@ export class BunServer {
   /**
    * 启动服务器
    */
-  public start(): void {
+  public async start(): Promise<void> {
     if (this.server) {
       throw new Error("Server is already running");
     }
@@ -97,15 +98,15 @@ export class BunServer {
     const postProcessSse = (
       response: Response,
       request: Request,
-      bunServer: Server<WebSocketConnectionData>,
+      serverHandle: IServerHandle,
     ): 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);
+      // 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(
@@ -127,8 +128,8 @@ export class BunServer {
 
     const fetchHandler = (
       request: Request,
-      bunServer: 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 });
       }
@@ -145,7 +146,7 @@ export class BunServer {
         }
         const context = new Context(request);
         const queryParams = new URLSearchParams(url.searchParams);
-        const upgraded = bunServer.upgrade(request, {
+        const upgraded = serverHandle.upgrade?.(request, {
           data: {
             path: url.pathname,
             query: queryParams,
@@ -165,7 +166,7 @@ export class BunServer {
 
       if (responsePromise instanceof Promise) {
         const processed = responsePromise.then(
-          (response) => postProcessSse(response, request, bunServer),
+          (response) => postProcessSse(response, request, serverHandle),
         );
         processed
           .finally(decrementAndMaybeShutdown)
@@ -174,40 +175,45 @@ export class BunServer {
       }
 
       decrementAndMaybeShutdown();
-      return postProcessSse(responsePromise, request, bunServer);
+      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,
       });
@@ -218,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));
       }
     }
   }
@@ -301,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;

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;

package/src/database/db-proxy.ts

@@ -49,10 +49,10 @@ const baseDb = async (
   if (tenantId) {
     const tenantSql = sqlManager.get(tenantId);
     if (tenantSql) {
-      return await tenantSql(strings, ...values);
+      return await (tenantSql as any)(strings, ...values);
     }
   }
-  return await sqlManager.getDefault()(strings, ...values);
+  return await (sqlManager.getDefault() as any)(strings, ...values);
 };
 
 function createDb(tenantId?: string): DbProxy {

package/src/database/orm/transaction-manager.ts

@@ -86,7 +86,7 @@ export class TransactionManager {
     fn: () => Promise<T>,
     options: TransactionOptions = {},
   ): Promise<T> {
-    const reserved = await this.sqlManager.getDefault().reserve();
+    const reserved = await (this.sqlManager.getDefault() as any).reserve();
     try {
       const tenantId = getCurrentSession()?.tenantId ?? 'default';
       return await runWithSession(

package/src/database/sql-manager.ts

@@ -1,24 +1,55 @@
-import { SQL } from 'bun';
-
 import type { BunSQLConfig } from './types';
+import { getRuntime } from '../platform/runtime';
 
+/**
+ * SQL 连接管理器
+ * 在 Bun 平台下使用 Bun.SQL，在 Node.js 平台下使用 postgres/mysql2
+ * 内部自动感知运行时，用户无需关心底层实现
+ */
 export class BunSQLManager {
-  private readonly instances = new Map<string, SQL>();
+  private readonly instances = new Map<string, unknown>();
   private defaultTenantId = 'default';
 
-  public getOrCreate(tenantId: string, config: BunSQLConfig): SQL {
+  public getOrCreate(tenantId: string, config: BunSQLConfig): unknown {
     const existing = this.instances.get(tenantId);
     if (existing) {
       return existing;
     }
 
     const pool = config.pool ?? {};
-    const sql = new SQL(config.url, {
-      max: pool.max ?? 10,
-      idleTimeout: pool.idleTimeout ?? 30,
-      maxLifetime: pool.maxLifetime ?? 0,
-      connectionTimeout: pool.connectionTimeout ?? 30000,
-    });
+    let sql: unknown;
+
+    if (getRuntime().engine === 'bun') {
+      const { SQL } = require('bun') as typeof import('bun');
+      sql = new SQL(config.url, {
+        max: pool.max ?? 10,
+        idleTimeout: pool.idleTimeout ?? 30,
+        maxLifetime: pool.maxLifetime ?? 0,
+        connectionTimeout: pool.connectionTimeout ?? 30000,
+      });
+    } else {
+      // Node.js: detect dialect from URL
+      const url = config.url.toLowerCase();
+      if (url.startsWith('mysql://') || url.startsWith('mysql2://')) {
+        const mysql2 = require('mysql2/promise') as typeof import('mysql2/promise');
+        // Create a pool in Node.js
+        sql = mysql2.createPool({
+          uri: config.url,
+          connectionLimit: pool.max ?? 10,
+          waitForConnections: true,
+        });
+      } else {
+        // postgres (default)
+        const postgres = require('postgres') as typeof import('postgres');
+        sql = postgres(config.url, {
+          max: pool.max ?? 10,
+          idle_timeout: pool.idleTimeout ?? 30,
+          max_lifetime: pool.maxLifetime ?? 0,
+          connect_timeout: (pool.connectionTimeout ?? 30000) / 1000,
+        });
+      }
+    }
+
     this.instances.set(tenantId, sql);
     return sql;
   }
@@ -27,7 +58,7 @@ export class BunSQLManager {
     return this.instances.has(tenantId);
   }
 
-  public get(tenantId: string): SQL | undefined {
+  public get(tenantId: string): unknown {
     return this.instances.get(tenantId);
   }
 
@@ -35,7 +66,7 @@ export class BunSQLManager {
     this.defaultTenantId = tenantId;
   }
 
-  public getDefault(): SQL {
+  public getDefault(): unknown {
     const sql = this.instances.get(this.defaultTenantId);
     if (!sql) {
       throw new Error(
@@ -50,7 +81,11 @@ export class BunSQLManager {
     if (!sql) {
       return;
     }
-    await sql.close({ timeout });
+    if (typeof (sql as any).close === 'function') {
+      await (sql as any).close({ timeout });
+    } else if (typeof (sql as any).end === 'function') {
+      await (sql as any).end();
+    }
     this.instances.delete(tenantId);
   }
 

package/src/database/sqlite-adapter.ts

@@ -1,6 +1,5 @@
-import { Database, type SQLQueryBindings } from 'bun:sqlite';
-
 import type { SqliteV2Config } from './types';
+import { getRuntime } from '../platform/runtime';
 
 export interface DisposableLock {
   [Symbol.dispose](): void;
@@ -39,30 +38,64 @@ export class Semaphore {
   }
 }
 
+/**
+ * SQLite 适配器（自动感知运行时）
+ * Bun 平台下使用 bun:sqlite，Node.js 平台下使用 better-sqlite3
+ */
 export class SqliteAdapter {
-  private readonly db: Database;
+  private readonly db: unknown;
   public readonly semaphore: Semaphore;
+  private readonly isBun: boolean;
 
   public constructor(config: SqliteV2Config) {
-    this.db = new Database(config.database);
-    if (config.wal !== false) {
-      this.db.exec('PRAGMA journal_mode = WAL;');
+    this.isBun = getRuntime().engine === 'bun';
+
+    if (this.isBun) {
+      const { Database } = require('bun:sqlite') as typeof import('bun:sqlite');
+      const db = new Database(config.database);
+      if (config.wal !== false) {
+        db.exec('PRAGMA journal_mode = WAL;');
+      }
+      this.db = db;
+    } else {
+      const BetterSqlite3 = require('better-sqlite3') as typeof import('better-sqlite3');
+      const db = BetterSqlite3(config.database);
+      if (config.wal !== false) {
+        db.exec('PRAGMA journal_mode = WAL;');
+      }
+      this.db = db;
     }
+
     this.semaphore = new Semaphore(config.maxWriteConcurrency ?? 1);
   }
 
-  public query<T = unknown>(sql: string, params: SQLQueryBindings[] = []): T[] {
-    const stmt = this.db.query(sql);
+  public query<T = unknown>(sql: string, params: unknown[] = []): T[] {
+    if (this.isBun) {
+      const db = this.db as import('bun:sqlite').Database;
+      const stmt = db.query(sql);
+      return stmt.all(...params as Parameters<typeof stmt.all>) as T[];
+    }
+    const db = this.db as import('better-sqlite3').Database;
+    const stmt = db.prepare(sql);
     return stmt.all(...params) as T[];
   }
 
-  public async execute(sql: string, params: SQLQueryBindings[] = []): Promise<void> {
-    const stmt = this.db.query(sql);
-    stmt.run(...params);
+  public async execute(sql: string, params: unknown[] = []): Promise<void> {
+    if (this.isBun) {
+      const db = this.db as import('bun:sqlite').Database;
+      const stmt = db.query(sql);
+      stmt.run(...params as Parameters<typeof stmt.run>);
+    } else {
+      const db = this.db as import('better-sqlite3').Database;
+      const stmt = db.prepare(sql);
+      stmt.run(...params);
+    }
   }
 
   public close(): void {
-    this.db.close();
+    if (typeof (this.db as any).close === 'function') {
+      (this.db as any).close();
+    }
   }
 }
 

package/src/debug/recorder.ts

@@ -110,11 +110,11 @@ export class RequestRecorder {
 
   /**
    * 从 JSONL 内容导入请求记录
-   * 利用 Bun 1.3.7+ 原生 Bun.JSONL.parse() 高性能解析
    * @param content - JSONL 格式文本
    */
   public importFromJsonl(content: string): void {
-    const records = Bun.JSONL.parse(content) as RequestRecord[];
+    const { getRuntime } = require('../platform/runtime') as typeof import('../platform/runtime');
+    const records = getRuntime().parser.parseJSONL(content) as RequestRecord[];
     for (const record of records) {
       if (record.id) {
         const oldRecord = this.buffer[this.writeIndex];
@@ -136,6 +136,7 @@ export class RequestRecorder {
    * @param content - JSONL 格式文本
    */
   public static parseJsonl(content: string): RequestRecord[] {
-    return Bun.JSONL.parse(content) as RequestRecord[];
+    const { getRuntime } = require('../platform/runtime') as typeof import('../platform/runtime');
+    return getRuntime().parser.parseJSONL(content) as RequestRecord[];
   }
 }

package/src/files/static-middleware.ts

@@ -2,6 +2,7 @@ import { join, normalize } from 'node:path';
 import { stat } from 'node:fs/promises';
 
 import type { Middleware } from '../middleware';
+import { getRuntime } from '../platform/runtime';
 
 export interface StaticFileOptions {
   root: string;
@@ -35,8 +36,8 @@ export function createStaticFileMiddleware(options: StaticFileOptions): Middlewa
         return await next();
       }
 
-      const file = Bun.file(filePath);
-      return new Response(file, {
+      const file = getRuntime().fs.file(filePath);
+      return new Response(file.stream(), {
         headers: {
           'Content-Type': file.type || 'application/octet-stream',
         },

package/src/files/storage.ts

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import { join } from 'node:path';
 
 import type { UploadedFileInfo } from './types';
+import { getRuntime } from '../platform/runtime';
 
 export interface SaveFileOptions {
   dest: string;
@@ -51,7 +52,7 @@ export class FileStorage {
       }
     }
 
-    await Bun.write(targetPath, file);
+    await getRuntime().fs.write(targetPath, await file.arrayBuffer());
 
     return {
       fieldName,

package/src/index.ts

@@ -1,4 +1,17 @@
 export { Application, type ApplicationOptions } from './core/application';
+export type {
+  PlatformEngine,
+  IServerHandle,
+  IWebSocket,
+  WebSocketHandlers,
+  IFsAdapter,
+  ICryptoAdapter,
+  IParserAdapter,
+  IProcessAdapter,
+  IHttpDriver,
+  IPlatform,
+} from './platform';
+export { getRuntime, initRuntime, resolvePlatform } from './platform';
 export { applyDecorators } from './core/apply-decorators';
 export { BunServer, type ServerOptions } from './core/server';
 export { ClusterManager, type ClusterOptions, type ClusterMode } from './core/cluster';

package/src/middleware/builtin/static-file.ts

@@ -1,14 +1,17 @@
 import { normalize, resolve, sep } from 'path';
 
 import type { Middleware } from '../middleware';
-import type { HeadersInit } from 'bun'
+import { getRuntime } from '../../platform/runtime';
+
+/** Cross-runtime compatible headers input type */
+type HeadersInput = Headers | string[][] | Record<string, string>;
 
 export interface StaticFileOptions {
   root: string;
   prefix?: string;
   indexFile?: string;
   enableCache?: boolean;
-  headers?: HeadersInit | Headers;
+  headers?: HeadersInput;
 }
 
 function isSubPath(root: string, target: string): boolean {
@@ -65,12 +68,12 @@ export function createStaticFileMiddleware(options: StaticFileOptions): Middlewa
       return context.createErrorResponse({ error: 'Forbidden' });
     }
 
-    const file = Bun.file(targetPath);
+    const file = getRuntime().fs.file(targetPath);
     if (!(await file.exists())) {
       return await next();
     }
 
-    const headers = new Headers(options.headers);
+    const headers = new Headers(options.headers as HeadersInput);
     if (enableCache) {
       headers.set('Cache-Control', 'public, max-age=31536000, immutable');
     }
@@ -78,7 +81,7 @@ export function createStaticFileMiddleware(options: StaticFileOptions): Middlewa
       headers.set('Content-Type', file.type);
     }
 
-    return new Response(file, {
+    return new Response(file.stream(), {
       status: 200,
       headers,
     });

package/src/platform/bun/crypto.ts

@@ -0,0 +1,30 @@
+import type { ICryptoAdapter, IHasher } from '../types';
+
+class BunHasher implements IHasher {
+  private readonly hasher: Bun.CryptoHasher;
+
+  public constructor(algorithm: string) {
+    this.hasher = new Bun.CryptoHasher(algorithm as any);
+  }
+
+  public update(data: string | Uint8Array | ArrayBuffer): IHasher {
+    this.hasher.update(data as Parameters<Bun.CryptoHasher['update']>[0]);
+    return this;
+  }
+
+  public digest(): Uint8Array;
+  public digest(encoding: 'hex' | 'base64' | 'base64url'): string;
+  public digest(encoding?: 'hex' | 'base64' | 'base64url'): Uint8Array | string {
+    if (encoding) {
+      return this.hasher.digest(encoding) as string;
+    }
+    // Bun.CryptoHasher.digest() returns Buffer which extends Uint8Array
+    return this.hasher.digest() as unknown as Uint8Array;
+  }
+}
+
+export const bunCryptoAdapter: ICryptoAdapter = {
+  createHasher(algorithm: string): IHasher {
+    return new BunHasher(algorithm);
+  },
+};