@dangao/bun-server 1.9.0 → 1.12.0

package/src/core/application.ts

@@ -19,6 +19,7 @@ import { ConfigModule } from '../config/config-module';
 import { CacheModule, CACHE_POST_PROCESSOR_TOKEN } from '../cache';
 import { LoggerManager } from '@dangao/logsmith';
 import { EventModule } from '../events/event-module';
+import { AsyncProviderRegistry } from '../di/async-module';
 
 /**
  * 应用配置选项
@@ -45,6 +46,14 @@ export interface ApplicationOptions {
    * 默认 true
    */
   enableSignalHandlers?: boolean;
+
+  /**
+   * 是否启用 SO_REUSEPORT
+   * 允许多进程绑定同一端口，用于多进程负载均衡
+   * 仅 Linux 有效，macOS/Windows 会忽略
+   * @default false
+   */
+  reusePort?: boolean;
 }
 
 /**
@@ -97,6 +106,12 @@ export class Application {
       throw new Error('Application is already running');
     }
 
+    // 初始化异步 providers（forRootAsync 注册的工厂）
+    const asyncRegistry = AsyncProviderRegistry.getInstance();
+    if (asyncRegistry.hasPending()) {
+      await asyncRegistry.initializeAll(this.getContainer());
+    }
+
     // 初始化所有扩展（包括数据库连接等）
     await this.initializeExtensions();
 
@@ -106,12 +121,20 @@ export class Application {
     // 自动初始化事件监听器（如果 EventModule 已注册且启用了 autoScan）
     this.initializeEventListeners();
 
+    // 调用生命周期钩子：onModuleInit
+    const registry = ModuleRegistry.getInstance();
+    await registry.callModuleInitHooks();
+
+    // 调用生命周期钩子：onApplicationBootstrap
+    await registry.callBootstrapHooks();
+
     const finalPort = port ?? this.options.port ?? 3000;
     const finalHostname = hostname ?? this.options.hostname;
 
     const serverOptions: ServerOptions = {
       port: finalPort,
       hostname: finalHostname,
+      reusePort: this.options.reusePort,
       fetch: this.handleRequest.bind(this),
       websocketRegistry: this.websocketRegistry,
       gracefulShutdownTimeout: this.options.gracefulShutdownTimeout,
@@ -214,6 +237,13 @@ export class Application {
     // 移除信号处理器
     this.removeSignalHandlers();
 
+    // 调用生命周期钩子：onApplicationShutdown
+    const moduleRegistry = ModuleRegistry.getInstance();
+    await moduleRegistry.callShutdownHooks();
+
+    // 调用生命周期钩子：onModuleDestroy
+    await moduleRegistry.callModuleDestroyHooks();
+
     // 自动注销服务（如果使用了 @ServiceRegistry 装饰器）
     await this.deregisterServices();
 
@@ -232,6 +262,13 @@ export class Application {
     // 移除信号处理器
     this.removeSignalHandlers();
 
+    // 调用生命周期钩子：onApplicationShutdown
+    const moduleRegistry = ModuleRegistry.getInstance();
+    await moduleRegistry.callShutdownHooks();
+
+    // 调用生命周期钩子：onModuleDestroy
+    await moduleRegistry.callModuleDestroyHooks();
+
     // 自动注销服务（如果使用了 @ServiceRegistry 装饰器）
     await this.deregisterServices();
 

package/src/core/apply-decorators.ts

@@ -0,0 +1,31 @@
+/**
+ * 装饰器组合工具
+ * 将多个装饰器合并为一个可复用的装饰器
+ */
+export function applyDecorators(
+  ...decorators: Array<ClassDecorator | MethodDecorator | PropertyDecorator>
+): ClassDecorator & MethodDecorator & PropertyDecorator {
+  return ((
+    target: unknown,
+    propertyKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ) => {
+    for (const decorator of decorators.reverse()) {
+      if (descriptor) {
+        const result = (decorator as MethodDecorator)(
+          target as object,
+          propertyKey!,
+          descriptor,
+        );
+        if (result) {
+          descriptor = result as PropertyDescriptor;
+        }
+      } else if (propertyKey) {
+        (decorator as PropertyDecorator)(target as object, propertyKey);
+      } else {
+        (decorator as ClassDecorator)(target as Function);
+      }
+    }
+    return descriptor;
+  }) as ClassDecorator & MethodDecorator & PropertyDecorator;
+}

