@dangao/bun-server 1.7.0 → 1.8.0

package/src/index.ts

@@ -25,7 +25,7 @@ export type {
   ControllerMetadata,
 } from './controller';
 export { Container } from './di/container';
-export { Injectable, Inject } from './di/decorators';
+export { Injectable, Inject, Global, isGlobalModule, GLOBAL_MODULE_METADATA_KEY } from './di/decorators';
 export { Lifecycle, type ProviderConfig, type DependencyMetadata } from './di/types';
 export {
   Module,
@@ -71,15 +71,97 @@ export {
   type RateLimitOptions,
   type RateLimitStore,
 } from './middleware/builtin';
+// Validation 模块
 export {
+  // 基础装饰器
   Validate,
   IsString,
   IsNumber,
   IsEmail,
   IsOptional,
   MinLength,
+  getValidationMetadata,
+  // 类型
+  type ValidationRuleDefinition,
+  type ValidationMetadata,
+  type ClassValidationMetadata,
+  type ValidationOptions,
+  // 验证器
+  validateParameters,
+  // 错误处理
   ValidationError,
   type ValidationIssue,
+  // 对象规则
+  IsObject,
+  IsNotEmpty,
+  IsNotEmptyObject,
+  ValidateNested,
+  type ObjectRuleOptions,
+  type ValidateNestedOptions,
+  // 数组规则
+  IsArray,
+  ArrayMinSize,
+  ArrayMaxSize,
+  ArrayUnique,
+  ArrayContains,
+  ArrayNotContains,
+  ArrayNotEmpty,
+  type ArrayRuleOptions,
+  // 通用规则
+  IsBoolean,
+  IsInt,
+  IsPositive,
+  IsNegative,
+  Min,
+  Max,
+  IsDate,
+  IsUUID,
+  Length,
+  MaxLength,
+  Matches,
+  IsIn,
+  IsNotIn,
+  IsUrl,
+  IsJSON,
+  Equals,
+  NotEquals,
+  IsDefined,
+  IsAlphanumeric,
+  IsAlpha,
+  IsNumberString,
+  type RuleOptions,
+  type UUIDVersion,
+  // 条件和转换规则
+  ValidateIf,
+  Transform,
+  type ConditionalRuleOptions,
+  // 自定义验证器
+  createCustomValidator,
+  createSimpleValidator,
+  createRegexValidator,
+  IsPhoneNumber,
+  IsIdCard,
+  IsIPv4,
+  IsPort,
+  IsPostalCode,
+  IsCreditCard,
+  IsHexColor,
+  IsMacAddress,
+  IsSemVer,
+  IsDivisibleBy,
+  IsBetween,
+  Contains,
+  NotContains,
+  type CustomValidatorOptions,
+  // 类级别验证
+  ValidateClass,
+  Property,
+  NestedProperty,
+  ArrayNestedProperty,
+  validateObject,
+  validateObjectSync,
+  getClassValidationMetadata,
+  isValidateClass,
 } from './validation';
 export {
   HttpException,
@@ -136,6 +218,8 @@ export {
   JwtAuthenticationProvider,
   OAuth2AuthenticationProvider,
   createSecurityFilter,
+  getGuardRegistry,
+  registerReflector,
   type SecurityModuleConfig,
   type SecurityConfig,
   type SecurityContext,
@@ -146,6 +230,32 @@ export {
   type Credentials,
   type AccessDecisionManager,
 } from './security';
+// Guards 子模块
+export {
+  UseGuards,
+  Roles,
+  getGuardsMetadata,
+  getRolesMetadata,
+  AuthGuard,
+  OptionalAuthGuard,
+  RolesGuard,
+  createRolesGuard,
+  GuardRegistry,
+  ExecutionContextImpl,
+  Reflector,
+  GUARDS_METADATA_KEY,
+  GUARD_REGISTRY_TOKEN,
+  ROLES_METADATA_KEY,
+  REFLECTOR_TOKEN,
+  type CanActivate,
+  type ExecutionContext,
+  type HttpArgumentsHost,
+  type WsArgumentsHost,
+  type GuardType,
+  type GuardMetadata,
+  type GuardOptions,
+  type RolesGuardOptions,
+} from './security/guards';
 export {
   ConfigModule,
   ConfigService,
@@ -254,10 +364,17 @@ export {
   Cacheable,
   CacheEvict,
   CachePut,
+  EnableCacheProxy,
+  CacheServiceProxy,
+  CachePostProcessor,
+  CacheableInterceptor,
+  CacheEvictInterceptor,
+  CachePutInterceptor,
   MemoryCacheStore,
   RedisCacheStore,
   CACHE_SERVICE_TOKEN,
   CACHE_OPTIONS_TOKEN,
+  CACHE_POST_PROCESSOR_TOKEN,
 } from './cache';
 export type {
   CacheModuleOptions,
@@ -387,4 +504,26 @@ export {
   type ServiceInstanceHealth,
   type MonitoringOptions,
 } from './microservice';
+// Events 模块
+export {
+  EventModule,
+  EventEmitterService,
+  EventListenerScanner,
+  OnEvent,
+  getOnEventMetadata,
+  isEventListenerClass,
+  EVENT_EMITTER_TOKEN,
+  EVENT_OPTIONS_TOKEN,
+  EVENT_LISTENER_SCANNER_TOKEN,
+  ON_EVENT_METADATA_KEY,
+  EVENT_LISTENER_CLASS_METADATA_KEY,
+  type EventEmitter,
+  type EventListener,
+  type EventMetadata,
+  type EventModuleOptions,
+  type ListenerOptions,
+  type OnEventMethodMetadata,
+  type OnEventOptions,
+  type RegisteredListener,
+} from './events';
 

package/src/security/filter.ts

@@ -1,5 +1,6 @@
 import type { Context } from '../core/context';
 import type { Middleware } from '../middleware';
+import type { Container } from '../di/container';
 import { SecurityContextHolder } from './context';
 import { AuthenticationManager } from './authentication-manager';
 import { RoleBasedAccessDecisionManager } from './access-decision-manager';
@@ -10,6 +11,10 @@ import {
 } from '../error/http-exception';
 import { ErrorCode } from '../error/error-codes';
 import { requiresAuth, getAuthMetadata } from '../auth/decorators';
+import { GuardRegistry } from './guards/guard-registry';
+import { ExecutionContextImpl } from './guards/execution-context';
+import { Reflector, REFLECTOR_TOKEN } from './guards/reflector';
+import { GUARD_REGISTRY_TOKEN } from './guards/types';
 
 /**
  * 安全过滤器配置
@@ -27,6 +32,14 @@ export interface SecurityFilterConfig extends SecurityConfig {
    * 令牌提取函数
    */
   extractToken?: (ctx: Context) => string | null;
+  /**
+   * DI 容器（用于解析守卫）
+   */
+  container?: Container;
+  /**
+   * 守卫注册表
+   */
+  guardRegistry?: GuardRegistry;
 }
 
 /**
@@ -39,8 +52,30 @@ export function createSecurityFilter(config: SecurityFilterConfig): Middleware {
     excludePaths = [],
     defaultAuthRequired = true,
     extractToken,
+    container: initialContainer,
+    guardRegistry,
   } = config;
 
+  // 创建或使用传入的守卫注册表
+  const registry = guardRegistry || new GuardRegistry();
+
+  // 延迟获取容器的函数
+  let cachedContainer: Container | null = initialContainer || null;
+  const getContainer = (): Container | null => {
+    if (cachedContainer) {
+      return cachedContainer;
+    }
+    // 尝试从 ControllerRegistry 获取容器
+    try {
+      // 动态导入避免循环依赖
+      const { ControllerRegistry } = require('../controller/controller');
+      cachedContainer = ControllerRegistry.getInstance().getContainer();
+      return cachedContainer;
+    } catch {
+      return null;
+    }
+  };
+
   return async (ctx: Context, next) => {
     return SecurityContextHolder.runWithContext(async () => {
       // 检查是否在排除列表中
@@ -74,6 +109,14 @@ export function createSecurityFilter(config: SecurityFilterConfig): Middleware {
           }
         }
 
+        // 将安全上下文附加到 Context（在守卫执行前）
+        (ctx as any).security = securityContext;
+        (ctx as any).auth = {
+          isAuthenticated: securityContext.isAuthenticated(),
+          user: securityContext.getPrincipal(),
+          payload: (securityContext.authentication?.details as any),
+        };
+
         // 检查是否需要认证
         const handler = (ctx as any).routeHandler;
         if (handler) {
@@ -82,6 +125,23 @@ export function createSecurityFilter(config: SecurityFilterConfig): Middleware {
             (controllerClass && controllerClass.prototype) || controllerClass;
           const method = handler.method;
 
+          // 执行守卫链（在 @Auth 检查之前）
+          // Guards 在中间件之后、拦截器之前执行
+          const container = getContainer();
+          // 只有当 controllerClass 是一个有效的类（构造函数）时才执行守卫
+          // 测试中可能传入原型而不是类，这种情况跳过守卫执行
+          if (container && typeof controllerClass === 'function') {
+            const methodHandler = controllerTarget[method];
+            const executionContext = new ExecutionContextImpl(
+              ctx,
+              controllerClass,
+              method,
+              methodHandler || (() => {}),
+            );
+            await registry.executeGuards(executionContext, container);
+          }
+
+          // 传统的 @Auth 装饰器检查（向后兼容）
           if (requiresAuth(controllerTarget, method)) {
             const authentication = securityContext.authentication;
             if (!authentication || !authentication.authenticated) {
@@ -118,14 +178,6 @@ export function createSecurityFilter(config: SecurityFilterConfig): Middleware {
           );
         }
 
-        // 将安全上下文附加到 Context
-        (ctx as any).security = securityContext;
-        (ctx as any).auth = {
-          isAuthenticated: securityContext.isAuthenticated(),
-          user: securityContext.getPrincipal(),
-          payload: (securityContext.authentication?.details as any),
-        };
-
         return await next();
       } finally {
         // 清理当前请求内的认证信息，防止泄漏到下一个请求
@@ -135,6 +187,34 @@ export function createSecurityFilter(config: SecurityFilterConfig): Middleware {
   };
 }
 
+/**
+ * 获取守卫注册表
+ * @param container - DI 容器
+ * @returns 守卫注册表实例
+ */
+export function getGuardRegistry(container: Container): GuardRegistry {
+  if (container.isRegistered(GUARD_REGISTRY_TOKEN)) {
+    return container.resolve<GuardRegistry>(GUARD_REGISTRY_TOKEN);
+  }
+  const registry = new GuardRegistry();
+  container.registerInstance(GUARD_REGISTRY_TOKEN, registry);
+  return registry;
+}
+
+/**
+ * 注册 Reflector 到 DI 容器
+ * @param container - DI 容器
+ * @returns Reflector 实例
+ */
+export function registerReflector(container: Container): Reflector {
+  if (container.isRegistered(REFLECTOR_TOKEN)) {
+    return container.resolve<Reflector>(REFLECTOR_TOKEN);
+  }
+  const reflector = new Reflector();
+  container.registerInstance(REFLECTOR_TOKEN, reflector);
+  return reflector;
+}
+
 /**
  * 从请求头提取令牌
  */

package/src/security/guards/builtin/auth-guard.ts

@@ -0,0 +1,68 @@
+import { Injectable } from '../../../di/decorators';
+import type { CanActivate, ExecutionContext } from '../types';
+import { SecurityContextHolder } from '../../context';
+import { UnauthorizedException } from '../../../error/http-exception';
+import { ErrorCode } from '../../../error/error-codes';
+
+/**
+ * 认证守卫
+ * 检查请求是否已认证
+ * 
+ * @example
+ * @Controller('/api/users')
+ * @UseGuards(AuthGuard)
+ * class UserController {
+ *   @GET('/profile')
+ *   getProfile() {
+ *     // 只有已认证的用户才能访问
+ *   }
+ * }
+ */
+@Injectable()
+export class AuthGuard implements CanActivate {
+  /**
+   * 判断是否允许访问
+   * @param context - 执行上下文
+   * @returns 如果已认证则返回 true，否则抛出 UnauthorizedException
+   */
+  public canActivate(context: ExecutionContext): boolean {
+    const securityContext = SecurityContextHolder.getContext();
+    
+    if (!securityContext.isAuthenticated()) {
+      throw new UnauthorizedException(
+        'Authentication required',
+        undefined,
+        ErrorCode.AUTH_REQUIRED,
+      );
+    }
+
+    return true;
+  }
+}
+
+/**
+ * 可选认证守卫
+ * 如果有 token 则验证，没有 token 也允许访问
+ * 
+ * @example
+ * @GET('/public')
+ * @UseGuards(OptionalAuthGuard)
+ * publicEndpoint() {
+ *   // 未认证也可以访问，但如果有 token 会被验证
+ * }
+ */
+@Injectable()
+export class OptionalAuthGuard implements CanActivate {
+  /**
+   * 判断是否允许访问
+   * 总是返回 true，但会检查认证状态
+   * @param context - 执行上下文
+   * @returns 总是返回 true
+   */
+  public canActivate(context: ExecutionContext): boolean {
+    // 可选认证：不强制要求认证，但如果有认证信息会被使用
+    // SecurityFilter 已经处理了 token 解析和认证
+    return true;
+  }
+}
+

package/src/security/guards/builtin/index.ts

@@ -0,0 +1,3 @@
+export { AuthGuard, OptionalAuthGuard } from './auth-guard';
+export { RolesGuard, createRolesGuard, type RolesGuardOptions } from './roles-guard';
+

package/src/security/guards/builtin/roles-guard.ts

@@ -0,0 +1,165 @@
+import { Injectable, Inject } from '../../../di/decorators';
+import type { CanActivate, ExecutionContext } from '../types';
+import { ROLES_METADATA_KEY } from '../types';
+import { SecurityContextHolder } from '../../context';
+import { ForbiddenException } from '../../../error/http-exception';
+import { ErrorCode } from '../../../error/error-codes';
+import { Reflector, REFLECTOR_TOKEN } from '../reflector';
+
+/**
+ * 角色守卫
+ * 检查用户是否具有所需角色
+ * 
+ * @example
+ * @Controller('/api/admin')
+ * @UseGuards(AuthGuard, RolesGuard)
+ * class AdminController {
+ *   @GET('/dashboard')
+ *   @Roles('admin')
+ *   dashboard() {
+ *     // 只有 admin 角色才能访问
+ *   }
+ * 
+ *   @GET('/super')
+ *   @Roles('admin', 'superadmin')
+ *   superAdmin() {
+ *     // admin 或 superadmin 角色可以访问
+ *   }
+ * }
+ */
+@Injectable()
+export class RolesGuard implements CanActivate {
+  private readonly reflector: Reflector;
+
+  public constructor(
+    @Inject(REFLECTOR_TOKEN) reflector?: Reflector,
+  ) {
+    this.reflector = reflector || new Reflector();
+  }
+
+  /**
+   * 判断是否允许访问
+   * @param context - 执行上下文
+   * @returns 如果用户具有所需角色则返回 true
+   */
+  public canActivate(context: ExecutionContext): boolean {
+    // 获取方法和类上定义的角色
+    const requiredRoles = this.reflector.getAllAndMerge<string[]>(
+      ROLES_METADATA_KEY,
+      context.getClass(),
+      context.getMethodName(),
+    );
+
+    // 如果没有定义角色要求，则允许访问
+    if (!requiredRoles || requiredRoles.length === 0) {
+      return true;
+    }
+
+    // 获取当前用户的角色
+    const securityContext = SecurityContextHolder.getContext();
+    const authentication = securityContext.authentication;
+
+    if (!authentication || !authentication.authenticated) {
+      throw new ForbiddenException(
+        'Access denied: authentication required for role check',
+        { requiredRoles },
+        ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+      );
+    }
+
+    const userRoles = authentication.authorities || [];
+
+    // 检查用户是否具有任一所需角色
+    const hasRole = requiredRoles.some((role) => userRoles.includes(role));
+
+    if (!hasRole) {
+      throw new ForbiddenException(
+        `Access denied: required roles [${requiredRoles.join(', ')}], but user has [${userRoles.join(', ')}]`,
+        { requiredRoles, userRoles },
+        ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+      );
+    }
+
+    return true;
+  }
+}
+
+/**
+ * 创建自定义角色守卫
+ * 支持自定义角色验证逻辑
+ * 
+ * @example
+ * const CustomRolesGuard = createRolesGuard({
+ *   // 所有角色都必须匹配
+ *   matchAll: true,
+ *   // 自定义角色获取逻辑
+ *   getRoles: (context) => {
+ *     const user = context.switchToHttp().getRequest().auth?.user;
+ *     return user?.roles || [];
+ *   },
+ * });
+ */
+export interface RolesGuardOptions {
+  /**
+   * 是否需要匹配所有角色
+   * @default false (只需匹配其中一个)
+   */
+  matchAll?: boolean;
+
+  /**
+   * 自定义获取用户角色的函数
+   */
+  getRoles?: (context: ExecutionContext) => string[];
+}
+
+/**
+ * 创建自定义角色守卫工厂
+ * @param options - 配置选项
+ * @returns 自定义角色守卫类
+ */
+export function createRolesGuard(options: RolesGuardOptions = {}): new () => CanActivate {
+  const { matchAll = false, getRoles } = options;
+
+  @Injectable()
+  class CustomRolesGuard implements CanActivate {
+    private readonly reflector = new Reflector();
+
+    public canActivate(context: ExecutionContext): boolean {
+      const requiredRoles = this.reflector.getAllAndMerge<string[]>(
+        ROLES_METADATA_KEY,
+        context.getClass(),
+        context.getMethodName(),
+      );
+
+      if (!requiredRoles || requiredRoles.length === 0) {
+        return true;
+      }
+
+      let userRoles: string[];
+
+      if (getRoles) {
+        userRoles = getRoles(context);
+      } else {
+        const securityContext = SecurityContextHolder.getContext();
+        userRoles = securityContext.authentication?.authorities || [];
+      }
+
+      const hasRole = matchAll
+        ? requiredRoles.every((role) => userRoles.includes(role))
+        : requiredRoles.some((role) => userRoles.includes(role));
+
+      if (!hasRole) {
+        throw new ForbiddenException(
+          `Access denied: required roles [${requiredRoles.join(', ')}], user has [${userRoles.join(', ')}]`,
+          { requiredRoles, userRoles, matchAll },
+          ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS,
+        );
+      }
+
+      return true;
+    }
+  }
+
+  return CustomRolesGuard;
+}
+

package/src/security/guards/decorators.ts

@@ -0,0 +1,124 @@
+import 'reflect-metadata';
+import type { GuardType } from './types';
+import { GUARDS_METADATA_KEY, ROLES_METADATA_KEY } from './types';
+
+/**
+ * 守卫装饰器
+ * 可用于控制器或方法级别
+ * 
+ * @example
+ * // 控制器级别
+ * @Controller('/api/admin')
+ * @UseGuards(AuthGuard, RolesGuard)
+ * class AdminController {}
+ * 
+ * @example
+ * // 方法级别
+ * @GET('/profile')
+ * @UseGuards(AuthGuard)
+ * getProfile() {}
+ * 
+ * @param guards - 守卫类或守卫实例
+ * @returns 类或方法装饰器
+ */
+export function UseGuards(
+  ...guards: GuardType[]
+): ClassDecorator & MethodDecorator {
+  return (
+    target: Object | Function,
+    propertyKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ) => {
+    if (propertyKey !== undefined) {
+      // 方法装饰器
+      const existingGuards: GuardType[] =
+        Reflect.getMetadata(GUARDS_METADATA_KEY, target, propertyKey) || [];
+      Reflect.defineMetadata(
+        GUARDS_METADATA_KEY,
+        [...existingGuards, ...guards],
+        target,
+        propertyKey,
+      );
+    } else {
+      // 类装饰器
+      const existingGuards: GuardType[] =
+        Reflect.getMetadata(GUARDS_METADATA_KEY, target) || [];
+      Reflect.defineMetadata(
+        GUARDS_METADATA_KEY,
+        [...existingGuards, ...guards],
+        target,
+      );
+    }
+  };
+}
+
+/**
+ * 角色装饰器
+ * 用于标记需要特定角色的方法或控制器
+ * 
+ * @example
+ * @GET('/admin')
+ * @Roles('admin', 'superadmin')
+ * adminOnly() {}
+ * 
+ * @param roles - 允许访问的角色列表
+ * @returns 类或方法装饰器
+ */
+export function Roles(
+  ...roles: string[]
+): ClassDecorator & MethodDecorator {
+  return (
+    target: Object | Function,
+    propertyKey?: string | symbol,
+    descriptor?: PropertyDescriptor,
+  ) => {
+    if (propertyKey !== undefined) {
+      // 方法装饰器
+      Reflect.defineMetadata(ROLES_METADATA_KEY, roles, target, propertyKey);
+    } else {
+      // 类装饰器
+      Reflect.defineMetadata(ROLES_METADATA_KEY, roles, target);
+    }
+  };
+}
+
+/**
+ * 获取守卫元数据
+ * @param target - 目标对象（类或原型）
+ * @param propertyKey - 方法名（可选）
+ * @returns 守卫列表
+ */
+export function getGuardsMetadata(
+  target: Object | Function,
+  propertyKey?: string | symbol,
+): GuardType[] {
+  // 安全检查：确保 target 是有效的对象或函数
+  if (target === null || target === undefined) {
+    return [];
+  }
+  if (typeof target !== 'object' && typeof target !== 'function') {
+    return [];
+  }
+
+  if (propertyKey !== undefined) {
+    return Reflect.getMetadata(GUARDS_METADATA_KEY, target, propertyKey) || [];
+  }
+  return Reflect.getMetadata(GUARDS_METADATA_KEY, target) || [];
+}
+
+/**
+ * 获取角色元数据
+ * @param target - 目标对象（类或原型）
+ * @param propertyKey - 方法名（可选）
+ * @returns 角色列表
+ */
+export function getRolesMetadata(
+  target: Object | Function,
+  propertyKey?: string | symbol,
+): string[] {
+  if (propertyKey !== undefined) {
+    return Reflect.getMetadata(ROLES_METADATA_KEY, target, propertyKey) || [];
+  }
+  return Reflect.getMetadata(ROLES_METADATA_KEY, target) || [];
+}
+