@dangao/bun-server 1.0.1 → 1.1.2

package/src/interceptor/builtin/cache-interceptor.ts

@@ -0,0 +1,169 @@
+import 'reflect-metadata';
+import { BaseInterceptor } from '../base-interceptor';
+import type { Container } from '../../di/container';
+import type { Context } from '../../core/context';
+
+/**
+ * 缓存元数据键
+ */
+export const CACHE_METADATA_KEY = Symbol('@dangao/bun-server:interceptor:cache');
+
+/**
+ * 缓存配置选项
+ */
+export interface CacheOptions {
+  /**
+   * 缓存时间（毫秒）
+   * @default 60000 (1分钟)
+   */
+  ttl?: number;
+  /**
+   * 自定义缓存键（可选）
+   * 如果不提供，将使用方法名和参数生成键
+   */
+  key?: string;
+}
+
+/**
+ * 缓存装饰器
+ * 标记方法需要缓存结果
+ * @param options - 缓存配置选项
+ */
+export function Cache(options: CacheOptions = {}): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const metadata = {
+      ttl: options.ttl ?? 60000,
+      key: options.key,
+    };
+    Reflect.defineMetadata(CACHE_METADATA_KEY, metadata, target, propertyKey);
+  };
+}
+
+/**
+ * 获取缓存元数据
+ */
+export function getCacheMetadata(
+  target: unknown,
+  propertyKey: string | symbol,
+): CacheOptions | undefined {
+  if (typeof target === 'object' && target !== null) {
+    return Reflect.getMetadata(CACHE_METADATA_KEY, target, propertyKey);
+  }
+  return undefined;
+}
+
+/**
+ * 缓存拦截器
+ * 实现方法结果缓存功能
+ */
+export class CacheInterceptor extends BaseInterceptor {
+  /**
+   * 内存缓存存储
+   * key: 缓存键
+   * value: { data: 缓存数据, expires: 过期时间戳 }
+   */
+  private static cache = new Map<
+    string,
+    { data: unknown; expires: number }
+  >();
+
+  /**
+   * 执行拦截器逻辑
+   */
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    const metadata = this.getMetadata<CacheOptions>(
+      target,
+      propertyKey,
+      CACHE_METADATA_KEY,
+    );
+
+    if (!metadata) {
+      // 没有缓存元数据，直接执行原方法
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 生成缓存键
+    const cacheKey = this.generateCacheKey(
+      target,
+      propertyKey,
+      args,
+      metadata.key,
+    );
+
+    // 检查缓存
+    const cached = CacheInterceptor.cache.get(cacheKey);
+    if (cached && cached.expires > Date.now()) {
+      // 缓存命中，返回缓存数据
+      return cached.data as T;
+    }
+
+    // 执行原方法
+    const result = await Promise.resolve(originalMethod.apply(target, args));
+
+    // 缓存结果
+    CacheInterceptor.cache.set(cacheKey, {
+      data: result,
+      expires: Date.now() + metadata.ttl!,
+    });
+
+    return result;
+  }
+
+  /**
+   * 生成缓存键
+   */
+  private generateCacheKey(
+    target: unknown,
+    propertyKey: string | symbol,
+    args: unknown[],
+    customKey?: string,
+  ): string {
+    if (customKey) {
+      return customKey;
+    }
+
+    // 使用类名、方法名和参数生成键
+    const className = typeof target === 'object' && target !== null
+      ? (target as any).constructor?.name || 'Unknown'
+      : 'Unknown';
+    const methodName = String(propertyKey);
+    const argsKey = JSON.stringify(args);
+
+    return `${className}:${methodName}:${argsKey}`;
+  }
+
+  /**
+   * 清除所有缓存
+   */
+  public static clearCache(): void {
+    CacheInterceptor.cache.clear();
+  }
+
+  /**
+   * 清除指定键的缓存
+   */
+  public static clearCacheKey(key: string): void {
+    CacheInterceptor.cache.delete(key);
+  }
+
+  /**
+   * 获取缓存统计信息
+   */
+  public static getCacheStats(): {
+    size: number;
+    keys: string[];
+  } {
+    return {
+      size: CacheInterceptor.cache.size,
+      keys: Array.from(CacheInterceptor.cache.keys()),
+    };
+  }
+}
+

package/src/interceptor/builtin/index.ts

@@ -0,0 +1,28 @@
+// Cache interceptor
+export {
+  Cache,
+  CacheInterceptor,
+  CACHE_METADATA_KEY,
+  getCacheMetadata,
+  type CacheOptions,
+} from './cache-interceptor';
+
+// Permission interceptor
+export {
+  Permission,
+  PermissionInterceptor,
+  PERMISSION_METADATA_KEY,
+  getPermissionMetadata,
+  type PermissionOptions,
+  type PermissionService,
+} from './permission-interceptor';
+
+// Log interceptor
+export {
+  Log,
+  LogInterceptor,
+  LOG_METADATA_KEY,
+  getLogMetadata,
+  type LogOptions,
+} from './log-interceptor';
+

