@dangao/bun-server 1.0.1 → 1.1.2

package/src/metrics/types.ts

@@ -0,0 +1,103 @@
+/**
+ * 指标类型
+ */
+export type MetricType = 'counter' | 'gauge' | 'histogram' | 'summary';
+
+/**
+ * 指标标签
+ */
+export type MetricLabels = Record<string, string>;
+
+/**
+ * 指标值
+ */
+export type MetricValue = number;
+
+/**
+ * 指标数据点
+ */
+export interface MetricDataPoint {
+  /**
+   * 指标名称
+   */
+  name: string;
+
+  /**
+   * 指标类型
+   */
+  type: MetricType;
+
+  /**
+   * 指标值
+   */
+  value: MetricValue;
+
+  /**
+   * 标签
+   */
+  labels?: MetricLabels;
+
+  /**
+   * 帮助文本
+   */
+  help?: string;
+}
+
+/**
+ * 自定义指标
+ */
+export interface CustomMetric {
+  /**
+   * 指标名称
+   */
+  name: string;
+
+  /**
+   * 指标类型
+   */
+  type: MetricType;
+
+  /**
+   * 帮助文本
+   */
+  help?: string;
+
+  /**
+   * 获取当前值
+   * @param labels - 标签
+   * @returns 指标值
+   */
+  getValue(labels?: MetricLabels): MetricValue | Promise<MetricValue>;
+}
+
+/**
+ * MetricsModule 配置选项
+ */
+export interface MetricsModuleOptions {
+  /**
+   * 是否启用 HTTP 请求指标收集
+   * @default true
+   */
+  enableHttpMetrics?: boolean;
+
+  /**
+   * 自定义指标列表
+   */
+  customMetrics?: CustomMetric[];
+
+  /**
+   * Metrics 端点路径
+   * @default '/metrics'
+   */
+  path?: string;
+}
+
+/**
+ * Metrics 服务 Token
+ */
+export const METRICS_SERVICE_TOKEN = Symbol('@dangao/bun-server:metrics:service');
+
+/**
+ * Metrics 选项 Token
+ */
+export const METRICS_OPTIONS_TOKEN = Symbol('@dangao/bun-server:metrics:options');

package/src/middleware/builtin/cors.ts

