@dangao/bun-server 1.0.0 → 1.0.3

package/src/metrics/metrics-module.ts

@@ -0,0 +1,58 @@
+import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+
+import { MetricsController } from './controller';
+import { MetricsCollector } from './collector';
+import type { MetricsModuleOptions } from './types';
+import { METRICS_SERVICE_TOKEN, METRICS_OPTIONS_TOKEN } from './types';
+
+@Module({
+  controllers: [MetricsController],
+  providers: [],
+})
+export class MetricsModule {
+  /**
+   * 创建指标监控模块
+   * @param options - 模块配置
+   */
+  public static forRoot(options: MetricsModuleOptions = {}): typeof MetricsModule {
+    const providers: ModuleProvider[] = [];
+
+    const collector = new MetricsCollector();
+
+    // 注册自定义指标
+    if (options.customMetrics) {
+      for (const metric of options.customMetrics) {
+        collector.registerCustomMetric(metric);
+      }
+    }
+
+    providers.push(
+      {
+        provide: METRICS_SERVICE_TOKEN,
+        useValue: collector,
+      },
+      {
+        provide: METRICS_OPTIONS_TOKEN,
+        useValue: options,
+      },
+      MetricsCollector,
+    );
+
+    // 动态更新模块元数据
+    const existingMetadata =
+      Reflect.getMetadata(MODULE_METADATA_KEY, MetricsModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      controllers: [...(existingMetadata.controllers || []), MetricsController],
+      providers: [...(existingMetadata.providers || []), ...providers],
+      exports: [
+        ...(existingMetadata.exports || []),
+        METRICS_SERVICE_TOKEN,
+        MetricsCollector,
+      ],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, MetricsModule);
+
+    return MetricsModule;
+  }
+}

package/src/metrics/middleware.ts

@@ -0,0 +1,46 @@
+import type { Context } from '../core/context';
+import type { Middleware } from '../middleware';
+import { MetricsCollector } from './collector';
+
+/**
+ * 创建 HTTP 请求指标收集中间件
+ */
+export function createHttpMetricsMiddleware(collector: MetricsCollector): Middleware {
+  return async (context: Context, next) => {
+    const startTime = Date.now();
+
+    // 执行请求
+    const response = await next();
+
+    // 计算延迟
+    const duration = Date.now() - startTime;
+    const durationSeconds = duration / 1000;
+
+    // 收集请求指标
+    const method = context.method;
+    const path = context.path;
+    const statusCode = response.status;
+
+    // HTTP 请求总数（计数器）
+    collector.incrementCounter('http_requests_total', {
+      method,
+      path,
+      status: statusCode.toString(),
+    });
+
+    // HTTP 请求延迟（直方图）
+    collector.observeHistogram('http_request_duration_seconds', {
+      method,
+      path,
+      status: statusCode.toString(),
+    }, durationSeconds);
+
+    // HTTP 请求延迟（摘要，用于 p50, p95, p99）
+    collector.observeHistogram('http_request_duration_seconds_summary', {
+      method,
+      path,
+    }, durationSeconds);
+
+    return response;
+  };
+}

package/src/metrics/prometheus.ts

@@ -0,0 +1,79 @@
+import type { MetricDataPoint } from './types';
+
+/**
+ * 将指标数据点转换为 Prometheus 格式
+ */
+export class PrometheusFormatter {
+  /**
+   * 格式化指标为 Prometheus 文本格式
+   */
+  public format(dataPoints: MetricDataPoint[]): string {
+    const lines: string[] = [];
+    const metricGroups = this.groupByMetricName(dataPoints);
+
+    for (const [metricName, points] of metricGroups.entries()) {
+      // 添加帮助文本（如果有）
+      const help = points[0]?.help;
+      if (help) {
+        lines.push(`# HELP ${metricName} ${help}`);
+      }
+
+      // 添加类型（如果有）
+      const type = points[0]?.type;
+      if (type) {
+        lines.push(`# TYPE ${metricName} ${type}`);
+      }
+
+      // 添加数据点
+      for (const point of points) {
+        const labelString = this.formatLabels(point.labels);
+        const line = labelString
+          ? `${point.name}${labelString} ${point.value}`
+          : `${point.name} ${point.value}`;
+        lines.push(line);
+      }
+
+      lines.push(''); // 空行分隔
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 按指标名称分组
+   */
+  private groupByMetricName(dataPoints: MetricDataPoint[]): Map<string, MetricDataPoint[]> {
+    const groups = new Map<string, MetricDataPoint[]>();
+
+    for (const point of dataPoints) {
+      const name = point.name;
+      const existing = groups.get(name) || [];
+      existing.push(point);
+      groups.set(name, existing);
+    }
+
+    return groups;
+  }
+
+  /**
+   * 格式化标签
+   */
+  private formatLabels(labels?: Record<string, string>): string {
+    if (!labels || Object.keys(labels).length === 0) {
+      return '';
+    }
+
+    const labelPairs = Object.keys(labels)
+      .sort()
+      .map((key) => `${key}="${this.escapeLabelValue(labels[key])}"`)
+      .join(',');
+    return `{${labelPairs}}`;
+  }
+
+  /**
+   * 转义标签值
+   */
+  private escapeLabelValue(value: string): string {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+  }
+}

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;
+    }
+  };
+}