@dangao/bun-server 1.8.1 → 1.8.2

package/docs/api.md

@@ -8,7 +8,9 @@ Framework for quick reference.
 | API                        | Description                                                                                                                                                              |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `Application(options?)`    | Main application class, supports `use` for global middleware, `registerController`/`registerWebSocketGateway` for components, and `listen/stop` for lifecycle management |
+| `BunServer(options?)`      | Low-level server wrapper, provides direct access to Bun's server API                                                                                                      |
 | `Context`                  | Unified request context, wraps `Request` and provides methods like `getQuery/getParam/getBody/setHeader/setStatus/createResponse`                                        |
+| `ContextService`           | Service for accessing request context in services, provides `getContext()` method                                                                                        |
 | `ResponseBuilder`          | Provides convenient response builders: `json/text/html/empty/redirect/error/file`                                                                                        |
 | `RouteRegistry` / `Router` | Can directly register functional routes or get the underlying `Router` for manual control                                                                                |
 
@@ -17,7 +19,7 @@ Framework for quick reference.
 - `@Controller(path)`: Declare controller prefix.
 - `@GET/@POST/@PUT/@PATCH/@DELETE(path)`: Declare HTTP methods.
 - Parameter decorators:
-  `@Body() / @Query(key) / @Param(key) / @Header(key) / @Session()`.
+  `@Body() / @Query(key) / @QueryMap() / @Param(key) / @Header(key) / @HeaderMap() / @Context()`.
 - `ControllerRegistry` automatically parses decorators and registers routes.
 
 **Example**:
@@ -191,6 +193,7 @@ For detailed information, please refer to
 - `Middleware` type: `(context, next) => Response`.
 - `MiddlewarePipeline`: `use`, `run`, `hasMiddlewares`, `clear`.
 - `@UseMiddleware(...middlewares)`: Applied to controller classes or methods.
+- `@RateLimit(options)`: Rate limiting decorator for controllers or methods.
 - Built-in middleware:
   - `createLoggerMiddleware`
   - `createRequestLoggingMiddleware`
@@ -198,6 +201,7 @@ For detailed information, please refer to
   - `createErrorHandlingMiddleware`
   - `createFileUploadMiddleware`
   - `createStaticFileMiddleware`
+  - `createRateLimitMiddleware`
 
 ## Validation
 
@@ -227,8 +231,15 @@ For detailed information, please refer to
 ## Request Utilities
 
 - `BodyParser`: `parse(request)`, automatically caches parsed results.
-- `FileHandler`: Parses `multipart/form-data`, returns structured file objects.
 - `RequestWrapper`: Lightweight wrapper for compatibility scenarios.
+- `ResponseBuilder`: Provides convenient response builders.
+
+## File Handling
+
+- `FileStorage`: File storage service for managing uploaded files.
+- `createFileUploadMiddleware(options?)`: Middleware for handling file uploads.
+- `createStaticFileMiddleware(root, options?)`: Middleware for serving static files.
+- `UploadedFileInfo`: Type definition for uploaded file information.
 
 ## Database Module
 
