@dangao/bun-server 1.12.0 → 2.0.0

package/src/core/cluster.ts

@@ -1,5 +1,16 @@
 import { spawn } from 'bun';
 import { LoggerManager } from '@dangao/logsmith';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdirSync, rmSync, existsSync } from 'fs';
+
+/**
+ * 集群模式
+ * - 'reusePort': 使用 SO_REUSEPORT 内核分发（仅 Linux 有效）
+ * - 'proxy': 主进程通过 Unix socket round-robin 代理转发（跨平台，有额外开销）
+ * - 'auto': 默认使用 reusePort
+ */
+export type ClusterMode = 'reusePort' | 'proxy' | 'auto';
 
 export interface ClusterOptions {
   /**
@@ -12,11 +23,18 @@ export interface ClusterOptions {
    * @default 'auto'
    */
   workers?: number | 'auto';
+  /**
+   * 集群模式
+   * @default 'auto'
+   */
+  mode?: ClusterMode;
 }
 
 /**
  * 集群管理器
- * 自动派生 worker 进程，每个 worker 使用 reusePort 绑定相同端口
+ * 自动派生 worker 进程，支持两种模式：
+ * - reusePort：每个 worker 使用 SO_REUSEPORT 绑定相同端口（Linux 内核分发）
+ * - proxy：主进程 round-robin 代理转发到 worker 随机端口（跨平台）
  */
 export class ClusterManager {
   private readonly workerCount: number;
@@ -24,52 +42,48 @@ export class ClusterManager {
   private readonly scriptPath: string;
   private readonly port: number;
   private readonly hostname?: string;
+  private readonly mode: 'reusePort' | 'proxy';
+  private proxyServer?: ReturnType<typeof Bun.serve>;
+  private socketPaths: string[] = [];
+  private roundRobinIndex = 0;
+  private socketDir?: string;
 
   public constructor(options: {
     workers: number | 'auto';
     scriptPath: string;
     port: number;
     hostname?: string;
+    mode?: ClusterMode;
   }) {
     this.workerCount =
       options.workers === 'auto' ? navigator.hardwareConcurrency : options.workers;
     this.scriptPath = options.scriptPath;
     this.port = options.port;
     this.hostname = options.hostname;
+
+    const requestedMode = options.mode ?? 'auto';
+    this.mode = requestedMode === 'auto' ? 'reusePort' : requestedMode;
   }
 
   /**
-   * 启动所有 worker 进程
+   * 获取已解析的集群模式
    */
-  public start(): void {
-    const logger = LoggerManager.getLogger();
-    logger.info(
-      `[Cluster] Starting ${this.workerCount} workers on port ${this.port}`,
-    );
+  public getMode(): 'reusePort' | 'proxy' {
+    return this.mode;
+  }
 
-    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);
+  /**
+   * 启动所有 worker 进程
+   *
+   * - reusePort 模式：立即返回（workers 异步启动）
+   * - proxy 模式：等待所有 worker 就绪后启动代理服务器再返回
+   */
+  public async start(): Promise<void> {
+    if (this.mode === 'reusePort') {
+      this.startReusePort();
+    } else {
+      await this.startProxy();
     }
-
-    logger.info(
-      `[Cluster] ${this.workerCount} workers started (reusePort mode)`,
-    );
-
-    // Monitor workers and auto-restart on crash
-    this.monitorWorkers();
   }
 
   /**
@@ -79,11 +93,15 @@ export class ClusterManager {
     const logger = LoggerManager.getLogger();
     logger.info('[Cluster] Stopping all workers...');
 
+    if (this.proxyServer) {
+      this.proxyServer.stop();
+      this.proxyServer = undefined;
+    }
+
     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');
@@ -94,39 +112,205 @@ export class ClusterManager {
     clearTimeout(timeout);
 
     this.workers.length = 0;
+    this.socketPaths.length = 0;
+
+    if (this.socketDir) {
+      try {
+        rmSync(this.socketDir, { recursive: true, force: true });
+      } catch {
+        // ignore cleanup errors
+      }
+      this.socketDir = undefined;
+    }
+
     logger.info('[Cluster] All workers stopped');
   }
 
-  private monitorWorkers(): void {
-    // For each worker, restart if it crashes unexpectedly
+  // ── reusePort mode ──────────────────────────────────────────────
+
+  private startReusePort(): void {
+    const logger = LoggerManager.getLogger();
+    logger.info(
+      `[Cluster] Starting ${this.workerCount} workers on port ${this.port}`,
+    );
+
+    for (let i = 0; i < this.workerCount; i++) {
+      this.workers.push(this.spawnReusePortWorker(i));
+    }
+
+    logger.info(
+      `[Cluster] ${this.workerCount} workers started (reusePort mode)`,
+    );
+
+    this.monitorReusePortWorkers();
+  }
+
+  private spawnReusePortWorker(index: number): ReturnType<typeof spawn> {
+    return 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',
+    });
+  }
+
+  private monitorReusePortWorkers(): void {
     for (let i = 0; i < this.workers.length; i++) {
       const index = i;
-      this.workers[index].exited.then((exitCode) => {
+      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...`,
           );
+          this.workers[index] = this.spawnReusePortWorker(index);
+        }
+      });
+    }
+  }
 
-          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',
+  // ── proxy mode (Unix socket) ─────────────────────────────────────
+
+  private async startProxy(): Promise<void> {
+    const logger = LoggerManager.getLogger();
+    logger.info(
+      `[Cluster] Starting ${this.workerCount} workers in proxy mode on port ${this.port}`,
+    );
+
+    this.socketDir = join(tmpdir(), `bun-cluster-${process.pid}`);
+    // Clean up stale directory from a previous run with the same PID
+    try { rmSync(this.socketDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    mkdirSync(this.socketDir, { recursive: true });
+
+    this.socketPaths = [];
+    for (let i = 0; i < this.workerCount; i++) {
+      const socketPath = join(this.socketDir, `w${i}.sock`);
+      this.socketPaths.push(socketPath);
+      this.workers.push(this.spawnProxyWorker(i, socketPath));
+    }
+
+    await this.waitForWorkerSockets();
+    this.startProxyServer();
+
+    logger.info(
+      `[Cluster] ${this.workerCount} workers ready (proxy mode, unix sockets)`,
+    );
+
+    this.monitorProxyWorkers();
+  }
+
+  private spawnProxyWorker(index: number, socketPath: string): ReturnType<typeof spawn> {
+    return spawn({
+      cmd: ['bun', 'run', this.scriptPath],
+      env: {
+        ...process.env,
+        PORT: '0',
+        REUSE_PORT: '0',
+        CLUSTER_WORKER: '1',
+        WORKER_ID: String(index),
+        CLUSTER_MODE: 'proxy',
+        CLUSTER_SOCKET_FILE: socketPath,
+        ...(this.hostname ? { HOSTNAME: this.hostname } : {}),
+      },
+      stdout: 'inherit',
+      stderr: 'inherit',
+    });
+  }
+
+  private async waitForWorkerSockets(): Promise<void> {
+    const deadline = Date.now() + 30_000;
+
+    while (Date.now() < deadline) {
+      let allReady = true;
+
+      for (const socketPath of this.socketPaths) {
+        if (!existsSync(socketPath)) {
+          allReady = false;
+          break;
+        }
+      }
+
+      if (allReady) {
+        // Give workers a moment to finish bind+listen after file creation
+        await Bun.sleep(200);
+        return;
+      }
+
+      await Bun.sleep(100);
+    }
+
+    const ready = this.socketPaths.filter((p) => existsSync(p)).length;
+    throw new Error(
+      `[Cluster] Not all workers created sockets within 30s (got ${ready}/${this.workerCount})`,
+    );
+  }
+
+  private startProxyServer(): void {
+    const sockets = this.socketPaths;
+    const count = sockets.length;
+
+    this.proxyServer = Bun.serve({
+      port: this.port,
+      hostname: this.hostname,
+      fetch: async (req) => {
+        const socketPath = sockets[this.roundRobinIndex % count]!;
+        this.roundRobinIndex++;
+
+        try {
+          return await fetch(req.url, {
+            method: req.method,
+            headers: req.headers,
+            body: req.body,
+            redirect: 'manual',
+            unix: socketPath,
           });
-          this.workers[index] = newWorker;
+        } catch {
+          return new Response('Bad Gateway', { status: 502 });
+        }
+      },
+    });
+  }
+
+  private monitorProxyWorkers(): void {
+    for (let i = 0; i < this.workers.length; i++) {
+      const index = i;
+      this.workers[index]!.exited.then(async (exitCode) => {
+        if (exitCode !== 0 && exitCode !== null) {
+          const logger = LoggerManager.getLogger();
+          logger.warn(
+            `[Cluster] Worker ${index} exited with code ${exitCode}, restarting...`,
+          );
+
+          const socketPath = this.socketPaths[index]!;
+          try { rmSync(socketPath); } catch { /* ignore */ }
+
+          this.workers[index] = this.spawnProxyWorker(index, socketPath);
+
+          const deadline = Date.now() + 15_000;
+          while (Date.now() < deadline) {
+            if (existsSync(socketPath)) {
+              await Bun.sleep(200);
+              logger.info(`[Cluster] Worker ${index} restarted (unix socket)`);
+              return;
+            }
+            await Bun.sleep(100);
+          }
+
+          logger.error(`[Cluster] Worker ${index} failed to restart within 15s`);
         }
       });
     }
   }
 
