@dangao/bun-server 2.3.0 → 3.0.0

package/src/platform/node/process.ts

@@ -0,0 +1,51 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { IProcessAdapter, IChildProcess, SpawnOptions } from '../types';
+
+class NodeChildProcess implements IChildProcess {
+  private readonly child: ReturnType<typeof nodeSpawn>;
+  private readonly _exited: Promise<number | null>;
+
+  public constructor(child: ReturnType<typeof nodeSpawn>) {
+    this.child = child;
+    this._exited = new Promise<number | null>((resolve) => {
+      child.on('exit', (code) => resolve(code));
+    });
+  }
+
+  public get pid(): number {
+    return this.child.pid ?? -1;
+  }
+
+  public get exited(): Promise<number | null> {
+    return this._exited;
+  }
+
+  public kill(signal?: string | number): void {
+    if (typeof signal === 'string') {
+      this.child.kill(signal as NodeJS.Signals);
+    } else if (typeof signal === 'number') {
+      this.child.kill(signal);
+    } else {
+      this.child.kill('SIGTERM');
+    }
+  }
+}
+
+export const nodeProcessAdapter: IProcessAdapter = {
+  spawn(options: SpawnOptions): IChildProcess {
+    const [cmd, ...args] = options.cmd;
+    const child = nodeSpawn(cmd!, args, {
+      env: (options.env ?? process.env) as Record<string, string>,
+      stdio: [
+        'ignore',
+        options.stdout === 'pipe' ? 'pipe' : options.stdout === 'ignore' ? 'ignore' : 'inherit',
+        options.stderr === 'pipe' ? 'pipe' : options.stderr === 'ignore' ? 'ignore' : 'inherit',
+      ],
+    });
+    return new NodeChildProcess(child);
+  },
+
+  async sleep(ms: number): Promise<void> {
+    await new Promise<void>((resolve) => setTimeout(resolve, ms));
+  },
+};

package/src/platform/runtime.ts

@@ -0,0 +1,50 @@
+import type { IPlatform, PlatformEngine } from './types';
+import { resolvePlatform } from './detector';
+
+let _runtime: IPlatform | null = null;
+
+/**
+ * 初始化全局运行时平台
+ * 应在 Application 构造函数中最先调用
+ *
+ * @param engine - 显式指定平台（优先级最高），省略则走优先级检测链
+ */
+export function initRuntime(engine?: PlatformEngine): void {
+  const resolved = resolvePlatform(engine);
+
+  if (_runtime && _runtime.engine === resolved) {
+    return;
+  }
+
+  if (resolved === 'bun') {
+    // 动态导入避免 Node.js 环境下引入 Bun 专属 API
+    const { createBunPlatform } = require('./bun/index');
+    _runtime = createBunPlatform();
+  } else {
+    const { createNodePlatform } = require('./node/index');
+    _runtime = createNodePlatform();
+  }
+}
+
+/**
+ * 获取当前已初始化的平台运行时
+ * 必须在 initRuntime() 调用之后使用
+ */
+export function getRuntime(): IPlatform {
+  if (!_runtime) {
+    throw new Error(
+      '[Platform] Runtime not initialized. ' +
+      'Make sure initRuntime() is called before using getRuntime(). ' +
+      'This is automatically done by new Application(options).',
+    );
+  }
+  return _runtime;
+}
+
+/**
+ * 重置运行时（仅用于测试）
+ * @internal
+ */
+export function _resetRuntime(): void {
+  _runtime = null;
+}

package/src/platform/types.ts

