@dangao/bun-server 1.0.0 → 1.0.3

package/src/error/http-exception.ts

@@ -0,0 +1,115 @@
+import { ErrorCode, ERROR_CODE_MESSAGES, ERROR_CODE_TO_STATUS } from './error-codes';
+import type { MessageParams } from './i18n';
+
+/**
+ * HTTP 异常基类
+ */
+export class HttpException extends Error {
+  public readonly status: number;
+  public readonly code?: ErrorCode;
+  public readonly details?: unknown;
+  public readonly messageParams?: MessageParams;
+
+  public constructor(
+    status: number,
+    message: string,
+    details?: unknown,
+    code?: ErrorCode,
+    messageParams?: MessageParams,
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.messageParams = messageParams;
+  }
+
+  /**
+   * 创建带错误码的异常
+   * @param code - 错误码
+   * @param message - 自定义错误消息（可选，如果不提供则使用默认消息）
+   * @param details - 错误详情（可选）
+   * @param messageParams - 消息模板参数（可选，用于替换消息模板中的占位符）
+   * @returns HttpException 实例
+   *
+   * @example
+   * ```ts
+   * // 基本用法
+   * HttpException.withCode(ErrorCode.RESOURCE_NOT_FOUND);
+   *
+   * // 带自定义消息
+   * HttpException.withCode(ErrorCode.RESOURCE_NOT_FOUND, 'User not found');
+   *
+   * // 带消息模板参数（如果消息模板支持）
+   * HttpException.withCode(ErrorCode.RESOURCE_NOT_FOUND, undefined, undefined, { resource: 'User' });
+   * ```
+   */
+  public static withCode(
+    code: ErrorCode,
+    message?: string,
+    details?: unknown,
+    messageParams?: MessageParams,
+  ): HttpException {
+    const status = ERROR_CODE_TO_STATUS[code] || 500;
+    const finalMessage = message || ERROR_CODE_MESSAGES[code] || 'Internal Server Error';
+    return new HttpException(status, finalMessage, details, code, messageParams);
+  }
+}
+
+export class BadRequestException extends HttpException {
+  public constructor(
+    message: string = 'Bad Request',
+    details?: unknown,
+    code?: ErrorCode,
+    messageParams?: MessageParams,
+  ) {
+    super(400, message, details, code, messageParams);
+  }
+}
+
+export class UnauthorizedException extends HttpException {
+  public constructor(
+    message: string = 'Unauthorized',
+    details?: unknown,
+    code?: ErrorCode,
+    messageParams?: MessageParams,
+  ) {
+    super(401, message, details, code, messageParams);
+  }
+}
+
+export class ForbiddenException extends HttpException {
+  public constructor(
+    message: string = 'Forbidden',
+    details?: unknown,
+    code?: ErrorCode,
+    messageParams?: MessageParams,
+  ) {
+    super(403, message, details, code, messageParams);
+  }
+}
+
+export class NotFoundException extends HttpException {
+  public constructor(
+    message: string = 'Not Found',
+    details?: unknown,
+    code?: ErrorCode,
+    messageParams?: MessageParams,
+  ) {
+    super(404, message, details, code, messageParams);
+  }
+}
+
+export class InternalServerErrorException extends HttpException {
+  public constructor(
+    message: string = 'Internal Server Error',
+    details?: unknown,
+    code?: ErrorCode,
+    messageParams?: MessageParams,
+  ) {
+    super(500, message, details, code, messageParams);
+  }
+}
+
+

package/src/error/i18n.ts

