xshell 1.2.89 → 1.3.0

package/net.browser.js

@@ -1,7 +1,5 @@
 import { t } from "./i18n/instance.js";
-import { rethrow } from "./prototype.browser.js"; // to_time_str()
-import { message_symbol, pack, parse } from "./io.common.js";
-import { assert, genid, delay, Lock, timeout, check } from "./utils.browser.js";
+import { assert, delay } from "./utils.browser.js";
 import { drop_request_headers } from "./net.common.js";
 export * from "./net.common.js";
 async function fetch_retry(url, options, timeout, retries = 0, count = 0) {
@@ -142,409 +140,4 @@ export async function request_json(url, options) {
         throw error;
     }
 }
-export class WebSocketConnectionError extends Error {
-    name = 'WebSocketConnectionError';
-    // 这里不保留 websocket 引用，防止循环引用导致 JSON 序列化失败
-    url;
-    protocols;
-    event;
-    type;
-    code;
-    reason;
-    constructor(url, protocols, event, message) {
-        super(`${url}${protocols ? ' ' + protocols.join(', ').bracket() : ''} ${t('连接出错了')}. ${message || ''}`);
-        this.url = url;
-        this.protocols = protocols;
-        this.event = event;
-        this.type = event.type;
-        if (this.type === 'close') {
-            this.code = event.code;
-            this.reason = event.reason;
-        }
-    }
-}
-/** 连接 websocket url, 设置各种事件监听器。在 open 事件后 resolve, 返回 websocket
-    遇到 error 时会创建 WebSocketConnectionError:
-        - reject 掉返回的 promise (若此时未 settle)
-        - 作为参数调用 on_error (已 settle 且有 on_error 回调)
-    可以用 WebSocket.bufferedAmount 来显示大消息的发送进度
-    https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/bufferedAmount
-    - url
-    - options:
-        - protocols?
-        - on_message: 根据 websocket frame 的 opcode 不同 (text frame 或 binary frame)，event 中的 data 对应为 ArrayBuffer 或者 string
-          https://datatracker.ietf.org/doc/html/rfc6455#section-5.2
-        - on_error?: 在 websocket 出错和非正常关闭 (close, error 事件) 时都调用，可以根据 error.type 来区分，error 的类型是 WebSocketConnectionError，
-            type 为 'close' 时有 code 和 reason 属性
-        - on_close?: 和 websocket 的 'close' 事件不相同，只在正常关闭 (close code 为 1000) 时才调用，否则都会调用 on_error
-            https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes
-        - print?: 是否打印连接、关闭信息 */
-export async function connect_websocket(url, { protocols, on_message, on_error, on_close, print = true }) {
-    let websocket = new WebSocket(url, protocols);
-    // https://stackoverflow.com/questions/11821096/what-is-the-difference-between-an-arraybuffer-and-a-blob/39951543
-    websocket.binaryType = 'arraybuffer';
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        websocket.addEventListener('open', event => {
-            if (print)
-                console.log(websocket.url +
-                    (websocket.protocol ? ' ' + websocket.protocol.bracket() : '') +
-                    t(' 已连接'));
-            settled = true;
-            resolve(websocket);
-        });
-        websocket.addEventListener('close', event => {
-            if (event.code === 1000) { // 正常关闭
-                if (on_close)
-                    on_close(event, websocket);
-                else if (print)
-                    console.log(`${websocket.url} ${t('已正常关闭')}`);
-            }
-            else { // 异常关闭，认为发生了错误，进行错误处理
-                const error = new WebSocketConnectionError(websocket.url, protocols, event, `${t('连接被关闭')}, code: ${event.code}${event.reason ? `, ${t('原因')}: ${event.reason}` : ''}`);
-                if (settled)
-                    if (on_error)
-                        on_error(error, websocket);
-                    else // 既然用户不传 on_error, 就当 unhandled error 抛出来
-                        throw error;
-                else {
-                    settled = true;
-                    reject(error);
-                }
-            }
-        });
-        websocket.addEventListener('error', event => {
-            const error = new WebSocketConnectionError(websocket.url, protocols, event);
-            // https://blog.insiderattack.net/promises-next-ticks-and-immediates-nodejs-event-loop-part-3-9226cbe7a6aa
-            // close 的错误信息比较多，这里延后触发 error 事件，放到微任务队列之后的 timers 队列中
-            setTimeout(() => {
-                if (settled)
-                    if (on_error)
-                        on_error(error, websocket);
-                    else // 既然用户不传 on_error, 就当 unhandled error 抛出来
-                        throw error;
-                else {
-                    settled = true;
-                    reject(error);
-                }
-            });
-        });
-        websocket.addEventListener('message', event => {
-            on_message(event.data, websocket);
-        });
-    });
-}
-/** 通过创建 remote 对象对 websocket rpc 进行抽象
-    创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
-    使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
-    使用 remote.call 进行一元 rpc
-    使用 remote.send 结合 message.id 进行复杂 rpc
-    创建后等到首个 remote.call 或 remote.send 时自动建立实际 websocket 连接
-    rpc 状态与底层连接的状态无关，如果是传入 url 创建的 remote 实例，remote.send 时检测到断线会自动建立新的 websocket 连接
-    
-    @example
-    // Zero 继承自 Remote 并通过 call 实现了一些方法
-    let zero = new Zero({ local: true })
-    
-    // 一元 rpc
-    await zero.repl_ts('1234')
-    
-    // 订阅流
-    const id = genid()
-    
-    zero.handlers.set(id, ({ data: [chunk] }: Message<[Uint8Array]>) => {
-        term.write(chunk)
-    })
-    
-    zero.send({ id, func: 'subscribe_stdio' }) */
-export class Remote {
-    /** 在构造 Remote 时, this.initiator = Boolean(url || websocket)
-        - true:  作为 websocket 连接发起方
-        - false: 作为 websocket 连接接收方 */
-    initiator;
-    /** 作为 websocket 连接发起方，对端的 url 地址 */
-    url;
-    /** 作为 websocket 连接发起方有 websocket lock */
-    lwebsocket;
-    /** websocket 连接发起方，接收方，都能被对端通过 (rpc message).func 调用的 rpc 函数 */
-    funcs;
-    /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
-        一元 rpc 接收方不需要设置 handlers, 发送方需要 */
-    handlers = new Map();
-    keeper;
-    /** `true` 是否打印连接信息、错误信息 */
-    print = true;
-    /** `false` 打印所有交互的 rpc messages */
-    verbose = false;
-    first_error = true;
-    keeping = false;
-    reconnecting = false;
-    disconnected = false;
-    /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
-        作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
-    constructor({ url, funcs, print, verbose, websocket, keeper, on_error, } = {}) {
-        check(!(url && websocket), '构建 Remote 时 url 和 websocket 最多只能传一个');
-        this.initiator = Boolean(url || websocket);
-        if (url)
-            this.url = url;
-        check(!funcs?.echo);
-        this.funcs = {
-            ...funcs,
-            echo({ data }) {
-                return data;
-            }
-        };
-        if (print !== undefined)
-            this.print = print;
-        if (verbose !== undefined)
-            this.verbose = verbose;
-        if (on_error)
-            this.on_error = on_error;
-        if (this.initiator)
-            this.lwebsocket = new Lock(websocket || null);
-        if (keeper) {
-            check(this.initiator && url);
-            this.keeper = {
-                reconnect_interval: 5000,
-                heartbeat_interval: 1000 * 60,
-                error_delay: 2000,
-                ...keeper
-            };
-        }
-    }
-    /** 统一处理首次连接和连接后的 websocket 错误 */
-    _on_error = (error, websocket) => {
-        if (this.keeper && !this.reconnecting && !this.disconnected) // 在一段时间后调度错误重连
-            (async () => {
-                this.reconnecting = true;
-                const { error_delay, reconnect_interval } = this.keeper;
-                if (this.first_error) {
-                    this.first_error = false;
-                    await delay(error_delay);
-                }
-                else
-                    await delay(reconnect_interval);
-                this.reconnecting = false;
-                if (!this.disconnected)
-                    try {
-                        await timeout(3000, this.connect(), undefined, this.print);
-                        this.first_error = true;
-                    }
-                    catch (error) {
-                        // 重连失败的错误这里需要简单打印下，_on_error 不会打印，这里也不继续往上抛了
-                        if (this.print)
-                            console.log(error.message);
-                        // 重连由 this.connect 里面调用 this._on_error 处理
-                    }
-            })();
-        this.on_error(error, websocket);
-    };
-    _on_message = (data, websocket) => {
-        this.handle(new Uint8Array(data), websocket);
-    };
-    /** 使用者自定义的在 websocket 连接出错时，或者 handlers 出错时的处理 */
-    on_error(error, websocket) {
-        // 使用者未定义 Remote 如何处理 error 时，一般来说直接忽略即可，因为 handlers 中报错了也会返回给对端
-        if (this.print)
-            console.log(error && error instanceof WebSocketConnectionError ? error.message : error);
-        // 这里继续往上层抛没有太大意义，上面一般都是 websocket on_message 这些
-    }
-    /** 幂等，保证 websocket 已连接，否则抛出异常
-        一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
-        连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
-        作为 websocket 连接发起方，不需要传入 websocket
-        作为 websocket 连接接收方，需要传入使用的 websocket 连接，确保这个这个连接的状态 */
-    async connect(websocket) {
-        if (!this.initiator)
-            if (websocket.readyState !== WebSocket.OPEN)
-                throw new Error('传入的 websocket 连接已断开');
-            else
-                return;
-        if (this.lwebsocket.resource?.readyState === WebSocket.OPEN)
-            return;
-        if (!this.url)
-            throw new Error('创建 Remote 时传入的 websocket 连接已断开');
-        let reconnected = false;
-        // 假设有多个请求想要并发连接 websocket, 且此时 websocket 是断开的状态
-        // 应该排队依次连接，而不是后续的连接直接使用第一次连接的 promise，后续调用还是应该尝试重连（不止连接一次）
-        await this.lwebsocket.request(async (websocket) => {
-            // 保存的 rpc 状态在 this.handlers, 与 websocket 无关，因此即使断开重连也不影响 rpc 的运行，即
-            // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
-            if (websocket?.readyState === WebSocket.OPEN)
-                return;
-            // 重连
-            try {
-                this.lwebsocket.resource = await connect_websocket(this.url, {
-                    on_message: this._on_message,
-                    on_error: this._on_error,
-                    print: this.print
-                });
-                reconnected = true;
-            }
-            catch (error) {
-                this._on_error(error);
-                throw error;
-            }
-        });
-        if (!this.keeper)
-            return;
-        const { heartbeat_interval, func, args } = this.keeper;
-        // 首次连接成功时，开始心跳保活
-        if (!this.keeping) {
-            this.keeping = true;
-            (async () => {
-                for (;;) {
-                    await delay(heartbeat_interval);
-                    if (this.disconnected)
-                        break;
-                    if (!this.reconnecting)
-                        try {
-                            await timeout(1000 * 2, this.call('echo'), undefined, this.print);
-                        }
-                        catch (error) {
-                            if (this.print)
-                                console.log(error.message);
-                            this._on_error(error);
-                        }
-                }
-            })();
-        }
-        if (reconnected && func)
-            await this.call(func, args);
-    }
-    /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
-    disconnect() {
-        this.disconnected = true;
-        this.lwebsocket.resource?.close(1000);
-    }
-    /** 发送 message 到对端 remote
-        作为 websocket 连接发起方，不需要传入 websocket
-        作为 websocket 连接接收方，必传 websocket 参数
-        发送或连接出错时自动清理 message.id 对应的 handler */
-    async send(message, websocket) {
-        if (this.verbose)
-            console.log('remote.send:', message);
-        try {
-            await this.connect(websocket);
-            message[message_symbol] = true;
-            (websocket || this.lwebsocket.resource).send(pack(message));
-        }
-        catch (error) {
-            if (message.id)
-                this.handlers.delete(message.id);
-            throw error;
-        }
-    }
-    /** 处理接收到的 websocket message 并解析, 根据 message.id 或 message.func 分发到对应的 handler 进行处理，
-        handler 处理完成后:
-        - 传了 func: 调用函数的情况下 (通常是一元 rpc)，总是将返回值包装为 message 回传
-        - 未传 func: 通过 id 调用，如果 handler 返回非 undefined 的值，也包装为 message 回传
-        
-        如果 message.done == true 则对端指示当前 remote 可以清理 handler
-        使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214
-        这个方法一般不会抛出错误，也不需要 await，一般在 websocket on_message 时使用 */
-    async handle(data, websocket) {
-        let message;
-        try {
-            check(data[0] === 0xcc, 'message 格式错误');
-            message = parse(data);
-        }
-        catch (error) {
-            this.on_error(error);
-            return;
-        }
-        const { id, func, done } = message;
-        if (this.verbose)
-            console.log('remote.handle:', message);
-        let handler;
-        if (func) {
-            handler = this.funcs[func];
-            // 传了 func 调用函数的情况下，如果 message.data 为 undefined, 默认为 [ ]
-            if (message.data === undefined)
-                message.data = [];
-        }
-        else {
-            handler = this.handlers.get(id);
-            if (done && handler)
-                this.handlers.delete(id);
-        }
-        try {
-            if (handler) {
-                const data = await handler(message, websocket);
-                if (func || data !== undefined)
-                    await this.send({ id, data }, websocket);
-            }
-            else
-                throw message.error || new Error(`找不到 rpc handler: ${func ? `func: ${func.quote()}` : `id: ${id}`}`);
-        }
-        catch (error) {
-            // handler 出错并不意味着 rpc 一定会结束，可能 error 是运行中的正常数据，所以不能清理 handler
-            if (websocket.readyState === WebSocket.OPEN &&
-                !message.error // 防止无限循环往对方发送 error, 只有在对方无错误时才可以发送
-            )
-                await this.send({ id, error, /* 不能设置 done 清理对面 handler, 理由同上 */ }, websocket);
-            // 这里继续往上层抛没有太大意义，上面一般都是 websocket on_message 这些，交给自定义或默认的 on_error 处理
-            this.on_error(error);
-        }
-    }
-    /** 调用对端 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应)
-        作为 websocket 连接发起方，不需要传入 websocket
-        作为 websocket 连接接收方，必传 websocket 参数  */
-    async call(func, args, websocket) {
-        return new Promise(async (resolve, reject) => {
-            const id = genid();
-            this.handlers.set(id, ({ error, data }) => {
-                if (error)
-                    reject(error);
-                else
-                    resolve(data);
-                this.handlers.delete(id);
-            });
-            try {
-                await this.send({ id, func, data: args }, websocket); // 不需要 done: true, 因为对面的 remote.handlers 中不会有这个 id 的 handler
-            }
-            catch (error) {
-                reject(error);
-            }
-        });
-    }
-    /** 调用对端 remote 中的 func, 开始订阅并接收连续的消息 (订阅流)
-        - func: 订阅处理函数
-        - on_data: 接收开始订阅后的数据
-        - options?:
-            - on_error?: 处理开始订阅后的错误
-            - websocket?: 作为 websocket 连接接收方，必传 websocket 参数 */
-    async subscribe(func, on_data, { on_error = rethrow, websocket } = {}) {
-        const id = genid();
-        let psubscribed = new Promise((resolve, reject) => {
-            let first = true;
-            this.handlers.set(id, ({ error, data }) => {
-                if (error) {
-                    if (first) {
-                        first = false;
-                        this.handlers.delete(id);
-                        reject(error);
-                    }
-                    else
-                        on_error(error);
-                    return;
-                }
-                if (first) {
-                    first = false;
-                    resolve({ id, data: data });
-                    return;
-                }
-                on_data(data);
-            });
-        });
-        try {
-            await this.send({ id, func }, websocket);
-        }
-        catch (error) {
-            this.handlers.delete(id);
-            throw error;
-        }
-        return psubscribed;
-    }
-}
 //# sourceMappingURL=net.browser.js.map

