@onebots/core 0.5.0 → 1.0.0

package/lib/retry.js

@@ -0,0 +1,205 @@
+/**
+ * 重试策略和网络请求重试机制
+ * 提供统一的重试逻辑，支持指数退避
+ */
+const DEFAULT_OPTIONS = {
+    maxRetries: 3,
+    initialDelay: 1000,
+    maxDelay: 30000,
+    backoffMultiplier: 2,
+    jitter: true,
+    shouldRetry: (error) => {
+        // 默认对网络错误和超时错误进行重试
+        const message = error.message.toLowerCase();
+        return (message.includes('timeout') ||
+            message.includes('network') ||
+            message.includes('econnreset') ||
+            message.includes('econnrefused') ||
+            message.includes('socket') ||
+            message.includes('fetch failed'));
+    },
+    onRetry: () => { },
+};
+/**
+ * 计算下一次重试的延迟时间
+ */
+function calculateDelay(attempt, options) {
+    let delay = options.initialDelay * Math.pow(options.backoffMultiplier, attempt - 1);
+    // 添加随机抖动（±25%）
+    if (options.jitter) {
+        const jitterFactor = 0.75 + Math.random() * 0.5;
+        delay *= jitterFactor;
+    }
+    return Math.min(delay, options.maxDelay);
+}
+/**
+ * 等待指定时间
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * 带重试的异步函数执行器
+ *
+ * @example
+ * ```typescript
+ * const result = await retry(
+ *     () => fetch('https://api.example.com/data'),
+ *     { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export async function retry(fn, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    let lastError;
+    for (let attempt = 1; attempt <= opts.maxRetries + 1; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // 检查是否还有重试机会
+            if (attempt > opts.maxRetries) {
+                break;
+            }
+            // 检查是否应该重试
+            if (!opts.shouldRetry(lastError, attempt)) {
+                break;
+            }
+            // 计算延迟并等待
+            const delay = calculateDelay(attempt, opts);
+            opts.onRetry(lastError, attempt, delay);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+/**
+ * 创建一个带重试功能的函数包装器
+ *
+ * @example
+ * ```typescript
+ * const fetchWithRetry = withRetry(fetch, { maxRetries: 3 });
+ * const response = await fetchWithRetry('https://api.example.com/data');
+ * ```
+ */
+export function withRetry(fn, options = {}) {
+    return ((...args) => {
+        return retry(() => fn(...args), options);
+    });
+}
+/**
+ * 重试策略预设
+ */
+export const RetryPresets = {
+    /** 快速重试：3次，1秒起始 */
+    fast: {
+        maxRetries: 3,
+        initialDelay: 1000,
+        maxDelay: 5000,
+        backoffMultiplier: 1.5,
+    },
+    /** 标准重试：5次，2秒起始 */
+    standard: {
+        maxRetries: 5,
+        initialDelay: 2000,
+        maxDelay: 30000,
+        backoffMultiplier: 2,
+    },
+    /** 持久重试：10次，5秒起始 */
+    persistent: {
+        maxRetries: 10,
+        initialDelay: 5000,
+        maxDelay: 60000,
+        backoffMultiplier: 2,
+    },
+    /** WebSocket 重连：无限重试 */
+    websocket: {
+        maxRetries: Infinity,
+        initialDelay: 1000,
+        maxDelay: 30000,
+        backoffMultiplier: 2,
+        jitter: true,
+    },
+};
+/**
+ * 连接管理器 - 用于 WebSocket 等长连接的重连管理
+ */
+export class ConnectionManager {
+    connect;
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    isConnecting = false;
+    options;
+    constructor(connect, options = RetryPresets.websocket) {
+        this.connect = connect;
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * 开始连接
+     */
+    async start() {
+        this.stop();
+        this.reconnectAttempt = 0;
+        await this.tryConnect();
+    }
+    /**
+     * 停止连接和重连
+     */
+    stop() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.isConnecting = false;
+    }
+    /**
+     * 触发重连
+     */
+    scheduleReconnect(error) {
+        if (this.isConnecting)
+            return;
+        this.reconnectAttempt++;
+        if (this.reconnectAttempt > this.options.maxRetries) {
+            console.error('[ConnectionManager] 达到最大重试次数，停止重连');
+            return;
+        }
+        const delay = calculateDelay(this.reconnectAttempt, this.options);
+        console.log(`[ConnectionManager] 将在 ${Math.round(delay / 1000)}s 后进行第 ${this.reconnectAttempt} 次重连`);
+        if (error) {
+            this.options.onRetry(error, this.reconnectAttempt, delay);
+        }
+        this.reconnectTimer = setTimeout(() => {
+            this.tryConnect();
+        }, delay);
+    }
+    /**
+     * 重置重连计数（连接成功时调用）
+     */
+    resetAttempts() {
+        this.reconnectAttempt = 0;
+    }
+    /**
+     * 获取当前重连次数
+     */
+    getAttempts() {
+        return this.reconnectAttempt;
+    }
+    async tryConnect() {
+        if (this.isConnecting)
+            return;
+        this.isConnecting = true;
+        try {
+            await this.connect();
+            this.resetAttempts();
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            console.error('[ConnectionManager] 连接失败:', err.message);
+            this.scheduleReconnect(err);
+        }
+        finally {
+            this.isConnecting = false;
+        }
+    }
+}