@@ -485,14 +496,40 @@ class OrderService {
 }
 ```
 
+## Config Module
+
+- `ConfigModule.forRoot(options)`: Configure configuration management
+- `ConfigService`: `get()`, `set()`, `has()`, `getOrThrow()`
+- `CONFIG_SERVICE_TOKEN`: Token for dependency injection
+
+**Example**:
+
+```typescript
+ConfigModule.forRoot({
+  defaultConfig: { app: { name: "MyApp", port: 3000 } },
+});
+
+@Injectable()
+class AppService {
+  public constructor(
+    @Inject(CONFIG_SERVICE_TOKEN) private readonly config: ConfigService,
+  ) {}
+
+  public getPort() {
+    return this.config.get<number>("app.port");
+  }
+}
+```
+
 ## Security Module
 
 - `SecurityModule.forRoot(options)`: Configure security and authentication
-- `@Auth(options?)`: Require authentication/authorization
 - `SecurityContextHolder`: Access current security context
 - `AuthenticationManager`: Manage authentication
 - `JwtAuthenticationProvider`: JWT authentication provider
 - `OAuth2AuthenticationProvider`: OAuth2 authentication provider
+- `createSecurityFilter()`: Create security filter middleware
+- `RoleBasedAccessDecisionManager`: Role-based access control
 
 **Example**:
 
@@ -507,96 +544,172 @@ SecurityModule.forRoot({
 @Controller("/api/users")
 class UserController {
   @GET("/profile")
-  @Auth() // Require authentication
+  public getProfile() {
+    const context = SecurityContextHolder.getContext();
+    return context.getPrincipal();
+  }
+}
+```
+
+## Guards System
+
+- `@UseGuards(...guards)`: Apply guards to controllers or methods
+- `@Roles(...roles)`: Require specific roles
+- `AuthGuard`: Require authentication
+- `OptionalAuthGuard`: Optional authentication
+- `RolesGuard`: Role-based authorization guard
+- `createRolesGuard(options)`: Create custom roles guard
+- `GuardRegistry`: Central registry for guards
+- `ExecutionContext`: Execution context for guards
+- `Reflector`: Metadata reflection utility
+
+**Example**:
+
+```typescript
+@Controller("/api/users")
+class UserController {
+  @GET("/profile")
+  @UseGuards(AuthGuard)
   public getProfile() {
     const context = SecurityContextHolder.getContext();
     return context.getPrincipal();
   }
 
   @GET("/admin")
-  @Auth({ roles: ["admin"] }) // Require admin role
+  @UseGuards(AuthGuard, RolesGuard)
+  @Roles("admin")
   public getAdmin() {
     return { message: "Admin access" };
   }
 }
 ```
 
-## Export Entry
+## Events Module
+
+- `EventModule.forRoot(options?)`: Configure event system
+- `EventEmitterService`: Event emitter service
+- `@OnEvent(event, options?)`: Register event listener method
+- `EventListenerScanner`: Scans and registers event listeners
+- `EVENT_EMITTER_TOKEN`: Token for dependency injection
 