+  // ── static helpers ──────────────────────────────────────────────
+
   /**
    * 检查当前进程是否为 cluster worker
    */
@@ -140,4 +324,13 @@ export class ClusterManager {
   public static getWorkerId(): number {
     return Number(process.env.WORKER_ID ?? -1);
   }
+
+  /**
+   * 获取当前 worker 的集群模式
+   * @returns 集群模式，非 worker 进程返回 null
+   */
+  public static getClusterMode(): 'reusePort' | 'proxy' | null {
+    if (!ClusterManager.isWorker()) return null;
+    return process.env.CLUSTER_MODE === 'proxy' ? 'proxy' : 'reusePort';
+  }
 }

package/src/core/index.ts

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

package/src/core/server.ts

@@ -75,92 +75,105 @@ export class BunServer {
     this.shutdownPromise = undefined;
     this.shutdownResolve = undefined;
 
-    this.server = Bun.serve({
-      port: this.options.port ?? 3000,
-      hostname: this.options.hostname,
-      reusePort: this.options.reusePort,
-      fetch: (
-        request: Request,
-        server: Server<WebSocketConnectionData>,
-      ): Response | Promise<Response> | undefined => {
-        // 如果正在关闭，拒绝新请求
-        if (this.isShuttingDown) {
-          return new Response("Server is shutting down", { status: 503 });
+    const fetchHandler = (
+      request: Request,
+      server: Server<WebSocketConnectionData>,
+    ): Response | Promise<Response> | undefined => {
+      if (this.isShuttingDown) {
+        return new Response("Server is shutting down", { status: 503 });
+      }
+
+      const upgradeHeader = request.headers.get("upgrade");
+      if (
+        this.options.websocketRegistry &&
+        upgradeHeader &&
+        upgradeHeader.toLowerCase() === "websocket"
+      ) {
+        const url = new URL(request.url);
+        if (!this.options.websocketRegistry.hasGateway(url.pathname)) {
+          return new Response("WebSocket gateway not found", { status: 404 });
         }
-
-        const upgradeHeader = request.headers.get("upgrade");
-        if (
-          this.options.websocketRegistry &&
-          upgradeHeader &&
-          upgradeHeader.toLowerCase() === "websocket"
-        ) {
-          const url = new URL(request.url);
-          // 检查是否有匹配的网关（支持动态路径匹配）
-          if (!this.options.websocketRegistry.hasGateway(url.pathname)) {
-            return new Response("WebSocket gateway not found", { status: 404 });
-          }
-          // 创建 Context 以便在 WebSocket 处理器中使用
-          const context = new Context(request);
-          // 创建 Bun 兼容的 URLSearchParams（需要 toJSON 方法）
-          const queryParams = new URLSearchParams(url.searchParams);
-          const upgraded = server.upgrade(request, {
-            data: {
-              path: url.pathname,
-              query: queryParams,
-              context,
-            },
+        const context = new Context(request);
+        const queryParams = new URLSearchParams(url.searchParams);
+        const upgraded = server.upgrade(request, {
+          data: {
+            path: url.pathname,
+            query: queryParams,
+            context,
+          },
+        });
+        if (upgraded) {
+          return undefined;
+        }
+        return new Response("WebSocket upgrade failed", { status: 400 });
+      }
+
+      this.activeRequests++;
+
+      const context = new Context(request);
+      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
           });
-          if (upgraded) {
-            return undefined;
-          }
-          return new Response("WebSocket upgrade failed", { status: 400 });
+      } else {
+        this.activeRequests--;
+        if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
+          this.shutdownResolve();
         }
+      }
 
-        // 增加活跃请求计数
-        this.activeRequests++;
-
-        const context = new Context(request);
-        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(() => {
-              // 错误已在中间件中处理，这里只负责计数
-            });
-        } else {
-          // 同步响应
-          this.activeRequests--;
-          if (this.isShuttingDown && this.activeRequests === 0 && this.shutdownResolve) {
-            this.shutdownResolve();
-          }
-        }
+      return responsePromise;
+    };
 
-        return responsePromise;
+    const websocketHandlers = {
+      open: async (ws: import("bun").ServerWebSocket<WebSocketConnectionData>) => {
+        await this.options.websocketRegistry?.handleOpen(ws);
       },
-      websocket: {
-        open: async (ws) => {
-          await this.options.websocketRegistry?.handleOpen(ws);
-        },
-        message: async (ws, message) => {
-          await this.options.websocketRegistry?.handleMessage(ws, message);
-        },
-        close: async (ws, code, reason) => {
-          await this.options.websocketRegistry?.handleClose(ws, code, reason);
-        },
+      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 socketFile = process.env.CLUSTER_SOCKET_FILE;
 
-    const hostname = this.options.hostname ?? "localhost";
-    const port = this.server.port;
-    logger.info(`Server started at http://${hostname}:${port}`);
+    if (socketFile) {
+      // Unix socket mode for cluster proxy workers
+      this.server = Bun.serve({
+        unix: socketFile,
+        fetch: fetchHandler,
+        websocket: websocketHandlers,
+      });
+      logger.info(`Server started at unix://${socketFile}`);
+    } else {
+      this.server = Bun.serve({
+        port: this.options.port ?? 3000,
+        hostname: this.options.hostname,
+        reusePort: this.options.reusePort,
+        fetch: fetchHandler,
+        websocket: websocketHandlers,
+      });
+      const hostname = this.options.hostname ?? "localhost";
+      const port = this.server.port;
+      logger.info(`Server started at http://${hostname}:${port}`);
+
+      // In proxy cluster mode (TCP fallback), report port to master
+      const portFile = process.env.CLUSTER_PORT_FILE;
+      if (portFile) {
+        Bun.write(portFile, String(port));
+      }
+    }
   }
 
   /**

package/src/embedding/embedding-module.ts

@@ -0,0 +1,52 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { EmbeddingService } from './service';
+import {
+  EMBEDDING_SERVICE_TOKEN,
+  EMBEDDING_OPTIONS_TOKEN,
+  type EmbeddingModuleOptions,
+} from './types';
+
+@Module({ providers: [] })
+export class EmbeddingModule {
+  /**
+   * Configure the embedding module.
+   *
+   * @example
+   * ```typescript
+   * EmbeddingModule.forRoot({
+   *   provider: {
+   *     name: 'openai',
+   *     provider: OpenAIEmbeddingProvider,
+   *     config: { apiKey: process.env.OPENAI_API_KEY! },
+   *   },
+   * });
+   * ```
+   */
+  public static forRoot(options: EmbeddingModuleOptions): typeof EmbeddingModule {
+    const service = new EmbeddingService(options);
+
+    const providers: ModuleProvider[] = [
+      { provide: EMBEDDING_OPTIONS_TOKEN, useValue: options },
+      { provide: EMBEDDING_SERVICE_TOKEN, useValue: service },
+      EmbeddingService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, EmbeddingModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        EMBEDDING_SERVICE_TOKEN,
+        EmbeddingService,
+      ],
+    }, EmbeddingModule);
+
+    return EmbeddingModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, EmbeddingModule);
+  }
+}

