@dangao/bun-server 1.0.0 → 1.0.3

package/src/middleware/builtin/rate-limit.ts

@@ -0,0 +1,252 @@
+import type { Context } from '../../core/context';
+import type { Middleware } from '../middleware';
+
+/**
+ * 速率限制存储接口
+ */
+export interface RateLimitStore {
+  /**
+   * 获取当前计数
+   * @param key - 存储键
+   * @returns 当前计数
+   */
+  get(key: string): Promise<number>;
+
+  /**
+   * 增加计数
+   * @param key - 存储键
+   * @param windowMs - 时间窗口（毫秒）
+   * @returns 增加后的计数
+   */
+  increment(key: string, windowMs: number): Promise<number>;
+
+  /**
+   * 重置计数
+   * @param key - 存储键
+   */
+  reset(key: string): Promise<void>;
+}
+
+/**
+ * 内存存储实现（使用 Map）
+ */
+export class MemoryRateLimitStore implements RateLimitStore {
+  private store: Map<string, { count: number; resetTime: number }> = new Map();
+
+  public async get(key: string): Promise<number> {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return 0;
+    }
+
+    // 如果已过期，返回 0
+    if (Date.now() > entry.resetTime) {
+      this.store.delete(key);
+      return 0;
+    }
+
+    return entry.count;
+  }
+
+  public async increment(key: string, windowMs: number): Promise<number> {
+    const now = Date.now();
+    const entry = this.store.get(key);
+
+    if (!entry || now > entry.resetTime) {
+      // 创建新条目或重置过期条目
+      const resetTime = now + windowMs;
+      this.store.set(key, { count: 1, resetTime });
+      return 1;
+    }
+
+    // 增加计数
+    entry.count++;
+    return entry.count;
+  }
+
+  public async reset(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  /**
+   * 清理过期条目（可选，用于内存管理）
+   */
+  public cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.resetTime) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+/**
+ * 速率限制选项
+ */
+export interface RateLimitOptions {
+  /**
+   * 时间窗口内的最大请求数
+   */
+  max: number;
+
+  /**
+   * 时间窗口（毫秒）
+   * @default 60000 (1 分钟)
+   */
+  windowMs?: number;
+
+  /**
+   * 存储实现（默认使用内存存储）
+   */
+  store?: RateLimitStore;
+
+  /**
+   * 获取限流键的函数
+   * @param context - 请求上下文
+   * @returns 限流键
+   */
+  keyGenerator?: (context: Context) => string | Promise<string>;
+
+  /**
+   * 是否跳过成功响应（只对错误响应计数）
+   * @default false
+   */
+  skipSuccessfulRequests?: boolean;
+
+  /**
+   * 是否跳过失败响应（只对成功响应计数）
+   * @default false
+   */
+  skipFailedRequests?: boolean;
+
+  /**
+   * 自定义错误消息
+   */
+  message?: string;
+
+  /**
+   * 自定义错误状态码
+   * @default 429
+   */
+  statusCode?: number;
+
+  /**
+   * 是否在响应头中包含限流信息
+   * @default true
+   */
+  standardHeaders?: boolean;
+
+  /**
+   * 是否启用 X-RateLimit-* 响应头
+   * @default true
+   */
+  legacyHeaders?: boolean;
+}
+
+/**
+ * 默认键生成器：基于 IP 地址
+ */
+function defaultKeyGenerator(context: Context): string {
+  return `rate-limit:${context.getClientIp()}`;
+}
+
+/**
+ * 创建速率限制中间件
+ */
+export function createRateLimitMiddleware(options: RateLimitOptions): Middleware {
+  const {
+    max,
+    windowMs = 60000, // 默认 1 分钟
+    store = new MemoryRateLimitStore(),
+    keyGenerator = defaultKeyGenerator,
+    skipSuccessfulRequests = false,
+    skipFailedRequests = false,
+    message = 'Too Many Requests',
+    statusCode = 429,
+    standardHeaders = true,
+    legacyHeaders = true,
+  } = options;
+
+  return async (context: Context, next) => {
+    // 生成限流键
+    const key = await keyGenerator(context);
+    const currentCount = await store.increment(key, windowMs);
+
+    // 计算剩余请求数和重置时间
+    const remaining = Math.max(0, max - currentCount);
+    const resetTime = Date.now() + windowMs;
+
+    // 设置响应头
+    if (standardHeaders) {
+      context.setHeader('RateLimit-Limit', max.toString());
+      context.setHeader('RateLimit-Remaining', remaining.toString());
+      context.setHeader('RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
+    }
+
+    if (legacyHeaders) {
+      context.setHeader('X-RateLimit-Limit', max.toString());
+      context.setHeader('X-RateLimit-Remaining', remaining.toString());
+      context.setHeader('X-RateLimit-Reset', Math.ceil(resetTime / 1000).toString());
+    }
+
+    // 检查是否超过限制
+    if (currentCount > max) {
+      context.setStatus(statusCode);
+      return context.createResponse({
+        error: message,
+        retryAfter: Math.ceil(windowMs / 1000),
+      });
+    }
+
+    // 执行下一个中间件或路由处理器
+    const response = await next();
+
+    // 根据选项决定是否计数
+    const shouldSkip =
+      (skipSuccessfulRequests && response.status >= 200 && response.status < 300) ||
+      (skipFailedRequests && response.status >= 400);
+
+    if (shouldSkip) {
+      // 如果跳过，需要减少计数（因为之前已经增加了）
+      const current = await store.get(key);
+      if (current > 0) {
+        // 注意：这里不能直接减少，因为滑动窗口算法不支持
+        // 所以这个选项在滑动窗口算法下效果有限
+        // 更好的做法是在请求成功后不增加计数，但这需要重构
+      }
+    }
+
+    return response;
+  };
+}
+
+/**
+ * 基于 Token/User 的键生成器
+ */
+export function createTokenKeyGenerator(tokenHeader: string = 'Authorization'): (context: Context) => string {
+  return (context: Context) => {
+    const token = context.getHeader(tokenHeader);
+    if (token) {
+      // 提取 token（可能包含 Bearer 前缀）
+      const tokenValue = token.startsWith('Bearer ') ? token.substring(7) : token;
+      return `rate-limit:token:${tokenValue}`;
+    }
+    // 如果没有 token，回退到 IP
+    return defaultKeyGenerator(context);
+  };
+}
+
+/**
+ * 基于用户 ID 的键生成器（需要从认证上下文获取）
+ */
+export function createUserKeyGenerator(getUserId: (context: Context) => string | null | undefined): (context: Context) => string {
+  return (context: Context) => {
+    const userId = getUserId(context);
+    if (userId) {
+      return `rate-limit:user:${userId}`;
+    }
+    // 如果没有用户 ID，回退到 IP
+    return defaultKeyGenerator(context);
+  };
+}

package/src/middleware/builtin/static-file.ts

@@ -0,0 +1,88 @@
+import { normalize, resolve, sep } from 'path';
+
+import type { Middleware } from '../middleware';
+import type { HeadersInit } from 'bun'
+
+export interface StaticFileOptions {
+  root: string;
+  prefix?: string;
+  indexFile?: string;
+  enableCache?: boolean;
+  headers?: HeadersInit | Headers;
+}
+
+function isSubPath(root: string, target: string): boolean {
+  const normalizedRoot = normalize(root);
+  const normalizedTarget = normalize(target);
+  if (normalizedRoot === normalizedTarget) {
+    return true;
+  }
+  const rootWithSep = normalizedRoot.endsWith(sep) ? normalizedRoot : normalizedRoot + sep;
+  return normalizedTarget.startsWith(rootWithSep);
+}
+
+/**
+ * 静态文件服务中间件
+ */
+export function createStaticFileMiddleware(options: StaticFileOptions): Middleware {
+  if (!options.root) {
+    throw new Error('Static file middleware requires a root directory');
+  }
+
+  const root = resolve(options.root);
+  const prefix = options.prefix ?? '/';
+  const indexFile = options.indexFile ?? 'index.html';
+  const enableCache = options.enableCache ?? true;
+
+  return async (context, next) => {
+    if (!context.path.startsWith(prefix)) {
+      return await next();
+    }
+
+    let relativePath = context.path.slice(prefix.length);
+    if (!relativePath || relativePath === '') {
+      relativePath = '/';
+    }
+
+    let cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
+    if (cleanPath === '') {
+      cleanPath = '.';
+    }
+
+    const segments = cleanPath.split('/').filter((segment) => segment.length > 0);
+    if (segments.some((segment) => segment === '..')) {
+      context.setStatus(403);
+      return context.createResponse({ error: 'Forbidden' });
+    }
+
+    let targetPath = resolve(root, cleanPath);
+    if (context.path.endsWith('/') || relativePath === '/') {
+      targetPath = resolve(root, cleanPath, indexFile);
+    }
+
+    if (!isSubPath(root, targetPath)) {
+      context.setStatus(403);
+      return context.createResponse({ error: 'Forbidden' });
+    }
+
+    const file = Bun.file(targetPath);
+    if (!(await file.exists())) {
+      return await next();
+    }
+
+    const headers = new Headers(options.headers);
+    if (enableCache) {
+      headers.set('Cache-Control', 'public, max-age=31536000, immutable');
+    }
+    if (!headers.has('Content-Type') && file.type) {
+      headers.set('Content-Type', file.type);
+    }
+
+    return new Response(file, {
+      status: 200,
+      headers,
+    });
+  };
+}
+
+

package/src/middleware/decorators.ts

@@ -0,0 +1,91 @@
+import 'reflect-metadata';
+import type { Middleware } from './middleware';
+import { createRateLimitMiddleware, type RateLimitOptions } from './builtin/rate-limit';
+
+const CLASS_MIDDLEWARE_METADATA_KEY = Symbol('middleware:class');
+const METHOD_MIDDLEWARE_METADATA_KEY = Symbol('middleware:method');
+
+/**
+ * 注册中间件到元数据
+ * @param target - 目标对象
+ * @param propertyKey - 属性键
+ * @param middlewares - 中间件列表
+ */
+function appendMiddlewareMetadata(
+  target: object,
+  propertyKey: string | symbol | undefined,
+  middlewares: Middleware[],
+): void {
+  if (!middlewares.length) {
+    return;
+  }
+
+  if (propertyKey === undefined) {
+    const existing = (Reflect.getMetadata(CLASS_MIDDLEWARE_METADATA_KEY, target) as Middleware[]) || [];
+    Reflect.defineMetadata(CLASS_MIDDLEWARE_METADATA_KEY, existing.concat(middlewares), target);
+    return;
+  }
+
+  const existing =
+    (Reflect.getMetadata(METHOD_MIDDLEWARE_METADATA_KEY, target, propertyKey) as Middleware[]) || [];
+  Reflect.defineMetadata(
+    METHOD_MIDDLEWARE_METADATA_KEY,
+    existing.concat(middlewares),
+    target,
+    propertyKey,
+  );
+}
+
+/**
+ * UseMiddleware 装饰器
+ * 可用于控制器类或方法
+ * @param middlewares - 中间件列表
+ */
+export function UseMiddleware(...middlewares: Middleware[]): ClassDecorator & MethodDecorator {
+  return function (target: object, propertyKey?: string | symbol) {
+    appendMiddlewareMetadata(
+      propertyKey === undefined ? (target as object) : target,
+      propertyKey,
+      middlewares,
+    );
+  };
+}
+
+/**
+ * RateLimit 装饰器
+ * 用于在控制器方法上应用速率限制
+ * @param options - 速率限制选项
+ */
+export function RateLimit(options: RateLimitOptions): MethodDecorator {
+  return function (target: object, propertyKey: string | symbol) {
+    const middleware = createRateLimitMiddleware(options);
+    appendMiddlewareMetadata(target, propertyKey, [middleware]);
+  };
+}
+
+/**
+ * 获取类级中间件
+ * @param constructor - 控制器构造函数
+ * @returns 中间件列表
+ */
+export function getClassMiddlewares(constructor: new (...args: unknown[]) => unknown): Middleware[] {
+  return (
+    (Reflect.getMetadata(CLASS_MIDDLEWARE_METADATA_KEY, constructor) as Middleware[]) || []
+  );
+}
+
+/**
+ * 获取方法级中间件
+ * @param target - 控制器原型
+ * @param propertyKey - 方法名
+ * @returns 中间件列表
+ */
+export function getMethodMiddlewares(
+  target: object,
+  propertyKey: string | symbol,
+): Middleware[] {
+  return (
+    (Reflect.getMetadata(METHOD_MIDDLEWARE_METADATA_KEY, target, propertyKey) as Middleware[]) ||
+    []
+  );
+}

package/src/middleware/index.ts

@@ -0,0 +1,11 @@
+export type { Middleware, NextFunction } from './middleware';
+export { MiddlewarePipeline, runMiddlewares } from './pipeline';
+export { UseMiddleware, RateLimit, getClassMiddlewares, getMethodMiddlewares } from './decorators';
+export {
+  createLoggerMiddleware,
+  createRequestLoggingMiddleware,
+  createErrorHandlingMiddleware,
+  createCorsMiddleware,
+} from './builtin';
+
+

package/src/middleware/middleware.ts

@@ -0,0 +1,13 @@
+import type { Context } from '../core/context';
+
+/**
+ * 中间件 Next 函数
+ */
+export type NextFunction = () => Promise<Response>;
+
+/**
+ * 中间件接口
+ */
+export type Middleware = (context: Context, next: NextFunction) => Promise<Response> | Response;
+
+

package/src/middleware/pipeline.ts

@@ -0,0 +1,93 @@
+import type { Context } from '../core/context';
+import type { Middleware, NextFunction } from './middleware';
+
+/**
+ * 中间件执行管道
+ */
+export class MiddlewarePipeline {
+  private readonly middlewares: Middleware[] = [];
+
+  public constructor(initialMiddlewares: Middleware[] = []) {
+    this.middlewares.push(...initialMiddlewares);
+  }
+
+  /**
+   * 注册中间件
+   * @param middleware - 要注册的中间件
+   */
+  public use(middleware: Middleware): void {
+    this.middlewares.push(middleware);
+  }
+
+  /**
+   * 清空所有中间件
+   */
+  public clear(): void {
+    this.middlewares.length = 0;
+  }
+
+  /**
+   * 是否存在中间件
+   */
+  public hasMiddlewares(): boolean {
+    return this.middlewares.length > 0;
+  }
+
+  /**
+   * 执行中间件管道
+   * @param context - 请求上下文
+   * @param finalHandler - 最终处理函数
+   * @returns 响应对象
+   */
+  public async run(context: Context, finalHandler: NextFunction): Promise<Response> {
+    const length = this.middlewares.length;
+    if (length === 0) {
+      return await finalHandler();
+    }
+
+    // 优化：使用索引而不是数组来跟踪调用状态，减少内存分配
+    let currentIndex = 0;
+    const called = new Array<boolean>(length).fill(false);
+
+    // 创建链式调用函数（从后往前构建）
+    const createNext = (index: number): NextFunction => {
+      if (index >= length) {
+        return finalHandler;
+      }
+
+      return async () => {
+        if (called[index]) {
+          throw new Error('next() called multiple times');
+        }
+        called[index] = true;
+        currentIndex = index + 1;
+        const middleware = this.middlewares[index];
+        return await middleware(context, createNext(index + 1));
+      };
+    };
+
+    return await createNext(0)();
+  }
+}
+
+/**
+ * 使用指定的中间件队列执行一次性管道
+ * @param middlewares - 中间件数组
+ * @param context - 请求上下文
+ * @param finalHandler - 最终处理函数
+ * @returns 响应对象
+ */
+export async function runMiddlewares(
+  middlewares: Middleware[],
+  context: Context,
+  finalHandler: NextFunction,
+): Promise<Response> {
+  if (middlewares.length === 0) {
+    return await finalHandler();
+  }
+
+  const pipeline = new MiddlewarePipeline(middlewares);
+  return await pipeline.run(context, finalHandler);
+}
+
+

package/src/queue/decorators.ts

@@ -0,0 +1,110 @@
+import 'reflect-metadata';
+
+/**
+ * 队列装饰器元数据键
+ */
+const QUEUE_METADATA_KEY = Symbol('@dangao/bun-server:queue:queue');
+const CRON_METADATA_KEY = Symbol('@dangao/bun-server:queue:cron');
+
+/**
+ * 队列配置
+ */
+export interface QueueOptions {
+  /**
+   * 队列名称
+   * @default 'default'
+   */
+  name?: string;
+}
+
+/**
+ * Cron 配置
+ */
+export interface CronDecoratorOptions {
+  /**
+   * Cron 表达式
+   */
+  pattern: string;
+
+  /**
+   * 时区
+   * @default 'UTC'
+   */
+  timezone?: string;
+
+  /**
+   * 是否立即执行一次
+   * @default false
+   */
+  runOnInit?: boolean;
+
+  /**
+   * 队列名称
+   * @default 'default'
+   */
+  queueName?: string;
+}
+
+/**
+ * 队列装饰器元数据
+ */
+export interface QueueMetadata {
+  name?: string;
+}
+
+export interface CronMetadata {
+  pattern: string;
+  timezone?: string;
+  runOnInit?: boolean;
+  queueName?: string;
+}
+
+/**
+ * 标记方法为队列任务处理器
+ * @param options - 队列配置
+ */
+export function Queue(options: QueueOptions = {}): MethodDecorator {
+  return function (
+    target: unknown,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) {
+    const metadata: QueueMetadata = {
+      name: options.name,
+    };
+
+    Reflect.defineMetadata(QUEUE_METADATA_KEY, metadata, descriptor.value);
+  };
+}
+
+/**
+ * 标记方法为定时任务（Cron）
+ * @param options - Cron 配置
+ */
+export function Cron(options: CronDecoratorOptions): MethodDecorator {
+  return function (
+    target: unknown,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) {
+    const metadata: CronMetadata = {
+      pattern: options.pattern,
+      timezone: options.timezone,
+      runOnInit: options.runOnInit ?? false,
+      queueName: options.queueName,
+    };
+
+    Reflect.defineMetadata(CRON_METADATA_KEY, metadata, descriptor.value);
+  };
+}
+
+/**
+ * 获取队列装饰器元数据
+ */
+export function getQueueMetadata(target: unknown): QueueMetadata | undefined {
+  return Reflect.getMetadata(QUEUE_METADATA_KEY, target as object);
+}
+
+export function getCronMetadata(target: unknown): CronMetadata | undefined {
+  return Reflect.getMetadata(CRON_METADATA_KEY, target as object);
+}

package/src/queue/index.ts

@@ -0,0 +1,26 @@
+export { QueueModule } from './queue-module';
+export { QueueService } from './service';
+export {
+  Queue,
+  Cron,
+  getQueueMetadata,
+  getCronMetadata,
+  type QueueOptions,
+  type CronDecoratorOptions,
+  type QueueMetadata,
+  type CronMetadata,
+} from './decorators';
+export {
+  MemoryQueueStore,
+  QUEUE_SERVICE_TOKEN,
+  QUEUE_OPTIONS_TOKEN,
+} from './types';
+export type {
+  QueueStore,
+  QueueModuleOptions,
+  Job,
+  JobData,
+  JobHandler,
+  JobOptions,
+  CronOptions,
+} from './types';