@kevisual/router 0.0.66 → 0.0.67

package/dist/ws.d.ts

@@ -0,0 +1,716 @@
+import { EventEmitter } from 'eventemitter3';
+import * as http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { IncomingMessage as IncomingMessage$1, ServerResponse as ServerResponse$1 } from 'http';
+
+type ReconnectConfig = {
+    /**
+     * 重连配置选项, 最大重试次数，默认无限
+     */
+    maxRetries?: number;
+    /**
+     * 重连配置选项, 重试延迟(ms)，默认1000
+     */
+    retryDelay?: number;
+    /**
+     * 重连配置选项, 最大延迟(ms)，默认30000
+     */
+    maxDelay?: number;
+    /**
+     * 重连配置选项, 退避倍数，默认2
+     */
+    backoffMultiplier?: number;
+};
+/**
+ * 一个支持自动重连的 WebSocket 客户端。
+ * 在连接断开时会根据配置进行重连尝试，支持指数退避。
+ */
+declare class ReconnectingWebSocket {
+    private ws;
+    private url;
+    private config;
+    private retryCount;
+    private reconnectTimer;
+    private isManualClose;
+    private messageHandlers;
+    private openHandlers;
+    private closeHandlers;
+    private errorHandlers;
+    constructor(url: string, config?: ReconnectConfig);
+    log(...args: any[]): void;
+    error(...args: any[]): void;
+    connect(): void;
+    private scheduleReconnect;
+    send(data: any): boolean;
+    onMessage(handler: (data: any) => void): void;
+    onOpen(handler: () => void): void;
+    onClose(handler: (code: number, reason: Buffer) => void): void;
+    onError(handler: (error: Error) => void): void;
+    close(): void;
+    getReadyState(): number;
+    getRetryCount(): number;
+}
+
+type RouterContextT = {
+    code?: number;
+    [key: string]: any;
+};
+type RouteContext<T = {
+    code?: number;
+}, S = any> = {
+    /**
+     * 本地自己调用的时候使用，可以标识为当前自调用，那么 auth 就不许重复的校验
+     * 或者不需要登录的，直接调用
+     */
+    appId?: string;
+    query?: {
+        [key: string]: any;
+    };
+    /** return body */
+    body?: number | string | Object;
+    forward?: (response: {
+        code: number;
+        data?: any;
+        message?: any;
+    }) => void;
+    /** return code */
+    code?: number;
+    /** return msg */
+    message?: string;
+    state?: S;
+    /**
+     * 当前路径
+     */
+    currentPath?: string;
+    /**
+     * 当前key
+     */
+    currentKey?: string;
+    /**
+     * 当前route
+     */
+    currentRoute?: Route;
+    /**
+     * 进度
+     */
+    progress?: [string, string][];
+    nextQuery?: {
+        [key: string]: any;
+    };
+    end?: boolean;
+    app?: QueryRouter;
+    error?: any;
+    /** 请求 route的返回结果，不解析body为data */
+    call?: (message: {
+        path: string;
+        key?: string;
+        payload?: any;
+        [key: string]: any;
+    } | {
+        id: string;
+        apyload?: any;
+        [key: string]: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }) => Promise<any>;
+    /** 请求 route的返回结果，解析了body为data，就类同于 query.post获取的数据*/
+    run?: (message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }) => Promise<any>;
+    index?: number;
+    throw?: (code?: number | string, message?: string, tips?: string) => void;
+    /** 是否需要序列化, 使用JSON.stringify和JSON.parse */
+    needSerialize?: boolean;
+} & T;
+type SimpleObject = Record<string, any>;
+type Run<T extends SimpleObject = {}> = (ctx: Required<RouteContext<T>>) => Promise<typeof ctx | null | void>;
+type NextRoute = Pick<Route, 'id' | 'path' | 'key'>;
+type RouteMiddleware = {
+    path: string;
+    key?: string;
+    id?: string;
+} | string;
+type RouteOpts<U = {}, T = SimpleObject> = {
+    path?: string;
+    key?: string;
+    id?: string;
+    run?: Run<U>;
+    nextRoute?: NextRoute;
+    description?: string;
+    metadata?: T;
+    middleware?: RouteMiddleware[];
+    type?: 'route' | 'middleware';
+    /**
+     * $#$ will be used to split path and key
+     */
+    idUsePath?: boolean;
+    /**
+     * id 合并的分隔符，默认为 $#$
+     */
+    delimiter?: string;
+    isDebug?: boolean;
+};
+type DefineRouteOpts = Omit<RouteOpts, 'idUsePath' | 'nextRoute'>;
+declare const pickValue: readonly ["path", "key", "id", "description", "type", "middleware", "metadata"];
+type RouteInfo = Pick<Route, (typeof pickValue)[number]>;
+declare class Route<U = {
+    [key: string]: any;
+}, T extends SimpleObject = SimpleObject> {
+    /**
+     * 一级路径
+     */
+    path?: string;
+    /**
+     * 二级路径
+     */
+    key?: string;
+    id?: string;
+    run?: Run;
+    nextRoute?: NextRoute;
+    description?: string;
+    metadata?: T;
+    middleware?: RouteMiddleware[];
+    type?: string;
+    data?: any;
+    /**
+     * 是否开启debug，开启后会打印错误信息
+     */
+    isDebug?: boolean;
+    constructor(path?: string, key?: string, opts?: RouteOpts);
+    prompt(description: string): this;
+    prompt(description: Function): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(opts: DefineRouteOpts): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(fn: Run<T & U>): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(key: string, fn: Run<T & U>): this;
+    define<T extends {
+        [key: string]: any;
+    } = RouterContextT>(path: string, key: string, fn: Run<T & U>): this;
+    update(opts: DefineRouteOpts, checkList?: string[]): this;
+    addTo(router: QueryRouter | {
+        add: (route: Route) => void;
+        [key: string]: any;
+    }, opts?: AddOpts): void;
+    setData(data: any): this;
+    throw(code?: number | string, message?: string, tips?: string): void;
+}
+/**
+ * @parmas override 是否覆盖已存在的route，默认true
+ */
+type AddOpts = {
+    override?: boolean;
+};
+declare class QueryRouter {
+    appId: string;
+    routes: Route[];
+    maxNextRoute: number;
+    context?: RouteContext;
+    constructor();
+    /**
+     * add route
+     * @param route
+     * @param opts
+     */
+    add(route: Route, opts?: AddOpts): void;
+    /**
+     * remove route by path and key
+     * @param route
+     */
+    remove(route: Route | {
+        path: string;
+        key?: string;
+    }): void;
+    /**
+     * remove route by id
+     * @param uniqueId
+     */
+    removeById(unique: string): void;
+    /**
+     * 执行route
+     * @param path
+     * @param key
+     * @param ctx
+     * @returns
+     */
+    runRoute(path: string, key: string, ctx?: RouteContext): any;
+    /**
+     * 第一次执行
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    parse(message: {
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<any>;
+    /**
+     * 返回的数据包含所有的context的请求返回的内容，可做其他处理
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    call(message: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<any>;
+    /**
+     * 请求 result 的数据
+     * @param message
+     * @param ctx
+     * @deprecated use run or call instead
+     * @returns
+     */
+    queryRoute(message: {
+        id?: string;
+        path: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<{
+        code: any;
+        data: any;
+        message: any;
+    }>;
+    /**
+     * Router Run获取数据
+     * @param message
+     * @param ctx
+     * @returns
+     */
+    run(message: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: RouteContext & {
+        [key: string]: any;
+    }): Promise<{
+        code: any;
+        data: any;
+        message: any;
+    }>;
+    /**
+     * 设置上下文
+     * @description 这里的上下文是为了在handle函数中使用
+     * @param ctx
+     */
+    setContext(ctx: RouteContext): void;
+    getList(filter?: (route: Route) => boolean): RouteInfo[];
+    /**
+     * 获取handle函数, 这里会去执行parse函数
+     */
+    getHandle<T = any>(router: QueryRouter, wrapperFn?: HandleFn<T>, ctx?: RouteContext): (msg: {
+        id?: string;
+        path?: string;
+        key?: string;
+        [key: string]: any;
+    }, handleContext?: RouteContext) => Promise<{
+        [key: string]: any;
+        code: string;
+        data?: any;
+        message?: string;
+    } | {
+        code: any;
+        data: any;
+        message: any;
+    } | {
+        code: number;
+        message: any;
+        data?: undefined;
+    }>;
+    exportRoutes(): Route<{
+        [key: string]: any;
+    }, SimpleObject>[];
+    importRoutes(routes: Route[]): void;
+    importRouter(router: QueryRouter): void;
+    throw(code?: number | string, message?: string, tips?: string): void;
+    hasRoute(path: string, key?: string): Route<{
+        [key: string]: any;
+    }, SimpleObject>;
+    findRoute(opts?: {
+        path?: string;
+        key?: string;
+        id?: string;
+    }): Route<{
+        [key: string]: any;
+    }, SimpleObject>;
+    createRouteList(force?: boolean, filter?: (route: Route) => boolean): void;
+    /**
+     * 等待程序运行, 获取到message的数据,就执行
+     * params 是预设参数
+     * emitter = process
+     * -- .exit
+     * -- .on
+     * -- .send
+     */
+    wait(params?: {
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, opts?: {
+        emitter?: any;
+        timeout?: number;
+        getList?: boolean;
+        force?: boolean;
+        filter?: (route: Route) => boolean;
+    }): Promise<void>;
+}
+interface HandleFn<T = any> {
+    (msg: {
+        path: string;
+        [key: string]: any;
+    }, ctx?: any): {
+        code: string;
+        data?: any;
+        message?: string;
+        [key: string]: any;
+    };
+    (res: RouteContext<T>): any;
+}
+
+type Cors = {
+    /**
+     * @default '*''
+     */
+    origin?: string | undefined;
+};
+type ServerOpts<T = {}> = {
+    /**path default `/api/router` */
+    path?: string;
+    /**handle Fn */
+    handle?: (msg?: {
+        path: string;
+        key?: string;
+        [key: string]: any;
+    }, ctx?: {
+        req: http.IncomingMessage;
+        res: http.ServerResponse;
+    }) => any;
+    cors?: Cors;
+    io?: boolean;
+    showConnected?: boolean;
+} & T;
+interface ServerType {
+    path?: string;
+    server?: any;
+    handle: ServerOpts['handle'];
+    setHandle(handle?: any): void;
+    listeners: Listener[];
+    listen(port: number, hostname?: string, backlog?: number, listeningListener?: () => void): void;
+    listen(port: number, hostname?: string, listeningListener?: () => void): void;
+    listen(port: number, backlog?: number, listeningListener?: () => void): void;
+    listen(port: number, listeningListener?: () => void): void;
+    listen(path: string, backlog?: number, listeningListener?: () => void): void;
+    listen(path: string, listeningListener?: () => void): void;
+    listen(handle: any, backlog?: number, listeningListener?: () => void): void;
+    listen(handle: any, listeningListener?: () => void): void;
+    /**
+     * 兜底监听，当除开 `/api/router` 之外的请求，框架只监听一个api，所以有其他的请求都执行其他的监听
+     * @description 主要是为了兼容其他的监听
+     * @param listener
+     */
+    on(listener: OnListener): void;
+    onWebSocket({ ws, message, pathname, token, id }: OnWebSocketOptions): void;
+    onWsClose<T = {}>(ws: WS<T>): void;
+    sendConnected<T = {}>(ws: WS<T>): void;
+}
+type OnWebSocketOptions<T = {}> = {
+    ws: WS<T>;
+    message: string | Buffer;
+    pathname: string;
+    token?: string;
+    id?: string;
+};
+type WS<T = {}> = {
+    send: (data: any) => void;
+    close: (code?: number, reason?: string) => void;
+    data?: {
+        url: URL;
+        pathname: string;
+        token?: string;
+        id?: string;
+        /**
+         * 鉴权后的获取的信息
+         */
+        userApp?: string;
+    } & T;
+};
+type Listener = {
+    id?: string;
+    io?: boolean;
+    path?: string;
+    func: WebSocketListenerFun | HttpListenerFun;
+    /**
+   * @description 是否默认解析为 JSON，如果为 true，则 message 会被 JSON.parse 处理，默认是 true
+   */
+    json?: boolean;
+};
+type WebSocketListenerFun = (req: WebSocketReq, res: WebSocketRes) => Promise<void> | void;
+type HttpListenerFun = (req: RouterReq, res: RouterRes) => Promise<void> | void;
+type WebSocketReq<T = {}, U = Record<string, any>> = {
+    emitter?: EventEmitter;
+    ws: WS<T>;
+    data?: U;
+    message?: string | Buffer;
+    pathname?: string;
+    token?: string;
+    id?: string;
+};
+type WebSocketRes = {
+    end: (data: any) => void;
+};
+type ListenerFun = WebSocketListenerFun | HttpListenerFun;
+type OnListener = Listener | ListenerFun | (Listener | ListenerFun)[];
+type RouterReq<T = {}> = {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    socket?: {
+        remoteAddress?: string;
+        remotePort?: number;
+    };
+    body?: string;
+    cookies?: Record<string, string>;
+    bun?: {
+        request: Bun.BunRequest;
+        server: Bun.Server<{}>;
+        resolve: (response: Response) => void;
+    };
+    on: (event: 'close', listener: Function) => void;
+} & T;
+type RouterRes<T = {}> = {
+    statusCode: number;
+    headersSent: boolean;
+    _headers: Record<string, string | string[]>;
+    _bodyChunks: any[];
+    writableEnded: boolean;
+    writeHead: (statusCode: number, headers?: Record<string, string>) => void;
+    setHeader: (name: string, value: string | string[]) => void;
+    cookie: (name: string, value: string, options?: any) => void;
+    write: (chunk: any) => void;
+    pipe: (stream: ReadableStream) => void;
+    end: (data?: any) => void;
+} & T;
+
+interface StringifyOptions {
+    /**
+     * Specifies a function that will be used to encode a [cookie-value](https://datatracker.ietf.org/doc/html/rfc6265#section-4.1.1).
+     * Since value of a cookie has a limited character set (and must be a simple string), this function can be used to encode
+     * a value into a string suited for a cookie's value, and should mirror `decode` when parsing.
+     *
+     * @default encodeURIComponent
+     */
+    encode?: (str: string) => string;
+}
+/**
+ * Set-Cookie object.
+ */
+interface SetCookie {
+    /**
+     * Specifies the name of the cookie.
+     */
+    name: string;
+    /**
+     * Specifies the string to be the value for the cookie.
+     */
+    value: string | undefined;
+    /**
+     * Specifies the `number` (in seconds) to be the value for the [`Max-Age` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.2).
+     *
+     * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
+     * `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
+     * so if both are set, they should point to the same date and time.
+     */
+    maxAge?: number;
+    /**
+     * Specifies the `Date` object to be the value for the [`Expires` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.1).
+     * When no expiration is set, clients consider this a "non-persistent cookie" and delete it when the current session is over.
+     *
+     * The [cookie storage model specification](https://tools.ietf.org/html/rfc6265#section-5.3) states that if both `expires` and
+     * `maxAge` are set, then `maxAge` takes precedence, but it is possible not all clients by obey this,
+     * so if both are set, they should point to the same date and time.
+     */
+    expires?: Date;
+    /**
+     * Specifies the value for the [`Domain` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.3).
+     * When no domain is set, clients consider the cookie to apply to the current domain only.
+     */
+    domain?: string;
+    /**
+     * Specifies the value for the [`Path` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.4).
+     * When no path is set, the path is considered the ["default path"](https://tools.ietf.org/html/rfc6265#section-5.1.4).
+     */
+    path?: string;
+    /**
+     * Enables the [`HttpOnly` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.6).
+     * When enabled, clients will not allow client-side JavaScript to see the cookie in `document.cookie`.
+     */
+    httpOnly?: boolean;
+    /**
+     * Enables the [`Secure` `Set-Cookie` attribute](https://tools.ietf.org/html/rfc6265#section-5.2.5).
+     * When enabled, clients will only send the cookie back if the browser has an HTTPS connection.
+     */
+    secure?: boolean;
+    /**
+     * Enables the [`Partitioned` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-cutler-httpbis-partitioned-cookies/).
+     * When enabled, clients will only send the cookie back when the current domain _and_ top-level domain matches.
+     *
+     * This is an attribute that has not yet been fully standardized, and may change in the future.
+     * This also means clients may ignore this attribute until they understand it. More information
+     * about can be found in [the proposal](https://github.com/privacycg/CHIPS).
+     */
+    partitioned?: boolean;
+    /**
+     * Specifies the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+     *
+     * - `'low'` will set the `Priority` attribute to `Low`.
+     * - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+     * - `'high'` will set the `Priority` attribute to `High`.
+     *
+     * More information about priority levels can be found in [the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+     */
+    priority?: "low" | "medium" | "high";
+    /**
+     * Specifies the value for the [`SameSite` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
+     *
+     * - `true` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+     * - `'lax'` will set the `SameSite` attribute to `Lax` for lax same site enforcement.
+     * - `'none'` will set the `SameSite` attribute to `None` for an explicit cross-site cookie.
+     * - `'strict'` will set the `SameSite` attribute to `Strict` for strict same site enforcement.
+     *
+     * More information about enforcement levels can be found in [the specification](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7).
+     */
+    sameSite?: boolean | "lax" | "strict" | "none";
+}
+/**
+ * Backward compatibility serialize options.
+ */
+type SerializeOptions = StringifyOptions & Omit<SetCookie, "name" | "value">;
+
+type CookieFn = (name: string, value: string, options?: SerializeOptions, end?: boolean) => void;
+type HandleCtx = {
+    req: IncomingMessage & {
+        cookies: Record<string, string>;
+    };
+    res: ServerResponse & {
+        /**
+         * cookie 函数， end 参数用于设置是否立即设置到响应头，设置了后面的cookie再设置会覆盖前面的
+         */
+        cookie: CookieFn;
+    };
+};
+
+type ServerNodeOpts = ServerOpts<{
+    httpType?: 'http' | 'https' | 'http2';
+    httpsKey?: string;
+    httpsCert?: string;
+}>;
+
+type RouterHandle = (msg: {
+    path: string;
+    [key: string]: any;
+}) => {
+    code: string;
+    data?: any;
+    message?: string;
+    [key: string]: any;
+};
+type AppOptions<T = {}> = {
+    router?: QueryRouter;
+    server?: ServerType;
+    /** handle msg 关联 */
+    routerHandle?: RouterHandle;
+    routerContext?: RouteContext<T>;
+    serverOptions?: ServerNodeOpts;
+    appId?: string;
+};
+type AppRouteContext<T = {}> = HandleCtx & RouteContext<T> & {
+    app: App<T>;
+};
+/**
+ *  封装了 Router 和 Server 的 App 模块，处理http的请求和响应，内置了 Cookie 和 Token 和 res 的处理
+ *  U - Route Context的扩展类型
+ */
+declare class App<U = {}> extends QueryRouter {
+    appId: string;
+    router: QueryRouter;
+    server: ServerType;
+    constructor(opts?: AppOptions<U>);
+    listen(port: number, hostname?: string, backlog?: number, listeningListener?: () => void): void;
+    listen(port: number, hostname?: string, listeningListener?: () => void): void;
+    listen(port: number, backlog?: number, listeningListener?: () => void): void;
+    listen(port: number, listeningListener?: () => void): void;
+    listen(path: string, backlog?: number, listeningListener?: () => void): void;
+    listen(path: string, listeningListener?: () => void): void;
+    listen(handle: any, backlog?: number, listeningListener?: () => void): void;
+    listen(handle: any, listeningListener?: () => void): void;
+    addRoute(route: Route, opts?: AddOpts): void;
+    Route: typeof Route;
+    route(opts: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
+    route(path: string, key?: string): Route<AppRouteContext<U>>;
+    route(path: string, opts?: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
+    route(path: string, key?: string, opts?: RouteOpts<AppRouteContext<U>>): Route<AppRouteContext<U>>;
+    prompt(description: string): Route<AppRouteContext<U>>;
+    prompt(description: Function): Route<AppRouteContext<U>>;
+    call(message: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: AppRouteContext<U> & {
+        [key: string]: any;
+    }): Promise<any>;
+    run(msg: {
+        id?: string;
+        path?: string;
+        key?: string;
+        payload?: any;
+    }, ctx?: Partial<AppRouteContext<U>> & {
+        [key: string]: any;
+    }): Promise<{
+        code: any;
+        data: any;
+        message: any;
+    }>;
+    static handleRequest(req: IncomingMessage$1, res: ServerResponse$1): Promise<{
+        cookies: Record<string, string>;
+        token: string;
+    }>;
+    onServerRequest(fn: (req: IncomingMessage$1, res: ServerResponse$1) => void): void;
+}
+
+declare const handleCallWsApp: (ws: ReconnectingWebSocket, app: App, message: any) => Promise<void>;
+declare const handleCallApp: (send: (data: any) => void, app: App, message: any) => Promise<void>;
+declare class Ws {
+    wsClient: ReconnectingWebSocket;
+    app: App;
+    showLog: boolean;
+    constructor(opts?: ReconnectConfig & {
+        url: string;
+        app: App;
+        showLog?: boolean;
+        handleMessage?: (ws: ReconnectingWebSocket, app: App, message: any) => void;
+    });
+    send(data: any): boolean;
+    log(...args: any[]): void;
+}
+
+export { ReconnectingWebSocket, Ws, handleCallApp, handleCallWsApp };
+export type { ReconnectConfig };

package/dist/ws.js

@@ -0,0 +1,186 @@
+import WebSocket from 'ws';
+
+/**
+ * 一个支持自动重连的 WebSocket 客户端。
+ * 在连接断开时会根据配置进行重连尝试，支持指数退避。
+ */
+class ReconnectingWebSocket {
+    ws = null;
+    url;
+    config;
+    retryCount = 0;
+    reconnectTimer = null;
+    isManualClose = false;
+    messageHandlers = [];
+    openHandlers = [];
+    closeHandlers = [];
+    errorHandlers = [];
+    constructor(url, config = {}) {
+        this.url = url;
+        this.config = {
+            maxRetries: config.maxRetries ?? Infinity,
+            retryDelay: config.retryDelay ?? 1000,
+            maxDelay: config.maxDelay ?? 30000,
+            backoffMultiplier: config.backoffMultiplier ?? 2,
+        };
+    }
+    log(...args) {
+        console.log('[ReconnectingWebSocket]', ...args);
+    }
+    error(...args) {
+        console.error('[ReconnectingWebSocket]', ...args);
+    }
+    connect() {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            return;
+        }
+        this.log(`正在连接到 ${this.url}...`);
+        this.ws = new WebSocket(this.url);
+        this.ws.on('open', () => {
+            this.log('WebSocket 连接已打开');
+            this.retryCount = 0;
+            this.openHandlers.forEach(handler => handler());
+            this.send({ type: 'heartbeat', timestamp: new Date().toISOString() });
+        });
+        this.ws.on('message', (data) => {
+            this.messageHandlers.forEach(handler => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    handler(message);
+                }
+                catch {
+                    handler(data.toString());
+                }
+            });
+        });
+        this.ws.on('close', (code, reason) => {
+            this.log(`WebSocket 连接已关闭: code=${code}, reason=${reason.toString()}`);
+            this.closeHandlers.forEach(handler => handler(code, reason));
+            if (!this.isManualClose) {
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.on('error', (error) => {
+            this.error('WebSocket 错误:', error.message);
+            this.errorHandlers.forEach(handler => handler(error));
+        });
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            return;
+        }
+        if (this.retryCount >= this.config.maxRetries) {
+            this.error(`已达到最大重试次数 (${this.config.maxRetries})，停止重连`);
+            return;
+        }
+        // 计算延迟（指数退避）
+        const delay = Math.min(this.config.retryDelay * Math.pow(this.config.backoffMultiplier, this.retryCount), this.config.maxDelay);
+        this.retryCount++;
+        this.log(`将在 ${delay}ms 后进行第 ${this.retryCount} 次重连尝试...`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    send(data) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(data));
+            return true;
+        }
+        this.log('WebSocket 未连接，无法发送消息');
+        return false;
+    }
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    onOpen(handler) {
+        this.openHandlers.push(handler);
+    }
+    onClose(handler) {
+        this.closeHandlers.push(handler);
+    }
+    onError(handler) {
+        this.errorHandlers.push(handler);
+    }
+    close() {
+        this.isManualClose = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    getReadyState() {
+        return this.ws?.readyState ?? WebSocket.CLOSED;
+    }
+    getRetryCount() {
+        return this.retryCount;
+    }
+}
+// const ws = new ReconnectingWebSocket('ws://localhost:51516/livecode/ws?id=test-live-app', {
+//   maxRetries: Infinity,    // 无限重试
+//   retryDelay: 1000,        // 初始重试延迟 1 秒
+//   maxDelay: 30000,         // 最大延迟 30 秒
+//   backoffMultiplier: 2,    // 指数退避倍数
+// });
+
+const handleCallWsApp = async (ws, app, message) => {
+    return handleCallApp((data) => {
+        ws.send(data);
+    }, app, message);
+};
+const handleCallApp = async (send, app, message) => {
+    if (message.type === 'router' && message.id) {
+        const data = message?.data;
+        if (!message.id) {
+            console.error('Message id is required for router type');
+            return;
+        }
+        if (!data) {
+            send({
+                type: 'router',
+                id: message.id,
+                data: { code: 500, message: 'No data received' }
+            });
+            return;
+        }
+        const { tokenUser, ...rest } = data || {};
+        const res = await app.run(rest, {
+            state: { tokenUser },
+            appId: app.appId,
+        });
+        send({
+            type: 'router',
+            id: message.id,
+            data: res
+        });
+    }
+};
+class Ws {
+    wsClient;
+    app;
+    showLog = true;
+    constructor(opts) {
+        const { url, app, showLog = true, handleMessage = handleCallWsApp, ...rest } = opts;
+        this.wsClient = new ReconnectingWebSocket(url, rest);
+        this.app = app;
+        this.showLog = showLog;
+        this.wsClient.connect();
+        const onMessage = async (data) => {
+            return handleMessage(this.wsClient, this.app, data);
+        };
+        this.wsClient.onMessage(onMessage);
+    }
+    send(data) {
+        return this.wsClient.send(data);
+    }
+    log(...args) {
+        if (this.showLog)
+            console.log('[Ws]', ...args);
+    }
+}
+
+export { ReconnectingWebSocket, Ws, handleCallApp, handleCallWsApp };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@kevisual/router",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "description": "",
   "type": "module",
   "main": "./dist/router.js",
@@ -24,17 +24,18 @@
   "packageManager": "pnpm@10.28.2",
   "devDependencies": {
     "@kevisual/context": "^0.0.4",
+    "@kevisual/dts": "^0.0.3",
     "@kevisual/js-filter": "^0.0.5",
     "@kevisual/local-proxy": "^0.0.8",
-    "@kevisual/query": "^0.0.38",
-    "@kevisual/use-config": "^1.0.28",
-    "@opencode-ai/plugin": "^1.1.47",
+    "@kevisual/query": "^0.0.39",
+    "@kevisual/use-config": "^1.0.30",
+    "@opencode-ai/plugin": "^1.1.48",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "29.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "@types/bun": "^1.3.8",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.2.0",
     "@types/send": "^1.2.1",
     "@types/ws": "^8.18.1",
     "@types/xml2js": "^0.4.14",
@@ -52,16 +53,14 @@
     "typescript": "^5.9.3",
     "ws": "npm:@kevisual/ws",
     "xml2js": "^0.6.2",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "hono": "^4.11.7"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abearxiong/kevisual-router.git"
   },
-  "dependencies": {
-    "@kevisual/dts": "^0.0.3",
-    "hono": "^4.11.7"
-  },
+  "dependencies": {},
   "publishConfig": {
     "access": "public"
   },
@@ -88,6 +87,7 @@
       "require": "./dist/router-define.js",
       "types": "./dist/router-define.d.ts"
     },
+    "./ws": "./dist/ws.js",
     "./mod.ts": {
       "import": "./mod.ts",
       "require": "./mod.ts",
@@ -102,4 +102,4 @@
       "require": "./src/modules/*"
     }
   }
-}
+}