@@ -0,0 +1,217 @@
+import { ErrorCode, ERROR_CODE_MESSAGES } from './error-codes';
+
+/**
+ * 支持的语言
+ */
+export type SupportedLanguage = 'en' | 'zh-CN' | 'ja' | 'ko';
+
+/**
+ * 消息模板参数
+ */
+export interface MessageParams {
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * 错误消息国际化映射
+ * 支持消息模板，使用 {key} 作为占位符
+ * 例如：'资源 {resource} 未找到'，可以通过参数替换 {resource}
+ */
+const ERROR_MESSAGES_I18N: Record<SupportedLanguage, Partial<Record<ErrorCode, string>>> = {
+  'en': {
+    // 使用默认英文消息
+    ...ERROR_CODE_MESSAGES,
+  },
+  'zh-CN': {
+    // 通用错误
+    [ErrorCode.INTERNAL_ERROR]: '服务器内部错误',
+    [ErrorCode.INVALID_REQUEST]: '无效的请求',
+    [ErrorCode.RESOURCE_NOT_FOUND]: '资源未找到',
+    [ErrorCode.METHOD_NOT_ALLOWED]: '方法不允许',
+    [ErrorCode.RATE_LIMIT_EXCEEDED]: '请求频率超限',
+    [ErrorCode.SERVICE_UNAVAILABLE]: '服务不可用',
+    [ErrorCode.TIMEOUT]: '请求超时',
+
+    // 认证和授权错误
+    [ErrorCode.AUTH_REQUIRED]: '需要认证',
+    [ErrorCode.AUTH_INVALID_TOKEN]: '无效的认证令牌',
+    [ErrorCode.AUTH_TOKEN_EXPIRED]: '认证令牌已过期',
+    [ErrorCode.AUTH_INSUFFICIENT_PERMISSIONS]: '权限不足',
+    [ErrorCode.AUTH_INVALID_CREDENTIALS]: '无效的凭据',
+    [ErrorCode.AUTH_ACCOUNT_LOCKED]: '账户已锁定',
+    [ErrorCode.AUTH_ACCOUNT_DISABLED]: '账户已禁用',
+
+    // 验证错误
+    [ErrorCode.VALIDATION_FAILED]: '验证失败',
+    [ErrorCode.VALIDATION_REQUIRED_FIELD]: '必填字段缺失',
+    [ErrorCode.VALIDATION_INVALID_FORMAT]: '格式无效',
+    [ErrorCode.VALIDATION_OUT_OF_RANGE]: '值超出范围',
+    [ErrorCode.VALIDATION_TYPE_MISMATCH]: '类型不匹配',
+    [ErrorCode.VALIDATION_CONSTRAINT_VIOLATION]: '约束违反',
+
+    // OAuth2 错误
+    [ErrorCode.OAUTH2_INVALID_CLIENT]: '无效的客户端',
+    [ErrorCode.OAUTH2_INVALID_GRANT]: '无效的授权',
+    [ErrorCode.OAUTH2_INVALID_SCOPE]: '无效的作用域',
+    [ErrorCode.OAUTH2_INVALID_REDIRECT_URI]: '无效的重定向 URI',
+    [ErrorCode.OAUTH2_UNSUPPORTED_GRANT_TYPE]: '不支持的授权类型',
+    [ErrorCode.OAUTH2_ACCESS_DENIED]: '访问被拒绝',
+    [ErrorCode.OAUTH2_SERVER_ERROR]: 'OAuth2 服务器错误',
+
+    // 数据库错误
+    [ErrorCode.DATABASE_CONNECTION_FAILED]: '数据库连接失败',
+    [ErrorCode.DATABASE_QUERY_FAILED]: '数据库查询失败',
+    [ErrorCode.DATABASE_TRANSACTION_FAILED]: '数据库事务失败',
+    [ErrorCode.DATABASE_CONSTRAINT_VIOLATION]: '数据库约束违反',
+    [ErrorCode.DATABASE_TIMEOUT]: '数据库超时',
+    [ErrorCode.DATABASE_POOL_EXHAUSTED]: '数据库连接池耗尽',
+    [ErrorCode.DATABASE_MIGRATION_FAILED]: '数据库迁移失败',
+
+    // 文件操作错误
+    [ErrorCode.FILE_NOT_FOUND]: '文件未找到',
+    [ErrorCode.FILE_UPLOAD_FAILED]: '文件上传失败',
+    [ErrorCode.FILE_DOWNLOAD_FAILED]: '文件下载失败',
+    [ErrorCode.FILE_SIZE_EXCEEDED]: '文件大小超限',
+    [ErrorCode.FILE_TYPE_NOT_ALLOWED]: '不允许的文件类型',
+    [ErrorCode.FILE_ACCESS_DENIED]: '文件访问被拒绝',
+    [ErrorCode.FILE_PATH_TRAVERSAL]: '检测到路径遍历攻击',
+
+    // 中间件错误
+    [ErrorCode.MIDDLEWARE_EXECUTION_FAILED]: '中间件执行失败',
+    [ErrorCode.MIDDLEWARE_TIMEOUT]: '中间件超时',
+    [ErrorCode.CORS_NOT_ALLOWED]: 'CORS 不允许',
+
+    // 配置错误
+    [ErrorCode.CONFIG_INVALID]: '无效的配置',
+    [ErrorCode.CONFIG_MISSING]: '缺少配置',
+    [ErrorCode.CONFIG_VALIDATION_FAILED]: '配置验证失败',
+  },
+  'ja': {
+    // 日语翻译（部分常用错误码）
+    [ErrorCode.INTERNAL_ERROR]: 'サーバー内部エラー',
+    [ErrorCode.INVALID_REQUEST]: '無効なリクエスト',
+    [ErrorCode.RESOURCE_NOT_FOUND]: 'リソースが見つかりません',
+    [ErrorCode.AUTH_REQUIRED]: '認証が必要です',
+    [ErrorCode.AUTH_INVALID_TOKEN]: '無効な認証トークン',
+    [ErrorCode.VALIDATION_FAILED]: '検証に失敗しました',
+  },
+  'ko': {
+    // 韩语翻译（部分常用错误码）
+    [ErrorCode.INTERNAL_ERROR]: '서버 내부 오류',
+    [ErrorCode.INVALID_REQUEST]: '잘못된 요청',
+    [ErrorCode.RESOURCE_NOT_FOUND]: '리소스를 찾을 수 없습니다',
+    [ErrorCode.AUTH_REQUIRED]: '인증이 필요합니다',
+    [ErrorCode.AUTH_INVALID_TOKEN]: '잘못된 인증 토큰',
+    [ErrorCode.VALIDATION_FAILED]: '유효성 검사 실패',
+  },
+};
+
+/**
+ * 错误消息国际化服务
+ * 支持消息模板和参数替换
+ */
+export class ErrorMessageI18n {
+  private static currentLanguage: SupportedLanguage = 'en';
+
+  /**
+   * 设置当前语言
+   */
+  public static setLanguage(language: SupportedLanguage): void {
+    this.currentLanguage = language;
+  }
+
+  /**
+   * 获取当前语言
+   */
+  public static getLanguage(): SupportedLanguage {
+    return this.currentLanguage;
+  }
+
+  /**
+   * 获取错误消息（国际化）
+   * @param code - 错误码
+   * @param language - 语言（可选，默认使用当前语言）
+   * @param params - 消息模板参数（可选）
+   * @returns 国际化后的错误消息
+   *
+   * @example
+   * ```ts
+   * // 基本用法
+   * ErrorMessageI18n.getMessage(ErrorCode.RESOURCE_NOT_FOUND);
+   *
+   * // 带参数的消息模板
+   * ErrorMessageI18n.getMessage(ErrorCode.RESOURCE_NOT_FOUND, 'en', { resource: 'User' });
+   * // 如果消息模板是 'Resource {resource} not found'，则返回 'Resource User not found'
+   * ```
+   */
+  public static getMessage(
+    code: ErrorCode,
+    language?: SupportedLanguage,
+    params?: MessageParams,
+  ): string {
+    const lang = language || this.currentLanguage;
+    const messages = ERROR_MESSAGES_I18N[lang];
+    let message = messages?.[code] || ERROR_CODE_MESSAGES[code] || 'Internal Server Error';
+
+    // 如果提供了参数，替换消息模板中的占位符
+    if (params) {
+      message = this.replaceTemplate(message, params);
+    }
+
+    return message;
+  }
+
+  /**
+   * 替换消息模板中的占位符
+   * @param template - 消息模板，使用 {key} 作为占位符
+   * @param params - 参数对象
+   * @returns 替换后的消息
+   *
+   * @example
+   * ```ts
+   * replaceTemplate('Resource {resource} not found', { resource: 'User' });
+   * // 返回: 'Resource User not found'
+   * ```
+   */
+  private static replaceTemplate(template: string, params: MessageParams): string {
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+      const value = params[key];
+      return value !== undefined ? String(value) : match;
+    });
+  }
+
+  /**
+   * 从 Accept-Language 头解析语言
+   * 支持的语言：en, zh-CN, ja, ko
+   *
+   * @param acceptLanguage - Accept-Language HTTP 头值
+   * @returns 解析后的语言代码
+   *
+   * @example
+   * ```ts
+   * parseLanguageFromHeader('zh-CN,zh;q=0.9,en;q=0.8');
+   * // 返回: 'zh-CN'
+   * ```
+   */
+  public static parseLanguageFromHeader(acceptLanguage?: string | null): SupportedLanguage {
+    if (!acceptLanguage) {
+      return 'en';
+    }
+
+    const lowerAcceptLanguage = acceptLanguage.toLowerCase();
+
+    // 按优先级检查语言
+    if (lowerAcceptLanguage.includes('zh-cn') || lowerAcceptLanguage.includes('zh')) {
+      return 'zh-CN';
+    }
+    if (lowerAcceptLanguage.includes('ja')) {
+      return 'ja';
+    }
+    if (lowerAcceptLanguage.includes('ko')) {
+      return 'ko';
+    }
+
+    return 'en';
+  }
+}
+