package/src/core/cluster.ts

@@ -0,0 +1,143 @@
+import { spawn } from 'bun';
+import { LoggerManager } from '@dangao/logsmith';
+
+export interface ClusterOptions {
+  /**
+   * 是否启用集群模式
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Worker 数量。'auto' 表示使用 CPU 核心数
+   * @default 'auto'
+   */
+  workers?: number | 'auto';
+}
+
+/**
+ * 集群管理器
+ * 自动派生 worker 进程，每个 worker 使用 reusePort 绑定相同端口
+ */
+export class ClusterManager {
+  private readonly workerCount: number;
+  private readonly workers: ReturnType<typeof spawn>[] = [];
+  private readonly scriptPath: string;
+  private readonly port: number;
+  private readonly hostname?: string;
+
+  public constructor(options: {
+    workers: number | 'auto';
+    scriptPath: string;
+    port: number;
+    hostname?: string;
+  }) {
+    this.workerCount =
+      options.workers === 'auto' ? navigator.hardwareConcurrency : options.workers;
+    this.scriptPath = options.scriptPath;
+    this.port = options.port;
+    this.hostname = options.hostname;
+  }
+
+  /**
+   * 启动所有 worker 进程
+   */
+  public start(): void {
+    const logger = LoggerManager.getLogger();
+    logger.info(
+      `[Cluster] Starting ${this.workerCount} workers on port ${this.port}`,
+    );
+
+    for (let i = 0; i < this.workerCount; i++) {
+      const worker = spawn({
+        cmd: ['bun', 'run', this.scriptPath],
+        env: {
+          ...process.env,
+          PORT: String(this.port),
+          REUSE_PORT: '1',
+          CLUSTER_WORKER: '1',
+          WORKER_ID: String(i),
+          ...(this.hostname ? { HOSTNAME: this.hostname } : {}),
+        },
+        stdout: 'inherit',
+        stderr: 'inherit',
+      });
+      this.workers.push(worker);
+    }
+
+    logger.info(
+      `[Cluster] ${this.workerCount} workers started (reusePort mode)`,
+    );
+
+    // Monitor workers and auto-restart on crash
+    this.monitorWorkers();
+  }
+
+  /**
+   * 停止所有 worker 进程
+   */
+  public async stop(): Promise<void> {
+    const logger = LoggerManager.getLogger();
+    logger.info('[Cluster] Stopping all workers...');
+
+    for (const worker of this.workers) {
+      worker.kill('SIGTERM');
+    }
+
+    // Wait up to 5 seconds for workers to exit
+    const timeout = setTimeout(() => {
+      for (const worker of this.workers) {
+        worker.kill('SIGKILL');
+      }
+    }, 5000);
+
+    await Promise.all(this.workers.map((w) => w.exited));
+    clearTimeout(timeout);
+
+    this.workers.length = 0;
+    logger.info('[Cluster] All workers stopped');
+  }
+
+  private monitorWorkers(): void {
+    // For each worker, restart if it crashes unexpectedly
+    for (let i = 0; i < this.workers.length; i++) {
+      const index = i;
+      this.workers[index].exited.then((exitCode) => {
+        if (exitCode !== 0 && exitCode !== null) {
+          const logger = LoggerManager.getLogger();
+          logger.warn(
+            `[Cluster] Worker ${index} exited with code ${exitCode}, restarting...`,
+          );
+
+          const newWorker = spawn({
+            cmd: ['bun', 'run', this.scriptPath],
+            env: {
+              ...process.env,
+              PORT: String(this.port),
+              REUSE_PORT: '1',
+              CLUSTER_WORKER: '1',
+              WORKER_ID: String(index),
+              ...(this.hostname ? { HOSTNAME: this.hostname } : {}),
+            },
+            stdout: 'inherit',
+            stderr: 'inherit',
+          });
+          this.workers[index] = newWorker;
+        }
+      });
+    }
+  }
+
+  /**
+   * 检查当前进程是否为 cluster worker
+   */
+  public static isWorker(): boolean {
+    return process.env.CLUSTER_WORKER === '1';
+  }
+
+  /**
+   * 获取当前 worker ID（仅在 worker 进程中有效）
+   */
+  public static getWorkerId(): number {
+    return Number(process.env.WORKER_ID ?? -1);
+  }
+}

