@dangao/bun-server 1.7.1 → 1.8.0

package/src/events/types.ts

@@ -0,0 +1,223 @@
+/**
+ * 事件监听器接口
+ * @template T - 事件负载类型
+ */
+export interface EventListener<T = unknown> {
+  (payload: T): void | Promise<void>;
+}
+
+/**
+ * 事件元数据
+ */
+export interface EventMetadata {
+  /**
+   * 事件名称或标识符
+   */
+  event: string | symbol;
+
+  /**
+   * 是否异步处理
+   * @default false
+   */
+  async?: boolean;
+
+  /**
+   * 监听器优先级（数值越大优先级越高）
+   * @default 0
+   */
+  priority?: number;
+}
+
+/**
+ * 已注册的监听器信息
+ */
+export interface RegisteredListener<T = unknown> {
+  /**
+   * 监听器函数
+   */
+  listener: EventListener<T>;
+
+  /**
+   * 是否一次性监听
+   */
+  once: boolean;
+
+  /**
+   * 优先级
+   */
+  priority: number;
+
+  /**
+   * 是否异步处理
+   */
+  async: boolean;
+}
+
+/**
+ * EventEmitter 服务接口
+ */
+export interface EventEmitter {
+  /**
+   * 发布事件（同步触发所有监听器，不等待异步监听器完成）
+   * @param event - 事件名称或标识符
+   * @param payload - 事件负载
+   */
+  emit<T>(event: string | symbol, payload: T): void;
+
+  /**
+   * 异步发布事件（等待所有监听器完成）
+   * @param event - 事件名称或标识符
+   * @param payload - 事件负载
+   */
+  emitAsync<T>(event: string | symbol, payload: T): Promise<void>;
+
+  /**
+   * 订阅事件
+   * @param event - 事件名称或标识符
+   * @param listener - 监听器函数
+   * @param options - 监听选项
+   * @returns 取消订阅函数
+   */
+  on<T>(
+    event: string | symbol,
+    listener: EventListener<T>,
+    options?: ListenerOptions,
+  ): () => void;
+
+  /**
+   * 一次性订阅
+   * @param event - 事件名称或标识符
+   * @param listener - 监听器函数
+   * @param options - 监听选项
+   * @returns 取消订阅函数
+   */
+  once<T>(
+    event: string | symbol,
+    listener: EventListener<T>,
+    options?: ListenerOptions,
+  ): () => void;
+
+  /**
+   * 取消订阅
+   * @param event - 事件名称或标识符
+   * @param listener - 监听器函数
+   */
+  off<T>(event: string | symbol, listener: EventListener<T>): void;
+
+  /**
+   * 移除指定事件的所有监听器，或移除所有事件的所有监听器
+   * @param event - 事件名称或标识符（可选）
+   */
+  removeAllListeners(event?: string | symbol): void;
+
+  /**
+   * 获取指定事件的监听器数量
+   * @param event - 事件名称或标识符
+   */
+  listenerCount(event: string | symbol): number;
+
+  /**
+   * 获取所有已注册的事件名称
+   */
+  eventNames(): (string | symbol)[];
+}
+
+/**
+ * 监听器选项
+ */
+export interface ListenerOptions {
+  /**
+   * 优先级（数值越大优先级越高）
+   * @default 0
+   */
+  priority?: number;
+
+  /**
+   * 是否异步处理
+   * @default false
+   */
+  async?: boolean;
+}
+
+/**
+ * EventModule 配置选项
+ */
+export interface EventModuleOptions {
+  /**
+   * 是否启用通配符事件（如 'user.*'）
+   * @default false
+   */
+  wildcard?: boolean;
+
+  /**
+   * 通配符分隔符
+   * @default '.'
+   */
+  delimiter?: string;
+
+  /**
+   * 全局事件前缀
+   */
+  globalPrefix?: string;
+
+  /**
+   * 最大监听器数量（防止内存泄漏）
+   * @default 10
+   */
+  maxListeners?: number;
+
+  /**
+   * 错误处理函数
+   * @param error - 错误对象
+   * @param event - 事件名称
+   * @param payload - 事件负载
+   */
+  onError?: (error: Error, event: string | symbol, payload: unknown) => void;
+}
+
+/**
+ * 装饰器方法元数据
+ */
+export interface OnEventMethodMetadata {
+  /**
+   * 方法名
+   */
+  methodName: string;
+
+  /**
+   * 事件名称或标识符
+   */
+  event: string | symbol;
+
+  /**
+   * 是否异步处理
+   */
+  async: boolean;
+
+  /**
+   * 优先级
+   */
+  priority: number;
+}
+
+/**
+ * 事件服务 Token
+ */
+export const EVENT_EMITTER_TOKEN = Symbol('@dangao/bun-server:events:emitter');
+
+/**
+ * 事件模块选项 Token
+ */
+export const EVENT_OPTIONS_TOKEN = Symbol('@dangao/bun-server:events:options');
+
+/**
+ * OnEvent 装饰器元数据 Key
+ */
+export const ON_EVENT_METADATA_KEY = Symbol('@dangao/bun-server:events:on-event');
+
+/**
+ * 事件监听器类元数据 Key
+ */
+export const EVENT_LISTENER_CLASS_METADATA_KEY = Symbol(
+  '@dangao/bun-server:events:listener-class',
+);

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,
@@ -394,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';
+