package/src/embedding/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './service';
+export * from './embedding-module';
+export * from './providers/openai-embedding-provider';
+export * from './providers/ollama-embedding-provider';

package/src/embedding/providers/ollama-embedding-provider.ts

@@ -0,0 +1,39 @@
+import type { EmbeddingProvider } from '../types';
+import { AiProviderError } from '../../ai/errors';
+
+export interface OllamaEmbeddingProviderConfig {
+  baseUrl?: string;
+  /** Default: nomic-embed-text */
+  model?: string;
+  /** Dimensions depend on model. Default 768 for nomic-embed-text */
+  dimensions?: number;
+}
+
+export class OllamaEmbeddingProvider implements EmbeddingProvider {
+  public readonly name = 'ollama';
+  public readonly dimensions: number;
+  private readonly baseUrl: string;
+  private readonly model: string;
+
+  public constructor(config: OllamaEmbeddingProviderConfig = {}) {
+    this.baseUrl = (config.baseUrl ?? 'http://localhost:11434').replace(/\/$/, '');
+    this.model = config.model ?? 'nomic-embed-text';
+    this.dimensions = config.dimensions ?? 768;
+  }
+
+  public async embed(text: string): Promise<number[]> {
+    const res = await fetch(`${this.baseUrl}/api/embed`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.model, input: text }),
+    });
+
+    if (!res.ok) throw new AiProviderError(await res.text(), 'ollama-embedding', res.status);
+    const data = await res.json() as { embeddings: number[][] };
+    return data.embeddings[0]!;
+  }
+
+  public async embedBatch(texts: string[]): Promise<number[][]> {
+    return Promise.all(texts.map((t) => this.embed(t)));
+  }
+}