package/src/core/index.ts

@@ -1,5 +1,6 @@
 export { Application, type ApplicationOptions } from './application';
 export { BunServer, type ServerOptions } from './server';
+export { ClusterManager, type ClusterOptions } from './cluster';
 export { Context } from './context';
 export { ContextService, CONTEXT_SERVICE_TOKEN, contextStore } from './context-service';
 

package/src/core/server.ts

@@ -33,6 +33,14 @@ export interface ServerOptions {
    * 默认 30 秒
    */
   gracefulShutdownTimeout?: number;
+
+  /**
+   * 是否启用 SO_REUSEPORT
+   * 允许多进程绑定同一端口，用于多进程负载均衡
+   * 仅 Linux 有效，macOS/Windows 会忽略
+   * @default false
+   */
+  reusePort?: boolean;
 }
 
 /**
@@ -70,6 +78,7 @@ export class BunServer {
     this.server = Bun.serve({
       port: this.options.port ?? 3000,
       hostname: this.options.hostname,
+      reusePort: this.options.reusePort,
       fetch: (
         request: Request,
         server: Server<WebSocketConnectionData>,
@@ -150,7 +159,7 @@ export class BunServer {
     });
 
     const hostname = this.options.hostname ?? "localhost";
-    const port = this.options.port ?? 3000;
+    const port = this.server.port;
     logger.info(`Server started at http://${hostname}:${port}`);
   }
 
@@ -249,8 +258,12 @@ export class BunServer {
 
   /**
    * 获取服务器端口
+   * 如果服务器正在运行，返回实际绑定的端口（支持 port:0 场景）
    */
   public getPort(): number {
+    if (this.server) {
+      return this.server.port ?? this.options.port ?? 3000;
+    }
     return this.options.port ?? 3000;
   }
 

package/src/dashboard/controller.ts

