@dangao/bun-server 1.12.0 → 2.0.0

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

@@ -0,0 +1,47 @@
+import type { EmbeddingProvider } from '../types';
+import { AiProviderError, AiRateLimitError } from '../../ai/errors';
+
+export interface OpenAIEmbeddingProviderConfig {
+  apiKey: string;
+  /** Default: text-embedding-3-small */
+  model?: string;
+  baseUrl?: string;
+}
+
+export class OpenAIEmbeddingProvider implements EmbeddingProvider {
+  public readonly name = 'openai';
+  public readonly dimensions: number;
+  private readonly apiKey: string;
+  private readonly model: string;
+  private readonly baseUrl: string;
+
+  public constructor(config: OpenAIEmbeddingProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.model = config.model ?? 'text-embedding-3-small';
+    this.baseUrl = (config.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+    // text-embedding-3-small: 1536, text-embedding-3-large: 3072
+    this.dimensions = this.model.includes('large') ? 3072 : 1536;
+  }
+
+  public async embed(text: string): Promise<number[]> {
+    const results = await this.embedBatch([text]);
+    return results[0]!;
+  }
+
+  public async embedBatch(texts: string[]): Promise<number[][]> {
+    const res = await fetch(`${this.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({ input: texts, model: this.model }),
+    });
+
+    if (res.status === 429) throw new AiRateLimitError('openai-embedding');
+    if (!res.ok) throw new AiProviderError(await res.text(), 'openai-embedding', res.status);
+
+    const data = await res.json() as { data: Array<{ embedding: number[] }> };
+    return data.data.map((d) => d.embedding);
+  }
+}

package/src/embedding/service.ts

@@ -0,0 +1,55 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type { EmbeddingProvider, EmbeddingModuleOptions } from './types';
+import { EMBEDDING_OPTIONS_TOKEN } from './types';
+
+/**
+ * Embedding service — generates vector embeddings for text using the configured provider.
+ */
+@Injectable()
+export class EmbeddingService {
+  private readonly provider: EmbeddingProvider;
+  private readonly batchSize: number;
+
+  public constructor(
+    @Inject(EMBEDDING_OPTIONS_TOKEN) options: EmbeddingModuleOptions,
+  ) {
+    this.provider = new options.provider.provider(options.provider.config);
+    this.batchSize = options.batchSize ?? 100;
+  }
+
+  /**
+   * Generate an embedding vector for a single text
+   */
+  public async embed(text: string): Promise<number[]> {
+    return this.provider.embed(text);
+  }
+
+  /**
+   * Generate embedding vectors for multiple texts.
+   * Automatically batches requests to stay within provider limits.
+   */
+  public async embedBatch(texts: string[]): Promise<number[][]> {
+    const results: number[][] = [];
+    for (let i = 0; i < texts.length; i += this.batchSize) {
+      const batch = texts.slice(i, i + this.batchSize);
+      const embeddings = await this.provider.embedBatch(batch);
+      results.push(...embeddings);
+    }
+    return results;
+  }
+
+  /**
+   * Number of dimensions in embeddings produced by this provider
+   */
+  public get dimensions(): number {
+    return this.provider.dimensions;
+  }
+
+  /**
+   * Provider name
+   */
+  public get providerName(): string {
+    return this.provider.name;
+  }
+}

package/src/embedding/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Abstract embedding provider interface
+ */
+export interface EmbeddingProvider {
+  /** Generate embedding vector for a single text */
+  embed(text: string): Promise<number[]>;
+  /** Generate embedding vectors for multiple texts (batch) */
+  embedBatch(texts: string[]): Promise<number[][]>;
+  /** Embedding dimensions */
+  readonly dimensions: number;
+  readonly name: string;
+}
+
+export interface EmbeddingProviderConfig<T = unknown> {
+  name: string;
+  provider: new (config: T) => EmbeddingProvider;
+  config: T;
+}
+
+export interface EmbeddingModuleOptions {
+  provider: EmbeddingProviderConfig;
+  /** Max texts per batch request (default: 100) */
+  batchSize?: number;
+}
+
+export const EMBEDDING_SERVICE_TOKEN = Symbol('@dangao/bun-server:embedding:service');
+export const EMBEDDING_OPTIONS_TOKEN = Symbol('@dangao/bun-server:embedding:options');

package/src/index.ts

@@ -1,7 +1,7 @@
 export { Application, type ApplicationOptions } from './core/application';
 export { applyDecorators } from './core/apply-decorators';
 export { BunServer, type ServerOptions } from './core/server';
-export { ClusterManager, type ClusterOptions } from './core/cluster';
+export { ClusterManager, type ClusterOptions, type ClusterMode } from './core/cluster';
 export { Context } from './core/context';
 export { ContextService, CONTEXT_SERVICE_TOKEN, contextStore } from './core/context-service';
 export { Route, Router, RouteRegistry } from './router';
@@ -562,3 +562,13 @@ export {
   type RegisteredListener,
 } from './events';
 
+// ── AI Modules (v2.0.0) ──────────────────────────────────────────────────────
+
+export * from './ai';
+export * from './conversation';
+export * from './prompt';
+export * from './embedding';
+export * from './vector-store';
+export * from './rag';
+export * from './mcp';
+export * from './ai-guard';

package/src/mcp/decorators.ts

@@ -0,0 +1,60 @@
+import type { McpToolDefinition, McpResourceDefinition } from './types';
+import { MCP_TOOL_METADATA_KEY, MCP_RESOURCE_METADATA_KEY } from './types';
+
+/**
+ * Mark a method as an MCP tool.
+ *
+ * @example
+ * ```typescript
+ * \@McpTool({
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a city',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { city: { type: 'string' } },
+ *     required: ['city'],
+ *   },
+ * })
+ * public async getWeather({ city }: { city: string }) {
+ *   return { temperature: 22, city };
+ * }
+ * ```
+ */
+export function McpTool(definition: McpToolDefinition): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(MCP_TOOL_METADATA_KEY, definition, target, propertyKey);
+  };
+}
+
+/**
+ * Mark a method as an MCP resource provider.
+ *
+ * @example
+ * ```typescript
+ * \@McpResource({
+ *   uri: 'user://{id}',
+ *   name: 'User Profile',
+ *   mimeType: 'application/json',
+ * })
+ * public async getUserResource(\@McpParam('id') id: string) {
+ *   return this.userService.find(id);
+ * }
+ * ```
+ */
+export function McpResource(definition: McpResourceDefinition): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(MCP_RESOURCE_METADATA_KEY, definition, target, propertyKey);
+  };
+}
+
+/**
+ * Extract a named parameter from MCP tool input arguments.
+ */
+export function McpParam(name: string): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    const existing: Array<{ index: number; name: string }> =
+      Reflect.getMetadata('mcp:params', target, propertyKey!) ?? [];
+    existing.push({ index: parameterIndex, name });
+    Reflect.defineMetadata('mcp:params', existing, target, propertyKey!);
+  };
+}

package/src/mcp/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './decorators';
+export * from './registry';
+export * from './server';
+export * from './mcp-module';

package/src/mcp/mcp-module.ts

@@ -0,0 +1,58 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { McpServer } from './server';
+import { McpRegistry } from './registry';
+import { MCP_SERVER_TOKEN, MCP_OPTIONS_TOKEN, type McpModuleOptions } from './types';
+
+@Module({ providers: [] })
+export class McpModule {
+  /**
+   * Configure the MCP module.
+   *
+   * @example
+   * ```typescript
+   * McpModule.forRoot({
+   *   transport: 'sse',
+   *   path: '/mcp',
+   *   serverInfo: { name: 'my-api', version: '1.0.0' },
+   * });
+   *
+   * // Register tools by scanning instances:
+   * const registry = container.resolve<McpRegistry>(MCP_SERVER_TOKEN);
+   * registry.scan(myServiceInstance);
+   * ```
+   */
+  public static forRoot(options: McpModuleOptions): typeof McpModule {
+    const registry = new McpRegistry();
+    const server = new McpServer(registry, options.serverInfo);
+
+    const resolvedOptions: McpModuleOptions = {
+      transport: 'sse',
+      path: '/mcp',
+      ...options,
+    };
+
+    const providers: ModuleProvider[] = [
+      { provide: MCP_OPTIONS_TOKEN, useValue: resolvedOptions },
+      { provide: MCP_SERVER_TOKEN, useValue: server },
+      { provide: McpRegistry, useValue: registry },
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, McpModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        MCP_SERVER_TOKEN,
+        McpRegistry,
+      ],
+    }, McpModule);
+
+    return McpModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, McpModule);
+  }
+}

package/src/mcp/registry.ts

@@ -0,0 +1,72 @@
+import type { McpToolDefinition, McpResourceDefinition } from './types';
+import { MCP_TOOL_METADATA_KEY, MCP_RESOURCE_METADATA_KEY } from './types';
+
+export interface RegisteredMcpTool extends McpToolDefinition {
+  execute(args: Record<string, unknown>): Promise<unknown>;
+}
+
+export interface RegisteredMcpResource extends McpResourceDefinition {
+  read(uriParams: Record<string, string>): Promise<unknown>;
+}
+
+/**
+ * Registry for MCP tools and resources discovered via decorators.
+ */
+export class McpRegistry {
+  private readonly tools = new Map<string, RegisteredMcpTool>();
+  private readonly resources = new Map<string, RegisteredMcpResource>();
+
+  /**
+   * Scan an object instance for @McpTool() and @McpResource() decorated methods
+   */
+  public scan(instance: object): void {
+    const proto = Object.getPrototypeOf(instance);
+    const methodNames = Object.getOwnPropertyNames(proto).filter(
+      (key) => key !== 'constructor',
+    );
+
+    for (const methodName of methodNames) {
+      const toolDef: McpToolDefinition | undefined = Reflect.getMetadata(
+        MCP_TOOL_METADATA_KEY,
+        proto,
+        methodName,
+      );
+      if (toolDef) {
+        const method = (instance as Record<string, unknown>)[methodName] as (args: unknown) => Promise<unknown>;
+        this.tools.set(toolDef.name, {
+          ...toolDef,
+          execute: (args) => method.call(instance, args),
+        });
+      }
+
+      const resourceDef: McpResourceDefinition | undefined = Reflect.getMetadata(
+        MCP_RESOURCE_METADATA_KEY,
+        proto,
+        methodName,
+      );
+      if (resourceDef) {
+        const method = (instance as Record<string, unknown>)[methodName] as (params: unknown) => Promise<unknown>;
+        this.resources.set(resourceDef.uri, {
+          ...resourceDef,
+          read: (params) => method.call(instance, params),
+        });
+      }
+    }
+  }
+
+  public getTools(): RegisteredMcpTool[] {
+    return Array.from(this.tools.values());
+  }
+
+  public getResources(): RegisteredMcpResource[] {
+    return Array.from(this.resources.values());
+  }
+
+  public getTool(name: string): RegisteredMcpTool | undefined {
+    return this.tools.get(name);
+  }
+
+  public getResource(uri: string): RegisteredMcpResource | undefined {
+    return this.resources.get(uri);
+  }
+}

package/src/mcp/server.ts

@@ -0,0 +1,164 @@
+import type { McpServerInfo, JsonRpcRequest, JsonRpcResponse } from './types';
+import type { McpRegistry } from './registry';
+
+/**
+ * MCP protocol server — handles JSON-RPC 2.0 requests from MCP clients.
+ * Supports SSE transport (HTTP) and stdio transport.
+ *
+ * Implements MCP specification 2024-11-05.
+ */
+export class McpServer {
+  private readonly registry: McpRegistry;
+  private readonly serverInfo: McpServerInfo;
+
+  public constructor(registry: McpRegistry, serverInfo: McpServerInfo) {
+    this.registry = registry;
+    this.serverInfo = serverInfo;
+  }
+
+  /**
+   * Handle an incoming JSON-RPC request and return a response
+   */
+  public async handle(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    try {
+      const result = await this.dispatch(request.method, request.params);
+      return { jsonrpc: '2.0', id: request.id ?? null, result };
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id: request.id ?? null,
+        error: {
+          code: err instanceof McpError ? err.code : -32603,
+          message: err instanceof Error ? err.message : 'Internal error',
+        },
+      };
+    }
+  }
+
+  /**
+   * Handle a raw HTTP request body (JSON-RPC over HTTP)
+   * Returns a Response suitable for Bun's serve()
+   */
+  public async handleHttp(req: Request): Promise<Response> {
+    const body = await req.json() as JsonRpcRequest;
+    const response = await this.handle(body);
+    return new Response(JSON.stringify(response), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  /**
+   * Create an SSE response that keeps the connection open for streaming
+   * This is the SSE transport endpoint
+   */
+  public createSseResponse(): Response {
+    const registry = this.registry;
+    const serverInfo = this.serverInfo;
+    const encoder = new TextEncoder();
+
+    const stream = new ReadableStream({
+      start(controller) {
+        // Send initial server info event
+        const initEvent = `event: endpoint\ndata: ${JSON.stringify({
+          type: 'endpoint',
+          method: 'POST',
+        })}\n\n`;
+        controller.enqueue(encoder.encode(initEvent));
+
+        // Keep connection alive with periodic pings
+        const pingInterval = setInterval(() => {
+          try {
+            controller.enqueue(encoder.encode(': ping\n\n'));
+          } catch {
+            clearInterval(pingInterval);
+          }
+        }, 15000);
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-MCP-Server': `${serverInfo.name}/${serverInfo.version}`,
+      },
+    });
+  }
+
+  private async dispatch(method: string, params: unknown): Promise<unknown> {
+    switch (method) {
+      case 'initialize':
+        return {
+          protocolVersion: '2024-11-05',
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: this.serverInfo,
+        };
+
+      case 'tools/list':
+        return {
+          tools: this.registry.getTools().map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        };
+
+      case 'tools/call': {
+        const { name, arguments: args = {} } = params as { name: string; arguments?: Record<string, unknown> };
+        const tool = this.registry.getTool(name);
+        if (!tool) throw new McpError(-32601, `Tool "${name}" not found`);
+        const result = await tool.execute(args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'resources/list':
+        return {
+          resources: this.registry.getResources().map((r) => ({
+            uri: r.uri,
+            name: r.name,
+            description: r.description,
+            mimeType: r.mimeType,
+          })),
+        };
+
+      case 'resources/read': {
+        const { uri } = params as { uri: string };
+        const resource = this.registry.getResource(uri);
+        if (!resource) throw new McpError(-32601, `Resource "${uri}" not found`);
+        const content = await resource.read({});
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: resource.mimeType ?? 'application/json',
+              text: typeof content === 'string' ? content : JSON.stringify(content),
+            },
+          ],
+        };
+      }
+
+      case 'ping':
+        return {};
+
+      default:
+        throw new McpError(-32601, `Method "${method}" not found`);
+    }
+  }
+}
+
+class McpError extends Error {
+  public constructor(
+    public readonly code: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}

package/src/mcp/types.ts

@@ -0,0 +1,63 @@
+/**
+ * MCP tool definition
+ */
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/**
+ * MCP resource definition
+ */
+export interface McpResourceDefinition {
+  uri: string;
+  name: string;
+  description?: string;
+  mimeType?: string;
+}
+
+/**
+ * MCP server info
+ */
+export interface McpServerInfo {
+  name: string;
+  version: string;
+  description?: string;
+}
+
+/**
+ * MCP transport type
+ */
+export type McpTransport = 'sse' | 'stdio';
+
+export interface McpModuleOptions {
+  transport?: McpTransport;
+  /** Path for SSE endpoint (default: '/mcp') */
+  path?: string;
+  serverInfo: McpServerInfo;
+}
+
+export const MCP_SERVER_TOKEN = Symbol('@dangao/bun-server:mcp:server');
+export const MCP_OPTIONS_TOKEN = Symbol('@dangao/bun-server:mcp:options');
+
+/** Metadata key for @McpTool() */
+export const MCP_TOOL_METADATA_KEY = '@dangao/bun-server:mcp:tool';
+/** Metadata key for @McpResource() */
+export const MCP_RESOURCE_METADATA_KEY = '@dangao/bun-server:mcp:resource';
+
+/** JSON-RPC 2.0 Request */
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  method: string;
+  params?: unknown;
+}
+
+/** JSON-RPC 2.0 Response */
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}

package/src/prompt/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './service';
+export * from './prompt-module';
+export * from './stores/memory-store';
+export * from './stores/file-store';

package/src/prompt/prompt-module.ts

@@ -0,0 +1,61 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { PromptService } from './service';
+import {
+  PROMPT_SERVICE_TOKEN,
+  PROMPT_OPTIONS_TOKEN,
+  type PromptModuleOptions,
+} from './types';
+import { InMemoryPromptStore } from './stores/memory-store';
+
+@Module({ providers: [] })
+export class PromptModule {
+  /**
+   * Configure the prompt module.
+   *
+   * @example
+   * ```typescript
+   * // With in-memory store (default):
+   * PromptModule.forRoot({});
+   *
+   * // With file store:
+   * PromptModule.forRoot({
+   *   store: new FilePromptStore({ promptsDir: './.prompts' }),
+   * });
+   * ```
+   */
+  public static forRoot(options: PromptModuleOptions = {}): typeof PromptModule {
+    const resolvedOptions: PromptModuleOptions = {
+      ...options,
+      store: options.store ?? new InMemoryPromptStore(),
+    };
+
+    const service = new PromptService(resolvedOptions as Required<PromptModuleOptions>);
+
+    const providers: ModuleProvider[] = [
+      { provide: PROMPT_OPTIONS_TOKEN, useValue: resolvedOptions },
+      { provide: PROMPT_SERVICE_TOKEN, useValue: service },
+      PromptService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, PromptModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        PROMPT_SERVICE_TOKEN,
+        PromptService,
+      ],
+    }, PromptModule);
+
+    return PromptModule;
+  }
+
+  /**
+   * Reset module state (for testing)
+   */
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, PromptModule);
+  }
+}