@dangao/bun-server 1.0.1 → 1.1.2

package/src/interceptor/interceptor-registry.ts

@@ -0,0 +1,132 @@
+import type { Interceptor, InterceptorMetadata } from './types';
+import { INTERCEPTOR_REGISTRY_TOKEN } from './types';
+
+/**
+ * 拦截器注册表
+ * 管理所有注册的拦截器，支持按优先级排序
+ */
+export class InterceptorRegistry {
+  /**
+   * 拦截器存储
+   * key: 元数据键（Symbol）
+   * value: 拦截器元数据列表
+   */
+  private readonly interceptors = new Map<symbol, InterceptorMetadata[]>();
+
+  /**
+   * 注册拦截器
+   * @param metadataKey - 元数据键（用于匹配装饰器）
+   * @param interceptor - 拦截器实例
+   * @param priority - 优先级（数字越小优先级越高，默认 100）
+   */
+  public register(
+    metadataKey: symbol,
+    interceptor: Interceptor,
+    priority: number = 100,
+  ): void {
+    if (!this.interceptors.has(metadataKey)) {
+      this.interceptors.set(metadataKey, []);
+    }
+
+    const metadataList = this.interceptors.get(metadataKey)!;
+    
+    // 检查是否已注册相同的拦截器
+    const exists = metadataList.some(
+      (meta) => meta.interceptor === interceptor,
+    );
+    
+    if (!exists) {
+      metadataList.push({
+        metadataKey,
+        interceptor,
+        priority,
+      });
+      
+      // 按优先级排序（数字越小优先级越高）
+      metadataList.sort((a, b) => a.priority - b.priority);
+    }
+  }
+
+  /**
+   * 获取拦截器元数据列表（按优先级排序）
+   * @param metadataKey - 元数据键
+   * @returns 拦截器元数据列表
+   */
+  public getInterceptorMetadata(metadataKey: symbol): InterceptorMetadata[] {
+    const metadataList = this.interceptors.get(metadataKey);
+    if (!metadataList || metadataList.length === 0) {
+      return [];
+    }
+    
+    // 返回已排序的拦截器元数据列表（包括优先级信息）
+    return [...metadataList];
+  }
+
+  /**
+   * 获取拦截器列表（按优先级排序）
+   * @param metadataKey - 元数据键
+   * @returns 拦截器列表
+   */
+  public getInterceptors(metadataKey: symbol): Interceptor[] {
+    const metadataList = this.interceptors.get(metadataKey);
+    if (!metadataList || metadataList.length === 0) {
+      return [];
+    }
+    
+    // 返回已排序的拦截器列表
+    return metadataList.map((meta) => meta.interceptor);
+  }
+
+  /**
+   * 检查是否有拦截器
+   * @param metadataKey - 元数据键
+   * @returns 是否有拦截器
+   */
+  public hasInterceptor(metadataKey: symbol): boolean {
+    const metadataList = this.interceptors.get(metadataKey);
+    return metadataList !== undefined && metadataList.length > 0;
+  }
+
+  /**
+   * 获取所有已注册的元数据键
+   * @returns 元数据键迭代器
+   */
+  public getAllMetadataKeys(): IterableIterator<symbol> {
+    return this.interceptors.keys();
+  }
+
+  /**
+   * 清除所有拦截器
+   */
+  public clear(): void {
+    this.interceptors.clear();
+  }
+
+  /**
+   * 移除指定元数据键的所有拦截器
+   * @param metadataKey - 元数据键
+   */
+  public remove(metadataKey: symbol): void {
+    this.interceptors.delete(metadataKey);
+  }
+
+  /**
+   * 获取拦截器数量
+   * @param metadataKey - 元数据键（可选）
+   * @returns 拦截器数量
+   */
+  public count(metadataKey?: symbol): number {
+    if (metadataKey) {
+      const metadataList = this.interceptors.get(metadataKey);
+      return metadataList ? metadataList.length : 0;
+    }
+    
+    // 返回所有拦截器的总数
+    let total = 0;
+    for (const metadataList of this.interceptors.values()) {
+      total += metadataList.length;
+    }
+    return total;
+  }
+}
+

package/src/interceptor/metadata.ts

@@ -0,0 +1,40 @@
+import 'reflect-metadata';
+import type { InterceptorRegistry } from './interceptor-registry';
+import type { Interceptor, InterceptorMetadata } from './types';
+
+/**
+ * 扫描方法上的所有拦截器元数据
+ * @param target - 目标对象（控制器实例的原型）
+ * @param propertyKey - 方法名
+ * @param registry - 拦截器注册表
+ * @returns 匹配的拦截器列表（按优先级排序）
+ */
+export function scanInterceptorMetadata(
+  target: object,
+  propertyKey: string | symbol,
+  registry: InterceptorRegistry,
+): Interceptor[] {
+  const interceptorMetadataList: InterceptorMetadata[] = [];
+
+  // 扫描所有已注册的元数据键
+  for (const metadataKey of registry.getAllMetadataKeys()) {
+    // 检查方法上是否有该元数据
+    const metadata = Reflect.getMetadata(metadataKey, target, propertyKey);
+    
+    if (metadata !== undefined && metadata !== null) {
+      // 找到匹配的元数据，获取对应的拦截器元数据
+      // 使用公共方法获取完整的元数据（包括优先级）
+      const metadataList = registry.getInterceptorMetadata(metadataKey);
+      if (metadataList.length > 0) {
+        interceptorMetadataList.push(...metadataList);
+      }
+    }
+  }
+
+  // 按优先级排序（数字越小优先级越高）
+  interceptorMetadataList.sort((a, b) => a.priority - b.priority);
+
+  // 返回排序后的拦截器列表
+  return interceptorMetadataList.map((meta) => meta.interceptor);
+}
+

