@thinkbun/middleware 1.0.0

package/README.md

@@ -0,0 +1,290 @@
+# ThinkBun Middleware Collection
+
+A comprehensive set of middleware for ThinkBun framework, following Koa middleware specification and supporting async/await syntax and onion model execution flow.
+
+## Installation
+
+```bash
+bun add @thinkbun/middleware
+```
+
+## Available Middleware
+
+### 1. Error Handler
+
+Global error handling middleware that captures and processes errors thrown by subsequent middleware, with support for different error information display in development and production environments.
+
+#### Usage
+
+```typescript
+import { errorHandler } from '@thinkbun/middleware';
+
+// Basic usage
+app.use(errorHandler());
+
+// With custom options
+app.use(errorHandler({
+  exposeStackTrace: true, // Show stack trace in error response (only recommended for development)
+  customHandler: (error, ctx) => {
+    // Custom error handling logic
+    return new Response(JSON.stringify({ error: error.message }), {
+      status: (error as any).status || 500,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  },
+  logger: (error) => {
+    // Custom error logging
+    console.error('Error occurred:', error);
+  }
+}));
+```
+
+#### Options
+
+| Option             | Type                                       | Default | Description                                     |
+| ------------------ | ------------------------------------------ | ------- | ----------------------------------------------- |
+| `exposeStackTrace` | `boolean`                                  | `false` | Whether to expose stack trace in error response |
+| `customHandler`    | `(error: Error, ctx: Context) => Response` | -       | Custom error handling function                  |
+| `logger`           | `(error: Error, ctx: Context) => void`     | -       | Custom error logging function                   |
+
+### 2. Logger
+
+Request logging middleware that records request and response information, with support for custom log formats, path filtering, and loggers.
+
+#### Usage
+
+```typescript
+import { logger } from '@thinkbun/middleware';
+
+// Basic usage
+app.use(logger());
+
+// With custom options
+app.use(logger({
+  format: (ctx) => `${ctx.method} ${ctx.path} ${ctx.header('user-agent')}`,
+  logger: (message) => {
+    // Custom logging
+    console.log('[LOG]', message);
+  },
+  ignorePaths: ['/health', '/metrics'] // Paths to exclude from logging
+}));
+```
+
+#### Options
+
+| Option        | Type                        | Default       | Description                            |
+| ------------- | --------------------------- | ------------- | -------------------------------------- |
+| `format`      | `(ctx: Context) => string`  | -             | Custom log format function             |
+| `logger`      | `(message: string) => void` | `console.log` | Custom logger function                 |
+| `ignorePaths` | `string[]`                  | `[]`          | Array of paths to exclude from logging |
+
+### 3. Validator
+
+Request parameter validation middleware that validates request body, query parameters, and route parameters using Ajv schema validation.
+
+#### Usage
+
+```typescript
+import { validator } from '@thinkbun/middleware';
+
+app.use(validator({
+  rules: [
+    {
+      path: '/api/users',
+      method: 'POST',
+      schema: {
+        body: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            email: { type: 'string', format: 'email' },
+            age: { type: 'number', minimum: 18 }
+          },
+          required: ['name', 'email']
+        },
+        query: {
+          type: 'object',
+          properties: {
+            active: { type: 'boolean' }
+          }
+        }
+      }
+    },
+    {
+      path: '/api/users/:id',
+      method: 'GET',
+      schema: {
+        params: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', pattern: '^\\d+$' }
+          },
+          required: ['id']
+        }
+      }
+    }
+  ],
+  errorHandler: (errors, ctx) => {
+    // Custom validation error handling
+    ctx.throw(400, `Validation error: ${errors[0].message}`);
+  }
+}));
+```
+
+#### Options
+
+| Option         | Type                                    | Default | Description                               |
+| -------------- | --------------------------------------- | ------- | ----------------------------------------- |
+| `rules`        | `ValidationRule[]`                      | -       | Array of validation rules                 |
+| `errorHandler` | `(errors: any[], ctx: Context) => void` | -       | Custom validation error handling function |
+
+#### ValidationRule Interface
+
+```typescript
+interface ValidationRule {
+  path: string;           // Request path pattern to match
+  method: string;         // HTTP method to match (GET, POST, etc.)
+  schema: {
+    body?: any;          // Request body schema
+    query?: any;         // Query parameters schema
+    params?: any;        // Route parameters schema
+  };
+}
+```
+
+### 4. CORS
+
+CORS configuration middleware that handles Cross-Origin Resource Sharing, supporting flexible configuration options.
+
+#### Usage
+
+```typescript
+import { cors } from '@thinkbun/middleware';
+
+// Basic usage (default allows all origins)
+app.use(cors());
+
+// With custom options
+app.use(cors({
+  origin: ['https://example.com', 'https://sub.example.com'], // Allow specific origins
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],                // Allowed HTTP methods
+  allowedHeaders: ['Content-Type', 'Authorization'],        // Allowed request headers
+  exposedHeaders: ['X-Custom-Header'],                      // Headers exposed to client
+  credentials: true,                                        // Allow credentials
+  maxAge: 86400,                                            // Preflight request cache time (seconds)
+  preflightContinue: true                                  // Continue processing preflight requests
+}));
+```
+
+#### Options
+
+| Option              | Type                                                  | Default                                             | Description                                                                |
+| ------------------- | ----------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------- |
+| `origin`            | `string \| string[] \| ((origin: string) => boolean)` | `'*'`                                               | Allowed origins                                                            |
+| `methods`           | `string[]`                                            | `['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']` | Allowed HTTP methods                                                       |
+| `allowedHeaders`    | `string[]`                                            | -                                                   | Allowed request headers (defaults to Access-Control-Request-Headers value) |
+| `exposedHeaders`    | `string[]`                                            | -                                                   | Headers exposed to client                                                  |
+| `credentials`       | `boolean`                                             | `false`                                             | Whether to allow credentials                                               |
+| `maxAge`            | `number`                                              | `86400` (24 hours)                                  | Preflight request cache time (seconds)                                     |
+| `preflightContinue` | `boolean`                                             | `true`                                              | Whether to continue processing preflight requests                          |
+
+### 5. Static Serve
+
+Static file serving middleware that serves static files from the specified directory, with support for request path prefixes, cache control, and more.
+
+#### Usage
+
+```typescript
+import { staticServe } from '@thinkbun/middleware';
+
+// Basic usage
+app.use(staticServe({ root: './public' }));
+
+// With custom options
+app.use(staticServe({
+  root: './public',        // Static file directory
+  prefix: '/static',       // Request path prefix (e.g., /static/css/style.css)
+  index: 'index.html',     // Default index file
+  maxAge: 3600,            // Cache control max-age (seconds)
+  gzip: true,              // Enable gzip compression
+  brotli: true,            // Enable Brotli compression
+  cacheControl: true       // Enable cache control headers
+}));
+```
+
+#### Options
+
+| Option         | Type      | Default        | Description                      |
+| -------------- | --------- | -------------- | -------------------------------- |
+| `root`         | `string`  | -              | Static file directory (required) |
+| `prefix`       | `string`  | `''`           | Request path prefix              |
+| `index`        | `string`  | `'index.html'` | Default index file               |
+| `maxAge`       | `number`  | `3600`         | Cache control max-age (seconds)  |
+| `gzip`         | `boolean` | `true`         | Enable gzip compression          |
+| `brotli`       | `boolean` | `true`         | Enable Brotli compression        |
+| `cacheControl` | `boolean` | `true`         | Enable cache control headers     |
+
+## Using All Middleware
+
+You can also import all middleware at once:
+
+```typescript
+import { middlewares } from '@thinkbun/middleware';
+
+// Use all middleware
+app.use(middlewares.errorHandler());
+app.use(middlewares.logger());
+app.use(middlewares.cors());
+app.use(middlewares.staticServe({ root: './public' }));
+```
+
+## Middleware Execution Flow
+
+The middleware follows the Koa onion model, where each middleware can execute code before and after subsequent middleware:
+
+```typescript
+app.use(async (ctx, next) => {
+  // Code executed before next middleware
+  console.log('Middleware 1: before');
+
+  const response = await next();
+
+  // Code executed after next middleware
+  console.log('Middleware 1: after');
+
+  return response;
+});
+
+app.use(async (ctx, next) => {
+  console.log('Middleware 2: before');
+
+  const response = await next();
+
+  console.log('Middleware 2: after');
+
+  return response;
+});
+
+// Output when handling a request:
+// Middleware 1: before
+// Middleware 2: before
+// (Request handling)
+// Middleware 2: after
+// Middleware 1: after
+```
+
+## Best Practices
+
+1. **Order Matters**: Middleware execution follows the order in which they are added with `app.use()`. Place global middleware (like error handler, logger, CORS) before route-specific middleware.
+
+2. **Error Handler Placement**: Always place the error handler middleware first to ensure it can capture errors from all subsequent middleware.
+
+3. **Static Files**: Place the static file serving middleware before route handlers to improve performance (static files are served directly without going through route processing).
+
+4. **Validation Scope**: Use the validator middleware with specific paths and methods to avoid unnecessary validation overhead.
+
+5. **Environment-Specific Configuration**: Configure middleware differently for development and production environments (e.g., expose stack trace only in development).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@thinkbun/middleware",
+  "version": "1.0.0",
+  "module": "src/index.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "@thinkbun/core": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+import { cors as _cors, type CorsOptions } from './middlewares/cors';
+// 首先导入所有中间件
+import { errorHandler as _errorHandler, type ErrorHandlerOptions } from './middlewares/errorHandler';
+import { logger as _logger, type LoggerOptions } from './middlewares/logger';
+import { staticServe as _staticServe, type StaticOptions } from './middlewares/static';
+import { validator as _validator, type ValidatorOptions, type ValidationRule } from './middlewares/validator';
+
+// 重新导出各个中间件
+export { _errorHandler as errorHandler };
+export type { ErrorHandlerOptions };
+export { _logger as logger };
+export type { LoggerOptions };
+export { _validator as validator };
+export type { ValidatorOptions, ValidationRule };
+export { _cors as cors };
+export type { CorsOptions };
+export { _staticServe as staticServe };
+export type { StaticOptions };
+
+// 导出所有中间件的类型
+export type { Middleware, Context } from '@thinkbun/core';
+
+// 导出所有中间件的集合
+export const middlewares = {
+  errorHandler: _errorHandler,
+  logger: _logger,
+  validator: _validator,
+  cors: _cors,
+  staticServe: _staticServe,
+};
+
+export default middlewares;