package/src/error/index.ts

@@ -0,0 +1,16 @@
+export {
+  HttpException,
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  InternalServerErrorException,
+} from './http-exception';
+export type { ExceptionFilter } from './filter';
+export { ExceptionFilterRegistry } from './filter';
+export { handleError } from './handler';
+export { ErrorCode, ERROR_CODE_MESSAGES, ERROR_CODE_TO_STATUS } from './error-codes';
+export { ErrorMessageI18n } from './i18n';
+export type { SupportedLanguage, MessageParams } from './i18n';
+
+

package/src/extensions/index.ts

@@ -0,0 +1,5 @@
+export type { ApplicationExtension } from "./types";
+export { LOGGER_TOKEN, LoggerExtension } from "./logger-extension";
+export { LoggerModule, type LoggerModuleOptions } from "./logger-module";
+export { LoggerManager, LogLevel, SimpleLogger } from "@dangao/logsmith";
+export type { LogEntry, Logger, LoggerOptions } from "@dangao/logsmith";

package/src/extensions/logger-extension.ts

@@ -0,0 +1,31 @@
+import type { Container } from "../di/container";
+import type { ApplicationExtension } from "./types";
+import {
+  LoggerManager,
+  type LoggerOptions,
+  LogLevel,
+  SimpleLogger,
+} from "@dangao/logsmith";
+
+export const LOGGER_TOKEN = Symbol("@dangao/bun-server:logger");
+
+/**
+ * Bun Server Logger Provider
+ */
+export class LoggerExtension implements ApplicationExtension {
+  private readonly options: LoggerOptions;
+
+  public constructor(options: LoggerOptions = {}) {
+    this.options = {
+      level: LogLevel.INFO,
+      ...options,
+    };
+  }
+
+  public register(container: Container): void {
+    const logger = new SimpleLogger(this.options);
+    LoggerManager.setLogger(logger);
+    container.registerInstance(SimpleLogger, logger);
+    container.registerInstance(LOGGER_TOKEN, logger);
+  }
+}

