befly 3.8.20 → 3.8.24

package/hooks/rateLimit.ts

@@ -0,0 +1,70 @@
+// 相对导入
+import { Logger } from '../lib/logger.js';
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 接口限流插件
+ *
+ * 功能：
+ * 1. 基于 Redis 实现滑动窗口或固定窗口限流
+ * 2. 支持配置格式 "count/seconds" (e.g. "10/60")
+ * 3. 针对每个用户(userId)或IP进行限制
+ */
+const hook: Hook = {
+    // 必须在 auth 之后（获取 userId），但在业务逻辑之前
+    after: ['parser'],
+    order: 25,
+
+    handler: async (befly, ctx, next) => {
+        const { api } = ctx;
+
+        // 1. 检查配置
+        if (!api || !api.rateLimit || !befly.redis) {
+            return next();
+        }
+
+        // 2. 解析配置 "10/60" -> count=10, seconds=60
+        const [countStr, secondsStr] = api.rateLimit.split('/');
+        const limitCount = parseInt(countStr, 10);
+        const limitSeconds = parseInt(secondsStr, 10);
+
+        if (isNaN(limitCount) || isNaN(limitSeconds)) {
+            Logger.warn(`[RateLimit] Invalid config: ${api.rateLimit}`);
+            return next();
+        }
+
+        // 3. 生成 Key
+        // 优先使用 userId，否则使用 IP
+        const identifier = ctx.user?.userId || ctx.ip || 'unknown';
+        const apiPath = ctx.route || `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
+        const key = `rate_limit:${apiPath}:${identifier}`;
+
+        try {
+            // 4. 执行限流逻辑 (使用 Redis INCR)
+            // 这是一个简单的固定窗口算法，对于严格场景可能需要 Lua 脚本实现滑动窗口
+            const current = await befly.redis.incr(key);
+
+            // 5. 设置过期时间 (如果是新 Key)
+            if (current === 1) {
+                await befly.redis.expire(key, limitSeconds);
+            }
+
+            // 6. 判断是否超限
+            if (current > limitCount) {
+                ctx.response = JsonResponse(ctx, '请求过于频繁，请稍后再试', 429);
+                return;
+            }
+
+            return next();
+        } catch (err) {
+            Logger.error('[RateLimit] Redis error:', err);
+            // Redis 故障时，默认放行，避免阻塞业务
+            return next();
+        }
+    }
+};
+
+export default hook;

package/hooks/requestId.ts

@@ -0,0 +1,24 @@
+import type { Hook } from '../types/hook.js';
+import { logContextStorage } from '../lib/logger.js';
+
+const hook: Hook = {
+    after: ['errorHandler'],
+    order: 3,
+    handler: async (befly, ctx, next) => {
+        // 生成唯一请求 ID
+        const requestId = crypto.randomUUID();
+        ctx.requestId = requestId;
+
+        // 添加到 CORS 响应头
+        if (!ctx.corsHeaders) {
+            ctx.corsHeaders = {};
+        }
+        ctx.corsHeaders['X-Request-ID'] = requestId;
+
+        // 在 AsyncLocalStorage 上下文中执行后续钩子
+        await logContextStorage.run({ requestId }, async () => {
+            await next();
+        });
+    }
+};
+export default hook;

package/hooks/requestLogger.ts

@@ -0,0 +1,25 @@
+// 相对导入
+import { Logger } from '../lib/logger.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 请求日志记录钩子
+ * 记录请求方法、路径、用户信息和响应时间
+ */
+const hook: Hook = {
+    after: ['parser'],
+    order: 30,
+    handler: async (befly, ctx, next) => {
+        await next();
+
+        if (ctx.api) {
+            const apiPath = `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
+            const duration = Date.now() - ctx.now;
+            const user = ctx.user?.userId ? `[User:${ctx.user.userId}]` : '[Guest]';
+            Logger.info(`[${ctx.req.method}] ${apiPath} ${user} ${duration}ms`);
+        }
+    }
+};
+export default hook;

package/hooks/responseFormatter.ts