package/src/interceptor/builtin/log-interceptor.ts

@@ -0,0 +1,178 @@
+import 'reflect-metadata';
+import { BaseInterceptor } from '../base-interceptor';
+import type { Container } from '../../di/container';
+import type { Context } from '../../core/context';
+import { LOGGER_TOKEN } from '../../extensions';
+import type { Logger } from '@dangao/logsmith';
+
+/**
+ * 日志元数据键
+ */
+export const LOG_METADATA_KEY = Symbol('@dangao/bun-server:interceptor:log');
+
+/**
+ * 日志配置选项
+ */
+export interface LogOptions {
+  /**
+   * 日志级别
+   * @default 'info'
+   */
+  level?: 'debug' | 'info' | 'warn' | 'error';
+
+  /**
+   * 自定义日志消息（可选）
+   * 如果不提供，将使用方法名
+   */
+  message?: string;
+
+  /**
+   * 是否记录方法参数
+   * @default false
+   */
+  logArgs?: boolean;
+
+  /**
+   * 是否记录返回值
+   * @default false
+   */
+  logResult?: boolean;
+
+  /**
+   * 是否记录执行时间
+   * @default true
+   */
+  logDuration?: boolean;
+}
+
+/**
+ * 日志装饰器
+ * 标记方法需要记录日志
+ * @param options - 日志配置选项
+ */
+export function Log(options: LogOptions = {}): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const metadata: LogOptions = {
+      level: options.level || 'info',
+      message: options.message,
+      logArgs: options.logArgs ?? false,
+      logResult: options.logResult ?? false,
+      logDuration: options.logDuration ?? true,
+    };
+    Reflect.defineMetadata(LOG_METADATA_KEY, metadata, target, propertyKey);
+  };
+}
+
+/**
+ * 获取日志元数据
+ */
+export function getLogMetadata(
+  target: unknown,
+  propertyKey: string | symbol,
+): LogOptions | undefined {
+  if (typeof target === 'object' && target !== null) {
+    return Reflect.getMetadata(LOG_METADATA_KEY, target, propertyKey);
+  }
+  return undefined;
+}
+
+/**
+ * 日志拦截器
+ * 记录方法执行日志，包括执行时间、参数和返回值
+ */
+export class LogInterceptor extends BaseInterceptor {
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    const options = this.getMetadata<LogOptions>(target, propertyKey, LOG_METADATA_KEY) || {};
+    const level = options.level || 'info';
+    const methodName = String(propertyKey);
+    const logMessage = options.message || `Executing ${methodName}`;
+    const logArgs = options.logArgs ?? false;
+    const logResult = options.logResult ?? false;
+    const logDuration = options.logDuration ?? true;
+
+    // Try to resolve logger from container
+    let logger: Logger | undefined;
+    try {
+      logger = container.resolve<Logger>(LOGGER_TOKEN);
+    } catch {
+      // Logger not available, use console
+    }
+
+    const log = (msg: string, data?: unknown) => {
+      if (logger) {
+        switch (level) {
+          case 'debug':
+            logger.debug(msg, data);
+            break;
+          case 'info':
+            logger.info(msg, data);
+            break;
+          case 'warn':
+            logger.warn(msg, data);
+            break;
+          case 'error':
+            logger.error(msg, data);
+            break;
+        }
+      } else {
+        console.log(`[${level.toUpperCase()}] ${msg}`, data || '');
+      }
+    };
+
+    const startTime = logDuration ? performance.now() : undefined;
+
+    // Log start
+    if (logArgs && args.length > 0) {
+      log(`${logMessage} - Start`, { args });
+    } else {
+      log(`${logMessage} - Start`);
+    }
+
+    try {
+      // Execute original method
+      const result = await Promise.resolve(originalMethod.apply(target, args));
+
+      // Calculate duration
+      const duration = startTime ? performance.now() - startTime : undefined;
+
+      // Log completion
+      const logData: Record<string, unknown> = {};
+      if (duration !== undefined) {
+        logData.duration = `${duration.toFixed(2)}ms`;
+      }
+      if (logResult) {
+        logData.result = result;
+      }
+
+      if (Object.keys(logData).length > 0) {
+        log(`${logMessage} - Completed`, logData);
+      } else {
+        log(`${logMessage} - Completed`);
+      }
+
+      return result;
+    } catch (error) {
+      // Calculate duration even on error
+      const duration = startTime ? performance.now() - startTime : undefined;
+
+      // Log error
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const logData: Record<string, unknown> = { error: errorMessage };
+      if (duration !== undefined) {
+        logData.duration = `${duration.toFixed(2)}ms`;
+      }
+
+      log(`${logMessage} - Failed`, logData);
+
+      throw error;
+    }
+  }
+}
+