package/net.common.d.ts

@@ -1,3 +1,5 @@
+import { type Message } from './io.common.ts';
+import { Lock, TimeoutError } from './utils.common.ts';
 /** 对于 request() 函数来说无意义的 headers，会自动过滤掉 */
 export declare const drop_request_headers: Set<string>;
 export interface BasicAuth {
@@ -26,3 +28,179 @@ export interface RemoteKeeperOptions {
     heartbeat_interval?: number;
     error_delay?: number;
 }
+export declare const WebSocketConnecting = 0;
+export declare const WebSocketOpen = 1;
+export declare const WebSocketClosing = 2;
+export declare const WebSocketClosed = 3;
+export declare const websocket_states: readonly ["connecting", "open", "closing", "closed"];
+export declare class WebSocketConnectionError extends Error {
+    name: "WebSocketConnectionError";
+    url: string;
+    protocols?: string[];
+    type?: 'close' | 'error';
+    /** close 事件时为 close code (非 1000 的 number), error 事件为 error code (可能是 string) */
+    code?: string | number;
+    reason?: string;
+    event?: CloseEvent | ErrorEvent;
+    address?: string;
+    errno?: number;
+    port?: number;
+    syscall?: string;
+    static get_reason_string(code: number | string, reason?: string): string | number;
+    constructor(url: string, protocols: string[] | undefined, event?: CloseEvent | ErrorEvent, message?: string);
+}
+/** 连接 websocket url, 设置各种事件监听器。在 open 事件后 resolve, 返回 websocket
+    遇到 error, close 事件时会创建 WebSocketConnectionError:
+        - reject 掉返回的 promise (若此时未 settle)
+        - 作为参数调用 on_error (已 settle 且有 on_error 回调)
+    可以用 WebSocket.bufferedAmount 来查询大消息的发送进度
+    https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/bufferedAmount
+    - url
+    - options:
+        - print?: 是否打印连接、关闭信息
+        - protocols?
+        - max_payload?: `8 gb` (仅 nodejs 环境有效)
+        - proxy?: string (仅 nodejs 环境有效)
+        - on_message: 根据 websocket frame 的 opcode 不同 (text frame 或 binary frame)，event 中的 data 对应为 ArrayBuffer 或者 string
+          https://datatracker.ietf.org/doc/html/rfc6455#section-5.2
+        - on_error?: 在 websocket 出错和非正常关闭 (close, error 事件) 时都调用，可以根据 error.type 来区分，error 的类型是 WebSocketConnectionError，
+            type 为 'close' 时有 code 和 reason 属性
+        - on_close?: 和 websocket 的 'close' 事件不相同，只在正常关闭 (close code 为 1000) 时才调用，否则都会调用 on_error
+            https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes */
+export declare function connect_websocket(url: string | URL, { print, protocols, max_payload, // 8 GB
+proxy, on_message, on_error, on_close, }: {
+    print?: boolean;
+    protocols?: string[];
+    max_payload?: number;
+    proxy?: string;
+    on_message(data: ArrayBuffer | string, websocket: WebSocket): any;
+    on_error?(error: WebSocketConnectionError, websocket: WebSocket): any;
+    on_close?(event: CloseEvent, websocket: WebSocket): any;
+}): Promise<WebSocket>;
+/** 接收到消息后的处理函数
+    返回值会自动被 await，然后可能被封装为 message 回传 */
+export type MessageHandler<TData = any> = (message: Message<TData>, remote: Remote) => void | any | Promise<void | any>;
+export interface RemoteOptions {
+    /** 对端名称，方便接收端提供更明确的报错信息 */
+    name?: string;
+    /** 作为 websocket 连接发起方，对端的 url 地址 */
+    url?: string;
+    /** 作为 websocket 连接接收方，将已有的 websocket 连接转为 rpc 通道 */
+    websocket?: WebSocket;
+    /** 能被对端调用的函数 */
+    funcs?: Remote['funcs'];
+    /** `false` 是否启用主动探测连接，在连接状态下以 30s 间隔发送心跳包确保连接状态 */
+    probe?: boolean;
+    /** websocket 连接建立成功时调用对端 register 函数的参数 (仅发起方有效) */
+    args?: any[];
+    /** `true` 是否打印连接信息、错误信息 */
+    print?: boolean;
+    /** `false` 打印所有交互的 rpc messages */
+    verbose?: boolean;
+    /** 使用者自定义的在 websocket 连接出错时，或者 handlers 出错时的处理
+        用户设置后会覆盖默认的 print 错误功能 */
+    on_error?(error: WebSocketConnectionError | Error, remote: Remote): void;
+}
+/** 通过创建 remote 对象对 websocket rpc 进行抽象
+    使用 remote.call() 进行一元 rpc
+    使用 remote.send() 结合 message.id 进行复杂 rpc
+    
+    可传入 funcs 注册函数，使得对端能调用，传入后，
+    连接发起方在检测到连接断开后间隔 2s (首次) / 10s 尝试重连
+    
+    可启用 probe 选项启用主动探测连接，进一步确保连接可靠性
+    
+    有两种创建方法:
+    - 传入 url 主动创建 websocket 连接
+        创建后等到首个 remote.call 或 remote.send 时建立实际 websocket 连接
+    - 传入 websocket，监听事件，将已有的 websocket 连接转为 rpc 通道
+    
+    rpc 状态与底层连接的状态无关，如果是发起方，remote.send 时检测到断线会自动尝试建立新的 websocket 连接 */
+export declare class Remote {
+    /** 对端名称，方便接收端提供更明确的报错信息 */
+    name?: string;
+    /** 作为 websocket 连接发起方，对端的 url 地址 */
+    url?: string;
+    /** 能被对端调用的函数 */
+    funcs: Record<string, MessageHandler>;
+    /** `false` 是否启用主动探测连接，在连接状态下以 30s 间隔发送心跳包确保连接状态 */
+    probe: boolean;
+    /** websocket 连接建立成功时调用对端 register 函数的参数 (仅发起方有效) */
+    args?: any[];
+    /** `true` 是否打印连接信息、错误信息 */
+    print: boolean;
+    /** `false` 打印所有交互的 rpc messages */
+    verbose: boolean;
+    /** 防止作为 websocket 连接发起方时并发创建 websocket 连接 */
+    lwebsocket: Lock<WebSocket>;
+    /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
+        一元 rpc 接收方不需要设置 handlers, 发送方需要 */
+    handlers: Map<number, MessageHandler<any>>;
+    /** 是否正在定时主动检测重连 */
+    probing: boolean;
+    /** websocket 检测到错误，_on_error 被调用，此时会尝试一段时间后重连 */
+    reconnecting: NodeJS.Timeout;
+    /** 用户是否手动调用了 disconnect() 主动断开了连接 (仅发起方有效) */
+    disconnected: boolean;
+    /** on_error 接收到的，正常 websocket 连接发生的首个非 TimeoutError 错误 */
+    error: WebSocketConnectionError | Error;
+    /** 作为 websocket 连接发起方，传入 url
+        作为 websocket 连接接收方，传入 websocket + name */
+    constructor({ name, url, websocket, funcs, print, verbose, probe, args, on_error, }?: RemoteOptions);
+    /** 统一处理首次连接和连接后的 websocket 错误 */
+    _on_error: (error: WebSocketConnectionError | Error) => void;
+    reconnect: () => void;
+    _on_message: (data: ArrayBuffer) => void;
+    /** 使用者自定义的在 websocket 连接出错时，或者 handlers 出错时的处理
+        用户设置后会覆盖默认的 print 错误功能 */
+    on_error(error: WebSocketConnectionError | Error, remote: Remote): void;
+    print_error(error: WebSocketConnectionError | Error): void;
+    /** 检查是否已经有 error, websocket 状态是否正常 (open | connecting)
+        返回 true: 连接正常，false: 连接异常 */
+    check_connection(): boolean;
+    /** 幂等，保证 websocket 已连接，否则抛出异常
+        通常用于手动建立 websocket 连接并确保成功
+        连接断开后，作为发起方会自动创建新的 websocket 连接;
+        作为接收方只会检查连接状态，在断开时抛出异常
+        保存的 rpc 状态在 this.handlers, 与 websocket 无关，因此即使断开重连也不影响 rpc 的运行，即
+        底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败 */
+    connect(): Promise<void>;
+    _connect: () => Promise<void>;
+    /** 尝试建立连接，通常用于开始保活
+        重连错误会在 this.connect 里面调用 this._on_error 处理 */
+    try_connect(): Promise<void>;
+    /** 开始心跳保活 */
+    probe_connection(print_timeout?: boolean): Promise<void>;
+    /** 检测连接，返回连接错误，出错时触发 on_error 打印错误信息
+        返回值:
+        - 连接正常返回: undefined
+        - 连接错误返回: 实际的连接错误，通常是 WebSocketConnectionError | TimeoutError */
+    test(print_timeout?: boolean): Promise<WebSocketConnectionError | TimeoutError | Error>;
+    /** 手动关闭到对端的 websocket 连接 */
+    disconnect(): void;
+    /** 发送 message 到对端 remote
+        发送或连接出错时自动清理 message.id 对应的 handler */
+    send(message: Message): Promise<void>;
+    /** 能发就发一下，忽略发送失败, best effort */
+    try_send(message: Message): void;
+    /** 处理接收到的 websocket message 并解析, 根据 message.id 或 message.func 分发到对应的 handler 进行处理，
+        handler 处理完成后:
+        - 传了 func: 调用函数的情况下 (通常是一元 rpc)，总是将返回值包装为 message 回传
+        - 未传 func: 通过 id 调用，如果 handler 返回非 undefined 的值，也包装为 message 回传
+        
+        如果 message.done == true 则对端指示当前 remote 可以清理 handler
+        使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214
+        这个方法一般不会抛出错误，也不需要 await，一般在 websocket on_message 时使用 */
+    handle(data: Uint8Array): Promise<void>;
+    /** 调用对端 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
+    call<TReturn = any>(func: string, args?: any[]): Promise<TReturn>;
+    /** 调用对端 remote 中的 func, 开始订阅并接收连续的消息 (订阅流)
+        - func: 订阅处理函数
+        - on_data: 接收开始订阅后的数据
+        - options?:
+            - on_error?: 处理开始订阅后的错误 */
+    subscribe<TData, TSubscribed = void>(func: string, on_data: (data: TData) => void, on_error?: Remote['on_error']): Promise<{
+        id: number;
+        data: TSubscribed;
+    }>;
+}