@dangao/bun-server 2.2.0 → 3.0.0

package/docs/platform.md

@@ -0,0 +1,299 @@
+# Platform Adapter Guide
+
+**English** | [中文](./zh/platform.md)
+
+---
+
+Bun Server runs natively on **Bun** and **Node.js 22+** through an internal Platform Adapter Layer. All runtime-specific APIs (HTTP server, file I/O, crypto, parsers, process management, WebSocket) are abstracted behind unified TypeScript interfaces. You write one codebase; the framework picks the right implementation at startup — no extra configuration required.
+
+## Table of Contents
+
+- [Architecture](#architecture)
+- [Runtime Detection](#runtime-detection)
+- [Platform Configuration](#platform-configuration)
+- [Support Matrix](#support-matrix)
+- [Database Auto-Adaptation](#database-auto-adaptation)
+- [Public API Changes](#public-api-changes)
+- [Bun-Exclusive Features](#bun-exclusive-features)
+- [Node.js Startup Guide](#nodejs-startup-guide)
+- [Testing on Multiple Runtimes](#testing-on-multiple-runtimes)
+- [Known Limitations](#known-limitations)
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  Application Layer                    │
+│   Controllers / Services / Modules / Middleware       │
+└──────────────────────────┬───────────────────────────┘
+                           │ getRuntime()
+┌──────────────────────────▼───────────────────────────┐
+│              Platform Adapter Layer                   │
+│  IFsAdapter · ICryptoAdapter · IParserAdapter         │
+│  IProcessAdapter · IHttpDriver · IWebSocket           │
+└──────┬───────────────────────────────┬───────────────┘
+       │                               │
+┌──────▼──────┐                 ┌──────▼──────┐
+│ BunPlatform │                 │ NodePlatform│
+│ Bun.serve   │                 │ node:http   │
+│ Bun.file    │                 │ node:fs     │
+│ Bun.Crypto  │                 │ node:crypto │
+│ spawn(bun)  │                 │ ws package  │
+└─────────────┘                 └─────────────┘
+```
+
+Each adapter surface has a corresponding TypeScript interface:
+
+| Interface | Bun Implementation | Node.js Implementation |
+|---|---|---|
+| `IFsAdapter` | `Bun.file`, `Bun.write`, `Bun.Glob` | `node:fs/promises`, `node:fs` glob |
+| `ICryptoAdapter` | `Bun.CryptoHasher` | `node:crypto` HMAC/hash |
+| `IParserAdapter` | `Bun.JSONC`, `Bun.JSON5`, `Bun.JSONL`, `Bun.markdown` | `jsonc-parser`, `json5`, custom JSONL, `marked` |
+| `IProcessAdapter` | `spawn` (bun), `Bun.sleep` | `node:child_process`, `setTimeout` |
+| `IHttpDriver` | `Bun.serve` | `node:http.createServer` |
+| `IWebSocket<T>` | `Bun.ServerWebSocket<T>` | `ws` package |
+
+---
+
+## Runtime Detection
+
+Platform is resolved at `Application` construction time following this priority chain:
+
+```
+1. Bootstrap config  →  new Application({ platform: 'node' })
+2. CLI argument      →  --platform=node
+3. Environment var   →  BUN_SERVER_PLATFORM=node
+4. Auto-detect       →  typeof Bun !== 'undefined' ? 'bun' : 'node'
+```
+
+Once resolved, the singleton is frozen for the lifetime of the process. Subsequent calls to `getRuntime()` return the same instance.
+
+---
+
+## Platform Configuration
+
+### Option 1 — Code (highest priority)
+
+```typescript
+import { Application } from '@dangao/bun-server';
+
+const app = new Application({ platform: 'node' }); // 'bun' | 'node'
+app.registerModule(AppModule);
+await app.listen(3000);
+```
+
+### Option 2 — CLI argument
+
+```bash
+# Bun runtime, but force Node.js adapter
+bun run src/main.ts --platform=node
+
+# Node.js runtime (auto-detected even without the flag)
+node dist/main.js
+```
+
+### Option 3 — Environment variable
+
+```bash
+BUN_SERVER_PLATFORM=node node dist/main.js
+```
+
+### Option 4 — Auto-detect (default)
+
+No configuration needed. If `typeof Bun !== 'undefined'`, `BunPlatform` is selected; otherwise `NodePlatform` is selected automatically.
+
+---
+
+## Support Matrix
+
+| Feature | Bun | Node.js 22+ |
+|---|---|---|
+| HTTP server | `Bun.serve` (native) | `node:http` |
+| WebSocket | `Bun.ServerWebSocket` (native) | `ws` package |
+| File I/O | `Bun.file / Bun.write` | `node:fs/promises` |
+| Crypto / JWT | `Bun.CryptoHasher` | `node:crypto` |
+| JSONC parsing | `Bun.JSONC` | `jsonc-parser` package |
+| JSON5 parsing | `Bun.JSON5` | `json5` package |
+| JSONL parsing | `Bun.JSONL` | Custom streaming parser |
+| Markdown render | `Bun.markdown` | `marked` package |
+| Cluster spawn | Bun `spawn` | `node:child_process` |
+| SQLite | `bun:sqlite` | `better-sqlite3` |
+| PostgreSQL | `Bun.SQL` | `postgres` package |
+| MySQL | `Bun.SQL` | `mysql2` package |
+| `idleTimeout` | Yes | Silently ignored |
+| `reusePort` | Yes | Silently ignored |
+| SSE TCP keepalive | Yes (via `server.timeout`) | Not available |
+| Overall performance | Optimal | Good |
+
+---
+
+## Database Auto-Adaptation
+
+`DatabaseModule` automatically selects drivers based on the detected platform. **No additional user configuration is required.**
+
+```
+Bun platform                     Node.js platform
+─────────────────────────────    ─────────────────────────────
+SQLite  →  bun:sqlite            SQLite  →  better-sqlite3
+PostgreSQL  →  Bun.SQL           PostgreSQL  →  postgres package
+MySQL  →  Bun.SQL                MySQL  →  mysql2 package
+```
+
+Your `DatabaseModule` configuration remains identical across platforms:
+
+```typescript
+DatabaseModule.forRoot({
+  connections: [
+    {
+      name: 'default',
+      type: 'sqlite',
+      database: './data/app.db',
+    },
+    {
+      name: 'pg',
+      type: 'postgres',
+      url: process.env.DATABASE_URL,
+    },
+  ],
+})
+```
+
+---
+
+## Public API Changes
+
+### `BunServer.getServer()`
+
+Returns `IServerHandle | undefined` (previously `Bun.Server | undefined`).
+
+```typescript
+const handle: IServerHandle | undefined = app.getServer();
+handle?.port;      // number
+handle?.hostname;  // string
+await handle?.stop();
+
+// Access the raw underlying server (not recommended — type is unknown)
+const native: unknown = app.getNativeServer();
+// Bun:    native as Bun.Server<any>
+// Node.js: native as import('node:http').Server
+```
+
+### `WsArgumentsHost.getClient()`
+
+Returns `IWebSocket<T>` instead of Bun's `ServerWebSocket<T>`. This is the only breaking WebSocket API change.
+
+```typescript
+import type { IWebSocket } from '@dangao/bun-server';
+
+@WebSocketGateway()
+class ChatGateway {
+  @OnMessage('chat')
+  onChat(client: IWebSocket<unknown>, data: unknown) {
+    client.send('pong');
+  }
+}
+```
+
+`IWebSocket<T>` exposes the same core methods as `ServerWebSocket<T>`:
+`send`, `close`, `data`, `readyState`, `remoteAddress`.
+
+---
+
+## Bun-Exclusive Features
+
+The following options are accepted in `ApplicationOptions` but only take effect on Bun. They are silently ignored on Node.js.
+
+| Option | Effect on Bun | Node.js |
+|---|---|---|
+| `idleTimeout` | TCP idle timeout via `Bun.serve` | Ignored |
+| `reusePort` | Port reuse via `Bun.serve` | Ignored |
+| `sseKeepAlive` | Uses `server.timeout(req, 0)` | Heartbeat injection only |
+
+If your application relies on these features, document the Bun runtime requirement explicitly.
+
+---
+
+## Node.js Startup Guide
+
+### 1. Install
+
+```bash
+npm install @dangao/bun-server
+# Node.js peer dependencies are included automatically
+```
+
+### 2. Build
+
+```bash
+# Compile TypeScript to plain JS targeting Node.js
+bun build src/main.ts --target=node --outdir=dist
+
+# Or use tsc:
+npx tsc
+```
+
+### 3. Run
+
+```bash
+node dist/main.js
+# Platform auto-detected as 'node' — no extra flags needed
+```
+
+### 4. Smoke test (verify bun build output runs on Node.js)
+
+```bash
+bun run test:node
+# Runs: vitest run tests/platform/node
+```
+
+---
+
+## Testing on Multiple Runtimes
+
+Shared test cases live in `tests/platform/shared/*.cases.ts`. Both Bun and Node.js runners import the same assertions, guaranteeing identical coverage.
+
+```
+tests/platform/
+├── shared/
+│   ├── suite.ts              ← TestSuite interface (test / expect / beforeEach)
+│   ├── fs.cases.ts
+│   ├── crypto.cases.ts
+│   ├── parser.cases.ts
+│   ├── process.cases.ts
+│   ├── websocket.cases.ts
+│   └── database.cases.ts
+├── bun/                      ← bun:test runners
+│   └── *.test.ts
+├── node/                     ← vitest runners
+│   ├── *.test.ts
+│   └── build-smoke.test.ts   ← verifies bun build --target=node output
+└── detector.test.ts          ← priority chain unit tests
+```
+
+### Run tests
+
+```bash
+# Bun platform tests
+bun run test:bun
+
+# Node.js platform tests
+bun run test:node
+
+# Both platforms
+bun run test:platform
+```
+
+---
+
+## Known Limitations
+
+| Limitation | Details |
+|---|---|
+| `idleTimeout` / `reusePort` | Bun-only; no Node.js equivalent |
+| SSE TCP keepalive (`server.timeout`) | Bun-only API; Node.js gets heartbeat injection only |
+| `Bun.SQL` features | Some advanced Bun.SQL options (e.g., prepared statement caching) are unavailable in `postgres` / `mysql2` |
+| Cluster mode on Node.js | Uses `node:child_process`; may behave differently from Bun's cluster |
+| `bun:sqlite` extensions | Bun SQLite supports extensions; `better-sqlite3` extension loading differs |
+| Performance | Bun native APIs outperform Node.js polyfills, especially for file I/O and crypto |

package/docs/testing.md

@@ -72,6 +72,66 @@ await client.close();
 
 Options support `headers`, `body`, and `query`.
 
+## Multi-Runtime Testing
+
+The framework ships with a shared test strategy that runs the same test cases on both Bun and Node.js.
+
+### Test Structure
+
+```
+tests/platform/
+├── shared/          ← platform-neutral assertion helpers
+│   ├── suite.ts     ← TestSuite interface (test / expect / beforeEach)
+│   ├── fs.cases.ts
+│   ├── crypto.cases.ts
+│   ├── parser.cases.ts
+│   ├── process.cases.ts
+│   ├── websocket.cases.ts
+│   └── database.cases.ts
+├── bun/             ← bun:test runners (initRuntime('bun'))
+│   └── *.test.ts
+└── node/            ← vitest runners (initRuntime('node'))
+    ├── *.test.ts
+    └── build-smoke.test.ts
+```
+
+### Running Platform Tests
+
+```bash
+# Bun platform tests only
+bun run test:bun
+
+# Node.js platform tests only (uses vitest)
+bun run test:node
+
+# Both platforms
+bun run test:platform
+```
+
+### Writing Tests that Work on Both Runtimes
+
+Always call `initRuntime()` at the start of your test file:
+
+```ts
+// tests/platform/bun/fs.test.ts
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { initRuntime, _resetRuntime } from '../../../src/platform/runtime';
+import { runFsCases } from '../shared/fs.cases';
+
+initRuntime('bun');
+runFsCases({ test, expect, beforeEach });
+```
+
+```ts
+// tests/platform/node/fs.test.ts
+import { describe, test, expect, beforeEach } from 'vitest';
+import { initRuntime, _resetRuntime } from '../../../src/platform/runtime';
+import { runFsCases } from '../shared/fs.cases';
+
+beforeEach(() => { _resetRuntime(); initRuntime('node'); });
+runFsCases({ test, expect, beforeEach });
+```
+
 ## Example with bun:test
 
 ```ts

package/docs/zh/deployment.md

@@ -1,10 +1,11 @@
 # 生产部署指南
 
-本文档介绍将 Bun Server Framework 应用部署到生产环境的最佳实践。
+本文档介绍将 Bun Server Framework 应用部署到生产环境的最佳实践。框架同时支持 **Bun**（最优性能）和 **Node.js 22+** 运行时，请根据基础设施选择合适的方案。
 
 ## 目录
 
 - [前置要求](#前置要求)
+- [运行时选择](#运行时选择)
 - [环境设置](#环境设置)
 - [配置](#配置)
 - [进程管理](#进程管理)
@@ -15,23 +16,45 @@
 
 ## 前置要求
 
-- Bun runtime（最新稳定版本）
-- Node.js 18+（用于兼容性）
-- 生产级数据库（PostgreSQL、MySQL 等）
+- **Bun** >= 1.3.10（Bun 部署方案）**或** **Node.js** >= 22.0.0（Node.js 部署方案）
+- 生产级数据库（PostgreSQL、MySQL、SQLite 等）
 - 反向代理（Nginx、Caddy 等）
 
+## 运行时选择
+
+| 维度 | Bun | Node.js |
+|---|---|---|
+| 性能 | 最优（原生 API） | 良好 |
+| 生态成熟度 | 持续增长 | 成熟 |
+| Docker 镜像 | `oven/bun` | `node:22-alpine` |
+| `idleTimeout` / `reusePort` | 支持 | 不可用 |
+| 推荐场景 | 新项目、延迟敏感型应用 | 已有 Node.js 基础设施 |
+
+框架在启动时自动检测运行时。详见[平台适配指南](./platform.md)。
+
 ## 环境设置
 
-### 安装 Bun
+### 方案 A — Bun 运行时
 
 ```bash
-# 在 Linux/macOS 上
+# 安装 Bun（Linux/macOS）
 curl -fsSL https://bun.sh/install | bash
 
-# 验证安装
+# 验证
 bun --version
 ```
 
+### 方案 B — Node.js 运行时
+
+```bash
+# 使用 Node.js 22+（LTS）
+node --version  # 应为 v22+
+
+# 构建 TypeScript 为 JS
+bun build src/main.ts --target=node --outdir=dist
+# 或：npx tsc
+```
+
 ### 设置环境变量
 
 创建 `.env.production` 文件：

package/docs/zh/idle-timeout.md

@@ -1,19 +1,32 @@
-# idleTimeout
+# idleTimeout 与 SSE 保活
 
-`idleTimeout` 现已支持全局与路由级两种配置方式。
+> **平台说明：** `idleTimeout`、`reusePort` 以及基于 `server.timeout` 的 SSE TCP 保活是 **Bun 独有**特性，在 Node.js 上会被静默忽略。`@IdleTimeout(ms)` 装饰器（handler 级超时）在两个平台均可用。详见[平台适配指南](./platform.md#bun-独有特性)。
+
+## 两层超时机制
+
+Bun Server 有**两套独立的超时机制**——理解它们的区别对 SSE / 流式场景至关重要。
+
+| 层面 | 配置方式 | 作用域 | 机制 | Bun | Node.js |
+|------|----------|--------|------|-----|---------|
+| **TCP 连接级** | `Application({ idleTimeout })` | Bun.serve 底层 | Bun 内核在连接无数据流动 N 秒后直接断开 socket | 支持 | 忽略 |
+| **Handler 逻辑级** | `@IdleTimeout(ms)` 装饰器 | 路由粒度的 `Promise.race` | handler 未在指定时间内 resolve 则返回 `408 Request Timeout` | 支持 | 支持 |
+
+> **关键：** 对于 SSE 响应，handler 会立即返回一个带流式 body 的 `Response`。此时 handler 层面的 `@IdleTimeout` 已经 resolve，**不会**保护或终止该流。只有 TCP 级别的 `idleTimeout` 才能断开 SSE 连接。
+
+---
 
 ## 全局 idleTimeout（毫秒）
 
-在 `Application` 中直接按毫秒设置，框架内部会转换后传给 `Bun.serve`。
+在 `Application` 中按毫秒设置，框架内部自动转换后传给 `Bun.serve`（`Math.ceil(ms / 1000)` → 秒）。
 
 ```ts
 const app = new Application({
   port: 3000,
-  idleTimeout: 15000, // ms
+  idleTimeout: 15000, // 15 秒 — 对所有非 SSE 连接生效
 });
 ```
 
-## 路由级超时（毫秒）
+## 路由级超时 — `@IdleTimeout(ms)`
 
 使用 `@IdleTimeout(ms)` 装饰器配置控制器级或方法级超时。
 
@@ -37,5 +50,85 @@ class ApiController {
 }
 ```
 
-超时后会抛出 `HttpException(408, "Request Timeout")`。
+### 匹配与生效规则
+
+1. **方法级** `@IdleTimeout` 优先检测——存在即生效。
+2. **类级** `@IdleTimeout` 作为兜底。
+3. 若均未设置，则不应用 handler 级超时（路由将持续运行直到 TCP 超时或自然完成）。
+
+handler 级超时触发时，框架抛出 `HttpException(408, "Request Timeout")`。
+
+---
+
+## SSE 保活（自动）
+
+当框架检测到响应的 `Content-Type` 包含 `text/event-stream` 时，会自动执行：
+
+1. **禁用该请求的 TCP 空闲超时** —— 通过 `server.timeout(req, 0)` 阻止 Bun 断开长连接。
+2. **注入 SSE 注释心跳** —— 按配置间隔发送 `: keepalive\n\n`，防止中间代理（nginx、云 LB）因空闲而断连。
+
+### 配置
+
+```ts
+const app = new Application({
+  port: 3000,
+  idleTimeout: 10000, // 普通请求：10 秒
+
+  // SSE 保活 — 以下为默认值
+  sseKeepAlive: {
+    enabled: true,      // 自动检测 SSE 并注入心跳
+    intervalMs: 15000,  // 每 15 秒一次心跳
+  },
+});
+```
 
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `sseKeepAlive.enabled` | `boolean` | `true` | 启用 SSE 自动检测、TCP 超时解除和心跳注入 |
+| `sseKeepAlive.intervalMs` | `number` | `15000` | 心跳间隔（毫秒） |
+
+当 `enabled` 为 `true`（默认）时，任何 `Content-Type` 头包含 `text/event-stream` 的响应都会触发 SSE 后处理器。**无需任何特殊装饰器或注解**——纯粹基于响应头自动检测。
+
+当 `enabled` 为 `false` 时，框架不做任何 SSE 特殊处理。你需要自行管理 keep-alive 和 `server.timeout`。
+
+---
+
+## 信号级联（`ctx.signal`）
+
+`Context` 通过 `ctx.signal` 暴露客户端的 `AbortSignal`。当客户端断连（网络故障、关闭浏览器标签、中断 `curl`）时，该信号会 abort。
+
+对于 AI 流式端点，将 `ctx.signal` 传递给 `AiService`，可立即取消上游 API 请求——**停止 token 消耗**：
+
+```ts
+import { Controller, GET, Context as Ctx } from '@dangao/bun-server';
+import type { Context } from '@dangao/bun-server';
+
+@Controller('/chat')
+class ChatController {
+  constructor(private readonly ai: AiService) {}
+
+  @GET('/stream')
+  public stream(@Ctx() ctx: Context) {
+    const stream = this.ai.stream({
+      messages: [{ role: 'user', content: 'Hello' }],
+      signal: ctx.signal, // ← 级联客户端断连
+    });
+    return new Response(stream, {
+      headers: { 'Content-Type': 'text/event-stream' },
+    });
+  }
+}
+```
+
+> **注意：** `Context` 参数装饰器既可通过 `Context`（从 `'./controller'`）导入，也可通过包根导出的别名 `ContextParam` 导入。推荐使用 `ContextParam` 或 `Context as Ctx` 以避免与 `Context` 类型名冲突。
+
+完整取消链路：
+
+```
+客户端断连
+  → request.signal abort
+    → 心跳定时器清理
+      → 包裹流取消
+        → AI Provider 内部 fetch() abort
+          → 上游 API 连接关闭（节省 token）
+```

package/docs/zh/migration.md

@@ -2,6 +2,48 @@
 
 适用于从项目早期版本或其他框架迁移到最新 Bun Server Framework 的场景。
 
+## v2.x → v3.0（平台适配层）
+
+v3.0.0 引入 **Platform Adapter Layer**，在保留 Bun 最优性能的同时支持 Node.js 22+。
+
+### 破坏性变更
+
+| 变更点 | 之前 | 之后 |
+|---|---|---|
+| `BunServer.getServer()` 返回类型 | `Bun.Server \| undefined` | `IServerHandle \| undefined` |
+| `WsArgumentsHost.getClient()` 返回类型 | `ServerWebSocket<T>` | `IWebSocket<T>` |
+
+### 迁移步骤
+
+**1. 更新 WebSocket 守卫类型**
+
+```typescript
+// 之前
+import type { ServerWebSocket } from 'bun';
+getClient(): ServerWebSocket<unknown>
+
+// 之后
+import type { IWebSocket } from '@dangao/bun-server';
+getClient(): IWebSocket<unknown>
+```
+
+**2. 更新服务器句柄访问**
+
+```typescript
+// 之前
+const server: Bun.Server | undefined = app.getServer();
+
+// 之后
+import type { IServerHandle } from '@dangao/bun-server';
+const server: IServerHandle | undefined = app.getServer();
+// 原生访问（不推荐，类型为 unknown）：
+const native: unknown = app.getNativeServer();
+```
+
+**3. 其他均向后兼容。** 数据库配置、模块 API、控制器、服务和中间件无需修改。
+
+---
+
 ## 1. 项目结构调整
 
 - 统一入口到 `src/index.ts`，示例项目可放在 `examples/`。