@@ -0,0 +1,150 @@
+/**
+ * 支持的运行时平台标识
+ */
+export type PlatformEngine = 'bun' | 'node';
+
+/**
+ * 文件引用抽象接口（替代 BunFile 的直接使用）
+ */
+export interface IFileRef {
+  readonly type: string;
+  readonly size: number;
+  text(): Promise<string>;
+  bytes(): Promise<Uint8Array>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  exists(): Promise<boolean>;
+  /** 返回可读流，用于 new Response(file.stream(), ...) */
+  stream(): ReadableStream<Uint8Array>;
+}
+
+/**
+ * 文件系统适配器接口
+ */
+export interface IFsAdapter {
+  /** 获取文件引用 */
+  file(path: string): IFileRef;
+  /** 写入文件 */
+  write(path: string, data: string | Uint8Array | ArrayBuffer): Promise<void>;
+  /** 匹配文件列表 */
+  glob(pattern: string, cwd?: string): string[];
+}
+
+/**
+ * 哈希器接口（替代 Bun.CryptoHasher）
+ */
+export interface IHasher {
+  update(data: string | Uint8Array | ArrayBuffer): IHasher;
+  digest(): Uint8Array;
+  digest(encoding: 'hex' | 'base64' | 'base64url'): string;
+}
+
+/**
+ * 加密适配器接口
+ */
+export interface ICryptoAdapter {
+  createHasher(algorithm: string): IHasher;
+}
+
+/**
+ * 解析器适配器接口
+ */
+export interface IParserAdapter {
+  parseJSONC(content: string): unknown;
+  parseJSON5(content: string): unknown;
+  parseJSONL(content: string): unknown[];
+  renderMarkdown(md: string): string;
+}
+
+/**
+ * 子进程接口
+ */
+export interface IChildProcess {
+  readonly pid: number;
+  readonly exited: Promise<number | null>;
+  kill(signal?: string | number): void;
+}
+
+/**
+ * spawn 选项
+ */
+export interface SpawnOptions {
+  cmd: string[];
+  env?: Record<string, string | undefined>;
+  stdout?: 'inherit' | 'pipe' | 'ignore';
+  stderr?: 'inherit' | 'pipe' | 'ignore';
+}
+
+/**
+ * 进程适配器接口
+ */
+export interface IProcessAdapter {
+  spawn(options: SpawnOptions): IChildProcess;
+  sleep(ms: number): Promise<void>;
+}
+
+/**
+ * WebSocket 连接抽象接口（替代 Bun.ServerWebSocket）
+ */
+export interface IWebSocket<T = unknown> {
+  readonly data: T;
+  readonly readyState: number;
+  send(data: string | Buffer | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+}
+
+/**
+ * WebSocket 事件处理器集合
+ */
+export interface WebSocketHandlers<T = unknown> {
+  open?: (ws: IWebSocket<T>) => void | Promise<void>;
+  message?: (ws: IWebSocket<T>, msg: string | Buffer) => void | Promise<void>;
+  close?: (ws: IWebSocket<T>, code: number, reason: string) => void | Promise<void>;
+}
+
+/**
+ * HTTP 服务启动选项
+ */
+export interface HttpServeOptions<T = unknown> {
+  port?: number;
+  hostname?: string;
+  reusePort?: boolean;
+  idleTimeout?: number;
+  /** Unix socket 路径（cluster proxy 模式使用） */
+  unix?: string;
+  fetch: (request: Request, server: IServerHandle) => Response | Promise<Response | undefined> | undefined;
+  websocket?: WebSocketHandlers<T>;
+}
+
+/**
+ * 服务器句柄接口（替代 Bun.Server）
+ */
+export interface IServerHandle {
+  readonly port: number;
+  readonly hostname?: string;
+  stop(): void;
+  /** 升级 WebSocket 连接（Bun 原生升级） */
+  upgrade?(request: Request, options?: { data?: unknown }): boolean;
+  /** 设置连接超时（Bun 专属） */
+  timeout?(request: Request, seconds: number): void;
+  /** 获取底层原生服务器实例（不推荐，类型为 unknown） */
+  getNative(): unknown;
+}
+
+/**
+ * HTTP 驱动适配器接口
+ */
+export interface IHttpDriver {
+  serve<T = unknown>(options: HttpServeOptions<T>): Promise<IServerHandle>;
+}
+
+/**
+ * 平台接口聚合
+ */
+export interface IPlatform {
+  readonly engine: PlatformEngine;
+  readonly fs: IFsAdapter;
+  readonly crypto: ICryptoAdapter;
+  readonly parser: IParserAdapter;
+  readonly process: IProcessAdapter;
+  readonly http: IHttpDriver;
+}

package/src/prompt/stores/file-store.ts

@@ -6,6 +6,7 @@ import type {
 } from '../types';
 import { extractVariables } from '../types';
 import { InMemoryPromptStore } from './memory-store';
+import { getRuntime } from '../../platform/runtime';
 
 export interface FilePromptStoreConfig {
   /** Directory containing JSON prompt files (default: './.prompts') */
@@ -73,7 +74,7 @@ export class FilePromptStore implements PromptStore {
     if (deleted) {
       try {
         const path = `${this.promptsDir}/${id}.json`;
-        await Bun.file(path).exists() && Bun.write(path, ''); // Soft delete (empty file)
+        await getRuntime().fs.file(path).exists() && getRuntime().fs.write(path, ''); // Soft delete (empty file)
       } catch (_error) {
         // ignore
       }
@@ -86,12 +87,12 @@ export class FilePromptStore implements PromptStore {
     this.loaded = true;
 
     try {
-      const glob = new Bun.Glob('*.json');
-      const files = Array.from(glob.scanSync(this.promptsDir));
+      const runtime = getRuntime();
+      const files = runtime.fs.glob('*.json', this.promptsDir);
 
       for (const file of files) {
         try {
-          const content = await Bun.file(`${this.promptsDir}/${file}`).text();
+          const content = await runtime.fs.file(`${this.promptsDir}/${file}`).text();
           if (!content.trim()) continue;
 
           const data = JSON.parse(content) as {
@@ -127,7 +128,7 @@ export class FilePromptStore implements PromptStore {
         null,
         2,
       );
-      await Bun.write(`${this.promptsDir}/${template.id}.json`, content);
+      await getRuntime().fs.write(`${this.promptsDir}/${template.id}.json`, content);
     } catch (_error) {
       // Ignore write errors (e.g., read-only filesystem)
     }

package/src/rag/service.ts

@@ -1,5 +1,6 @@
 import { Injectable } from '../di/decorators';
 import { Inject } from '../di/decorators';
+import { getRuntime } from '../platform/runtime';
 import type { EmbeddingService } from '../embedding/service';
 import { EMBEDDING_SERVICE_TOKEN } from '../embedding/types';
 import type { VectorStore } from '../vector-store/types';
@@ -120,7 +121,7 @@ export class RagService {
         return source.content;
 
       case 'file': {
-        const file = Bun.file(source.path);
+        const file = getRuntime().fs.file(source.path);
         return file.text();
       }
 

package/src/request/response.ts

@@ -1,4 +1,7 @@
-import type { BodyInit, HeadersInit } from 'bun';
+import { getRuntime } from '../platform/runtime';
+
+/** Cross-runtime compatible headers input type */
+type HeadersInit = Headers | string[][] | Record<string, string>;
 
 /**
  * 响应封装类
@@ -131,17 +134,17 @@ export class ResponseBuilder {
     }
 
     if (typeof source === 'string') {
-      const file = Bun.file(source);
+      const file = getRuntime().fs.file(source);
       if (!headers.has('Content-Type') && file.type) {
         headers.set('Content-Type', file.type);
       }
-      return new Response(file, {
+      return new Response(file.stream(), {
         status: options.status ?? 200,
         headers,
       });
     }
 
-    return new Response(source as BodyInit, {
+    return new Response(source as any, {
       status: options.status ?? 200,
       headers,
     });

package/src/security/guards/execution-context.ts

@@ -1,5 +1,5 @@
 import 'reflect-metadata';
-import type { ServerWebSocket } from 'bun';
+import type { IWebSocket } from '../../platform/types';
 import type { Context } from '../../core/context';
 import type { ResponseBuilder } from '../../request/response';
 import type { Constructor } from '../../core/types';
@@ -38,14 +38,14 @@ class HttpArgumentsHostImpl implements HttpArgumentsHost {
  */
 class WsArgumentsHostImpl implements WsArgumentsHost {
   public constructor(
-    private readonly client: ServerWebSocket<unknown>,
+    private readonly client: IWebSocket<unknown>,
     private readonly data: unknown,
   ) {}
 
   /**
    * 获取 WebSocket 客户端
    */
-  public getClient(): ServerWebSocket<unknown> {
+  public getClient(): IWebSocket<unknown> {
     return this.client;
   }
 
@@ -80,7 +80,7 @@ export class ExecutionContextImpl implements ExecutionContext {
    * @param client - WebSocket 客户端
    * @param data - 消息数据
    */
-  public setWsContext(client: ServerWebSocket<unknown>, data: unknown): void {
+  public setWsContext(client: IWebSocket<unknown>, data: unknown): void {
     this.wsHost = new WsArgumentsHostImpl(client, data);
   }
 

package/src/security/guards/types.ts

@@ -1,7 +1,7 @@
 import type { Context } from '../../core/context';
 import type { ResponseBuilder } from '../../request/response';
 import type { Constructor } from '../../core/types';
-import type { ServerWebSocket } from 'bun';
+import type { IWebSocket } from '../../platform/types';
 
 /**
  * 守卫接口
@@ -43,7 +43,7 @@ export interface WsArgumentsHost {
    * 获取 WebSocket 客户端
    * @returns WebSocket 连接对象
    */
-  getClient(): ServerWebSocket<unknown>;
+  getClient(): IWebSocket<unknown>;
 
   /**
    * 获取消息数据

package/src/swagger/generator.ts

@@ -1,6 +1,7 @@
 import type { SwaggerDocument, SwaggerOptions, SwaggerPathItem } from './types';
 import { ControllerRegistry } from '../controller/controller';
 import { getControllerMetadata, getRouteMetadata } from '../controller/metadata';
+import { getRuntime } from '../platform/runtime';
 import {
   getApiTags,
   getApiOperation,
@@ -311,7 +312,7 @@ export class SwaggerGenerator {
    */
   public generateMarkdownHtml(): string {
     const md = this.generateMarkdown();
-    return Bun.markdown.html(md, { headings: true });
+    return getRuntime().parser.renderMarkdown(md);
   }
 
   /**

package/src/websocket/registry.ts

@@ -1,5 +1,4 @@
-import type { ServerWebSocket } from 'bun';
-
+import type { IWebSocket } from '../platform/types';
 import { Container } from '../di/container';
 import { ControllerRegistry } from '../controller/controller';
 import { getGatewayMetadata, getHandlerMetadata } from './decorators';
@@ -161,7 +160,7 @@ export class WebSocketGatewayRegistry {
    * @param args - 原始参数（message, code, reason 等，不包括 ws）
    */
   private async invokeHandler(
-    ws: ServerWebSocket<WebSocketConnectionData>,
+    ws: IWebSocket<WebSocketConnectionData>,
     definition: GatewayDefinition,
     handlerName: string | undefined,
     ...args: unknown[]
@@ -266,7 +265,7 @@ export class WebSocketGatewayRegistry {
     }
   }
 
-  public async handleOpen(ws: ServerWebSocket<WebSocketConnectionData>): Promise<void> {
+  public async handleOpen(ws: IWebSocket<WebSocketConnectionData>): Promise<void> {
     const path = ws.data?.path;
     const match = path ? this.getGateway(path) : undefined;
     if (!match) {
@@ -281,8 +280,8 @@ export class WebSocketGatewayRegistry {
   }
 
   public async handleMessage(
-    ws: ServerWebSocket<WebSocketConnectionData>,
-    message: string | ArrayBuffer | ArrayBufferView,
+    ws: IWebSocket<WebSocketConnectionData>,
+    message: string | ArrayBuffer | ArrayBufferView | Buffer,
   ): Promise<void> {
     const path = ws.data?.path;
     const match = path ? this.getGateway(path) : undefined;
@@ -298,7 +297,7 @@ export class WebSocketGatewayRegistry {
   }
 
   public async handleClose(
-    ws: ServerWebSocket<WebSocketConnectionData>,
+    ws: IWebSocket<WebSocketConnectionData>,
     code: number,
     reason: string,
   ): Promise<void> {

package/tests/controller/path-combination.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
 import { Application } from '../../src/core/application';
 import { Controller, ControllerRegistry } from '../../src/controller/controller';
-import { GET, POST } from '../../src/router/decorators';
-import { Param } from '../../src/controller/decorators';
+import { GET, POST, PUT, DELETE, PATCH } from '../../src/router/decorators';
+import { Param, Body } from '../../src/controller/decorators';
 import { RouteRegistry } from '../../src/router/registry';
 import { getTestPort } from '../utils/test-port';
 
@@ -203,6 +203,81 @@ describe('Controller Path Combination', () => {
     expect(rootResponse.status).toBe(404);
   });
 
+  test('should match GET POST PUT DELETE PATCH all registered on same dynamic route /api/:id independently', async () => {
+    @Controller('/api')
+    class ResourceController {
+      @GET('/:id')
+      public getResource(@Param('id') id: string) {
+        return { method: 'GET', id };
+      }
+
+      @POST('/:id')
+      public postResource(@Param('id') id: string) {
+        return { method: 'POST', id };
+      }
+
+      @PUT('/:id')
+      public putResource(@Param('id') id: string) {
+        return { method: 'PUT', id };
+      }
+
+      @DELETE('/:id')
+      public deleteResource(@Param('id') id: string) {
+        return { method: 'DELETE', id };
+      }
+
+      @PATCH('/:id')
+      public patchResource(@Param('id') id: string) {
+        return { method: 'PATCH', id };
+      }
+    }
+
+    app.registerController(ResourceController);
+    await app.listen();
+
+    const methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] as const;
+    for (const method of methods) {
+      const res = await fetch(`http://localhost:${port}/api/123`, { method });
+      expect(res.status).toBe(200);
+      const data = await res.json() as { method: string; id: string };
+      expect(data.method).toBe(method);
+      expect(data.id).toBe('123');
+    }
+  });
+
+  test('should not cross-match methods: only registered methods respond 200, others respond 404/405', async () => {
+    @Controller('/items')
+    class ItemController {
+      @GET('/:id')
+      public getItem(@Param('id') id: string) {
+        return { method: 'GET', id };
+      }
+
+      @POST('/:id')
+      public createItem(@Param('id') id: string) {
+        return { method: 'POST', id };
+      }
+    }
+
+    app.registerController(ItemController);
+    await app.listen();
+
+    const getRes = await fetch(`http://localhost:${port}/items/42`);
+    expect(getRes.status).toBe(200);
+    expect((await getRes.json() as { method: string }).method).toBe('GET');
+
+    const postRes = await fetch(`http://localhost:${port}/items/42`, { method: 'POST' });
+    expect(postRes.status).toBe(200);
+    expect((await postRes.json() as { method: string }).method).toBe('POST');
+
+    // PUT and DELETE are not registered — should return a non-200 status
+    const putRes = await fetch(`http://localhost:${port}/items/42`, { method: 'PUT' });
+    expect(putRes.ok).toBe(false);
+
+    const deleteRes = await fetch(`http://localhost:${port}/items/42`, { method: 'DELETE' });
+    expect(deleteRes.ok).toBe(false);
+  });
+
   test('should correctly combine root controller "/" with method path "/health"', async () => {
     // 这是 metrics-rate-limit-app.ts 示例中的场景
     // @Controller('/') + @GET('/health') 应该映射到 /health，而不是 //health
@@ -275,6 +350,125 @@ describe('Controller Path Combination', () => {
     expect(dataResponse.status).toBe(200);
     expect((await dataResponse.json()).received).toBe(true);
   });
+
+  /**
+   * 模拟真实业务场景：ProjectController
+   *
+   * 路由表：
+   *   GET    /api/projects/         → list()
+   *   GET    /api/projects/:id      → get(id)
+   *   POST   /api/projects/         → create(dto)
+   *   PUT    /api/projects/:id      → update(id, dto)
+   *   DELETE /api/projects/:id      → remove(id)
+   *   GET    /api/projects/:id/pages → listPages(id)
+   */
+  test('ProjectController: all routes on /api/projects should match independently', async () => {
+    const db: Record<string, { id: string; name: string; description: string; pages: string[] }> = {
+      'proj-1': { id: 'proj-1', name: 'Alpha', description: 'desc-a', pages: ['page-1', 'page-2'] },
+      'proj-2': { id: 'proj-2', name: 'Beta',  description: 'desc-b', pages: [] },
+    };
+
+    @Controller('/api/projects')
+    class ProjectController {
+      @GET('/')
+      list() {
+        return Object.values(db);
+      }
+
+      @GET('/:id')
+      get(@Param('id') id: string) {
+        return db[id] ?? null;
+      }
+
+      @POST('/')
+      create(@Body() dto: { name: string; description?: string }) {
+        const id = `proj-new`;
+        db[id] = { id, name: dto.name, description: dto.description ?? '', pages: [] };
+        return db[id];
+      }
+
+      @PUT('/:id')
+      update(@Param('id') id: string, @Body() dto: { name?: string; description?: string }) {
+        if (!db[id]) return null;
+        db[id] = { ...db[id], ...dto };
+        return db[id];
+      }
+
+      @DELETE('/:id')
+      remove(@Param('id') id: string) {
+        const existed = !!db[id];
+        delete db[id];
+        return { success: existed };
+      }
+
+      @GET('/:id/pages')
+      listPages(@Param('id') id: string) {
+        return db[id]?.pages ?? [];
+      }
+    }
+
+    app.registerController(ProjectController);
+    await app.listen();
+
+    const base = `http://localhost:${port}/api/projects`;
+
+    // GET / → 列表
+    const listRes = await fetch(`${base}/`);
+    expect(listRes.status).toBe(200);
+    const list = await listRes.json() as { id: string }[];
+    expect(list.length).toBe(2);
+
+    // GET /:id → 单条
+    const getRes = await fetch(`${base}/proj-1`);
+    expect(getRes.status).toBe(200);
+    const item = await getRes.json() as { id: string; name: string };
+    expect(item.id).toBe('proj-1');
+    expect(item.name).toBe('Alpha');
+
+    // POST / → 创建
+    const createRes = await fetch(`${base}/`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Gamma', description: 'desc-c' }),
+    });
+    expect(createRes.status).toBe(200);
+    const created = await createRes.json() as { id: string; name: string };
+    expect(created.name).toBe('Gamma');
+
+    // PUT /:id → 更新
+    const updateRes = await fetch(`${base}/proj-1`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Alpha-Updated' }),
+    });
+    expect(updateRes.status).toBe(200);
+    const updated = await updateRes.json() as { name: string };
+    expect(updated.name).toBe('Alpha-Updated');
+
+    // GET /:id/pages → 子资源，不能被 GET /:id 拦截
+    const pagesRes = await fetch(`${base}/proj-2/pages`);
+    expect(pagesRes.status).toBe(200);
+    const pages = await pagesRes.json() as string[];
+    expect(Array.isArray(pages)).toBe(true);
+
+    // proj-1 pages（改名后仍可访问）
+    const pages1Res = await fetch(`${base}/proj-1/pages`);
+    expect(pages1Res.status).toBe(200);
+    const pages1 = await pages1Res.json() as string[];
+    expect(pages1).toEqual(['page-1', 'page-2']);
+
+    // DELETE /:id → 删除
+    const delRes = await fetch(`${base}/proj-2`, { method: 'DELETE' });
+    expect(delRes.status).toBe(200);
+    const delData = await delRes.json() as { success: boolean };
+    expect(delData.success).toBe(true);
+
+    // 删除后 GET /:id 返回 null（项目已不存在）
+    const afterDelRes = await fetch(`${base}/proj-2`);
+    expect(afterDelRes.status).toBe(200);
+    const afterDel = await afterDelRes.json();
+    expect(afterDel).toBeNull();
+  });
 });
 
 /**