-All above APIs can be exported from `src/index.ts`, via
-
-```ts
-import {
-  // Core
-  Application,
-  // Security
-  Auth,
-  BadRequestException,
-  CACHE_SERVICE_TOKEN,
-  Cacheable,
-  CacheEvict,
-  CacheModule,
-  // Cache
-  CacheService,
-  Column,
-  // Modules
-  ConfigModule,
-  Container,
-  Context,
-  Controller,
-  createCorsMiddleware,
-  createErrorHandlingMiddleware,
-  createLoggerMiddleware,
-  Cron,
-  DATABASE_SERVICE_TOKEN,
-  DatabaseModule,
-  // Database
-  DatabaseService,
-  DELETE,
-  Entity,
-  GET,
-  HealthModule,
-  // Errors
-  HttpException,
-  Inject,
-  // Dependency Injection
-  Injectable,
-  IsEmail,
-  IsNumber,
-  IsString,
-  LoggerModule,
-  MetricsModule,
-  Module,
-  NotFoundException,
-  OnMessage,
-  PATCH,
-  // Testing
-  PerformanceHarness,
-  POST,
-  PrimaryKey,
-  PUT,
-  Queue,
-  QUEUE_SERVICE_TOKEN,
-  QueueModule,
-  // Queue
-  QueueService,
-  Repository,
-  SecurityContextHolder,
-  SecurityModule,
-  Session,
-  SESSION_SERVICE_TOKEN,
-  SessionModule,
-  // Session
-  SessionService,
-  SwaggerModule,
-  Transactional,
-  // Middleware
-  UseMiddleware,
-  // Validation
-  Validate,
-  // WebSocket
-  WebSocketGateway,
-} from "@dangao/bun-server";
+**Example**:
+
+```typescript
+EventModule.forRoot({
+  wildcard: true,
+  maxListeners: 20,
+});
+
+@Injectable()
+class NotificationService {
+  public constructor(
+    @Inject(EVENT_EMITTER_TOKEN) private readonly eventEmitter: EventEmitter,
+  ) {}
+
+  @OnEvent('user.created')
+  public async handleUserCreated(data: { userId: string }) {
+    // Send notification
+  }
+}
 ```
 
-for use in applications.
+## Microservice Modules
+
+### Config Center Module
+
+- `ConfigCenterModule.forRoot(options)`: Configure config center (Nacos, Consul, etc.)
+- `CONFIG_CENTER_TOKEN`: Token for dependency injection
+- `NacosConfigCenter`: Nacos implementation
+
+**Example**:
+
+```typescript
+ConfigCenterModule.forRoot({
+  provider: 'nacos',
+  nacos: {
+    client: {
+      serverList: 'localhost:8848',
+      namespace: 'public',
+    },
+  },
+});
+```
+
+### Service Registry Module
+
+- `ServiceRegistryModule.forRoot(options)`: Configure service registry (Nacos, Consul, etc.)
+- `SERVICE_REGISTRY_TOKEN`: Token for dependency injection
+- `NacosServiceRegistry`: Nacos implementation
+- `@RegisterService(options)`: Register service instance
+- `@DiscoverService(serviceName)`: Discover service instances
+
+**Example**:
+
+```typescript
+ServiceRegistryModule.forRoot({
+  provider: 'nacos',
+  nacos: {
+    client: {
+      serverList: 'localhost:8848',
+    },
+  },
+});
+
+@Injectable()
+class MyService {
+  @RegisterService({
+    serviceName: 'my-service',
+    ip: '127.0.0.1',
+    port: 3000,
+  })
+  public start() {
+    // Service registered
+  }
+}
+```
+
+### Service Client
+
+- `ServiceClient`: Service-to-service communication client
+- `@ServiceClient(serviceName, options?)`: Inject service client
+- `@ServiceCall(method, path, options?)`: Declare service call
+- Load balancers: `RandomLoadBalancer`, `RoundRobinLoadBalancer`, `WeightedRoundRobinLoadBalancer`, `ConsistentHashLoadBalancer`, `LeastActiveLoadBalancer`
+- Interceptors: `TraceIdRequestInterceptor`, `UserInfoRequestInterceptor`, `RequestLogInterceptor`, etc.
+
+**Example**:
+
+```typescript
+@Injectable()
+class OrderService {
+  @ServiceClient('user-service')
+  private readonly userClient!: ServiceClient;
+
+  @ServiceCall('GET', '/users/:id')
+  public async getUser(id: string) {
+    return await this.userClient.call('GET', `/users/${id}`);
+  }
+}
+```
+
+### Governance
+
+- `CircuitBreaker`: Circuit breaker pattern implementation
+- `RateLimiter`: Rate limiting for service calls
+- `RetryStrategyImpl`: Retry strategy implementation
+
+### Tracing
+
+- `Tracer`: Distributed tracing
+- `ConsoleTraceCollector`: Console-based trace collector
+- `MemoryTraceCollector`: In-memory trace collector
+- `SpanStatus`, `SpanKind`: Span types
+
+### Monitoring
+
+- `ServiceMetricsCollector`: Service call metrics collection
+- `ServiceCallMetrics`: Metrics data structure
+- `ServiceInstanceHealth`: Health check data
+
+## Export Entry
+
+All above APIs can be exported from `src/index.ts`. See the full export list in `src/index.ts` for complete API reference.

package/docs/extensions.md

@@ -81,10 +81,12 @@ import {
   createErrorHandlingMiddleware,     // Error handling
   createFileUploadMiddleware,        // File upload
   createStaticFileMiddleware,       // Static file serving
+  createRateLimitMiddleware,        // Rate limiting
 } from '@dangao/bun-server';
 
 app.use(createLoggerMiddleware({ prefix: '[App]' }));
 app.use(createCorsMiddleware({ origin: 'https://example.com' }));
+app.use(createRateLimitMiddleware({ windowMs: 60000, max: 100 }));
 app.use(createStaticFileMiddleware({ root: './public', prefix: '/assets' }));
 ```
 
