@dangao/bun-server 1.0.0 → 1.0.3

package/src/health/controller.ts

@@ -0,0 +1,76 @@
+import { Controller } from '../controller';
+import { GET } from '../router/decorators';
+import { Inject } from '../di/decorators';
+
+import type {
+  HealthIndicator,
+  HealthIndicatorResult,
+  HealthStatus,
+} from './types';
+import type { HealthModuleOptions } from './types';
+import { HEALTH_INDICATORS_TOKEN, HEALTH_OPTIONS_TOKEN } from './types';
+
+/**
+ * 健康检查控制器
+ *
+ * 提供 `/health` 和 `/ready` 两个端点：
+ * - /health：存活检查（liveness）
+ * - /ready：就绪检查（readiness）
+ */
+@Controller('/')
+export class HealthController {
+  public constructor(
+    @Inject(HEALTH_INDICATORS_TOKEN)
+    private readonly indicators: HealthIndicator[] = [],
+    @Inject(HEALTH_OPTIONS_TOKEN)
+    private readonly options?: HealthModuleOptions,
+  ) {}
+
+  /**
+   * 存活检查
+   */
+  @GET('/health')
+  public async health(): Promise<HealthStatus> {
+    return await this.checkIndicators();
+  }
+
+  /**
+   * 就绪检查
+   */
+  @GET('/ready')
+  public async ready(): Promise<HealthStatus> {
+    return await this.checkIndicators();
+  }
+
+  /**
+   * 执行所有健康检查指示器
+   */
+  private async checkIndicators(): Promise<HealthStatus> {
+    const details: Record<string, HealthIndicatorResult> = {};
+
+    for (const indicator of this.indicators || []) {
+      try {
+        const result = await indicator.check();
+        details[indicator.name] = result;
+      } catch (error) {
+        details[indicator.name] = {
+          status: 'down',
+          details: {
+            error: (error as Error).message,
+          },
+        };
+      }
+    }
+
+    const allUp =
+      Object.keys(details).length === 0 ||
+      Object.values(details).every((result) => result.status === 'up');
+
+    return {
+      status: allUp ? 'up' : 'down',
+      details,
+    };
+  }
+}
+
+

package/src/health/health-module.ts

@@ -0,0 +1,51 @@
+import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+
+import { HealthController } from './controller';
+import type { HealthIndicator, HealthModuleOptions } from './types';
+import { HEALTH_INDICATORS_TOKEN, HEALTH_OPTIONS_TOKEN } from './types';
+
+@Module({
+  controllers: [HealthController],
+  providers: [],
+})
+export class HealthModule {
+  /**
+   * 创建健康检查模块
+   * @param options - 模块配置
+   */
+  public static forRoot(options: HealthModuleOptions = {}): typeof HealthModule {
+    const providers: ModuleProvider[] = [];
+
+    const indicators: HealthIndicator[] = options.indicators ?? [];
+
+    providers.push(
+      {
+        provide: HEALTH_INDICATORS_TOKEN,
+        useValue: indicators,
+      },
+      {
+        provide: HEALTH_OPTIONS_TOKEN,
+        useValue: options,
+      },
+    );
+
+    // 动态更新模块元数据
+    const existingMetadata =
+      Reflect.getMetadata(MODULE_METADATA_KEY, HealthModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      controllers: [...(existingMetadata.controllers || []), HealthController],
+      providers: [...(existingMetadata.providers || []), ...providers],
+      exports: [
+        ...(existingMetadata.exports || []),
+        HEALTH_INDICATORS_TOKEN,
+        HEALTH_OPTIONS_TOKEN,
+      ],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, HealthModule);
+
+    return HealthModule;
+  }
+}
+
+

package/src/health/index.ts

@@ -0,0 +1,12 @@
+export { HealthModule } from './health-module';
+export { HealthController } from './controller';
+export {
+  HEALTH_INDICATORS_TOKEN,
+  HEALTH_OPTIONS_TOKEN,
+  type HealthIndicator,
+  type HealthIndicatorResult,
+  type HealthStatus,
+  type HealthModuleOptions,
+} from './types';
+
+

package/src/health/types.ts