@@ -0,0 +1,60 @@
+import type { Middleware } from '../middleware';
+
+export interface CorsOptions {
+  origin?: string | string[] | '*';
+  methods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+
+function getOriginHeader(option: CorsOptions['origin'], requestOrigin: string | null): string {
+  if (!option || option === '*') {
+    return '*';
+  }
+
+  if (Array.isArray(option)) {
+    if (requestOrigin && option.includes(requestOrigin)) {
+      return requestOrigin;
+    }
+    return option[0];
+  }
+
+  return option;
+}
+
+/**
+ * CORS 中间件
+ */
+export function createCorsMiddleware(options: CorsOptions = {}): Middleware {
+  const methods = options.methods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+  const allowedHeaders = options.allowedHeaders ?? ['Content-Type', 'Authorization'];
+  const exposedHeaders = options.exposedHeaders ?? [];
+  const credentials = options.credentials ?? true;
+  const maxAge = options.maxAge ?? 600;
+
+  return async (context, next) => {
+    const requestOrigin = context.getHeader('Origin');
+    const originHeader = getOriginHeader(options.origin ?? '*', requestOrigin);
+
+    context.setHeader('Access-Control-Allow-Origin', originHeader);
+    if (credentials) {
+      context.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+    context.setHeader('Access-Control-Allow-Methods', methods.join(','));
+    context.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(','));
+    if (exposedHeaders.length > 0) {
+      context.setHeader('Access-Control-Expose-Headers', exposedHeaders.join(','));
+    }
+    context.setHeader('Access-Control-Max-Age', maxAge.toString());
+
+    if (context.method === 'OPTIONS') {
+      return new Response(null, { status: 204, headers: context.responseHeaders });
+    }
+
+    return await next();
+  };
+}
+
+

package/src/middleware/builtin/error-handler.ts

@@ -0,0 +1,90 @@
+import type { Middleware } from "../middleware";
+import { ValidationError } from "../../validation";
+import { LoggerManager } from "@dangao/logsmith";
+import { HttpException } from "../../error";
+import { handleError } from "../../error/handler";
+import { ErrorMessageI18n } from "../../error/i18n";
+
+export interface ErrorHandlerOptions {
+  /**
+   * 自定义错误日志函数
+   */
+  logger?: (error: unknown, context: { method: string; path: string }) => void;
+
+  /**
+   * 是否返回详细错误信息（默认 false，用于生产环境隐藏细节）
+   */
+  exposeError?: boolean;
+
+  /**
+   * 默认状态码
+   */
+  statusCode?: number;
+}
+
+/**
+ * 错误处理中间件：捕获下游异常并统一生成响应
+ */
+export function createErrorHandlingMiddleware(
+  options: ErrorHandlerOptions = {},
+): Middleware {
+  const log = options.logger ??
+    ((error: unknown, context: { method: string; path: string }) => {
+      LoggerManager.getLogger().error("[Error]", { ...context, error });
+    });
+  const expose = options.exposeError ?? false;
+  const defaultStatus = options.statusCode ?? 500;
+
+  return async (context, next) => {
+    const logger = LoggerManager.getLogger();
+
+    try {
+      return await next();
+    } catch (error) {
+      log(error, { method: context.method, path: context.path });
+      logger.error("Unhandled error", {
+        method: context.method,
+        path: context.path,
+        error,
+      });
+
+      if (error instanceof Response) {
+        return error as Response;
+      }
+
+      if (error instanceof ValidationError) {
+        return context.createResponse(
+          {
+            error: error.message,
+            issues: error.issues,
+          },
+          {
+            status: 400,
+          },
+        );
+      }
+
+      if (error instanceof HttpException) {
+        // 统一使用 handleError 处理，它已经包含了错误码和国际化逻辑
+          return await handleError(error, context);
+      }
+
+      if (error instanceof Error && !expose) {
+        return await handleError(error, context);
+      }
+
+      if (error instanceof Error) {
+        return context.createResponse(
+          {
+            error: error.message,
+          },
+          {
+            status: defaultStatus,
+          },
+        );
+      }
+
+      return await handleError(error, context);
+    }
+  };
+}

package/src/middleware/builtin/file-upload.ts

@@ -0,0 +1,42 @@
+import type { Middleware } from '../middleware';
+import { FileHandler } from '../../request/file-handler';
+
+export interface FileUploadOptions {
+  maxSize?: number;
+}
+
+/**
+ * 简单的文件上传中间件：解析 multipart/form-data 并将文件附加到 context.body
+ */
+export function createFileUploadMiddleware(options: FileUploadOptions = {}): Middleware {
+  const maxSize = options.maxSize ?? 10 * 1024 * 1024;
+
+  return async (context, next) => {
+    const contentType = context.getHeader('Content-Type');
+    if (!contentType || !contentType.includes('multipart/form-data')) {
+      return await next();
+    }
+
+    const formData = await FileHandler.parseFormData(context);
+    const files = await FileHandler.getFiles(formData);
+
+    // 限制大小
+    for (const fileList of Object.values(files)) {
+      for (const file of fileList) {
+        if (file.size > maxSize) {
+          context.setStatus(413);
+          return context.createResponse({ error: `File ${file.name} exceeds max size` });
+        }
+      }
+    }
+
+    context.body = {
+      fields: Object.fromEntries(formData.entries()),
+      files,
+    };
+
+    return await next();
+  };
+}
+
+

package/src/middleware/builtin/index.ts

@@ -0,0 +1,14 @@
+export { createLoggerMiddleware, createRequestLoggingMiddleware } from './logger';
+export { createErrorHandlingMiddleware } from './error-handler';
+export { createCorsMiddleware } from './cors';
+export { createFileUploadMiddleware } from './file-upload';
+export { createStaticFileMiddleware } from './static-file';
+export {
+  createRateLimitMiddleware,
+  createTokenKeyGenerator,
+  createUserKeyGenerator,
+  type RateLimitOptions,
+  type RateLimitStore,
+} from './rate-limit';
+
+

package/src/middleware/builtin/logger.ts

@@ -0,0 +1,91 @@
+import type { Middleware } from "../middleware";
+import { LoggerManager } from "@dangao/logsmith";
+
+export interface LoggerMiddlewareOptions {
+  /**
+   * 自定义日志函数
+   */
+  logger?: (message: string, details?: Record<string, unknown>) => void;
+
+  /**
+   * 日志前缀
+   */
+  prefix?: string;
+}
+
+/**
+ * 简单日志中间件：记录请求方法与路径
+ */
+export function createLoggerMiddleware(
+  options: LoggerMiddlewareOptions = {},
+): Middleware {
+  const log = options.logger ??
+    ((message: string, details?: Record<string, unknown>) => {
+      const logger = LoggerManager.getLogger();
+      if (details) {
+        logger.info(message, details);
+      } else {
+        logger.info(message);
+      }
+    });
+  const prefix = options.prefix ?? "[Logger]";
+
+  return async (context, next) => {
+    let response: Response | undefined;
+    try {
+      response = await next();
+      return response;
+    } finally {
+      const status = response?.status ?? context.statusCode ?? 200;
+      log(`${prefix} ${context.method} ${context.path} ${status}`);
+    }
+  };
+}
+
+export interface RequestLoggingOptions extends LoggerMiddlewareOptions {
+  /**
+   * 是否在响应头中附加请求耗时
+   */
+  setHeader?: boolean;
+}
+
+/**
+ * 请求日志中间件：记录耗时与状态码
+ */
+export function createRequestLoggingMiddleware(
+  options: RequestLoggingOptions = {},
+): Middleware {
+  const log = options.logger ??
+    ((message: string, details?: Record<string, unknown>) => {
+      const logger = LoggerManager.getLogger();
+      logger.info(message, details);
+    });
+  const prefix = options.prefix ?? "[Request]";
+  const setHeader = options.setHeader ?? true;
+
+  return async (context, next) => {
+    const start = performance.now();
+    try {
+      const response = await next();
+      const duration = performance.now() - start;
+      log(
+        `${prefix} ${context.method} ${context.path} ${response.status} ${
+          duration.toFixed(2)
+        }ms`,
+      );
+      if (setHeader) {
+        context.setHeader("x-request-duration", duration.toFixed(2));
+      }
+      return response;
+    } catch (error) {
+      const duration = performance.now() - start;
+      log(
+        `${prefix} ${context.method} ${context.path} error ${
+          duration.toFixed(2)
+        }ms`,
+        error instanceof Error ? { error: error.message } : undefined,
+      );
+      throw error;
+    }
+  };
+}

package/src/middleware/builtin/rate-limit.ts

@@ -0,0 +1,252 @@
+import type { Context } from '../../core/context';
+import type { Middleware } from '../middleware';
+
+/**
+ * 速率限制存储接口
+ */
+export interface RateLimitStore {
+  /**
+   * 获取当前计数
+   * @param key - 存储键
+   * @returns 当前计数
+   */
+  get(key: string): Promise<number>;
+
+  /**
+   * 增加计数
+   * @param key - 存储键
+   * @param windowMs - 时间窗口（毫秒）
+   * @returns 增加后的计数
+   */
+  increment(key: string, windowMs: number): Promise<number>;
+
+  /**
+   * 重置计数
+   * @param key - 存储键
+   */
+  reset(key: string): Promise<void>;
+}
+
+/**
+ * 内存存储实现（使用 Map）
+ */
+export class MemoryRateLimitStore implements RateLimitStore {
+  private store: Map<string, { count: number; resetTime: number }> = new Map();
+
+  public async get(key: string): Promise<number> {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return 0;
+    }
+
+    // 如果已过期，返回 0
+    if (Date.now() > entry.resetTime) {
+      this.store.delete(key);
+      return 0;
+    }
+
+    return entry.count;
+  }
+
+  public async increment(key: string, windowMs: number): Promise<number> {
+    const now = Date.now();
+    const entry = this.store.get(key);
+
+    if (!entry || now > entry.resetTime) {
+      // 创建新条目或重置过期条目
+      const resetTime = now + windowMs;
+      this.store.set(key, { count: 1, resetTime });
+      return 1;
+    }
+
+    // 增加计数
+    entry.count++;
+    return entry.count;
+  }
+
+  public async reset(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  /**
+   * 清理过期条目（可选，用于内存管理）
+   */
+  public cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.resetTime) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+/**
+ * 速率限制选项
+ */
+export interface RateLimitOptions {
+  /**
+   * 时间窗口内的最大请求数
+   */
+  max: number;
+
+  /**
+   * 时间窗口（毫秒）
+   * @default 60000 (1 分钟)
+   */
+  windowMs?: number;
+
+  /**
+   * 存储实现（默认使用内存存储）
+   */
+  store?: RateLimitStore;
+
+  /**
+   * 获取限流键的函数
+   * @param context - 请求上下文
+   * @returns 限流键
+   */
+  keyGenerator?: (context: Context) => string | Promise<string>;
+
+  /**
+   * 是否跳过成功响应（只对错误响应计数）
+   * @default false
+   */
+  skipSuccessfulRequests?: boolean;
+
+  /**
+   * 是否跳过失败响应（只对成功响应计数）
+   * @default false
+   */
+  skipFailedRequests?: boolean;
+
+  /**
+   * 自定义错误消息
+   */
+  message?: string;
+
+  /**
+   * 自定义错误状态码
+   * @default 429
+   */
+  statusCode?: number;
+
+  /**
+   * 是否在响应头中包含限流信息
+   * @default true
+   */
+  standardHeaders?: boolean;
+
+  /**
+   * 是否启用 X-RateLimit-* 响应头
+   * @default true
+   */
+  legacyHeaders?: boolean;
+}
+
+/**
+ * 默认键生成器：基于 IP 地址
+ */
+function defaultKeyGenerator(context: Context): string {
+  return `rate-limit:${context.getClientIp()}`;
+}
+
+/**
+ * 创建速率限制中间件
+ */
+export function createRateLimitMiddleware(options: RateLimitOptions): Middleware {
+  const {
+    max,
+    windowMs = 60000, // 默认 1 分钟
+    store = new MemoryRateLimitStore(),
+    keyGenerator = defaultKeyGenerator,
+    skipSuccessfulRequests = false,
+    skipFailedRequests = false,
+    message = 'Too Many Requests',
+    statusCode = 429,
+    standardHeaders = true,
+    legacyHeaders = true,
+  } = options;
+
+  return async (context: Context, next) => {
+    // 生成限流键
+    const key = await keyGenerator(context);
+    const currentCount = await store.increment(key, windowMs);
+
+    // 计算剩余请求数和重置时间
+    const remaining = Math.max(0, max - currentCount);
+    const resetTime = Date.now() + windowMs;
+
+    // 设置响应头
+    if (standardHeaders) {
+      context.setHeader('RateLimit-Limit', max.toString());
+      context.setHeader('RateLimit-Remaining', remaining.toString());
+      context.setHeader('RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
+    }
+
+    if (legacyHeaders) {
+      context.setHeader('X-RateLimit-Limit', max.toString());
+      context.setHeader('X-RateLimit-Remaining', remaining.toString());
+      context.setHeader('X-RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
+    }
+
+    // 检查是否超过限制
+    if (currentCount > max) {
+      context.setStatus(statusCode);
+      return context.createResponse({
+        error: message,
+        retryAfter: Math.ceil(windowMs / 1000),
+      });
+    }
+
+    // 执行下一个中间件或路由处理器
+    const response = await next();
+
+    // 根据选项决定是否计数
+    const shouldSkip =
+      (skipSuccessfulRequests && response.status >= 200 && response.status < 300) ||
+      (skipFailedRequests && response.status >= 400);
+
+    if (shouldSkip) {
+      // 如果跳过，需要减少计数（因为之前已经增加了）
+      const current = await store.get(key);
+      if (current > 0) {
+        // 注意：这里不能直接减少，因为滑动窗口算法不支持
+        // 所以这个选项在滑动窗口算法下效果有限
+        // 更好的做法是在请求成功后不增加计数，但这需要重构
+      }
+    }
+
+    return response;
+  };
+}
+
+/**
+ * 基于 Token/User 的键生成器
+ */
+export function createTokenKeyGenerator(tokenHeader: string = 'Authorization'): (context: Context) => string {
+  return (context: Context) => {
+    const token = context.getHeader(tokenHeader);
+    if (token) {
+      // 提取 token（可能包含 Bearer 前缀）
+      const tokenValue = token.startsWith('Bearer ') ? token.substring(7) : token;
+      return `rate-limit:token:${tokenValue}`;
+    }
+    // 如果没有 token，回退到 IP
+    return defaultKeyGenerator(context);
+  };
+}
+
+/**
+ * 基于用户 ID 的键生成器（需要从认证上下文获取）
+ */
+export function createUserKeyGenerator(getUserId: (context: Context) => string | null | undefined): (context: Context) => string {
+  return (context: Context) => {
+    const userId = getUserId(context);
+    if (userId) {
+      return `rate-limit:user:${userId}`;
+    }
+    // 如果没有用户 ID，回退到 IP
+    return defaultKeyGenerator(context);
+  };
+}