package/lib/router.d.ts

@@ -1,16 +1,53 @@
 import KoaRouter from "@koa/router";
 import { WebSocketServer, WebSocket, ServerOptions } from "ws";
 import { IncomingMessage, Server } from "http";
-export declare class WsServer<T extends typeof WebSocket.WebSocket = typeof WebSocket.WebSocket, U extends typeof IncomingMessage = typeof IncomingMessage> extends WebSocketServer<T, U> {
-    constructor(options?: WsServer.Options<T, U>);
+import type { RouterContext as KoaRouterContext } from "@koa/router";
+import type { Request } from 'koa';
+export type RouterContext = KoaRouterContext & {
+    request: Request & {
+        body: any;
+    };
+};
+export type { Next } from "koa";
+export declare class WsServer<T extends typeof WebSocket = typeof WebSocket, U extends typeof IncomingMessage = typeof IncomingMessage> extends WebSocketServer<T, U> {
+    readonly path: string;
+    constructor(options: WsServer.Options<T, U>);
 }
 export declare namespace WsServer {
-    interface Options<T extends typeof WebSocket.WebSocket = typeof WebSocket.WebSocket, U extends typeof IncomingMessage = typeof IncomingMessage> extends ServerOptions<T, U> {
+    interface Options<T extends typeof WebSocket = typeof WebSocket, U extends typeof IncomingMessage = typeof IncomingMessage> extends ServerOptions<T, U> {
         path: string;
     }
 }
 export declare class Router extends KoaRouter {
-    wsStack: WsServer[];
-    constructor(server: Server, options?: KoaRouter.RouterOptions);
-    ws(path: string): WsServer<typeof import("ws"), typeof IncomingMessage>;
+    private wsMap;
+    private upgradeHandler?;
+    private readonly server;
+    constructor(server: Server, options?: ConstructorParameters<typeof KoaRouter>[0]);
+    /**
+     * 设置 WebSocket upgrade 处理器
+     */
+    private setupUpgradeHandler;
+    /**
+     * 创建并注册一个新的 WebSocket 服务器
+     * @param path WebSocket 路径（客户端请求的完整路径，不受 router prefix 影响）
+     * @returns WebSocket 服务器实例
+     */
+    ws(path: string): WsServer;
+    /**
+     * 移除 WebSocket 服务器
+     * @param path WebSocket 路径（客户端请求的完整路径）
+     */
+    removeWs(path: string): boolean;
+    /**
+     * 清理所有 WebSocket 服务器和事件监听器
+     */
+    cleanup(): void;
+    /**
+     * 异步清理（返回 Promise）
+     */
+    cleanupAsync(): Promise<void>;
+    /**
+     * 获取所有已注册的 WebSocket 路径
+     */
+    getWsPaths(): string[];
 }

package/lib/router.js

@@ -1,28 +1,155 @@
 import KoaRouter from "@koa/router";
 import { WebSocketServer } from "ws";
 export class WsServer extends WebSocketServer {
+    path = '';
     constructor(options) {
         super(options);
+        // 设置 path（基类可能不会自动设置，因为使用了 noServer: true）
         this.path = options.path;
     }
 }
 export class Router extends KoaRouter {
-    wsStack = [];
+    wsMap = new Map();
+    upgradeHandler;
+    server;
     constructor(server, options) {
         super(options);
-        server.on("upgrade", (request, socket, head) => {
-            const { pathname } = new URL(request.url, `wss://localhost`);
-            const wsServer = this.wsStack.find(wss => wss.path === pathname);
-            if (!wsServer)
-                return socket.destroy();
-            wsServer.handleUpgrade(request, socket, head, function done(ws) {
-                wsServer.emit("connection", ws, request);
-            });
-        });
+        this.server = server;
+        this.setupUpgradeHandler();
+    }
+    /**
+     * 设置 WebSocket upgrade 处理器
+     */
+    setupUpgradeHandler() {
+        this.upgradeHandler = (request, socket, head) => {
+            try {
+                const url = new URL(request.url || "/", `http://localhost`);
+                const pathname = url.pathname;
+                // WebSocket upgrade 请求的路径是客户端直接请求的完整路径
+                // 不受 Koa router prefix 影响，所以直接使用 pathname 进行匹配
+                const wsServer = this.wsMap.get(pathname);
+                if (!wsServer) {
+                    // 没有找到匹配的 WebSocket 服务器，优雅地关闭连接
+                    socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+                    socket.destroy();
+                    return;
+                }
+                // 处理 WebSocket 升级
+                wsServer.handleUpgrade(request, socket, head, (ws) => {
+                    wsServer.emit("connection", ws, request);
+                });
+            }
+            catch (error) {
+                // 处理 URL 解析错误
+                socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+                socket.destroy();
+            }
+        };
+        this.server.on("upgrade", this.upgradeHandler);
     }
+    /**
+     * 创建并注册一个新的 WebSocket 服务器
+     * @param path WebSocket 路径（客户端请求的完整路径，不受 router prefix 影响）
+     * @returns WebSocket 服务器实例
+     */
     ws(path) {
-        const wsServer = new WsServer({ noServer: true, path });
-        this.wsStack.push(wsServer);
+        // 规范化路径：确保以 / 开头
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        // WebSocket 路径不受 Router prefix 影响
+        // 因为 WebSocket upgrade 是直接处理 HTTP upgrade 请求的，使用原始 pathname
+        // 所以直接使用传入的路径，不添加 prefix
+        const fullPath = normalizedPath;
+        // 检查路径是否已存在
+        if (this.wsMap.has(fullPath)) {
+            throw new Error(`WebSocket server already exists at path: ${fullPath}`);
+        }
+        // 创建 WebSocket 服务器
+        const wsServer = new WsServer({
+            noServer: true,
+            path: fullPath
+        });
+        // 存储完整路径（客户端请求的路径，不受 prefix 影响）
+        this.wsMap.set(fullPath, wsServer);
         return wsServer;
     }
+    /**
+     * 移除 WebSocket 服务器
+     * @param path WebSocket 路径（客户端请求的完整路径）
+     */
+    removeWs(path) {
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        // 尝试匹配完整路径或相对路径
+        let fullPath;
+        if (this.opts.prefix && !normalizedPath.startsWith(this.opts.prefix)) {
+            fullPath = `${this.opts.prefix}${normalizedPath}`;
+        }
+        else {
+            fullPath = normalizedPath;
+        }
+        const wsServer = this.wsMap.get(fullPath) || this.wsMap.get(normalizedPath);
+        if (wsServer) {
+            // 关闭所有连接
+            wsServer.close();
+            this.wsMap.delete(fullPath);
+            if (fullPath !== normalizedPath && this.wsMap.has(normalizedPath)) {
+                this.wsMap.delete(normalizedPath);
+            }
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 清理所有 WebSocket 服务器和事件监听器
+     */
+    cleanup() {
+        // 关闭所有 WebSocket 服务器
+        for (const wsServer of this.wsMap.values()) {
+            try {
+                wsServer.close();
+            }
+            catch (error) {
+                // 忽略关闭错误
+            }
+        }
+        this.wsMap.clear();
+        // 移除 upgrade 事件监听器
+        if (this.upgradeHandler) {
+            this.server.removeListener("upgrade", this.upgradeHandler);
+            this.upgradeHandler = undefined;
+        }
+    }
+    /**
+     * 异步清理（返回 Promise）
+     */
+    async cleanupAsync() {
+        return new Promise((resolve) => {
+            // 关闭所有 WebSocket 服务器
+            const closePromises = [];
+            for (const wsServer of this.wsMap.values()) {
+                closePromises.push(new Promise((resolve) => {
+                    try {
+                        wsServer.close(() => resolve());
+                    }
+                    catch {
+                        resolve();
+                    }
+                }));
+            }
+            Promise.all(closePromises).then(() => {
+                this.wsMap.clear();
+                // 移除 upgrade 事件监听器
+                if (this.upgradeHandler) {
+                    this.server.removeListener("upgrade", this.upgradeHandler);
+                    this.upgradeHandler = undefined;
+                }
+                resolve();
+            });
+        });
+    }
+    /**
+     * 获取所有已注册的 WebSocket 路径
+     */
+    getWsPaths() {
+        return Array.from(this.wsMap.keys());
+    }
 }

package/lib/types.d.ts

@@ -1,3 +1,4 @@
+import 'koa-body';
 export type Dict<T = any, K extends string | symbol = string> = Record<K, T>;
 export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "mark" | "off";
 export type Dispose = () => any;

package/lib/types.js

@@ -1 +1,2 @@
-export {};
+// 导入 koa-body 的类型定义，它会自动扩展 Request 接口
+import 'koa-body';

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@onebots/core",
-  "version": "0.5.0",
-  "description": "多平台多协议的机器人应用启动器核心包",
+  "version": "1.0.0",
+  "description": "IMHelper 核心抽象层，提供适配器、协议、账号等基础接口和类型",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "engines": {
     "node": ">=22"
   },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "import": "./lib/types.js"
+    }
+  },
   "keywords": [
     "onebot",
     "qq",
@@ -19,11 +29,10 @@
   "author": "凉菜",
   "license": "MIT",
   "devDependencies": {
-    "@types/koa": "^2.13.4",
-    "@types/koa-basic-auth": "^2.0.6",
-    "@types/koa-bodyparser": "^4.3.7",
-    "@types/koa__router": "^8.0.11",
+    "@types/koa": "^3.0.1",
     "@types/node": "^22.7.3",
+    "@types/koa-basic-auth": "^2.0.6",
+    "@types/koa__router": "^12.0.5",
     "@types/ws": "^8.5.3",
     "tsc-alias": "latest",
     "tsconfig-paths": "latest",
@@ -36,18 +45,18 @@
     "/lib/**/*.d.ts"
   ],
   "dependencies": {
-    "@koa/router": "^10.1.1",
+    "@koa/router": "^15.1.0",
     "js-yaml": "^4.1.0",
-    "koa": "^2.13.4",
+    "koa": "^3.1.1",
     "koa-basic-auth": "^4.0.0",
-    "koa-bodyparser": "^4.3.0",
+    "koa-body": "^7.0.0",
     "log4js": "^6.5.2",
     "reflect-metadata": "^0.1.13",
     "ws": "^8.16.0"
   },
   "scripts": {
     "start": "node .",
-    "build": "tsc --project tsconfig.json && tsc-alias -p tsconfig.json",
+    "build": "rm -f *.tsbuildinfo && tsc --project tsconfig.json && tsc-alias -p tsconfig.json",
     "clean": "rm -rf lib *.tsbuildinfo"
   }
 }