package/src/interceptor/types.ts

@@ -0,0 +1,52 @@
+import type { Container } from '../di/container';
+import type { Context } from '../core/context';
+
+/**
+ * 拦截器接口
+ * 定义拦截器的核心执行方法
+ */
+export interface Interceptor {
+  /**
+   * 执行拦截器逻辑
+   * @param target - 目标对象（控制器实例的原型）
+   * @param propertyKey - 方法名
+   * @param originalMethod - 原始方法
+   * @param args - 方法参数
+   * @param container - DI 容器
+   * @param context - 请求上下文（可选）
+   * @returns 方法执行结果
+   */
+  execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T>;
+}
+
+/**
+ * 拦截器元数据
+ * 用于存储拦截器的注册信息
+ */
+export interface InterceptorMetadata {
+  /**
+   * 元数据键（用于匹配装饰器）
+   */
+  metadataKey: symbol;
+  /**
+   * 拦截器实例
+   */
+  interceptor: Interceptor;
+  /**
+   * 优先级（数字越小优先级越高，默认 100）
+   */
+  priority: number;
+}
+
+/**
+ * 拦截器注册表 Token
+ */
+export const INTERCEPTOR_REGISTRY_TOKEN = Symbol('@dangao/bun-server:interceptor-registry');
+

package/src/metrics/collector.ts

