@onebots/core 0.5.0 → 1.0.4

package/lib/retry.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 重试策略和网络请求重试机制
+ * 提供统一的重试逻辑，支持指数退避
+ */
+export interface RetryOptions {
+    /** 最大重试次数 */
+    maxRetries?: number;
+    /** 初始延迟时间（毫秒） */
+    initialDelay?: number;
+    /** 最大延迟时间（毫秒） */
+    maxDelay?: number;
+    /** 退避倍数 */
+    backoffMultiplier?: number;
+    /** 是否添加随机抖动 */
+    jitter?: boolean;
+    /** 判断是否应该重试的函数 */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    /** 重试前的回调 */
+    onRetry?: (error: Error, attempt: number, delay: number) => void;
+}
+/**
+ * 带重试的异步函数执行器
+ *
+ * @example
+ * ```typescript
+ * const result = await retry(
+ *     () => fetch('https://api.example.com/data'),
+ *     { maxRetries: 3, initialDelay: 1000 }
+ * );
+ * ```
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * 创建一个带重试功能的函数包装器
+ *
+ * @example
+ * ```typescript
+ * const fetchWithRetry = withRetry(fetch, { maxRetries: 3 });
+ * const response = await fetchWithRetry('https://api.example.com/data');
+ * ```
+ */
+export declare function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, options?: RetryOptions): T;
+/**
+ * 重试策略预设
+ */
+export declare const RetryPresets: {
+    /** 快速重试：3次，1秒起始 */
+    fast: RetryOptions;
+    /** 标准重试：5次，2秒起始 */
+    standard: RetryOptions;
+    /** 持久重试：10次，5秒起始 */
+    persistent: RetryOptions;
+    /** WebSocket 重连：无限重试 */
+    websocket: RetryOptions;
+};
+/**
+ * 连接管理器 - 用于 WebSocket 等长连接的重连管理
+ */
+export declare class ConnectionManager {
+    private connect;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private isConnecting;
+    private options;
+    constructor(connect: () => Promise<void>, options?: RetryOptions);
+    /**
+     * 开始连接
+     */
+    start(): Promise<void>;
+    /**
+     * 停止连接和重连
+     */
+    stop(): void;
+    /**
+     * 触发重连
+     */
+    scheduleReconnect(error?: Error): void;
+    /**
+     * 重置重连计数（连接成功时调用）
+     */
+    resetAttempts(): void;
+    /**
+     * 获取当前重连次数
+     */
+    getAttempts(): number;
+    private tryConnect;
+}

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/timestamp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 统一时间戳工具：各平台有的返回 Unix **秒**、有的返回 **毫秒**，CommonEvent 等统一用 **毫秒**。
+ */
+/** 启发式阈值：大于等于该值视为已是毫秒（约对应 2001-09-09 之后的毫秒时间戳） */
+export declare const UNIX_TIMESTAMP_MS_MIN = 10000000000;
+/**
+ * 平台明确给出 **Unix 秒**（如微信公众号 CreateTime、飞书 create_time）时，转为事件用的 **毫秒**。
+ *
+ * @param seconds - 秒级时间戳（number / 数字字符串）
+ * @param options.fallbackMs - 空值、非有限数或 ≤0 时使用的毫秒时间，默认 `Date.now()`
+ */
+export declare function unixSecondsToEventMs(seconds: unknown, options?: {
+    fallbackMs?: number;
+}): number;
+/**
+ * 平台明确给出 **Unix 毫秒** 时，校验并取整；无效时使用 fallback。
+ */
+export declare function unixMillisToEventMs(ms: unknown, options?: {
+    fallbackMs?: number;
+}): number;
+/**
+ * 不确定单位时使用：**大于等于 {@link UNIX_TIMESTAMP_MS_MIN} 视为毫秒**，否则视为秒。
+ * 适用于部分文档不清或中间层混传的场景。
+ */
+export declare function coerceUnixToEventMs(value: unknown, options?: {
+    fallbackMs?: number;
+}): number;
+/**
+ * 需要 **Unix 秒** 的字段（如部分协议里的 message `time`）时使用。
+ *
+ * @param seconds - 秒级时间戳
+ * @param options.fallbackSec - 无效时的秒级时间，默认当前 `Date.now()/1000` 取整
+ */
+export declare function toUnixSeconds(seconds: unknown, options?: {
+    fallbackSec?: number;
+}): number;
+/**
+ * 平台返回 **ISO 8601 字符串**或其它 `Date` 可解析格式（如 QQ 开放消息 `timestamp`）时，转为事件用的 **毫秒**。
+ */
+export declare function dateLikeToEventMs(value: unknown, options?: {
+    fallbackMs?: number;
+}): number;