package/src/extensions/logger-module.ts

@@ -0,0 +1,69 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import { LoggerExtension } from './logger-extension';
+import { createLoggerMiddleware } from '../middleware/builtin';
+import type { LoggerOptions } from '@dangao/logsmith';
+
+/**
+ * Logger 模块配置
+ */
+export interface LoggerModuleOptions {
+  /**
+   * Logger 选项
+   */
+  logger?: LoggerOptions;
+  /**
+   * 是否启用请求日志中间件
+   */
+  enableRequestLogging?: boolean;
+  /**
+   * 请求日志中间件前缀
+   */
+  requestLoggingPrefix?: string;
+}
+
+/**
+ * Logger 模块
+ * 提供日志功能和请求日志中间件
+ */
+@Module({
+  extensions: [
+    // 将在运行时根据配置创建
+  ],
+  middlewares: [
+    // 将在运行时根据配置创建
+  ],
+})
+export class LoggerModule {
+  /**
+   * 创建 Logger 模块
+   * @param options - 模块配置
+   */
+  public static forRoot(options: LoggerModuleOptions = {}): typeof LoggerModule {
+    const extensions: any[] = [];
+    const middlewares: any[] = [];
+
+    // 创建 Logger 扩展
+    const loggerExtension = new LoggerExtension(options.logger);
+    extensions.push(loggerExtension);
+
+    // 如果启用请求日志，添加中间件
+    if (options.enableRequestLogging !== false) {
+      const requestLoggingMiddleware = createLoggerMiddleware({
+        prefix: options.requestLoggingPrefix,
+      });
+      middlewares.push(requestLoggingMiddleware);
+    }
+
+    // 动态更新模块元数据
+    const existingMetadata = Reflect.getMetadata(MODULE_METADATA_KEY, LoggerModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      extensions,
+      middlewares,
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, LoggerModule);
+
+    return LoggerModule;
+  }
+}
+