@@ -0,0 +1,209 @@
+import type {
+  CustomMetric,
+  MetricDataPoint,
+  MetricLabels,
+  MetricType,
+  MetricValue,
+} from './types';
+
+/**
+ * 指标收集器
+ */
+export class MetricsCollector {
+  private counters: Map<string, Map<string, number>> = new Map();
+  private gauges: Map<string, Map<string, number>> = new Map();
+  private histograms: Map<string, Map<string, number[]>> = new Map();
+  private customMetrics: CustomMetric[] = [];
+
+  /**
+   * 注册自定义指标
+   */
+  public registerCustomMetric(metric: CustomMetric): void {
+    this.customMetrics.push(metric);
+  }
+
+  /**
+   * 增加计数器
+   */
+  public incrementCounter(name: string, labels?: MetricLabels, value: number = 1): void {
+    const key = this.getKey(name, labels);
+    const counterMap = this.counters.get(name) || new Map();
+    const current = counterMap.get(key) || 0;
+    counterMap.set(key, current + value);
+    this.counters.set(name, counterMap);
+  }
+
+  /**
+   * 设置仪表值
+   */
+  public setGauge(name: string, labels: MetricLabels | undefined, value: number): void {
+    const key = this.getKey(name, labels);
+    const gaugeMap = this.gauges.get(name) || new Map();
+    gaugeMap.set(key, value);
+    this.gauges.set(name, gaugeMap);
+  }
+
+  /**
+   * 观察直方图值
+   */
+  public observeHistogram(name: string, labels: MetricLabels | undefined, value: number): void {
+    const key = this.getKey(name, labels);
+    const histogramMap = this.histograms.get(name) || new Map();
+    const values = histogramMap.get(key) || [];
+    values.push(value);
+    histogramMap.set(key, values);
+    this.histograms.set(name, histogramMap);
+  }
+
+  /**
+   * 获取所有指标数据点
+   */
+  public async getAllDataPoints(): Promise<MetricDataPoint[]> {
+    const dataPoints: MetricDataPoint[] = [];
+
+    // 收集计数器
+    for (const [name, counterMap] of this.counters.entries()) {
+      for (const [key, value] of counterMap.entries()) {
+        const labels = this.parseKey(key);
+        dataPoints.push({
+          name,
+          type: 'counter',
+          value,
+          labels: labels && Object.keys(labels).length > 0 ? labels : undefined,
+        });
+      }
+    }
+
+    // 收集仪表
+    for (const [name, gaugeMap] of this.gauges.entries()) {
+      for (const [key, value] of gaugeMap.entries()) {
+        const labels = this.parseKey(key);
+        dataPoints.push({
+          name,
+          type: 'gauge',
+          value,
+          labels: labels && Object.keys(labels).length > 0 ? labels : undefined,
+        });
+      }
+    }
+
+    // 收集直方图（计算统计信息）
+    for (const [name, histogramMap] of this.histograms.entries()) {
+      for (const [key, values] of histogramMap.entries()) {
+        const labels = this.parseKey(key);
+        const sum = values.reduce((a, b) => a + b, 0);
+        const count = values.length;
+        const buckets = this.calculateBuckets(values);
+
+        // 添加 sum
+        dataPoints.push({
+          name: `${name}_sum`,
+          type: 'histogram',
+          value: sum,
+          labels: labels && Object.keys(labels).length > 0 ? labels : undefined,
+        });
+
+        // 添加 count
+        dataPoints.push({
+          name: `${name}_count`,
+          type: 'histogram',
+          value: count,
+          labels: labels && Object.keys(labels).length > 0 ? labels : undefined,
+        });
+
+        // 添加 buckets
+        for (const [bucket, bucketCount] of Object.entries(buckets)) {
+          dataPoints.push({
+            name: `${name}_bucket`,
+            type: 'histogram',
+            value: bucketCount,
+            labels: {
+              ...labels,
+              le: bucket,
+            },
+          });
+        }
+      }
+    }
+
+    // 收集自定义指标
+    for (const metric of this.customMetrics) {
+      try {
+        const value = await metric.getValue();
+        dataPoints.push({
+          name: metric.name,
+          type: metric.type,
+          value,
+          help: metric.help,
+        });
+      } catch (error) {
+        // 忽略自定义指标错误
+        console.error(`Failed to collect custom metric ${metric.name}:`, error);
+      }
+    }
+
+    return dataPoints;
+  }
+
+  /**
+   * 重置所有指标
+   */
+  public reset(): void {
+    this.counters.clear();
+    this.gauges.clear();
+    this.histograms.clear();
+  }
+
+  /**
+   * 生成标签键
+   */
+  private getKey(name: string, labels?: MetricLabels): string {
+    if (!labels || Object.keys(labels).length === 0) {
+      return '';
+    }
+
+    const sortedLabels = Object.keys(labels)
+      .sort()
+      .map((key) => `${key}="${labels[key]}"`)
+      .join(',');
+    return `{${sortedLabels}}`;
+  }
+
+  /**
+   * 解析标签键
+   */
+  private parseKey(key: string): MetricLabels | undefined {
+    if (!key || key === '') {
+      return undefined;
+    }
+
+    const labels: MetricLabels = {};
+    const match = key.match(/\{([^}]+)\}/);
+    if (match) {
+      const labelPairs = match[1].split(',');
+      for (const pair of labelPairs) {
+        const [k, v] = pair.split('=');
+        if (k && v) {
+          labels[k.trim()] = v.trim().replace(/^"|"$/g, '');
+        }
+      }
+    }
+    return Object.keys(labels).length > 0 ? labels : undefined;
+  }
+
+  /**
+   * 计算直方图桶
+   */
+  private calculateBuckets(values: number[]): Record<string, number> {
+    // Prometheus 默认桶：.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10, +Inf
+    const defaultBuckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+    const buckets: Record<string, number> = {};
+
+    for (const bucket of defaultBuckets) {
+      buckets[bucket.toString()] = values.filter((v) => v <= bucket).length;
+    }
+    buckets['+Inf'] = values.length;
+
+    return buckets;
+  }
+}

package/src/metrics/controller.ts

@@ -0,0 +1,40 @@
+import { GET } from '../router/decorators';
+import { Inject } from '../di/decorators';
+import { Controller } from '../controller';
+
+import { MetricsCollector } from './collector';
+import { PrometheusFormatter } from './prometheus';
+import { METRICS_SERVICE_TOKEN, METRICS_OPTIONS_TOKEN, type MetricsModuleOptions } from './types';
+
+/**
+ * Metrics 控制器
+ * 提供 `/metrics` 端点用于 Prometheus 指标导出
+ */
+@Controller('/')
+export class MetricsController {
+  private readonly formatter: PrometheusFormatter;
+
+  public constructor(
+    @Inject(METRICS_SERVICE_TOKEN)
+    private readonly collector: MetricsCollector,
+    @Inject(METRICS_OPTIONS_TOKEN)
+    private readonly options?: MetricsModuleOptions,
+  ) {
+    this.formatter = new PrometheusFormatter();
+  }
+
+  /**
+   * 获取 Prometheus 格式的指标
+   */
+  @GET('/metrics')
+  public async metrics(): Promise<Response> {
+    const dataPoints = await this.collector.getAllDataPoints();
+    const prometheusText = this.formatter.format(dataPoints);
+
+    return new Response(prometheusText, {
+      headers: {
+        'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+      },
+    });
+  }
+}

package/src/metrics/index.ts

@@ -0,0 +1,15 @@
+export { MetricsModule } from './metrics-module';
+export { MetricsCollector } from './collector';
+export { PrometheusFormatter } from './prometheus';
+export { MetricsController } from './controller';
+export { createHttpMetricsMiddleware } from './middleware';
+export {
+  METRICS_SERVICE_TOKEN,
+  METRICS_OPTIONS_TOKEN,
+  type MetricsModuleOptions,
+  type MetricType,
+  type MetricLabels,
+  type MetricValue,
+  type MetricDataPoint,
+  type CustomMetric,
+} from './types';

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