package/lib/timestamp.js

@@ -0,0 +1,72 @@
+/**
+ * 统一时间戳工具：各平台有的返回 Unix **秒**、有的返回 **毫秒**，CommonEvent 等统一用 **毫秒**。
+ */
+/** 启发式阈值：大于等于该值视为已是毫秒（约对应 2001-09-09 之后的毫秒时间戳） */
+export const UNIX_TIMESTAMP_MS_MIN = 10_000_000_000;
+/**
+ * 平台明确给出 **Unix 秒**（如微信公众号 CreateTime、飞书 create_time）时，转为事件用的 **毫秒**。
+ *
+ * @param seconds - 秒级时间戳（number / 数字字符串）
+ * @param options.fallbackMs - 空值、非有限数或 ≤0 时使用的毫秒时间，默认 `Date.now()`
+ */
+export function unixSecondsToEventMs(seconds, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (seconds == null || seconds === "")
+        return fallback;
+    const n = typeof seconds === "string" ? parseFloat(seconds) : Number(seconds);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n * 1000);
+}
+/**
+ * 平台明确给出 **Unix 毫秒** 时，校验并取整；无效时使用 fallback。
+ */
+export function unixMillisToEventMs(ms, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (ms == null || ms === "")
+        return fallback;
+    const n = typeof ms === "string" ? parseFloat(ms) : Number(ms);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n);
+}
+/**
+ * 不确定单位时使用：**大于等于 {@link UNIX_TIMESTAMP_MS_MIN} 视为毫秒**，否则视为秒。
+ * 适用于部分文档不清或中间层混传的场景。
+ */
+export function coerceUnixToEventMs(value, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (value == null || value === "")
+        return fallback;
+    const n = typeof value === "string" ? parseFloat(value) : Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    if (n >= UNIX_TIMESTAMP_MS_MIN)
+        return Math.floor(n);
+    return Math.floor(n * 1000);
+}
+/**
+ * 需要 **Unix 秒** 的字段（如部分协议里的 message `time`）时使用。
+ *
+ * @param seconds - 秒级时间戳
+ * @param options.fallbackSec - 无效时的秒级时间，默认当前 `Date.now()/1000` 取整
+ */
+export function toUnixSeconds(seconds, options) {
+    const fallback = options?.fallbackSec ?? Math.floor(Date.now() / 1000);
+    if (seconds == null || seconds === "")
+        return fallback;
+    const n = typeof seconds === "string" ? parseFloat(seconds) : Number(seconds);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.floor(n);
+}
+/**
+ * 平台返回 **ISO 8601 字符串**或其它 `Date` 可解析格式（如 QQ 开放消息 `timestamp`）时，转为事件用的 **毫秒**。
+ */
+export function dateLikeToEventMs(value, options) {
+    const fallback = options?.fallbackMs ?? Date.now();
+    if (value == null || value === "")
+        return fallback;
+    const t = new Date(value).getTime();
+    return Number.isFinite(t) ? t : fallback;
+}

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/lib/utils.d.ts

@@ -11,8 +11,9 @@ export declare function omit<T, K extends keyof T>(source: T, keys?: Iterable<K>
  * 将驼峰命名替换为下划线分割命名
  * @param name
  * @returns
- * @todo 是否应该改名 ToUnderLine()？
  */
+export declare function toUnderLine(name: string): string;
+/** @deprecated Use {@link toUnderLine} instead. */
 export declare function toLine<T extends string>(name: T): string;
 export interface Class<T = any> {
     new (...args: any[]): T;