@@ -0,0 +1,64 @@
+// 相对导入
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+const hook: Hook = {
+    after: ['requestId'],
+    order: 100,
+    handler: async (befly, ctx, next) => {
+        await next();
+
+        // 如果已经有 response，直接返回
+        if (ctx.response) {
+            return;
+        }
+
+        // 如果有 result，格式化为 JSON 响应
+        if (ctx.result !== undefined) {
+            let result = ctx.result;
+
+            // 1. 如果是字符串，自动包裹为成功响应
+            if (typeof result === 'string') {
+                result = {
+                    code: 0,
+                    msg: result,
+                    data: {}
+                };
+            }
+            // 2. 如果是对象，自动补充 code: 0
+            else if (result && typeof result === 'object') {
+                if (!('code' in result)) {
+                    result = {
+                        code: 0,
+                        ...result
+                    };
+                }
+            }
+
+            // 处理 BigInt 序列化问题
+            if (result && typeof result === 'object') {
+                const jsonString = JSON.stringify(result, (key, value) => (typeof value === 'bigint' ? value.toString() : value));
+                ctx.response = new Response(jsonString, {
+                    headers: {
+                        ...ctx.corsHeaders,
+                        'Content-Type': 'application/json'
+                    }
+                });
+            } else {
+                // 简单类型直接返回
+                ctx.response = Response.json(result, {
+                    headers: ctx.corsHeaders
+                });
+            }
+            return;
+        }
+
+        // 如果还没有响应，且不是 OPTIONS 请求，则设置默认 JSON 响应
+        if (ctx.req.method !== 'OPTIONS' && !ctx.response) {
+            ctx.response = JsonResponse(ctx, 'No response generated');
+        }
+    }
+};
+export default hook;

package/hooks/validator.ts

@@ -0,0 +1,34 @@
+// 相对导入
+import { Validator } from '../lib/validator.js';
+import { JsonResponse } from '../util.js';
+
+// 类型导入
+import type { Hook } from '../types/hook.js';
+
+/**
+ * 参数验证钩子
+ * 根据 API 定义的 fields 和 required 验证请求参数
+ */
+const hook: Hook = {
+    after: ['parser'],
+    order: 15,
+    handler: async (befly, ctx, next) => {
+        if (!ctx.api) return next();
+
+        // 无需验证
+        if (!ctx.api.fields) {
+            return next();
+        }
+
+        // 验证参数
+        const result = Validator.validate(ctx.body, ctx.api.fields, ctx.api.required || []);
+
+        if (result.code !== 0) {
+            ctx.response = JsonResponse(ctx, '无效的请求参数格式', 1, result.fields);
+            return;
+        }
+
+        await next();
+    }
+};
+export default hook;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.8.20",
+    "version": "3.8.24",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -39,38 +39,39 @@
     "homepage": "https://chensuiyi.me",
     "license": "Apache-2.0",
     "files": [
-        "sync/",
-        "config/",
-        "lib/",
-        "loader/",
-        "plugins/",
-        "router/",
-        "types/",
+        "checks",
+        "dist",
+        "hooks",
+        "lib",
+        "loader",
+        "plugins",
+        "router",
+        "sync",
+        "tests",
+        "types",
         ".npmrc",
         ".prettierignore",
         ".prettierrc",
         "bunfig.toml",
-        "tsconfig.json",
+        "config.ts",
         "LICENSE",
         "main.ts",
-        "check.ts",
         "paths.ts",
-        "response.ts",
-        "dist/",
         "package.json",
         "README.md",
+        "tsconfig.json",
         "LICENSE"
     ],
     "engines": {
         "bun": ">=1.3.0"
     },
     "dependencies": {
-        "befly-util": "0.1.2",
+        "befly-util": "^1.0.3",
         "chalk": "^5.6.2",
         "es-toolkit": "^1.41.0",
         "pathe": "^2.0.3"
     },
-    "gitHead": "e43aefa3abeda7a35669778793d39b23b4180c4e",
+    "gitHead": "6ef0daf22630fda66543e730e0fe244ac401dcfb",
     "devDependencies": {
         "typescript": "^5.9.3"
     }

package/tests/cipher.test.ts