package/src/extensions/types.ts

@@ -0,0 +1,14 @@
+import type { Container } from '../di/container';
+
+/**
+ * 应用扩展接口
+ */
+export interface ApplicationExtension {
+  /**
+   * 注册扩展
+   * @param container - 应用 DI 容器
+   */
+  register(container: Container): void;
+}
+
+

package/src/files/index.ts

@@ -0,0 +1,5 @@
+export type { UploadedFileInfo } from './types';
+export { FileStorage } from './storage';
+export { createFileUploadMiddleware } from './upload-middleware';
+export { createStaticFileMiddleware } from './static-middleware';
+

package/src/files/static-middleware.ts

@@ -0,0 +1,53 @@
+import { join, normalize } from 'node:path';
+import { stat } from 'node:fs/promises';
+
+import type { Middleware } from '../middleware';
+
+export interface StaticFileOptions {
+  root: string;
+  prefix?: string;
+  fallthrough?: boolean;
+}
+
+function safeResolve(root: string, requestPath: string): string {
+  const normalized = normalize(requestPath).replace(/^(\.\.(\/|\\|$))+/, '');
+  return join(root, normalized);
+}
+
+export function createStaticFileMiddleware(options: StaticFileOptions): Middleware {
+  const prefix = options.prefix?.replace(/\/$/, '') || '';
+  const fallthrough = options.fallthrough ?? true;
+
+  return async (context, next) => {
+    if (context.method !== 'GET' && context.method !== 'HEAD') {
+      return await next();
+    }
+
+    if (prefix && !context.path.startsWith(prefix)) {
+      return await next();
+    }
+
+    const relativePath = prefix ? context.path.slice(prefix.length) || '/' : context.path;
+    const filePath = safeResolve(options.root, relativePath);
+    try {
+      const stats = await stat(filePath);
+      if (!stats.isFile()) {
+        return await next();
+      }
+
+      const file = Bun.file(filePath);
+      return new Response(file, {
+        headers: {
+          'Content-Type': file.type || 'application/octet-stream',
+        },
+      });
+    } catch {
+      if (fallthrough) {
+        return await next();
+      }
+      return context.createResponse({ error: 'File Not Found' }, { status: 404 });
+    }
+  };
+}
+
+