@@ -0,0 +1,28 @@
+export const HEALTH_INDICATORS_TOKEN = Symbol('@dangao/bun-server:health:indicators');
+export const HEALTH_OPTIONS_TOKEN = Symbol('@dangao/bun-server:health:options');
+
+export type HealthStatusValue = 'up' | 'down';
+
+export interface HealthIndicatorResult {
+  status: HealthStatusValue;
+  details?: Record<string, unknown>;
+}
+
+export interface HealthIndicator {
+  name: string;
+  check(): Promise<HealthIndicatorResult> | HealthIndicatorResult;
+}
+
+export interface HealthStatus {
+  status: HealthStatusValue;
+  details: Record<string, HealthIndicatorResult>;
+}
+
+export interface HealthModuleOptions {
+  /**
+   * 健康检查指示器列表
+   */
+  indicators?: HealthIndicator[];
+}
+
+

package/src/index.ts

@@ -0,0 +1,270 @@
+export { Application, type ApplicationOptions } from './core/application';
+export { BunServer, type ServerOptions } from './core/server';
+export { Context } from './core/context';
+export { Route, Router, RouteRegistry } from './router';
+export { GET, POST, PUT, DELETE, PATCH } from './router/decorators';
+export type { HttpMethod, RouteHandler, RouteMatch } from './router/types';
+export { BodyParser, RequestWrapper, ResponseBuilder } from './request';
+export { Body, Query, Param, Header, ParamBinder, Controller, ControllerRegistry } from './controller';
+export type { ParamMetadata, ControllerMetadata } from './controller';
+export { Container } from './di/container';
+export { Injectable, Inject } from './di/decorators';
+export { Lifecycle, type ProviderConfig, type DependencyMetadata } from './di/types';
+export {
+  Module,
+  type ModuleMetadata,
+  type ModuleProvider,
+  type ModuleClass,
+} from './di/module';
+export { ModuleRegistry } from './di/module-registry';
+export { UseMiddleware, RateLimit, MiddlewarePipeline } from './middleware';
+export type { Middleware, NextFunction } from './middleware';
+export {
+  createLoggerMiddleware,
+  createRequestLoggingMiddleware,
+  createErrorHandlingMiddleware,
+  createCorsMiddleware,
+  createFileUploadMiddleware,
+  createStaticFileMiddleware,
+  createRateLimitMiddleware,
+  createTokenKeyGenerator,
+  createUserKeyGenerator,
+  type RateLimitOptions,
+  type RateLimitStore,
+} from './middleware/builtin';
+export {
+  Validate,
+  IsString,
+  IsNumber,
+  IsEmail,
+  IsOptional,
+  MinLength,
+  ValidationError,
+  type ValidationIssue,
+} from './validation';
+export {
+  HttpException,
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  InternalServerErrorException,
+  ExceptionFilterRegistry,
+  type ExceptionFilter,
+} from './error';
+export {
+  WebSocketGateway,
+  OnOpen,
+  OnMessage,
+  OnClose,
+  WebSocketGatewayRegistry,
+  type WebSocketConnectionData,
+} from './websocket';
+export {
+  LoggerExtension,
+  LoggerModule,
+  LogLevel,
+  LOGGER_TOKEN,
+  type Logger,
+  type LoggerOptions,
+  type LoggerModuleOptions,
+  type LogEntry,
+} from './extensions';
+export {
+  SwaggerExtension,
+  SwaggerModule,
+  SwaggerGenerator,
+  createSwaggerUIMiddleware,
+  ApiTags,
+  ApiOperation,
+  ApiParam,
+  ApiBody,
+  ApiResponse,
+  type SwaggerOptions,
+  type SwaggerModuleOptions,
+  type SwaggerDocument,
+  type ApiOperationMetadata,
+  type ApiParamMetadata,
+  type ApiBodyMetadata,
+  type ApiResponseMetadata,
+} from './swagger';
+// Security 模块（推荐使用）
+export {
+  SecurityModule,
+  SecurityContextHolder,
+  AuthenticationManager,
+  RoleBasedAccessDecisionManager,
+  JwtAuthenticationProvider,
+  OAuth2AuthenticationProvider,
+  createSecurityFilter,
+  type SecurityModuleConfig,
+  type SecurityConfig,
+  type SecurityContext,
+  type Authentication,
+  type AuthenticationProvider,
+  type AuthenticationRequest,
+  type Principal,
+  type Credentials,
+  type AccessDecisionManager,
+} from './security';
+export {
+  ConfigModule,
+  ConfigService,
+  CONFIG_SERVICE_TOKEN,
+  type ConfigModuleOptions,
+} from './config';
+export {
+  HealthModule,
+  type HealthIndicator,
+  type HealthIndicatorResult,
+  type HealthStatus,
+  type HealthModuleOptions,
+  HEALTH_INDICATORS_TOKEN,
+  HEALTH_OPTIONS_TOKEN,
+} from './health';
+export {
+  MetricsModule,
+  MetricsCollector,
+  PrometheusFormatter,
+  createHttpMetricsMiddleware,
+  METRICS_SERVICE_TOKEN,
+  METRICS_OPTIONS_TOKEN,
+  type MetricsModuleOptions,
+  type MetricType,
+  type MetricLabels,
+  type MetricValue,
+  type MetricDataPoint,
+  type CustomMetric,
+} from './metrics';
+export {
+  DatabaseModule,
+  DatabaseService,
+  DatabaseConnectionManager,
+  ConnectionPool,
+  DatabaseHealthIndicator,
+  DatabaseExtension,
+  DATABASE_SERVICE_TOKEN,
+  DATABASE_OPTIONS_TOKEN,
+  type DatabaseModuleOptions,
+  type DatabaseConfig,
+  type DatabaseType,
+  type ConnectionInfo,
+  type ConnectionPoolOptions,
+  type SqliteConfig,
+  type PostgresConfig,
+  type MysqlConfig,
+  // ORM exports
+  Entity,
+  Column,
+  PrimaryKey,
+  Repository,
+  BaseRepository,
+  DrizzleBaseRepository,
+  OrmService,
+  ORM_SERVICE_TOKEN,
+  getEntityMetadata,
+  getColumnMetadata,
+  getRepositoryMetadata,
+  type OrmModuleOptions,
+  type BaseRepository as BaseRepositoryInterface,
+  type EntityMetadata,
+  type ColumnMetadata,
+  // Transaction exports
+  Transactional,
+  TransactionManager,
+  TransactionInterceptor,
+  Propagation,
+  IsolationLevel,
+  TransactionStatus,
+  TRANSACTION_SERVICE_TOKEN,
+  getTransactionMetadata,
+  type TransactionOptions,
+  type TransactionContext,
+} from './database';
+// Auth 模块（底层实现，供 Security 模块使用）
+export {
+  JWTUtil,
+  OAuth2Service,
+  OAuth2Controller,
+  Auth,
+  getAuthMetadata,
+  requiresAuth,
+  checkRoles,
+  OAUTH2_SERVICE_TOKEN,
+  JWT_UTIL_TOKEN,
+  type JWTConfig,
+  type JWTPayload,
+  type OAuth2Client,
+  type OAuth2AuthorizationRequest,
+  type OAuth2TokenRequest,
+  type OAuth2TokenResponse,
+  type UserInfo,
+  type AuthContext,
+  type AuthConfig,
+} from './auth';
+export {
+  PerformanceHarness,
+  StressTester,
+  type BenchmarkResult,
+  type StressResult,
+} from './testing/harness';
+// Cache 模块
+export {
+  CacheModule,
+  CacheService,
+  Cacheable,
+  CacheEvict,
+  CachePut,
+  MemoryCacheStore,
+  RedisCacheStore,
+  CACHE_SERVICE_TOKEN,
+  CACHE_OPTIONS_TOKEN,
+} from './cache';
+export type {
+  CacheModuleOptions,
+  CacheStore,
+  RedisCacheStoreOptions,
+  CacheableOptions,
+  CacheEvictOptions,
+  CachePutOptions,
+} from './cache';
+// Queue 模块
+export {
+  QueueModule,
+  QueueService,
+  Queue,
+  Cron,
+  MemoryQueueStore,
+  QUEUE_SERVICE_TOKEN,
+  QUEUE_OPTIONS_TOKEN,
+} from './queue';
+export type {
+  QueueModuleOptions,
+  QueueStore,
+  Job,
+  JobData,
+  JobHandler,
+  JobOptions,
+  CronOptions,
+  QueueOptions,
+  CronDecoratorOptions,
+} from './queue';
+// Session 模块
+export {
+  SessionModule,
+  SessionService,
+  createSessionMiddleware,
+  SessionDecorator as Session,
+  MemorySessionStore,
+  RedisSessionStore,
+  SESSION_SERVICE_TOKEN,
+  SESSION_OPTIONS_TOKEN,
+} from './session';
+export type {
+  SessionModuleOptions,
+  SessionStore,
+  Session as SessionType,
+  SessionData,
+  RedisSessionStoreOptions,
+} from './session';
+

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';