@dangao/bun-server 1.0.0 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -26,7 +26,9 @@
   "files": [
     "dist",
     "readme.md",
-    "LICENSE"
+    "LICENSE",
+    "src",
+    "tests"
   ],
   "author": "dangaogit",
   "license": "MIT",

package/readme.md

@@ -14,6 +14,7 @@
 - [Benchmark Suite](#benchmark-suite)
 - [Docs & Localization](#docs--localization)
 - [Roadmap](#roadmap)
+- [AI-Assisted Development](#ai-assisted-development)
 - [Engineering Guidelines](#engineering-guidelines)
 - [Contributing](#contributing)
 - [License](#license)
@@ -29,6 +30,9 @@
   provider that scales from MVP to enterprise.
 - **Well-tested**: unit, integration, stress and benchmark suites ship with the
   repo.
+- **AI-friendly**: source code and tests are included in the npm package,
+  enabling AI tools (like Cursor) to provide better code analysis, suggestions,
+  and understanding of the framework internals.
 
 ## Features
 
@@ -70,7 +74,6 @@ bun install
 ### Hello World
 
 ```ts
-import "reflect-metadata";
 import { Application, Controller, GET, Injectable } from "@dangao/bun-server";
 
 @Injectable()
@@ -108,6 +111,127 @@ bun --cwd=packages/@dangao/bun-server run bench:di
 > Running `bun test` from the repo root fails because Bun only scans the current
 > workspace. Use the commands above or `cd packages/@dangao/bun-server` first.
 
+### Advanced Example: Interface + Symbol + Module
+
+This example demonstrates using interfaces with Symbol tokens and module-based
+dependency injection:
+
+```ts
+import {
+  Application,
+  Body,
+  CONFIG_SERVICE_TOKEN,
+  ConfigModule,
+  ConfigService,
+  Controller,
+  GET,
+  Inject,
+  Injectable,
+  Module,
+  Param,
+  POST,
+} from "@dangao/bun-server";
+
+// Define service interface
+interface UserService {
+  find(id: string): Promise<{ id: string; name: string } | undefined>;
+  create(name: string): { id: string; name: string };
+}
+
+// Create Symbol token for DI
+const UserService = Symbol("UserService");
+
+// Implement the interface
+@Injectable()
+class UserServiceImpl implements UserService {
+  private readonly users = new Map<string, { id: string; name: string }>([
+    ["1", { id: "1", name: "Alice" }],
+  ]);
+
+  public async find(id: string) {
+    return this.users.get(id);
+  }
+
+  public create(name: string) {
+    const id = String(this.users.size + 1);
+    const user = { id, name };
+    this.users.set(id, user);
+    return user;
+  }
+}
+
+@Controller("/api/users")
+class UserController {
+  public constructor(
+    private readonly service: UserService,
+    @Inject(CONFIG_SERVICE_TOKEN) private readonly config: ConfigService,
+  ) {}
+
+  @GET("/:id")
+  public async getUser(@Param("id") id: string) {
+    const user = await this.service.find(id);
+    if (!user) {
+      return { error: "Not Found" };
+    }
+    return user;
+  }
+
+  @POST("/")
+  public createUser(@Body("name") name: string) {
+    return this.service.create(name);
+  }
+}
+
+// Define module with Symbol-based provider
+@Module({
+  controllers: [UserController],
+  providers: [
+    {
+      provide: UserService,
+      useClass: UserServiceImpl,
+    },
+  ],
+  exports: [UserService],
+})
+class UserModule {}
+
+// Configure modules
+ConfigModule.forRoot({
+  defaultConfig: {
+    app: {
+      name: "Advanced App",
+      port: 3100,
+    },
+  },
+});
+
+// Register module and start application
+@Module({
+  imports: [ConfigModule],
+  controllers: [UserController],
+  providers: [
+    {
+      provide: UserService,
+      useClass: UserServiceImpl,
+    },
+  ],
+})
+class AppModule {}
+
+const app = new Application({ port: 3100 });
+app.registerModule(AppModule);
+app.listen();
+```
+
+**Key points:**
+
+- **Interface-based design**: Define contracts with TypeScript interfaces
+- **Symbol tokens**: Use `Symbol()` for type-safe dependency injection tokens
+- **Module providers**: Register providers using
+  `provide: Symbol, useClass: Implementation`
+- **Type-safe injection**: Inject services using `@Inject(Symbol)` with
+  interface types
+
 ## Examples & Extensions
 
 - `examples/basic-app.ts`: minimal DI + Logger + Middleware showcase.
@@ -137,7 +261,9 @@ Or use `bun run bench*` scripts for convenience.
 ## Docs & Localization
 
 - **English** (default): `docs/api.md`, `docs/guide.md`,
-  `docs/best-practices.md`, `docs/migration.md`, `docs/extensions.md`.
+  `docs/best-practices.md`, `docs/migration.md`, `docs/extensions.md`,
+  `docs/deployment.md`, `docs/performance.md`, `docs/troubleshooting.md`,
+  `docs/error-handling.md`.
 - **Chinese**: mirrored under `docs/zh/`. If something is missing, please fall
   back to the English source.
 
@@ -146,6 +272,41 @@ Or use `bun run bench*` scripts for convenience.
 Detailed milestones and history are tracked in
 [`.roadmap/v0.3.0.md`](./.roadmap/v0.3.0.md).
 
+## AI-Assisted Development
+
+Bun Server is designed to work seamlessly with AI coding assistants like Cursor,
+GitHub Copilot, and others. The framework includes source code and tests in the
+npm package distribution, enabling AI tools to:
+
+- **Understand framework internals**: AI can analyze the actual implementation
+  code, not just type definitions, providing more accurate suggestions.
+- **Provide context-aware help**: When you ask about framework features, AI can
+  reference the actual source code to give precise answers.
+- **Suggest best practices**: AI can learn from the framework's patterns and
+  suggest similar approaches in your code.
+- **Debug more effectively**: AI can trace through the framework code to help
+  diagnose issues.
+
+### Best Practices for AI-Assisted Development
+
+1. **Reference framework source**: When working with Bun Server, AI tools can
+   access the source code at `node_modules/@dangao/bun-server/src/` to
+   understand implementation details.
+
+2. **Use type hints**: The framework provides comprehensive TypeScript types.
+   Leverage these in your code to help AI understand your intent better.
+
+3. **Follow framework patterns**: The included source code serves as a reference
+   for framework patterns. Ask AI to suggest code that follows similar patterns.
+
+4. **Leverage test examples**: The included test files demonstrate usage
+   patterns and edge cases. Reference these when asking AI for implementation
+   help.
+
+5. **Ask specific questions**: Since AI can access the framework source, you can
+   ask specific questions like "How does the DI container resolve dependencies?"
+   and get accurate answers based on the actual code.
+
 ## Engineering Guidelines
 
 - Comments & log messages **must be in English** to keep the codebase

package/src/auth/controller.ts

@@ -0,0 +1,148 @@
+import { Controller, Query, Body } from '../controller';
+import { GET, POST } from '../router/decorators';
+import { Injectable, Inject } from '../di';
+import { ResponseBuilder } from '../request';
+import { OAuth2Service } from './oauth2';
+import { Auth } from './decorators';
+import type {
+  OAuth2AuthorizationRequest,
+  OAuth2TokenRequest,
+  OAuth2TokenResponse,
+} from './types';
+
+/**
+ * OAuth2 令牌 Token
+ */
+export const OAUTH2_SERVICE_TOKEN = Symbol('OAUTH2_SERVICE');
+export const JWT_UTIL_TOKEN = Symbol('JWT_UTIL');
+
+/**
+ * OAuth2 控制器
+ */
+@Controller('/oauth2')
+@Injectable()
+export class OAuth2Controller {
+  public constructor(
+    @Inject(OAUTH2_SERVICE_TOKEN) private readonly oauth2Service: OAuth2Service,
+  ) {}
+
+  /**
+   * 授权端点
+   * GET /oauth2/authorize?client_id=...&redirect_uri=...&response_type=code&state=...
+   */
+  @GET('/authorize')
+  public authorize(
+    @Query('client_id') clientId: string | null,
+    @Query('redirect_uri') redirectUri: string | null,
+    @Query('response_type') responseType: string | null,
+    @Query('state') state?: string | null,
+    @Query('scope') scope?: string | null,
+  ) {
+    // 验证必需参数
+    if (!clientId || !redirectUri) {
+      throw new Error('Missing required parameters: client_id and redirect_uri are required');
+    }
+
+    if (responseType !== 'code') {
+      throw new Error(`Unsupported response_type: ${responseType}. Only 'code' is supported.`);
+    }
+
+    const request: OAuth2AuthorizationRequest = {
+      clientId,
+      redirectUri,
+      responseType: 'code',
+      scope: scope || undefined,
+      state: state || undefined,
+    };
+
+    // 验证请求
+    const validation = this.oauth2Service.validateAuthorizationRequest(request);
+    if (!validation.valid) {
+      throw new Error(`Invalid authorization request: ${validation.error}`);
+    }
+
+    // 这里应该显示授权页面，让用户登录并授权
+    // 为了简化，我们假设用户已经登录，使用默认用户 ID
+    const userId = 'user-1';
+
+    // 生成授权码
+    const code = this.oauth2Service.generateAuthorizationCode(
+      request.clientId,
+      request.redirectUri,
+      userId,
+      request.scope,
+    );
+
+    // 构建重定向 URL
+    const redirectUrl = new URL(request.redirectUri);
+    redirectUrl.searchParams.set('code', code);
+    if (request.state) {
+      redirectUrl.searchParams.set('state', request.state);
+    }
+
+    // 返回重定向 URL（框架会处理）
+    // 注意：实际实现中可能需要使用 ResponseBuilder.redirect()
+    return ResponseBuilder.redirect(redirectUrl.toString());
+  }
+
+  /**
+   * 令牌端点
+   * POST /oauth2/token
+   */
+  @POST('/token')
+  public async token(@Body() body: Record<string, string>): Promise<OAuth2TokenResponse | any> {
+    const request: OAuth2TokenRequest = {
+      code: body.code || '',
+      clientId: body.client_id || '',
+      clientSecret: body.client_secret || '',
+      redirectUri: body.redirect_uri || '',
+      grantType: (body.grant_type as 'authorization_code' | 'refresh_token') || 'authorization_code',
+      refreshToken: body.refresh_token,
+    };
+
+    if (request.grantType === 'authorization_code') {
+      const tokenResponse = await this.oauth2Service.exchangeCodeForToken(request);
+      if (!tokenResponse) {
+        return {
+          error: 'invalid_grant',
+          error_description: 'Invalid authorization code',
+        };
+      }
+      return tokenResponse;
+    }
+
+    if (request.grantType === 'refresh_token' && request.refreshToken) {
+      const tokenResponse = await this.oauth2Service.refreshToken(request.refreshToken);
+      if (!tokenResponse) {
+        return {
+          error: 'invalid_grant',
+          error_description: 'Invalid refresh token',
+        };
+      }
+      return tokenResponse;
+    }
+
+    return {
+      error: 'unsupported_grant_type',
+      error_description: 'Unsupported grant type',
+    };
+  }
+
+  /**
+   * 用户信息端点
+   * GET /oauth2/userinfo
+   * 注意：此端点需要认证，应该通过认证中间件保护
+   */
+  @GET('/userinfo')
+  @Auth()
+  public userinfo() {
+    // 用户信息应该通过认证中间件注入到 Context
+    // 这里简化处理，返回占位符
+    return {
+      sub: 'user-1',
+      username: 'alice',
+      roles: ['user'],
+    };
+  }
+}
+

package/src/auth/decorators.ts

@@ -0,0 +1,81 @@
+import 'reflect-metadata';
+
+/**
+ * 认证元数据键
+ */
+const AUTH_METADATA_KEY = Symbol('@dangao/bun-server:auth');
+
+/**
+ * 认证配置
+ */
+export interface AuthConfig {
+  /**
+   * 是否需要认证
+   * @default true
+   */
+  required?: boolean;
+  /**
+   * 允许的角色列表
+   */
+  roles?: string[];
+  /**
+   * 是否允许匿名访问
+   * @default false
+   */
+  allowAnonymous?: boolean;
+}
+
+/**
+ * 认证装饰器
+ * 用于标记需要认证的路由
+ */
+export function Auth(config: AuthConfig = {}): MethodDecorator {
+  return (target: Object, propertyKey: string | symbol) => {
+    const metadata = Reflect.getMetadata(AUTH_METADATA_KEY, target) || {};
+    metadata[propertyKey] = {
+      required: config.required !== false,
+      roles: config.roles || [],
+      allowAnonymous: config.allowAnonymous || false,
+    };
+    Reflect.defineMetadata(AUTH_METADATA_KEY, metadata, target);
+  };
+}
+
+/**
+ * 获取认证元数据
+ */
+export function getAuthMetadata(
+  target: Object,
+  propertyKey: string | symbol,
+): AuthConfig | undefined {
+  const metadata = Reflect.getMetadata(AUTH_METADATA_KEY, target);
+  return metadata?.[propertyKey];
+}
+
+/**
+ * 检查是否需要认证
+ */
+export function requiresAuth(target: Object, propertyKey: string | symbol): boolean {
+  const config = getAuthMetadata(target, propertyKey);
+  // 如果没有配置，默认不需要认证；只有显式标注 @Auth 时才进入认证流程
+  if (!config) {
+    return false;
+  }
+  return config.required !== false;
+}
+
+/**
+ * 检查角色权限
+ */
+export function checkRoles(
+  target: Object,
+  propertyKey: string | symbol,
+  userRoles: string[] = [],
+): boolean {
+  const config = getAuthMetadata(target, propertyKey);
+  if (!config?.roles || config.roles.length === 0) {
+    return true;
+  }
+  return config.roles.some((role) => userRoles.includes(role));
+}
+

package/src/auth/index.ts

@@ -0,0 +1,12 @@
+// 核心实现（保留）
+export * from './types';
+export * from './jwt';
+export * from './oauth2';
+export * from './decorators';
+export * from './controller';
+
+// 已废弃，请使用 SecurityModule
+// export * from './middleware';
+// export { AuthModule } from './auth-module';
+// export { AuthExtension } from './auth-extension';
+

package/src/auth/jwt.ts

@@ -0,0 +1,169 @@
+import type { JWTConfig, JWTPayload } from './types';
+
+/**
+ * JWT 工具类
+ */
+export class JWTUtil {
+  private readonly config: Required<JWTConfig>;
+
+  public constructor(config: JWTConfig) {
+    this.config = {
+      secret: config.secret,
+      accessTokenExpiresIn: config.accessTokenExpiresIn ?? 3600,
+      refreshTokenExpiresIn: config.refreshTokenExpiresIn ?? 86400 * 7,
+      algorithm: config.algorithm ?? 'HS256',
+    };
+  }
+
+  /**
+   * 生成访问令牌
+   * @param payload - JWT 载荷
+   * @returns 访问令牌
+   */
+  public generateAccessToken(payload: Omit<JWTPayload, 'exp' | 'iat'>): string {
+    const now = Math.floor(Date.now() / 1000);
+    const tokenPayload: JWTPayload = {
+      ...payload,
+      sub: payload.sub as string,
+      iat: now,
+      exp: now + this.config.accessTokenExpiresIn,
+    };
+    return this.sign(tokenPayload);
+  }
+
+  /**
+   * 生成刷新令牌
+   * @param payload - JWT 载荷
+   * @returns 刷新令牌
+   */
+  public generateRefreshToken(payload: Omit<JWTPayload, 'exp' | 'iat'>): string {
+    const now = Math.floor(Date.now() / 1000);
+    const tokenPayload: JWTPayload = {
+      ...payload,
+      sub: payload.sub as string,
+      iat: now,
+      exp: now + this.config.refreshTokenExpiresIn,
+    };
+    return this.sign(tokenPayload);
+  }
+
+  /**
+   * 验证令牌
+   * @param token - JWT 令牌
+   * @returns 载荷或 null（如果无效）
+   */
+  public verify(token: string): JWTPayload | null {
+    try {
+      const parts = token.split('.');
+      if (parts.length !== 3) {
+        return null;
+      }
+
+      // 解析载荷
+      const payload = JSON.parse(
+        Buffer.from(parts[1], 'base64url').toString('utf-8'),
+      ) as JWTPayload;
+
+      // 验证签名
+      const signature = this.signature(parts[0] + '.' + parts[1]);
+      if (signature !== parts[2]) {
+        return null;
+      }
+
+      // 验证过期时间
+      if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+        return null;
+      }
+
+      return payload;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 签名 JWT
+   */
+  private sign(payload: JWTPayload): string {
+    const header = {
+      alg: this.config.algorithm,
+      typ: 'JWT',
+    };
+
+    const encodedHeader = this.base64UrlEncode(JSON.stringify(header));
+    const encodedPayload = this.base64UrlEncode(JSON.stringify(payload));
+    const signature = this.signature(encodedHeader + '.' + encodedPayload);
+
+    return `${encodedHeader}.${encodedPayload}.${signature}`;
+  }
+
+  /**
+   * 生成签名
+   */
+  private signature(data: string): string {
+    // 使用 Bun 的 CryptoHasher
+    const encoder = new TextEncoder();
+    const keyData = encoder.encode(this.config.secret);
+    const messageData = encoder.encode(data);
+
+    // 使用 HMAC-SHA256
+    const hash = this.hmacSha256(keyData, messageData);
+    return this.base64UrlEncode(Buffer.from(hash).toString('base64'));
+  }
+
+  /**
+   * HMAC-SHA256 实现
+   */
+  private hmacSha256(key: Uint8Array, data: Uint8Array): Uint8Array {
+    const blockSize = 64;
+    let keyBuffer: Uint8Array;
+
+    if (key.length > blockSize) {
+      // 如果密钥长度超过块大小，先哈希
+      const hasher = new Bun.CryptoHasher('sha256');
+      hasher.update(key);
+      keyBuffer = new Uint8Array(hasher.digest());
+    } else {
+      keyBuffer = new Uint8Array(blockSize);
+      keyBuffer.set(key);
+    }
+
+    // 创建 o_key_pad 和 i_key_pad
+    const oKeyPad = new Uint8Array(blockSize);
+    const iKeyPad = new Uint8Array(blockSize);
+
+    for (let i = 0; i < blockSize; i++) {
+      oKeyPad[i] = keyBuffer[i] ^ 0x5c;
+      iKeyPad[i] = keyBuffer[i] ^ 0x36;
+    }
+
+    // 计算 inner hash
+    const innerData = new Uint8Array(iKeyPad.length + data.length);
+    innerData.set(iKeyPad);
+    innerData.set(data, iKeyPad.length);
+    const innerHasher = new Bun.CryptoHasher('sha256');
+    innerHasher.update(innerData);
+    const innerHash = new Uint8Array(innerHasher.digest());
+
+    // 计算 outer hash
+    const outerData = new Uint8Array(oKeyPad.length + innerHash.length);
+    outerData.set(oKeyPad);
+    outerData.set(innerHash, oKeyPad.length);
+    const outerHasher = new Bun.CryptoHasher('sha256');
+    outerHasher.update(outerData);
+
+    return new Uint8Array(outerHasher.digest());
+  }
+
+  /**
+   * Base64URL 编码
+   */
+  private base64UrlEncode(str: string): string {
+    return Buffer.from(str)
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '');
+  }
+}
+