package/src/files/storage.ts

@@ -0,0 +1,67 @@
+import { access, mkdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join } from 'node:path';
+
+import type { UploadedFileInfo } from './types';
+
+export interface SaveFileOptions {
+  dest: string;
+  filename?: string;
+  overwrite?: boolean;
+}
+
+async function ensureDirectory(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sanitizeFilename(value: string): string {
+  return value.replace(/[^a-zA-Z0-9.-]/g, '_');
+}
+
+export class FileStorage {
+  public static async saveFile(
+    file: File,
+    options: SaveFileOptions,
+    fieldName: string,
+  ): Promise<UploadedFileInfo> {
+    await ensureDirectory(options.dest);
+
+    const baseName = sanitizeFilename(options.filename ?? file.name ?? `file-${Date.now()}`);
+    let targetName = baseName || `file-${Date.now()}`;
+    let targetPath = join(options.dest, targetName);
+
+    if (!options.overwrite) {
+      let counter = 1;
+      const dotIndex = targetName.lastIndexOf('.');
+      const name = dotIndex > 0 ? targetName.slice(0, dotIndex) : targetName;
+      const extension = dotIndex > 0 ? targetName.slice(dotIndex) : '';
+      while (await fileExists(targetPath)) {
+        targetName = `${name}-${counter}${extension}`;
+        targetPath = join(options.dest, targetName);
+        counter += 1;
+      }
+    }
+
+    await Bun.write(targetPath, file);
+
+    return {
+      fieldName,
+      filename: targetName,
+      originalName: file.name,
+      mimeType: file.type || 'application/octet-stream',
+      size: file.size,
+      path: targetPath,
+    };
+  }
+}
+
+

package/src/files/types.ts

@@ -0,0 +1,33 @@
+export interface UploadedFileInfo {
+  /**
+   * 表单字段名
+   */
+  fieldName: string;
+
+  /**
+   * 保存后的文件名
+   */
+  filename: string;
+
+  /**
+   * 原始文件名
+   */
+  originalName?: string;
+
+  /**
+   * MIME 类型
+   */
+  mimeType: string;
+
+  /**
+   * 文件大小（字节）
+   */
+  size: number;
+
+  /**
+   * 文件保存路径
+   */
+  path: string;
+}
+
+

package/src/files/upload-middleware.ts

@@ -0,0 +1,45 @@
+import type { Middleware } from '../middleware';
+import type { UploadedFileInfo } from './types';
+import { FileStorage, type SaveFileOptions } from './storage';
+
+export interface FileUploadOptions extends Omit<SaveFileOptions, 'filename'> {
+  filename?: (fieldName: string, file: File) => string | undefined;
+}
+
+export function createFileUploadMiddleware(options: FileUploadOptions): Middleware {
+  const dest = options.dest;
+
+  return async (context, next) => {
+    const body = await context.getBody();
+    if (!(body instanceof FormData)) {
+      return await next();
+    }
+
+    const savedFiles: UploadedFileInfo[] = [];
+
+    for (const [field, value] of body.entries()) {
+      const candidate = value as unknown;
+      if (candidate instanceof File) {
+        const filename = options.filename?.(field, candidate);
+        const info = await FileStorage.saveFile(
+          candidate,
+          {
+            dest,
+            filename,
+            overwrite: options.overwrite,
+          },
+          field,
+        );
+        savedFiles.push(info);
+      }
+    }
+
+    if (savedFiles.length > 0) {
+      context.files = savedFiles;
+    }
+
+    return await next();
+  };
+}
+
+