package/src/interceptor/builtin/permission-interceptor.ts

@@ -0,0 +1,173 @@
+import 'reflect-metadata';
+import { BaseInterceptor } from '../base-interceptor';
+import type { Container } from '../../di/container';
+import type { Context } from '../../core/context';
+import { ForbiddenException } from '../../error';
+
+/**
+ * 权限元数据键
+ */
+export const PERMISSION_METADATA_KEY = Symbol('@dangao/bun-server:interceptor:permission');
+
+/**
+ * 权限配置选项
+ */
+export interface PermissionOptions {
+  /**
+   * 资源名称
+   */
+  resource: string;
+  /**
+   * 操作名称（如：read, write, delete）
+   */
+  action: string;
+  /**
+   * 是否允许匿名访问
+   * @default false
+   */
+  allowAnonymous?: boolean;
+}
+
+/**
+ * 权限服务接口
+ * 用户需要实现此接口来提供权限检查逻辑
+ */
+export interface PermissionService {
+  /**
+   * 检查权限
+   * @param userId - 用户 ID（从请求头或上下文获取）
+   * @param resource - 资源名称
+   * @param action - 操作名称
+   * @returns 是否有权限
+   */
+  check(userId: string | null, resource: string, action: string): Promise<boolean>;
+}
+
+/**
+ * 权限装饰器
+ * 标记方法需要权限检查
+ * @param options - 权限配置选项
+ */
+export function Permission(options: PermissionOptions): MethodDecorator {
+  return (target, propertyKey, descriptor) => {
+    const metadata = {
+      resource: options.resource,
+      action: options.action,
+      allowAnonymous: options.allowAnonymous ?? false,
+    };
+    Reflect.defineMetadata(PERMISSION_METADATA_KEY, metadata, target, propertyKey);
+  };
+}
+
+/**
+ * 获取权限元数据
+ */
+export function getPermissionMetadata(
+  target: unknown,
+  propertyKey: string | symbol,
+): PermissionOptions | undefined {
+  if (typeof target === 'object' && target !== null) {
+    return Reflect.getMetadata(PERMISSION_METADATA_KEY, target, propertyKey);
+  }
+  return undefined;
+}
+
+/**
+ * 权限拦截器
+ * 实现权限检查功能
+ */
+export class PermissionInterceptor extends BaseInterceptor {
+  /**
+   * 权限服务 Token
+   * 用户需要在 DI 容器中注册 PermissionService 实现
+   */
+  public static readonly PERMISSION_SERVICE_TOKEN = Symbol(
+    '@dangao/bun-server:interceptor:permission:service',
+  );
+
+  /**
+   * 执行拦截器逻辑
+   */
+  public async execute<T>(
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    const metadata = this.getMetadata<PermissionOptions>(
+      target,
+      propertyKey,
+      PERMISSION_METADATA_KEY,
+    );
+
+    if (!metadata) {
+      // 没有权限元数据，直接执行原方法
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 如果允许匿名访问，直接执行
+    if (metadata.allowAnonymous) {
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 获取用户 ID（从请求头或上下文）
+    const userId = this.getUserId(context);
+
+    // 尝试获取权限服务
+    let permissionService: PermissionService | undefined;
+    try {
+      permissionService = this.resolveService<PermissionService>(
+        container,
+        PermissionInterceptor.PERMISSION_SERVICE_TOKEN,
+      );
+    } catch (error) {
+      // 如果权限服务未注册，抛出错误
+      throw new Error(
+        'PermissionService not found. Please register PermissionService in DI container.',
+      );
+    }
+
+    // 检查权限
+    const hasPermission = await permissionService.check(
+      userId,
+      metadata.resource,
+      metadata.action,
+    );
+
+    if (!hasPermission) {
+      throw new ForbiddenException(
+        `Permission denied: ${metadata.action} on ${metadata.resource}`,
+      );
+    }
+
+    // 权限检查通过，执行原方法
+    return await Promise.resolve(originalMethod.apply(target, args));
+  }
+
+  /**
+   * 从上下文获取用户 ID
+   */
+  private getUserId(context: Context | undefined): string | null {
+    if (!context) {
+      return null;
+    }
+
+    // 优先从 Authorization header 获取（Bearer token）
+    const authHeader = this.getHeader(context, 'Authorization');
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+      // 这里可以解析 JWT token 获取用户 ID
+      // 简化实现：从 X-User-Id header 获取
+    }
+
+    // 从 X-User-Id header 获取
+    const userId = this.getHeader(context, 'X-User-Id');
+    if (userId) {
+      return userId;
+    }
+
+    return null;
+  }
+}
+

package/src/interceptor/index.ts

@@ -0,0 +1,26 @@
+export { type Interceptor, type InterceptorMetadata, INTERCEPTOR_REGISTRY_TOKEN } from './types';
+export { InterceptorRegistry, type InterceptorRegistry as InterceptorRegistryType } from './interceptor-registry';
+export { InterceptorChain } from './interceptor-chain';
+export { scanInterceptorMetadata } from './metadata';
+export { BaseInterceptor } from './base-interceptor';
+
+// Built-in interceptors
+export {
+  Cache,
+  CacheInterceptor,
+  CACHE_METADATA_KEY,
+  getCacheMetadata,
+  type CacheOptions,
+  Permission,
+  PermissionInterceptor,
+  PERMISSION_METADATA_KEY,
+  getPermissionMetadata,
+  type PermissionOptions,
+  type PermissionService,
+  Log,
+  LogInterceptor,
+  LOG_METADATA_KEY,
+  getLogMetadata,
+  type LogOptions,
+} from './builtin';
+

package/src/interceptor/interceptor-chain.ts

@@ -0,0 +1,79 @@
+import type { Interceptor } from './types';
+import type { Container } from '../di/container';
+import type { Context } from '../core/context';
+
+/**
+ * 拦截器链执行器
+ * 负责按优先级顺序执行多个拦截器
+ */
+export class InterceptorChain {
+  /**
+   * 执行拦截器链
+   * @param interceptors - 拦截器列表（已按优先级排序）
+   * @param target - 目标对象
+   * @param propertyKey - 方法名
+   * @param originalMethod - 原始方法
+   * @param args - 方法参数
+   * @param container - DI 容器
+   * @param context - 请求上下文（可选）
+   * @returns 方法执行结果
+   */
+  public static async execute<T>(
+    interceptors: Interceptor[],
+    target: unknown,
+    propertyKey: string | symbol,
+    originalMethod: (...args: unknown[]) => T | Promise<T>,
+    args: unknown[],
+    container: Container,
+    context?: Context,
+  ): Promise<T> {
+    if (interceptors.length === 0) {
+      // 没有拦截器，直接执行原方法
+      return await Promise.resolve(originalMethod.apply(target, args));
+    }
+
+    // 构建执行链
+    let index = 0;
+    let currentArgs = args; // Track arguments that might be modified by interceptors
+    
+    const next = async (modifiedArgs?: unknown[]): Promise<T> => {
+      // 如果拦截器传递了新参数，使用新参数；否则使用当前参数
+      if (modifiedArgs && modifiedArgs.length > 0) {
+        currentArgs = modifiedArgs;
+      }
+      
+      if (index >= interceptors.length) {
+        // 所有拦截器执行完毕，执行原方法（使用可能被修改的参数）
+        return await Promise.resolve(originalMethod.apply(target, currentArgs));
+      }
+
+      const interceptor = interceptors[index++];
+      
+      // 执行当前拦截器，传递 next 作为下一个执行函数
+      // 注意：拦截器接口要求 originalMethod 的类型是 (...args: unknown[]) => T | Promise<T>
+      // 这允许原始方法可以是同步（返回 T）或异步（返回 Promise<T>）
+      // 虽然 next 函数是异步的（总是返回 Promise<T>），但我们保持类型签名为 T | Promise<T>
+      // 以符合拦截器接口的要求。拦截器应该使用 Promise.resolve() 来统一处理同步和异步返回值
+      const wrappedNext = (...nextArgs: unknown[]): T | Promise<T> => {
+        // 如果拦截器传递了新参数，传递给 next；否则传递 undefined（使用当前参数）
+        // next 是异步函数，总是返回 Promise<T>，但类型签名允许 T | Promise<T>
+        const result = next(nextArgs.length > 0 ? nextArgs : undefined);
+        // 类型断言：虽然 result 总是 Promise<T>，但类型系统允许我们将其视为 T | Promise<T>
+        // 因为 Promise<T> 在运行时可以表示同步值（通过 Promise.resolve(syncValue)）
+        return result as T | Promise<T>;
+      };
+      
+      return await interceptor.execute(
+        target,
+        propertyKey,
+        wrappedNext,
+        currentArgs, // Pass current args to the interceptor
+        container,
+        context,
+      );
+    };
+
+    return await next();
+  }
+}
+