package/src/server/reconnect-ws.ts

@@ -0,0 +1,170 @@
+import WebSocket from 'ws';
+
+export type ReconnectConfig = {
+  /**
+   * 重连配置选项, 最大重试次数，默认无限
+   */
+  maxRetries?: number;
+  /**
+   * 重连配置选项, 重试延迟(ms)，默认1000
+   */
+  retryDelay?: number;
+  /**
+   * 重连配置选项, 最大延迟(ms)，默认30000
+   */
+  maxDelay?: number;
+  /**
+   * 重连配置选项, 退避倍数，默认2
+   */
+  backoffMultiplier?: number;
+};
+
+/**
+ * 一个支持自动重连的 WebSocket 客户端。
+ * 在连接断开时会根据配置进行重连尝试，支持指数退避。
+ */
+export class ReconnectingWebSocket {
+  private ws: WebSocket | null = null;
+  private url: string;
+  private config: Required<ReconnectConfig>;
+  private retryCount: number = 0;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private isManualClose: boolean = false;
+  private messageHandlers: Array<(data: any) => void> = [];
+  private openHandlers: Array<() => void> = [];
+  private closeHandlers: Array<(code: number, reason: Buffer) => void> = [];
+  private errorHandlers: Array<(error: Error) => void> = [];
+
+  constructor(url: string, config: ReconnectConfig = {}) {
+    this.url = url;
+    this.config = {
+      maxRetries: config.maxRetries ?? Infinity,
+      retryDelay: config.retryDelay ?? 1000,
+      maxDelay: config.maxDelay ?? 30000,
+      backoffMultiplier: config.backoffMultiplier ?? 2,
+    };
+  }
+  log(...args: any[]): void {
+    console.log('[ReconnectingWebSocket]', ...args);
+  }
+  error(...args: any[]): void {
+    console.error('[ReconnectingWebSocket]', ...args);
+  }
+  connect(): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      return;
+    }
+
+    this.log(`正在连接到 ${this.url}...`);
+    this.ws = new WebSocket(this.url);
+
+    this.ws.on('open', () => {
+      this.log('WebSocket 连接已打开');
+      this.retryCount = 0;
+      this.openHandlers.forEach(handler => handler());
+      this.send({ type: 'heartbeat', timestamp: new Date().toISOString() });
+    });
+
+    this.ws.on('message', (data: any) => {
+      this.messageHandlers.forEach(handler => {
+        try {
+          const message = JSON.parse(data.toString());
+          handler(message);
+        } catch {
+          handler(data.toString());
+        }
+      });
+    });
+
+    this.ws.on('close', (code: number, reason: Buffer) => {
+      this.log(`WebSocket 连接已关闭: code=${code}, reason=${reason.toString()}`);
+      this.closeHandlers.forEach(handler => handler(code, reason));
+
+      if (!this.isManualClose) {
+        this.scheduleReconnect();
+      }
+    });
+
+    this.ws.on('error', (error: Error) => {
+      this.error('WebSocket 错误:', error.message);
+      this.errorHandlers.forEach(handler => handler(error));
+    });
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) {
+      return;
+    }
+
+    if (this.retryCount >= this.config.maxRetries) {
+      this.error(`已达到最大重试次数 (${this.config.maxRetries})，停止重连`);
+      return;
+    }
+
+    // 计算延迟（指数退避）
+    const delay = Math.min(
+      this.config.retryDelay * Math.pow(this.config.backoffMultiplier, this.retryCount),
+      this.config.maxDelay
+    );
+
+    this.retryCount++;
+    this.log(`将在 ${delay}ms 后进行第 ${this.retryCount} 次重连尝试...`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+
+  send(data: any): boolean {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data));
+      return true;
+    }
+    this.log('WebSocket 未连接，无法发送消息');
+    return false;
+  }
+
+  onMessage(handler: (data: any) => void): void {
+    this.messageHandlers.push(handler);
+  }
+
+  onOpen(handler: () => void): void {
+    this.openHandlers.push(handler);
+  }
+
+  onClose(handler: (code: number, reason: Buffer) => void): void {
+    this.closeHandlers.push(handler);
+  }
+
+  onError(handler: (error: Error) => void): void {
+    this.errorHandlers.push(handler);
+  }
+
+  close(): void {
+    this.isManualClose = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  getReadyState(): number {
+    return this.ws?.readyState ?? WebSocket.CLOSED;
+  }
+
+  getRetryCount(): number {
+    return this.retryCount;
+  }
+}
+
+// const ws = new ReconnectingWebSocket('ws://localhost:51516/livecode/ws?id=test-live-app', {
+//   maxRetries: Infinity,    // 无限重试
+//   retryDelay: 1000,        // 初始重试延迟 1 秒
+//   maxDelay: 30000,         // 最大延迟 30 秒
+//   backoffMultiplier: 2,    // 指数退避倍数
+// });