@@ -0,0 +1,227 @@
+import { RouteRegistry } from '../router/registry';
+import type { Context } from '../core/context';
+import { createDashboardHTML } from './ui';
+import { ControllerRegistry } from '../controller/controller';
+import { HEALTH_INDICATORS_TOKEN } from '../health/types';
+import type { HealthIndicator } from '../health/types';
+
+/**
+ * Dashboard 服务
+ * 提供监控 UI 和 API 端点
+ */
+export class DashboardService {
+  private readonly basePath: string;
+  private readonly auth?: { username: string; password: string };
+  private readonly startTime: number = Date.now();
+
+  /**
+   * 创建 Dashboard 服务实例
+   * @param basePath - Dashboard 基础路径
+   * @param auth - Basic Auth 认证配置（可选）
+   */
+  public constructor(
+    basePath: string,
+    auth?: { username: string; password: string },
+  ) {
+    this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    this.auth = auth;
+  }
+
+  /**
+   * 注册 Dashboard 路由
+   */
+  public registerRoutes(): void {
+    const registry = RouteRegistry.getInstance();
+
+    registry.register('GET', this.basePath, (ctx) => this.handleDashboard(ctx));
+    registry.register(
+      'GET',
+      `${this.basePath}/api/system`,
+      (ctx) => this.handleSystem(ctx),
+    );
+    registry.register(
+      'GET',
+      `${this.basePath}/api/routes`,
+      (ctx) => this.handleRoutes(ctx),
+    );
+    registry.register(
+      'GET',
+      `${this.basePath}/api/health`,
+      (ctx) => this.handleHealth(ctx),
+    );
+    registry.register(
+      'POST',
+      `${this.basePath}/api/markdown`,
+      (ctx) => this.handleMarkdownRender(ctx),
+    );
+  }
+
+  /**
+   * 检查 Basic Auth
+   * @param ctx - 请求上下文
+   * @returns 是否通过认证，未配置 auth 时返回 true
+   */
+  private checkAuth(ctx: Context): boolean {
+    if (!this.auth) {
+      return true;
+    }
+    const authHeader = ctx.getHeader('Authorization');
+    if (!authHeader || !authHeader.startsWith('Basic ')) {
+      return false;
+    }
+    try {
+      const decoded = atob(authHeader.slice(6));
+      const [username, password] = decoded.split(':');
+      return (
+        username === this.auth.username && password === this.auth.password
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 返回 401 Unauthorized 响应
+   */
+  private unauthorizedResponse(): Response {
+    return new Response('Unauthorized', {
+      status: 401,
+      headers: {
+        'WWW-Authenticate': 'Basic realm="Dashboard"',
+        'Content-Type': 'text/plain',
+      },
+    });
+  }
+
+  /**
+   * 处理 Dashboard 主页面
+   */
+  private async handleDashboard(ctx: Context): Promise<Response> {
+    if (!this.checkAuth(ctx)) {
+      return this.unauthorizedResponse();
+    }
+    const html = createDashboardHTML(this.basePath);
+    return new Response(html, {
+      headers: { 'Content-Type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  /**
+   * 处理系统信息 API
+   */
+  private async handleSystem(ctx: Context): Promise<Response> {
+    if (!this.checkAuth(ctx)) {
+      return this.unauthorizedResponse();
+    }
+    const mem = process.memoryUsage();
+    const data = {
+      uptime: Math.floor(process.uptime()),
+      memory: {
+        rss: mem.rss,
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+      },
+      platform: process.platform,
+      bunVersion: typeof Bun !== 'undefined' ? Bun.version : undefined,
+    };
+    return new Response(JSON.stringify(data), {
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    });
+  }
+
+  /**
+   * 处理路由列表 API
+   */
+  private async handleRoutes(ctx: Context): Promise<Response> {
+    if (!this.checkAuth(ctx)) {
+      return this.unauthorizedResponse();
+    }
+    const registry = RouteRegistry.getInstance();
+    const router = registry.getRouter();
+    const routes = router.getRoutes();
+    const data = routes.map((r) => ({
+      method: r.method,
+      path: r.path,
+      controller: r.controllerClass?.name ?? undefined,
+      methodName: r.methodName ?? undefined,
+    }));
+    return new Response(JSON.stringify(data), {
+      headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    });
+  }
+
+  /**
+   * 将 Markdown 文本渲染为 HTML
+   * 利用 Bun 1.3.8+ 内置 Bun.markdown 解析器（Zig 实现，支持 GFM）
+   */
+  private async handleMarkdownRender(ctx: Context): Promise<Response> {
+    if (!this.checkAuth(ctx)) {
+      return this.unauthorizedResponse();
+    }
+    try {
+      const body = await ctx.request.json() as { content?: string };
+      if (!body.content) {
+        return new Response(JSON.stringify({ error: 'content field is required' }), {
+          status: 400,
+          headers: { 'Content-Type': 'application/json; charset=utf-8' },
+        });
+      }
+      const html = Bun.markdown.html(body.content, { headings: true });
+      return new Response(JSON.stringify({ html }), {
+        headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      });
+    } catch (err) {
+      return new Response(JSON.stringify({ error: (err as Error).message }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      });
+    }
+  }
+
+  /**
+   * 处理健康检查 API
+   * 如果 HealthModule 已注册则运行健康指示器，否则返回基本状态
+   */
+  private async handleHealth(ctx: Context): Promise<Response> {
+    if (!this.checkAuth(ctx)) {
+      return this.unauthorizedResponse();
+    }
+    try {
+      const container = ControllerRegistry.getInstance().getContainer();
+      const indicators = container.resolve<HealthIndicator[]>(
+        HEALTH_INDICATORS_TOKEN,
+      );
+      const details: Record<string, { status: string; details?: unknown }> = {};
+      for (const indicator of indicators) {
+        try {
+          const result = await indicator.check();
+          details[indicator.name] = result;
+        } catch (err) {
+          details[indicator.name] = {
+            status: 'down',
+            details: { error: (err as Error).message },
+          };
+        }
+      }
+      const allUp =
+        Object.keys(details).length === 0 ||
+        Object.values(details).every((r) => r.status === 'up');
+      const data = {
+        status: allUp ? 'up' : 'down',
+        timestamp: Date.now(),
+        details,
+      };
+      return new Response(JSON.stringify(data), {
+        headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      });
+    } catch {
+      const data = {
+        status: 'up',
+        timestamp: Date.now(),
+      };
+      return new Response(JSON.stringify(data), {
+        headers: { 'Content-Type': 'application/json; charset=utf-8' },
+      });
+    }
+  }
+}

package/src/dashboard/dashboard-extension.ts

@@ -0,0 +1,26 @@
+import type { ApplicationExtension } from '../extensions/types';
+import type { Container } from '../di/container';
+import { DashboardService } from './controller';
+
+/**
+ * Dashboard 扩展
+ * 在应用初始化时注册 Dashboard 路由
+ */
+export class DashboardExtension implements ApplicationExtension {
+  private readonly service: DashboardService;
+
+  /**
+   * 创建 Dashboard 扩展
+   * @param service - Dashboard 服务实例
+   */
+  public constructor(service: DashboardService) {
+    this.service = service;
+  }
+
+  /**
+   * 注册扩展，将 Dashboard 路由注册到 RouteRegistry
+   */
+  public register(_container: Container): void {
+    this.service.registerRoutes();
+  }
+}

package/src/dashboard/dashboard-module.ts

@@ -0,0 +1,38 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import { DashboardService } from './controller';
+import { DashboardExtension } from './dashboard-extension';
+import type { DashboardModuleOptions } from './types';
+
+/**
+ * Dashboard 模块
+ * 提供监控 Web UI，可视化指标、健康状态、路由和系统信息
+ */
+@Module({
+  extensions: [],
+  controllers: [],
+  providers: [],
+})
+export class DashboardModule {
+  /**
+   * 创建 Dashboard 模块
+   * @param options - 模块配置
+   */
+  public static forRoot(
+    options: DashboardModuleOptions = {},
+  ): typeof DashboardModule {
+    const path = options.path ?? '/_dashboard';
+    const basePath = path.endsWith('/') ? path.slice(0, -1) : path;
+    const service = new DashboardService(basePath, options.auth);
+    const extension = new DashboardExtension(service);
+
+    const existingMetadata =
+      Reflect.getMetadata(MODULE_METADATA_KEY, DashboardModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      extensions: [extension],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, DashboardModule);
+
+    return DashboardModule;
+  }
+}

package/src/dashboard/index.ts

@@ -0,0 +1,3 @@
+export { DashboardModule } from './dashboard-module';
+export { DashboardService } from './controller';
+export { DASHBOARD_OPTIONS_TOKEN, type DashboardModuleOptions } from './types';

package/src/dashboard/types.ts

@@ -0,0 +1,16 @@
+export interface DashboardModuleOptions {
+  /**
+   * Dashboard UI 路径
+   * @default '/_dashboard'
+   */
+  path?: string;
+  /**
+   * Basic Auth 认证配置
+   */
+  auth?: {
+    username: string;
+    password: string;
+  };
+}
+
+export const DASHBOARD_OPTIONS_TOKEN = Symbol('@dangao/bun-server:dashboard:options');