@@ -378,6 +380,57 @@ class UserController {
 - **Validation hook**: `validate(config)` can integrate class-validator style validation
 - **Non-intrusive**: Examples (`basic-app.ts` / `full-app.ts` / `multi-module-app.ts` / `auth-app.ts`) use `ConfigModule` to manage ports, logger prefixes, etc.
 
+#### EventModule (Event System)
+
+EventModule provides a powerful event-driven architecture:
+
+```typescript
+import {
+  EventModule,
+  OnEvent,
+  EVENT_EMITTER_TOKEN,
+  Injectable,
+  Inject,
+  Module,
+} from '@dangao/bun-server';
+import type { EventEmitter } from '@dangao/bun-server';
+
+// Configure Event module
+EventModule.forRoot({
+  wildcard: true,
+  maxListeners: 20,
+});
+
+@Injectable()
+class NotificationService {
+  @OnEvent('user.created')
+  public handleUserCreated(payload: { userId: string }) {
+    console.log('User created:', payload);
+  }
+}
+
+@Module({
+  imports: [EventModule],
+  providers: [NotificationService],
+})
+class AppModule {}
+```
+
+#### Other Official Modules
+
+The framework also provides:
+
+- **CacheModule**: Caching with `@Cacheable`, `@CacheEvict`, `@CachePut` decorators
+- **QueueModule**: Job queue with `@Queue` and `@Cron` decorators
+- **SessionModule**: Session management with `@Session` decorator
+- **HealthModule**: Health checks with `/health` and `/ready` endpoints
+- **MetricsModule**: Metrics collection with Prometheus support
+- **DatabaseModule**: Database connection and ORM integration
+- **ConfigCenterModule**: Configuration center (Nacos, Consul, etc.)
+- **ServiceRegistryModule**: Service registry and discovery (Nacos, Consul, etc.)
+
+For detailed documentation on these modules, see the [API Overview](./api.md).
+
 ### Complete Example
 
 ```typescript

package/docs/guide.md

@@ -25,6 +25,50 @@ app.listen();
 > Tip: Default port is 3000, can be adjusted via `app.listen(customPort)` or
 > `new Application({ port })`.
 
+### Using BunServer (Low-level API)
+
+For advanced use cases, you can use `BunServer` directly:
+
+```ts
+import { BunServer } from "@dangao/bun-server";
+
+const server = new BunServer({
+  port: 3000,
+  fetch: async (request) => {
+    // Custom request handling
+    return new Response("Hello World");
+  },
+});
+
+server.listen();
+```
+
+### Accessing Request Context in Services
+
+Use `ContextService` to access the current request context in services:
+
+```ts
+import {
+  ContextService,
+  CONTEXT_SERVICE_TOKEN,
+  Inject,
+  Injectable,
+} from "@dangao/bun-server";
+
+@Injectable()
+class UserService {
+  public constructor(
+    @Inject(CONTEXT_SERVICE_TOKEN) private readonly contextService: ContextService,
+  ) {}
+
+  public getCurrentUser() {
+    const ctx = this.contextService.getContext();
+    const userId = ctx.getHeader("x-user-id");
+    return { userId };
+  }
+}
+```
+
 ## 2. Register Controllers and Dependencies
 
 ```ts
@@ -61,12 +105,68 @@ app.registerController(UserController);
 app.listen();
 ```
 
+### Advanced Parameter Binding
+
+Bun Server supports advanced parameter binding decorators:
+
+```ts
+import {
+  Body,
+  Context,
+  Controller,
+  GET,
+  Header,
+  HeaderMap,
+  Param,
+  Query,
+  QueryMap,
+} from "@dangao/bun-server";
+
+@Controller("/api/users")
+class UserController {
+  // Get single query parameter
+  @GET("/search")
+  public search(@Query("q") query: string) {
+    return { query };
+  }
+
+  // Get all query parameters as an object
+  @GET("/filter")
+  public filter(@QueryMap() params: Record<string, string>) {
+    return { filters: params };
+  }
+
+  // Get single header
+  @GET("/profile")
+  public getProfile(@Header("authorization") token: string) {
+    return { token };
+  }
+
+  // Get all headers as an object
+  @GET("/headers")
+  public getHeaders(@HeaderMap() headers: Record<string, string>) {
+    return { headers };
+  }
+
+  // Get full context object
+  @GET("/context")
+  public getContext(@Context() ctx: Context) {
+    return {
+      method: ctx.getMethod(),
+      path: ctx.getPath(),
+      query: ctx.getQuery(),
+    };
+  }
+}
+```
+
 ## 3. Using Middleware
 
 ```ts
 import {
   createCorsMiddleware,
   createLoggerMiddleware,
+  createRateLimitMiddleware,
 } from "@dangao/bun-server";
 
 const app = new Application({ port: 3000 });
@@ -75,6 +175,14 @@ const app = new Application({ port: 3000 });
 app.use(createLoggerMiddleware({ prefix: "[App]" }));
 app.use(createCorsMiddleware({ origin: "*" }));
 
+// Rate limiting middleware
+app.use(
+  createRateLimitMiddleware({
+    windowMs: 60000, // 1 minute
+    max: 100, // 100 requests per window
+  }),
+);
+
 // Custom middleware
 app.use(async (ctx, next) => {
   console.log("Before request");
@@ -84,6 +192,29 @@ app.use(async (ctx, next) => {
 });
 ```
 
+### Rate Limiting Decorator
+
+You can also use the `@RateLimit()` decorator on controllers or methods:
+
+```ts
+import { Controller, GET, RateLimit } from "@dangao/bun-server";
+
+@Controller("/api")
+@RateLimit({ windowMs: 60000, max: 10 }) // Applied to all methods
+class ApiController {
+  @GET("/public")
+  public publicEndpoint() {
+    return { message: "Public" };
+  }
+
+  @GET("/limited")
+  @RateLimit({ windowMs: 60000, max: 5 }) // Override controller limit
+  public limitedEndpoint() {
+    return { message: "Limited" };
+  }
+}
+```
+
 ## 4. Parameter Validation
 
 ```ts
@@ -125,6 +256,7 @@ app.listen();
 import {
   createFileUploadMiddleware,
   createStaticFileMiddleware,
+  FileStorage,
 } from "@dangao/bun-server";
 
 const app = new Application({ port: 3000 });
@@ -134,6 +266,22 @@ app.use(createFileUploadMiddleware({ maxSize: 5 * 1024 * 1024 }));
 
 // Static files
 app.use(createStaticFileMiddleware({ root: "./public", prefix: "/assets" }));
+
+// Using FileStorage service
+@Injectable()
+class FileService {
+  public constructor(
+    @Inject(FileStorage) private readonly fileStorage: FileStorage,
+  ) {}
+
+  public async saveFile(file: File): Promise<string> {
+    const path = await this.fileStorage.save(file, {
+      directory: "./uploads",
+      filename: `file-${Date.now()}`,
+    });
+    return path;
+  }
+}
 ```
 
 ## 7. Error Handling and Custom Filters
@@ -928,7 +1076,101 @@ class AppService {
 }
 ```
 
-## 19. Testing Recommendations
+## 19. Microservice Support
+
+Bun Server provides comprehensive microservice architecture support, including configuration center, service registry, service client, governance, and observability.
+
+### Configuration Center
+
+```ts
+import {
+  ConfigCenterModule,
+  CONFIG_CENTER_TOKEN,
+  Inject,
+  Injectable,
+} from "@dangao/bun-server";
+import type { ConfigCenter } from "@dangao/bun-server";
+
+ConfigCenterModule.forRoot({
+  provider: "nacos",
+  nacos: {
+    client: {
+      serverList: ["http://localhost:8848"],
+      namespace: "public",
+    },
+  },
+});
+
+@Injectable()
+class ConfigService {
+  public constructor(
+    @Inject(CONFIG_CENTER_TOKEN) private readonly configCenter: ConfigCenter,
+  ) {}
+
+  public async getConfig() {
+    const config = await this.configCenter.getConfig(
+      "my-config",
+      "DEFAULT_GROUP",
+    );
+    return JSON.parse(config.content);
+  }
+}
+```
+
+### Service Registry
+
+```ts
+import {
+  RegisterService,
+  ServiceRegistryModule,
+} from "@dangao/bun-server";
+
+ServiceRegistryModule.forRoot({
+  provider: "nacos",
+  nacos: {
+    client: {
+      serverList: ["http://localhost:8848"],
+    },
+  },
+});
+
+@Injectable()
+class MyService {
+  @RegisterService({
+    serviceName: "my-service",
+    ip: "127.0.0.1",
+    port: 3000,
+  })
+  public start() {
+    // Service registered
+  }
+}
+```
+
+### Service Client
+
+```ts
+import {
+  ServiceClient,
+  ServiceCall,
+  Injectable,
+} from "@dangao/bun-server";
+
+@Injectable()
+class OrderService {
+  @ServiceClient("user-service")
+  private readonly userClient!: ServiceClient;
+
+  @ServiceCall("GET", "/users/:id")
+  public async getUser(id: string) {
+    return await this.userClient.call("GET", `/users/${id}`);
+  }
+}
+```
+
+For detailed documentation, see [Microservice Architecture](./microservice.md).
+
+## 20. Testing Recommendations
 
 - Use `tests/utils/test-port.ts` to get auto-incrementing ports, avoiding local
   conflicts.