package/src/ws.ts

@@ -0,0 +1,65 @@
+import { ReconnectingWebSocket, ReconnectConfig } from "./server/reconnect-ws.ts";
+
+export * from "./server/reconnect-ws.ts";
+import type { App } from "./app.ts";
+
+export const handleCallWsApp = async (ws: ReconnectingWebSocket, app: App, message: any) => {
+  return handleCallApp((data: any) => {
+    ws.send(data);
+  }, app, message);
+}
+export const handleCallApp = async (send: (data: any) => void, app: App, message: any) => {
+  if (message.type === 'router' && message.id) {
+    const data = message?.data;
+    if (!message.id) {
+      console.error('Message id is required for router type');
+      return;
+    }
+    if (!data) {
+      send({
+        type: 'router',
+        id: message.id,
+        data: { code: 500, message: 'No data received' }
+      });
+      return;
+    }
+    const { tokenUser, ...rest } = data || {};
+    const res = await app.run(rest, {
+      state: { tokenUser },
+      appId: app.appId,
+    });
+    send({
+      type: 'router',
+      id: message.id,
+      data: res
+    });
+  }
+}
+export class Ws {
+  wsClient: ReconnectingWebSocket;
+  app: App;
+  showLog: boolean = true;
+  constructor(opts?: ReconnectConfig & {
+    url: string;
+    app: App;
+    showLog?: boolean;
+    handleMessage?: (ws: ReconnectingWebSocket, app: App, message: any) => void;
+  }) {
+    const { url, app, showLog = true, handleMessage = handleCallWsApp, ...rest } = opts;
+    this.wsClient = new ReconnectingWebSocket(url, rest);
+    this.app = app;
+    this.showLog = showLog;
+    this.wsClient.connect();
+    const onMessage = async (data: any) => {
+      return handleMessage(this.wsClient, this.app, data);
+    }
+    this.wsClient.onMessage(onMessage);
+  }
+  send(data: any): boolean {
+    return this.wsClient.send(data);
+  }
+  log(...args: any[]): void {
+    if (this.showLog)
+      console.log('[Ws]', ...args);
+  }
+}