@@ -0,0 +1,248 @@
+/**
+ * Cipher 加密工具测试
+ */
+
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Cipher } from '../lib/cipher';
+import { writeFileSync, unlinkSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+describe('Cipher - 哈希功能', () => {
+    const testData = 'hello world';
+    const testDataBytes = new TextEncoder().encode(testData);
+
+    test('MD5 哈希 - 字符串输入', () => {
+        const result = Cipher.md5(testData);
+        expect(result).toBe('5eb63bbbe01eeed093cb22bb8f5acdc3');
+        expect(result.length).toBe(32);
+    });
+
+    test('MD5 哈希 - Uint8Array 输入', () => {
+        const result = Cipher.md5(testDataBytes);
+        expect(result).toBe('5eb63bbbe01eeed093cb22bb8f5acdc3');
+    });
+
+    test('MD5 哈希 - base64 编码', () => {
+        const result = Cipher.md5(testData, 'base64');
+        expect(typeof result).toBe('string');
+        expect(result.length).toBeGreaterThan(0);
+    });
+
+    test('SHA1 哈希', () => {
+        const result = Cipher.sha1(testData);
+        expect(result).toBe('2aae6c35c94fcfb415dbe95f408b9ce91ee846ed');
+        expect(result.length).toBe(40);
+    });
+
+    test('SHA256 哈希', () => {
+        const result = Cipher.sha256(testData);
+        expect(result).toBe('b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+        expect(result.length).toBe(64);
+    });
+
+    test('SHA512 哈希', () => {
+        const result = Cipher.sha512(testData);
+        expect(result.length).toBe(128);
+        expect(typeof result).toBe('string');
+    });
+
+    test('通用 hash 方法 - SHA256', () => {
+        const result = Cipher.hash('sha256', testData);
+        expect(result).toBe('b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+    });
+
+    test('通用 hash 方法 - MD5', () => {
+        const result = Cipher.hash('md5', testData);
+        expect(result).toBe('5eb63bbbe01eeed093cb22bb8f5acdc3');
+    });
+});
+
+describe('Cipher - HMAC 签名', () => {
+    const key = 'secret-key';
+    const data = 'test data';
+
+    test('HMAC-MD5', () => {
+        const result = Cipher.hmacMd5(key, data);
+        expect(result.length).toBe(32);
+        expect(typeof result).toBe('string');
+    });
+
+    test('HMAC-SHA1', () => {
+        const result = Cipher.hmacSha1(key, data);
+        expect(result.length).toBe(40);
+        expect(typeof result).toBe('string');
+    });
+
+    test('HMAC-SHA256', () => {
+        const result = Cipher.hmacSha256(key, data);
+        expect(result.length).toBe(64);
+        expect(typeof result).toBe('string');
+    });
+
+    test('HMAC-SHA512', () => {
+        const result = Cipher.hmacSha512(key, data);
+        expect(result.length).toBe(128);
+        expect(typeof result).toBe('string');
+    });
+
+    test('通用 HMAC 方法', () => {
+        const result1 = Cipher.hmac('sha256', key, data);
+        const result2 = Cipher.hmacSha256(key, data);
+        expect(result1).toBe(result2);
+    });
+
+    test('HMAC - Uint8Array 输入', () => {
+        const keyBytes = new TextEncoder().encode(key);
+        const dataBytes = new TextEncoder().encode(data);
+        const result = Cipher.hmacSha256(keyBytes, dataBytes);
+        expect(result.length).toBe(64);
+    });
+});
+
+describe('Cipher - 密码加密', () => {
+    const password = 'MySecurePassword123!';
+
+    test('密码哈希', async () => {
+        const hash = await Cipher.hashPassword(password);
+        expect(hash).toBeDefined();
+        expect(hash.length).toBeGreaterThan(0);
+        expect(hash).not.toBe(password);
+    });
+
+    test('密码验证 - 正确密码', async () => {
+        const hash = await Cipher.hashPassword(password);
+        const isValid = await Cipher.verifyPassword(password, hash);
+        expect(isValid).toBe(true);
+    });
+
+    test('密码验证 - 错误密码', async () => {
+        const hash = await Cipher.hashPassword(password);
+        const isValid = await Cipher.verifyPassword('wrong-password', hash);
+        expect(isValid).toBe(false);
+    });
+
+    test('相同密码生成不同哈希', async () => {
+        const hash1 = await Cipher.hashPassword(password);
+        const hash2 = await Cipher.hashPassword(password);
+        expect(hash1).not.toBe(hash2);
+    });
+});
+
+describe('Cipher - Base64 编码', () => {
+    const original = 'Hello, 世界!';
+
+    test('Base64 编码', () => {
+        const encoded = Cipher.base64Encode(original);
+        expect(encoded).toBe('SGVsbG8sIOS4lueVjCE=');
+    });
+
+    test('Base64 解码', () => {
+        const encoded = 'SGVsbG8sIOS4lueVjCE=';
+        const decoded = Cipher.base64Decode(encoded);
+        expect(decoded).toBe(original);
+    });
+
+    test('Base64 编码解码循环', () => {
+        const encoded = Cipher.base64Encode(original);
+        const decoded = Cipher.base64Decode(encoded);
+        expect(decoded).toBe(original);
+    });
+
+    test('Base64 编码空字符串', () => {
+        const encoded = Cipher.base64Encode('');
+        expect(encoded).toBe('');
+    });
+});
+
+describe('Cipher - 随机字符串', () => {
+    test('生成指定长度的随机字符串', () => {
+        const result = Cipher.randomString(16);
+        expect(result.length).toBe(16);
+        expect(/^[0-9a-f]+$/.test(result)).toBe(true);
+    });
+
+    test('生成不同的随机字符串', () => {
+        const result1 = Cipher.randomString(32);
+        const result2 = Cipher.randomString(32);
+        expect(result1).not.toBe(result2);
+    });
+
+    test('生成奇数长度的随机字符串', () => {
+        const result = Cipher.randomString(15);
+        expect(result.length).toBe(15);
+    });
+
+    test('生成 0 长度字符串', () => {
+        const result = Cipher.randomString(0);
+        expect(result).toBe('');
+    });
+});
+
+describe('Cipher - 文件哈希', () => {
+    const testFilePath = join(process.cwd(), 'temp', 'cipher-test-file.txt');
+    const testContent = 'Test file content for hashing';
+
+    beforeAll(() => {
+        const tempDir = join(process.cwd(), 'temp');
+        if (!existsSync(tempDir)) {
+            mkdirSync(tempDir, { recursive: true });
+        }
+        writeFileSync(testFilePath, testContent, 'utf8');
+    });
+
+    test('SHA256 文件哈希', async () => {
+        const result = await Cipher.hashFile(testFilePath, 'sha256');
+        expect(result.length).toBe(64);
+        expect(typeof result).toBe('string');
+    });
+
+    test('MD5 文件哈希', async () => {
+        const result = await Cipher.hashFile(testFilePath, 'md5');
+        expect(result.length).toBe(32);
+    });
+
+    test('文件哈希与内容哈希一致', async () => {
+        const fileHash = await Cipher.hashFile(testFilePath, 'sha256');
+        const contentHash = Cipher.sha256(testContent);
+        expect(fileHash).toBe(contentHash);
+    });
+
+    test('文件哈希 - base64 编码', async () => {
+        const result = await Cipher.hashFile(testFilePath, 'sha256', 'base64');
+        expect(typeof result).toBe('string');
+        expect(result.length).toBeGreaterThan(0);
+    });
+});
+
+describe('Cipher - 快速哈希', () => {
+    const testData = 'quick hash test';
+
+    test('快速哈希 - 字符串输入', () => {
+        const result = Cipher.fastHash(testData);
+        expect(typeof result).toBe('bigint');
+        expect(result).toBeGreaterThan(0n);
+    });
+
+    test('快速哈希 - Uint8Array 输入', () => {
+        const bytes = new TextEncoder().encode(testData);
+        const result = Cipher.fastHash(bytes);
+        expect(typeof result).toBe('bigint');
+    });
+
+    test('快速哈希 - 相同输入产生相同哈希', () => {
+        const result1 = Cipher.fastHash(testData);
+        const result2 = Cipher.fastHash(testData);
+        expect(result1).toBe(result2);
+    });
+
+    test('快速哈希 - 不同 seed 产生不同结果', () => {
+        const result1 = Cipher.fastHash(testData, 0);
+        const result2 = Cipher.fastHash(testData, 1);
+        expect(result1).not.toBe(result2);
+    });
+
+    test('快速哈希 - 空字符串', () => {
+        const result = Cipher.fastHash('');
+        expect(typeof result).toBe('bigint');
+    });
+});