@dangao/bun-server 1.0.1 → 1.1.2

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,292 @@
+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 {
+  InterceptorRegistry,
+  InterceptorChain,
+  scanInterceptorMetadata,
+  BaseInterceptor,
+  Cache,
+  CacheInterceptor,
+  Permission,
+  PermissionInterceptor,
+  Log,
+  LogInterceptor,
+  INTERCEPTOR_REGISTRY_TOKEN,
+  CACHE_METADATA_KEY,
+  PERMISSION_METADATA_KEY,
+  LOG_METADATA_KEY,
+  type Interceptor,
+  type InterceptorMetadata,
+  type CacheOptions,
+  type PermissionOptions,
+  type PermissionService,
+  type LogOptions,
+} from './interceptor';
+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/interceptor/base-interceptor.ts

@@ -0,0 +1,203 @@
+import type { Interceptor } from './types';
+import type { Container } from '../di/container';
+import type { Context } from '../core/context';
+import 'reflect-metadata';
+
+/**
+ * 拦截器基类
+ * 提供便捷的前置处理、后置处理和错误处理方法
+ */
+export abstract class BaseInterceptor implements Interceptor {
+  /**
+   * 执行拦截器逻辑
+   * 子类必须实现此方法
+   */
+  public abstract execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T>;
+
+  /**
+   * 前置处理（可选）
+   * 在方法执行前调用，子类可以覆盖此方法
+   * @param target - 目标对象
+   * @param propertyKey - 方法名
+   * @param args - 方法参数
+   * @param container - DI 容器
+   * @param context - 请求上下文（可选）
+   */
+  protected async before(
+    target: unknown,
+    propertyKey: string | symbol,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<void> {
+    // 默认空实现，子类可覆盖
+  }
+
+  /**
+   * 后置处理（可选）
+   * 在方法执行后调用，子类可以覆盖此方法
+   * @param target - 目标对象
+   * @param propertyKey - 方法名
+   * @param result - 方法执行结果
+   * @param container - DI 容器
+   * @param context - 请求上下文（可选）
+   * @returns 处理后的结果（默认返回原结果）
+   */
+  protected async after<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    result: T,
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    // 默认返回原结果，子类可覆盖
+    return result;
+  }
+
+  /**
+   * 错误处理（可选）
+   * 在方法执行出错时调用，子类可以覆盖此方法
+   * @param target - 目标对象
+   * @param propertyKey - 方法名
+   * @param error - 错误对象
+   * @param container - DI 容器
+   * @param context - 请求上下文（可选）
+   * @returns 永远不会返回（总是抛出错误）
+   * @throws 重新抛出错误或抛出新的错误
+   */
+  protected async onError(
+    target: unknown,
+    propertyKey: string | symbol,
+    error: unknown,
+    container: Container,
+    context?: Context,
+  ): Promise<never> {
+    // 默认重新抛出错误，子类可覆盖
+    throw error;
+  }
+
+  /**
+   * 获取元数据
+   * 从目标对象的方法上获取指定元数据键的元数据
+   * 支持从实例或原型上获取元数据（元数据通常存储在原型上）
+   * @param target - 目标对象（可能是实例或原型）
+   * @param propertyKey - 方法名
+   * @param metadataKey - 元数据键
+   * @returns 元数据值，如果不存在则返回 undefined
+   */
+  protected getMetadata<T = unknown>(
+    target: unknown,
+    propertyKey: string | symbol,
+    metadataKey: symbol,
+  ): T | undefined {
+    if (typeof target !== 'object' || target === null) {
+      return undefined;
+    }
+
+    // 首先尝试直接从 target 获取（如果 target 是原型）
+    let metadata = Reflect.getMetadata(metadataKey, target, propertyKey) as T | undefined;
+    if (metadata !== undefined) {
+      return metadata;
+    }
+
+    // 如果 target 是实例，尝试从原型获取
+    // 装饰器元数据通常存储在原型上，而不是实例上
+    const prototype = Object.getPrototypeOf(target);
+    if (prototype && prototype !== Object.prototype) {
+      metadata = Reflect.getMetadata(metadataKey, prototype, propertyKey) as T | undefined;
+      if (metadata !== undefined) {
+        return metadata;
+      }
+    }
+
+    // 如果仍然找不到，尝试从构造函数原型获取
+    // 这处理了 target 是实例但原型链查找失败的情况
+    const constructor = (target as any).constructor;
+    if (constructor && typeof constructor === 'function') {
+      // 如果 target 本身不是构造函数原型，尝试从构造函数原型获取
+      if (target !== constructor.prototype) {
+        metadata = Reflect.getMetadata(metadataKey, constructor.prototype, propertyKey) as T | undefined;
+        if (metadata !== undefined) {
+          return metadata;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * 从容器解析服务
+   * @param container - DI 容器
+   * @param token - 服务标识符
+   * @returns 服务实例
+   */
+  protected resolveService<T>(
+    container: Container,
+    token: (new (...args: unknown[]) => T) | string | symbol,
+  ): T {
+    return container.resolve<T>(token);
+  }
+
+  /**
+   * 从上下文获取值
+   * @param context - 请求上下文
+   * @param key - 键名
+   * @returns 值，如果不存在则返回 undefined
+   */
+  protected getContextValue<T = unknown>(context: Context | undefined, key: string): T | undefined {
+    if (!context) {
+      return undefined;
+    }
+    // Context 没有直接的存储机制，可以通过 headers 或其他方式获取
+    // 这里提供一个基础实现，子类可以根据需要扩展
+    return undefined;
+  }
+
+  /**
+   * 从上下文获取请求头
+   * @param context - 请求上下文
+   * @param headerName - 请求头名称
+   * @returns 请求头值，如果不存在则返回 null
+   */
+  protected getHeader(context: Context | undefined, headerName: string): string | null {
+    if (!context) {
+      return null;
+    }
+    return context.getHeader(headerName);
+  }
+
+  /**
+   * 从上下文获取查询参数
+   * @param context - 请求上下文
+   * @param paramName - 参数名称
+   * @returns 参数值，如果不存在则返回 null
+   */
+  protected getQuery(context: Context | undefined, paramName: string): string | null {
+    if (!context) {
+      return null;
+    }
+    return context.getQuery(paramName);
+  }
+
+  /**
+   * 从上下文获取路径参数
+   * @param context - 请求上下文
+   * @param paramName - 参数名称
+   * @returns 参数值，如果不存在则返回 undefined
+   */
+  protected getParam(context: Context | undefined, paramName: string): string | undefined {
+    if (!context) {
+      return undefined;
+    }
+    return context.getParam(paramName);
+  }
+}
+