package/src/middlewares/cors.ts

@@ -0,0 +1,182 @@
+import type { Context, Middleware } from '@thinkbun/core';
+
+export interface CorsOptions {
+  /**
+   * 允许的源
+   * @default '*'
+   * @example '*' | 'https://example.com' | ['https://example.com', 'https://sub.example.com'] | (origin: string) => boolean
+   */
+  origin?: string | string[] | ((origin: string) => boolean);
+  /**
+   * 允许的HTTP方法
+   * @default ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']
+   */
+  methods?: string[];
+  /**
+   * 允许的请求头
+   * @default 请求头中的Access-Control-Request-Headers值
+   */
+  allowedHeaders?: string[];
+  /**
+   * 允许客户端访问的响应头
+   */
+  exposedHeaders?: string[];
+  /**
+   * 是否允许凭证
+   * @default false
+   */
+  credentials?: boolean;
+  /**
+   * 预检请求的缓存时间（秒）
+   * @default 86400 (24小时)
+   */
+  maxAge?: number;
+  /**
+   * 是否处理预检请求
+   * @default true
+   */
+  preflightContinue?: boolean;
+}
+
+export function cors(options: CorsOptions = {}): Middleware {
+  const {
+    origin = '*',
+    methods = ['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH'],
+    allowedHeaders,
+    exposedHeaders,
+    credentials = false,
+    maxAge = 86400,
+    preflightContinue = true,
+  } = options;
+
+  // 格式化methods为字符串
+  const methodsStr = methods.join(', ').toUpperCase();
+
+  // 检查origin是否允许
+  const checkOrigin = (originHeader: string | null): string | false => {
+    if (!originHeader) return false;
+
+    if (origin === '*') {
+      return origin;
+    }
+
+    if (typeof origin === 'string') {
+      return originHeader === origin ? origin : false;
+    }
+
+    if (Array.isArray(origin)) {
+      return origin.includes(originHeader) ? originHeader : false;
+    }
+
+    if (typeof origin === 'function') {
+      return origin(originHeader) ? originHeader : false;
+    }
+
+    return false;
+  };
+
+  return async (ctx: Context, next: () => Promise<Response | Context | void>): Promise<Response | Context | void> => {
+    // 处理OPTIONS预检请求
+    if (ctx.method === 'OPTIONS') {
+      const originHeader = ctx.header('Origin');
+      const allowedOrigin = checkOrigin(originHeader);
+
+      if (!allowedOrigin) {
+        // 不允许的源，直接返回403
+        return new Response('Forbidden', { status: 403 });
+      }
+
+      // 构建预检响应
+      const preflightResponse = new Response(null, { 
+        status: 204,
+        headers: {
+          'Access-Control-Allow-Origin': allowedOrigin,
+          'Access-Control-Allow-Methods': methodsStr,
+          'Access-Control-Allow-Headers':
+            allowedHeaders?.join(', ') || ctx.header('Access-Control-Request-Headers') || '',
+          'Access-Control-Max-Age': maxAge.toString(),
+          ...(credentials && { 'Access-Control-Allow-Credentials': 'true' }),
+        },
+      });
+
+      if (!preflightContinue) {
+        return preflightResponse;
+      }
+
+      // 调用next()获取响应
+      const nextResponse = await next();
+
+      // 如果next()返回了Response对象，将CORS头合并到该对象
+      if (nextResponse instanceof Response) {
+        const headers = new Headers(nextResponse.headers);
+
+        // 复制preflightResponse的所有头到新响应
+        preflightResponse.headers.forEach((value, name) => {
+          headers.set(name, value);
+        });
+
+        return new Response(nextResponse.body, {
+          status: nextResponse.status,
+          statusText: nextResponse.statusText,
+          headers,
+        });
+      } else if (nextResponse === undefined) {
+        // 如果next()返回undefined，直接返回preflightResponse
+        return preflightResponse;
+      }
+
+      // 否则，将CORS头设置到上下文的responseHeaders
+      ctx.responseHeaders = preflightResponse.headers;
+      return nextResponse;
+    }
+
+    // 处理正常请求
+    const originHeader = ctx.header('Origin');
+    const allowedOrigin = checkOrigin(originHeader);
+
+    // 如果没有Origin头或不允许的源，直接继续执行
+    if (!originHeader || !allowedOrigin) {
+      return await next();
+    }
+
+    // 执行后续中间件
+    const response = await next();
+
+    // 设置CORS响应头
+    const setCorsHeaders = (res: Response) => {
+      const headers = new Headers(res.headers);
+      headers.set('Access-Control-Allow-Origin', allowedOrigin);
+
+      if (credentials) {
+        headers.set('Access-Control-Allow-Credentials', 'true');
+      }
+
+      if (exposedHeaders && exposedHeaders.length > 0) {
+        headers.set('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+      }
+
+      return new Response(res.body, {
+        status: res.status,
+        statusText: res.statusText,
+        headers,
+      });
+    };
+
+    if (response instanceof Response) {
+      return setCorsHeaders(response);
+    } else {
+      // 如果返回的是上下文对象或undefined，设置响应头
+      ctx.responseHeaders.set('Access-Control-Allow-Origin', allowedOrigin);
+
+      if (credentials) {
+        ctx.responseHeaders.set('Access-Control-Allow-Credentials', 'true');
+      }
+
+      if (exposedHeaders && exposedHeaders.length > 0) {
+        ctx.responseHeaders.set('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+      }
+    }
+
+    return response;
+  };
+}

package/src/middlewares/errorHandler.ts

@@ -0,0 +1,88 @@
+import type { Context, Middleware } from '@thinkbun/core';
+
+export interface ErrorHandlerOptions {
+  /**
+   * 是否在响应中包含详细错误信息
+   * @default true（开发环境）/ false（生产环境）
+   */
+  exposeStackTrace?: boolean;
+  /**
+   * 自定义错误处理函数
+   * @param error 捕获到的错误
+   * @param ctx 请求上下文
+   * @returns 返回自定义的Response对象或undefined使用默认处理
+   */
+  customHandler?: (error: Error, ctx: Context) => Response | undefined;
+  /**
+   * 错误日志记录函数
+   * @param error 捕获到的错误
+   * @param ctx 请求上下文
+   */
+  logger?: (error: Error, ctx: Context) => void;
+}
+
+export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
+  const { exposeStackTrace = process.env.NODE_ENV !== 'production', customHandler, logger = console.error } = options;
+
+  return async (ctx: Context, next: () => Promise<Response | Context | void>): Promise<Response | Context | void> => {
+    try {
+      return await next();
+    } catch (error) {
+      // 记录错误日志
+      logger(error as Error, ctx);
+
+      // 检查是否有自定义错误处理
+      if (customHandler) {
+        const customResponse = customHandler(error as Error, ctx);
+        if (customResponse) {
+          return customResponse;
+        }
+      }
+
+      // 默认错误处理
+      const err = error as Error;
+      let status = 500;
+      let message = 'Internal Server Error';
+
+      // 根据错误类型设置状态码
+      if (err.name === 'BadRequestError') {
+        status = 400;
+        message = err.message || 'Bad Request';
+      } else if (err.name === 'UnauthorizedError') {
+        status = 401;
+        message = err.message || 'Unauthorized';
+      } else if (err.name === 'ForbiddenError') {
+        status = 403;
+        message = err.message || 'Forbidden';
+      } else if (err.name === 'NotFoundError') {
+        status = 404;
+        message = err.message || 'Not Found';
+      } else if (err.name === 'MethodNotAllowedError') {
+        status = 405;
+        message = err.message || 'Method Not Allowed';
+      } else if (err.name === 'ConflictError') {
+        status = 409;
+        message = err.message || 'Conflict';
+      } else if (err.name === 'UnprocessableEntityError') {
+        status = 422;
+        message = err.message || 'Unprocessable Entity';
+      }
+
+      // 构建错误响应
+      const errorResponse = {
+        error: message,
+        ...(exposeStackTrace && {
+          stack: err.stack,
+          name: err.name,
+        }),
+      };
+
+      return ctx.json(errorResponse, {
+        status,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+    }
+  };
+}