xshell 1.0.112 → 1.0.114

package/file.d.ts

@@ -71,8 +71,8 @@ interface FWriteOptions {
         - print?: `true` */
 export declare function fwrite(fp: string, data: string | Uint8Array | any, options?: FWriteOptions): Promise<string>;
 export declare function fwrite(fp: FileHandle, data: string | Uint8Array | any, options?: FWriteOptions): Promise<FileHandle>;
-export declare function fappend(fp: string, data: string | Uint8Array, { dir, print }?: {
-    dir?: string;
+/** 追加内容到文件末尾，如果文件不存在会自动创建 */
+export declare function fappend(fp: string, data: string | Uint8Array, { print }?: {
     print?: boolean;
 }): Promise<void>;
 export type FStats = fs.BigIntStats & {

package/file.js

@@ -99,16 +99,23 @@ export async function fwrite(fp, data, { print = true } = {}) {
     }
     return fp;
 }
-export async function fappend(fp, data, { dir, print = true } = {}) {
-    if (dir) {
-        assert(dir.isdir, t('dir 必须以 / 结尾'));
-        fp = dir + fp;
-    }
+/** 追加内容到文件末尾，如果文件不存在会自动创建 */
+export async function fappend(fp, data, { print = true } = {}) {
     assert(path.isAbsolute(fp), `${t('fp 必须是绝对路径，当前为:')} ${fp}`);
     if (print)
         console.log(t('追加'), fp);
     assert(isUint8Array(data) || typeof data === 'string');
-    await fsp.appendFile(fp, data);
+    try {
+        await fsp.appendFile(fp, data);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            await fmkdir(fp.fdir, { print: false });
+            await fsp.appendFile(fp, data);
+        }
+        else
+            throw error;
+    }
 }
 export async function flist(fpd, options = {}) {
     const { filter, deep = false, absolute = false, print = true, stats = false } = options;

package/net.browser.d.ts

@@ -130,6 +130,23 @@ export interface Message<TData extends any[] = any[]> {
     /** bins: data 中哪些下标对应的原始值是 Uint8Array 类型的，如: [0, 3] */
     bins?: number[];
 }
+/** 自动保持 remote 连接，只对 initiator 且传入 url 有效，
+    - 在未连接，或 websocket on_error 检测到连接断开后以 reconnect_interval 间隔尝试 remote.call(func) 重连
+    - 在连接状态下以 heartbeat_interval 间隔发送心跳包确保连接状态
+    
+    配置选项:
+    - func?: 连接后调用的函数，通常为某个 register 函数，将自身注册到 server
+    - args?: 连接后调用函数时传递的参数，与 func 配合使用
+    - reconnect_interval?: `1000 * 5` 首次重连失败后的后续尝试间隔 (单位: ms)
+    - heartbeat_interval?: `1000 * 60` 发送心跳包确保连接的间隔 (单位: ms)
+    - error_delay?: `2000` 遇到错误时首次尝试重连的延时 (单位: ms) */
+export interface RemoteKeeperOptions {
+    func?: string;
+    args?: any[];
+    reconnect_interval?: number;
+    heartbeat_interval?: number;
+    error_delay?: number;
+}
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
     创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
     使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
@@ -167,22 +184,31 @@ export declare class Remote {
     /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
         一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers: Map<number, MessageHandler<any[]>>;
+    keeper?: RemoteKeeperOptions;
     /** `false` 打印所有交互的 rpc messages */
     print: boolean;
+    first_error: boolean;
+    keeping: boolean;
     reconnecting: boolean;
+    disconnected: boolean;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse<TData extends any[] = any[]>(buffer: Uint8Array): Message<TData>;
     static pack({ id, func, data, done, error }: Message): Uint8Array;
     /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
         作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
-    constructor({ url, funcs, print, websocket, on_error }?: {
+    constructor({ url, funcs, print, websocket, keeper, on_error, }?: {
         url?: string;
         funcs?: Remote['funcs'];
         print?: boolean;
         websocket?: WebSocket;
-        on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
+        keeper?: RemoteKeeperOptions;
+        on_error?(error: WebSocketConnectionError, websocket?: WebSocket): void;
     });
-    on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
+    /** 统一处理首次连接错误和连接后的错误 */
+    _on_error: (error: WebSocketConnectionError, websocket?: WebSocket) => void;
+    _on_message: (data: ArrayBuffer, websocket: WebSocket) => void;
+    /** 使用者自定义的在连接后出错时的处理 */
+    on_error?(error: WebSocketConnectionError, websocket?: WebSocket): void;
     /** 幂等，保证 websocket 已连接，否则抛出异常
         一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
         连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
@@ -205,18 +231,4 @@ export declare class Remote {
         作为 websocket 连接发起方，不需要传入 websocket
         作为 websocket 连接接收方，必传 websocket 参数  */
     call<TReturn extends any[] = any[]>(func: string, args?: any[], websocket?: WebSocket): Promise<TReturn>;
-    /** 是幂等的，在未连接，或 (on_error) 检测到连接断开后以固定间隔尝试 remote.call(func) 重连
-        通常在 on_error 中和首次启动时调用
-        - func?: 连接后调用的函数，通常为某个 register 函数，将自身注册到 server
-        - duration?: `1000 * 30` 首次重连失败后的后续尝试间隔 (单位: ms)
-        - first_delay?: `0` 调用函数后是否立即连接，还是在 first_delay 后重连 (单位: ms)
-        - on_error?: 接收每次尝试连接的错误 */
-    start_reconnecting({ func, args, interval, first_delay, on_error, }?: RemoteReconnectingOptions): Promise<void>;
-}
-export interface RemoteReconnectingOptions {
-    func?: string;
-    args?: any[];
-    interval?: number;
-    first_delay?: number;
-    on_error?(error: Error): void;
 }

package/net.browser.js

@@ -277,9 +277,13 @@ export class Remote {
     /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
         一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers = new Map();
+    keeper;
     /** `false` 打印所有交互的 rpc messages */
     print = false;
+    first_error = true;
+    keeping = false;
     reconnecting = false;
+    disconnected = false;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse(buffer) {
         const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -300,7 +304,7 @@ export class Remote {
         return message;
     }
     static pack({ id, func, data = [], done, error }) {
-        assert('length' in data, t('message.data 必须是数组'));
+        assert('length' in data, 'message.data 必须是数组');
         let data_ = new Array(data.length);
         let bins = [];
         let bufs = [];
@@ -330,22 +334,68 @@ export class Remote {
     }
     /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
         作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
-    constructor({ url, funcs, print, websocket, on_error } = {}) {
-        assert(!(url && websocket), t('构建 Remote 时 url 和 websocket 最多只能传一个'));
+    constructor({ url, funcs, print, websocket, keeper, on_error, } = {}) {
+        assert(!(url && websocket), '构建 Remote 时 url 和 websocket 最多只能传一个');
         this.initiator = Boolean(url || websocket);
         if (url)
             this.url = url;
-        if (funcs)
-            this.funcs = funcs;
+        assert(!funcs?.echo);
+        this.funcs = this.initiator ? funcs : {
+            ...funcs,
+            echo({ data }) {
+                return data;
+            }
+        };
         if (print !== undefined)
             this.print = print;
         if (on_error)
             this.on_error = on_error;
         if (this.initiator)
             this.lwebsocket = new Lock(websocket || null);
+        if (keeper) {
+            assert(this.initiator && url);
+            this.keeper = {
+                reconnect_interval: 1000 * 5,
+                heartbeat_interval: 1000 * 60,
+                error_delay: 1000 * 2,
+                ...keeper
+            };
+        }
     }
+    /** 统一处理首次连接错误和连接后的错误 */
+    _on_error = (error, websocket) => {
+        if (websocket) // 连接后出现的错误
+            this.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 this.connect();
+                        this.first_error = true;
+                    }
+                    catch {
+                        // 错误由 this.connect 里面处理
+                    }
+            })();
+    };
+    _on_message = (data, websocket) => {
+        this.handle(new Uint8Array(data), websocket);
+    };
+    /** 使用者自定义的在连接后出错时的处理 */
     on_error(error, websocket) {
-        throw error;
+        if (this.keeper)
+            console.log(error.message);
+        else
+            throw error;
     }
     /** 幂等，保证 websocket 已连接，否则抛出异常
         一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
@@ -357,28 +407,58 @@ export class Remote {
             if (this.lwebsocket.resource?.readyState === WebSocket.OPEN)
                 return;
             else if (!this.url)
-                throw new Error(t('创建 Remote 时传入的 websocket 连接已断开'));
-            else
+                throw new Error('创建 Remote 时传入的 websocket 连接已断开');
+            else {
+                let reconnected = false;
                 // 假设有多个请求想要并发连接 websocket, 且此时 websocket 是断开的状态
                 // 应该排队依次连接，而不是后续的连接直接使用第一次连接的 promise，后续调用还是应该尝试重连（不止连接一次）
-                return this.lwebsocket.request(async (websocket) => {
+                await this.lwebsocket.request(async (websocket) => {
                     // 保存的 rpc 状态在 this.handlers, 与 websocket 无关，因此即使断开重连也不影响 rpc 的运行，即
                     // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
-                    if (websocket?.readyState === WebSocket.OPEN)
-                        return;
-                    else // 重连
-                        this.lwebsocket.resource = await connect_websocket(this.url, {
-                            on_message: (data, websocket) => {
-                                this.handle(new Uint8Array(data), websocket);
-                            },
-                            on_error: this.on_error.bind(this)
-                        });
+                    if (websocket?.readyState !== WebSocket.OPEN) { // 重连
+                        try {
+                            this.lwebsocket.resource = await connect_websocket(this.url, {
+                                on_message: this._on_message,
+                                on_error: this._on_error
+                            });
+                            reconnected = true;
+                        }
+                        catch (error) {
+                            this._on_error(error);
+                            throw error;
+                        }
+                    }
                 });
+                if (this.keeper) {
+                    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 this.call('echo', []);
+                                    }
+                                    catch (error) {
+                                        this._on_error(error);
+                                    }
+                            }
+                        })();
+                    }
+                    if (reconnected && func)
+                        await this.call(func, args);
+                }
+            }
         else if (websocket.readyState !== WebSocket.OPEN)
-            throw new Error(t('传入的 websocket 连接已断开'));
+            throw new Error('传入的 websocket 连接已断开');
     }
     /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
     disconnect() {
+        this.disconnected = true;
         this.lwebsocket.resource?.close(1000);
     }
     /** 发送 message 到对端 remote
@@ -386,7 +466,7 @@ export class Remote {
         作为 websocket 连接接收方，必传 websocket 参数
         发送或连接出错时自动清理 message.id 对应的 handler */
     async send(message, websocket) {
-        assert(!message.data || message.data.every(arg => arg !== undefined), t('message.data 数组中不能有 undefined 的项, 因为 json 序列化后会变为 null'));
+        assert(!message.data || message.data.every(arg => arg !== undefined), `message.data 数组中不能有 undefined 的项, 因为 json 序列化后会变为 null. (func: ${message.func}, id: ${message.id})`);
         if (this.print)
             console.log('remote.send:', message);
         try {
@@ -425,7 +505,7 @@ export class Remote {
                     await this.send({ id, data }, websocket);
             }
             else
-                throw message.error || new Error(`${t('找不到 rpc handler')}: ${func ? `func: ${func.quote()}` : `id: ${id}`}`);
+                throw message.error || new Error(`找不到 rpc handler: ${func ? `func: ${func.quote()}` : `id: ${id}`}`);
         }
         catch (error) {
             // handler 出错并不意味着 rpc 一定会结束，可能 error 是运行中的正常数据，所以不能清理 handler
@@ -458,38 +538,5 @@ export class Remote {
             }
         });
     }
-    /** 是幂等的，在未连接，或 (on_error) 检测到连接断开后以固定间隔尝试 remote.call(func) 重连
-        通常在 on_error 中和首次启动时调用
-        - func?: 连接后调用的函数，通常为某个 register 函数，将自身注册到 server
-        - duration?: `1000 * 30` 首次重连失败后的后续尝试间隔 (单位: ms)
-        - first_delay?: `0` 调用函数后是否立即连接，还是在 first_delay 后重连 (单位: ms)
-        - on_error?: 接收每次尝试连接的错误 */
-    async start_reconnecting({ func, args, interval = 1000 * 10, first_delay = 0, on_error, } = {}) {
-        assert(this.url);
-        if (this.reconnecting)
-            return;
-        this.reconnecting = true;
-        if (first_delay)
-            await delay(first_delay);
-        for (;;) {
-            if (this.lwebsocket.resource?.readyState !== WebSocket.OPEN)
-                try {
-                    if (func)
-                        await this.call(func, args);
-                    else
-                        await this.connect();
-                    this.reconnecting = false;
-                    break;
-                }
-                catch (error) {
-                    on_error?.(error);
-                }
-            else {
-                this.reconnecting = false;
-                break;
-            }
-            await delay(interval);
-        }
-    }
 }
 //# sourceMappingURL=net.browser.js.map

package/net.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="node" resolution-mode="require"/>
 /// <reference types="node" resolution-mode="require"/>
-import type { Readable } from 'stream';
+import { type Readable } from 'stream';
 import type { FormData } from 'undici';
 import type { WebSocket, CloseEvent, ErrorEvent } from 'ws';
 import type { Cookie, CookieJar, MemoryCookieStore } from 'tough-cookie';
@@ -20,7 +20,7 @@ export declare const WebSocketClosed = 3;
 export declare enum MyProxy {
     socks5 = "http://localhost:10080",
     whistle = "http://localhost:8899",
-    work = "http://127.0.0.1:10090"
+    work = "http://localhost:10090"
 }
 export declare const cookies: {
     store: MemoryCookieStore;
@@ -51,7 +51,7 @@ export interface RequestOptions {
     method?: 'GET' | 'POST' | 'PUT' | 'HEAD' | 'DELETE' | 'PATCH';
     queries?: Record<string, any>;
     headers?: Record<string, string>;
-    body?: string | Record<string, any> | Uint8Array | URLSearchParams | FormData;
+    body?: string | Record<string, any> | Uint8Array | URLSearchParams | FormData | Readable;
     type?: 'application/json' | 'application/x-www-form-urlencoded' | 'multipart/form-data';
     proxy?: boolean | MyProxy | string;
     encoding?: Encoding | 'binary';
@@ -60,6 +60,7 @@ export interface RequestOptions {
     auth?: BasicAuth | BearerAuth;
     cookies?: Record<string, string>;
     redirect?: RequestRedirect;
+    decode?: boolean;
 }
 export interface RequestFullOptions extends RequestOptions {
     full: true;
@@ -97,7 +98,8 @@ export interface RequestError extends Error {
         - auth?: BasicAuth | BearerAuth
         - cookies?: 需要额外添加到请求的 cookies, 默认情况下携带了 MemoryCookieStore 中保存的之前 http 响应中的 cookies
         - raw?: `false` 传入后返回整个 response (RawResponse)，body 为 Readable
-        - full?: `false` 传入后返回整个 response (FullResponse)，body 根据 encoding 对应为 string 或 Buffer */
+        - full?: `false` 传入后返回整个 response (FullResponse)，body 根据 encoding 对应为 string 或 Buffer
+        - decode?: 根据 content-encoding: br 等解码压缩后的 response.body */
 export declare function request(url: string | URL): Promise<string>;
 export declare function request(url: string | URL, options: RequestRawOptions): Promise<RawResponse>;
 export declare function request(url: string | URL, options: RequestFullOptions & {
@@ -195,6 +197,23 @@ export interface Message<TData extends any[] = any[]> {
     /** bins: data 中哪些下标对应的原始值是 Uint8Array 类型的，如: [0, 3] */
     bins?: number[];
 }
+/** 自动保持 remote 连接，只对 initiator 且传入 url 有效，
+    - 在未连接，或 websocket on_error 检测到连接断开后以 reconnect_interval 间隔尝试 remote.call(func) 重连
+    - 在连接状态下以 heartbeat_interval 间隔发送心跳包确保连接状态
+    
+    配置选项:
+    - func?: 连接后调用的函数，通常为某个 register 函数，将自身注册到 server
+    - args?: 连接后调用函数时传递的参数，与 func 配合使用
+    - reconnect_interval?: `1000 * 5` 首次重连失败后的后续尝试间隔 (单位: ms)
+    - heartbeat_interval?: `1000 * 60` 发送心跳包确保连接的间隔 (单位: ms)
+    - error_delay?: `2000` 遇到错误时首次尝试重连的延时 (单位: ms) */
+export interface RemoteKeeperOptions {
+    func?: string;
+    args?: any[];
+    reconnect_interval?: number;
+    heartbeat_interval?: number;
+    error_delay?: number;
+}
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
     创建 remote 对象时传入 funcs 注册处理函数，使得对端能通过 (rpc message).func 调用
     使用 remote.handle 方法处理对端发来的 websocket message，对于 websocket 连接接收方需要手动绑定 websocket message 事件到 remote.handle
@@ -232,22 +251,31 @@ export declare class Remote {
     /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
         一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers: Map<number, MessageHandler<any[]>>;
+    keeper?: RemoteKeeperOptions;
     /** `false` 打印所有交互的 rpc messages */
     print: boolean;
+    first_error: boolean;
+    keeping: boolean;
     reconnecting: boolean;
+    disconnected: boolean;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse<TData extends any[] = any[]>(buffer: Uint8Array): Message<TData>;
     static pack({ id, func, data, done, error }: Message): Uint8Array;
     /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
         作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
-    constructor({ url, funcs, print, websocket, on_error }?: {
+    constructor({ url, funcs, print, websocket, keeper, on_error, }?: {
         url?: string;
         funcs?: Remote['funcs'];
         print?: boolean;
         websocket?: WebSocket;
-        on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
+        keeper?: RemoteKeeperOptions;
+        on_error?(error: WebSocketConnectionError, websocket?: WebSocket): void;
     });
-    on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
+    /** 统一处理首次连接错误和连接后的错误 */
+    _on_error: (error: WebSocketConnectionError, websocket?: WebSocket) => void;
+    _on_message: (data: ArrayBuffer, websocket: WebSocket) => void;
+    /** 使用者自定义的在连接后出错时的处理 */
+    on_error?(error: WebSocketConnectionError, websocket?: WebSocket): void;
     /** 幂等，保证 websocket 已连接，否则抛出异常
         一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
         连接断开后，通过传入 url 参数构造的 remote 实例会自动创建新的 websocket 连接，而通过传入 websocket 参数构造的实例只会检查连接状态，在断开时抛出异常
@@ -270,13 +298,6 @@ export declare class Remote {
         作为 websocket 连接发起方，不需要传入 websocket
         作为 websocket 连接接收方，必传 websocket 参数  */
     call<TReturn extends any[] = any[]>(func: string, args?: any[], websocket?: WebSocket): Promise<TReturn>;
-    /** 是幂等的，在未连接，或 (on_error) 检测到连接断开后以固定间隔尝试 remote.call(func) 重连
-        通常在 on_error 中和首次启动时调用
-        - func?: 连接后调用的函数，通常为某个 register 函数，将自身注册到 server
-        - duration?: `1000 * 30` 首次重连失败后的后续尝试间隔 (单位: ms)
-        - first_delay?: `0` 调用函数后是否立即连接，还是在 first_delay 后重连 (单位: ms)
-        - on_error?: 接收每次尝试连接的错误 */
-    start_reconnecting({ func, args, interval, first_delay, on_error, }?: RemoteReconnectingOptions): Promise<void>;
 }
 /** 为连接到 server 的 client 创建 RemoteClient，以便后续调用 client 中方法 */
 export declare class RemoteClient {
@@ -289,10 +310,3 @@ export declare class RemoteClient {
         发送或连接出错时自动清理 message.id 对应的 handler */
     send(message: Message): Promise<void>;
 }
-export interface RemoteReconnectingOptions {
-    func?: string;
-    args?: any[];
-    interval?: number;
-    first_delay?: number;
-    on_error?(error: Error): void;
-}

package/net.js

@@ -1,5 +1,6 @@
 import zlib from 'zlib';
 import { buffer as stream_to_buffer, text as stream_to_text } from 'stream/consumers';
+import { isReadable } from 'stream';
 import { t } from './i18n/instance.js';
 import './prototype.js';
 import { inspect, concat, assert, genid, delay, Lock, encode, decode, pipe_with_error, map_values, unique } from './utils.js';
@@ -11,7 +12,7 @@ export var MyProxy;
 (function (MyProxy) {
     MyProxy["socks5"] = "http://localhost:10080";
     MyProxy["whistle"] = "http://localhost:8899";
-    MyProxy["work"] = "http://127.0.0.1:10090";
+    MyProxy["work"] = "http://localhost:10090";
 })(MyProxy || (MyProxy = {}));
 // ------------------------------------ fetch, request
 export const cookies = {
@@ -62,7 +63,7 @@ export async function request(url, options = {}) {
     const { ProxyAgent: UndiciProxyAgent, FormData } = await import('undici');
     const { Cookie } = await import('tough-cookie');
     await cookies.init();
-    const { queries, headers: _headers, body, type = 'application/json', timeout = 5 * 1000, auth, cookies: _cookies, raw = false, full = false, redirect = 'follow', } = options;
+    const { queries, headers: _headers, body, type = 'application/json', timeout = 5 * 1000, auth, cookies: _cookies, raw = false, full = false, redirect = 'follow', decode = true, } = options;
     let { method, retries, encoding, proxy, } = options;
     url = new URL(url);
     if (queries)
@@ -133,6 +134,8 @@ export async function request(url, options = {}) {
         body: (() => {
             if (body === undefined)
                 return;
+            if (typeof body?.read === 'function' && isReadable(body))
+                return body;
             switch (type) {
                 case 'application/json': // 可能的类型 string | Record<string, any> | Uint8Array
                     if (typeof body === 'string')
@@ -169,7 +172,7 @@ export async function request(url, options = {}) {
         // UndiciResponse.body 没有自动根据 content-encoding 来解码，这里手动处理并替换 body 为解码后的 stream
         let body = _body;
         const content_encoding = headers['content-encoding']?.trim().toLowerCase();
-        if (content_encoding) {
+        if (decode && content_encoding) {
             assert(!content_encoding.includes(','));
             switch (content_encoding) {
                 case 'gzip':
@@ -485,9 +488,13 @@ export class Remote {
     /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
         一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers = new Map();
+    keeper;
     /** `false` 打印所有交互的 rpc messages */
     print = false;
+    first_error = true;
+    keeping = false;
     reconnecting = false;
+    disconnected = false;
     /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
     static parse(buffer) {
         const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -508,7 +515,7 @@ export class Remote {
         return message;
     }
     static pack({ id, func, data = [], done, error }) {
-        assert('length' in data, t('message.data 必须是数组'));
+        assert('length' in data, 'message.data 必须是数组');
         let data_ = new Array(data.length);
         let bins = [];
         let bufs = [];
@@ -538,22 +545,68 @@ export class Remote {
     }
     /** 作为 websocket 连接发起方，传入 url 或 websocket，定义远程 Remote
         作为 websocket 连接接收方，不传 url 和 websocket，定义本地 Remote */
-    constructor({ url, funcs, print, websocket, on_error } = {}) {
-        assert(!(url && websocket), t('构建 Remote 时 url 和 websocket 最多只能传一个'));
+    constructor({ url, funcs, print, websocket, keeper, on_error, } = {}) {
+        assert(!(url && websocket), '构建 Remote 时 url 和 websocket 最多只能传一个');
         this.initiator = Boolean(url || websocket);
         if (url)
             this.url = url;
-        if (funcs)
-            this.funcs = funcs;
+        assert(!funcs?.echo);
+        this.funcs = this.initiator ? funcs : {
+            ...funcs,
+            echo({ data }) {
+                return data;
+            }
+        };
         if (print !== undefined)
             this.print = print;
         if (on_error)
             this.on_error = on_error;
         if (this.initiator)
             this.lwebsocket = new Lock(websocket || null);
+        if (keeper) {
+            assert(this.initiator && url);
+            this.keeper = {
+                reconnect_interval: 1000 * 5,
+                heartbeat_interval: 1000 * 60,
+                error_delay: 1000 * 2,
+                ...keeper
+            };
+        }
     }
+    /** 统一处理首次连接错误和连接后的错误 */
+    _on_error = (error, websocket) => {
+        if (websocket) // 连接后出现的错误
+            this.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 this.connect();
+                        this.first_error = true;
+                    }
+                    catch {
+                        // 错误由 this.connect 里面处理
+                    }
+            })();
+    };
+    _on_message = (data, websocket) => {
+        this.handle(new Uint8Array(data), websocket);
+    };
+    /** 使用者自定义的在连接后出错时的处理 */
     on_error(error, websocket) {
-        throw error;
+        if (this.keeper)
+            console.log(error.message);
+        else
+            throw error;
     }
     /** 幂等，保证 websocket 已连接，否则抛出异常
         一般情况不需要手动调用，在其它方法中会自动调用这个方法，除非需要手动建立 websocket 连接并确保成功
@@ -565,28 +618,58 @@ export class Remote {
             if (this.lwebsocket.resource?.readyState === WebSocketOpen)
                 return;
             else if (!this.url)
-                throw new Error(t('创建 Remote 时传入的 websocket 连接已断开'));
-            else
+                throw new Error('创建 Remote 时传入的 websocket 连接已断开');
+            else {
+                let reconnected = false;
                 // 假设有多个请求想要并发连接 websocket, 且此时 websocket 是断开的状态
                 // 应该排队依次连接，而不是后续的连接直接使用第一次连接的 promise，后续调用还是应该尝试重连（不止连接一次）
-                return this.lwebsocket.request(async (websocket) => {
+                await this.lwebsocket.request(async (websocket) => {
                     // 保存的 rpc 状态在 this.handlers, 与 websocket 无关，因此即使断开重连也不影响 rpc 的运行，即
                     // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
-                    if (websocket?.readyState === WebSocketOpen)
-                        return;
-                    else // 重连
-                        this.lwebsocket.resource = await connect_websocket(this.url, {
-                            on_message: (data, websocket) => {
-                                this.handle(new Uint8Array(data), websocket);
-                            },
-                            on_error: this.on_error.bind(this)
-                        });
+                    if (websocket?.readyState !== WebSocketOpen) { // 重连
+                        try {
+                            this.lwebsocket.resource = await connect_websocket(this.url, {
+                                on_message: this._on_message,
+                                on_error: this._on_error
+                            });
+                            reconnected = true;
+                        }
+                        catch (error) {
+                            this._on_error(error);
+                            throw error;
+                        }
+                    }
                 });
+                if (this.keeper) {
+                    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 this.call('echo', []);
+                                    }
+                                    catch (error) {
+                                        this._on_error(error);
+                                    }
+                            }
+                        })();
+                    }
+                    if (reconnected && func)
+                        await this.call(func, args);
+                }
+            }
         else if (websocket.readyState !== WebSocketOpen)
-            throw new Error(t('传入的 websocket 连接已断开'));
+            throw new Error('传入的 websocket 连接已断开');
     }
     /** 作为 websocket 连接发起方手动关闭到对端的 websocket 连接 */
     disconnect() {
+        this.disconnected = true;
         this.lwebsocket.resource?.close(1000);
     }
     /** 发送 message 到对端 remote
@@ -594,7 +677,7 @@ export class Remote {
         作为 websocket 连接接收方，必传 websocket 参数
         发送或连接出错时自动清理 message.id 对应的 handler */
     async send(message, websocket) {
-        assert(!message.data || message.data.every(arg => arg !== undefined), t('message.data 数组中不能有 undefined 的项, 因为 json 序列化后会变为 null'));
+        assert(!message.data || message.data.every(arg => arg !== undefined), `message.data 数组中不能有 undefined 的项, 因为 json 序列化后会变为 null. (func: ${message.func}, id: ${message.id})`);
         if (this.print)
             console.log('remote.send:', message);
         try {
@@ -633,7 +716,7 @@ export class Remote {
                     await this.send({ id, data }, websocket);
             }
             else
-                throw message.error || new Error(`${t('找不到 rpc handler')}: ${func ? `func: ${func.quote()}` : `id: ${id}`}`);
+                throw message.error || new Error(`找不到 rpc handler: ${func ? `func: ${func.quote()}` : `id: ${id}`}`);
         }
         catch (error) {
             // handler 出错并不意味着 rpc 一定会结束，可能 error 是运行中的正常数据，所以不能清理 handler
@@ -666,39 +749,6 @@ export class Remote {
             }
         });
     }
-    /** 是幂等的，在未连接，或 (on_error) 检测到连接断开后以固定间隔尝试 remote.call(func) 重连
-        通常在 on_error 中和首次启动时调用
-        - func?: 连接后调用的函数，通常为某个 register 函数，将自身注册到 server
-        - duration?: `1000 * 30` 首次重连失败后的后续尝试间隔 (单位: ms)
-        - first_delay?: `0` 调用函数后是否立即连接，还是在 first_delay 后重连 (单位: ms)
-        - on_error?: 接收每次尝试连接的错误 */
-    async start_reconnecting({ func, args, interval = 1000 * 10, first_delay = 0, on_error, } = {}) {
-        assert(this.url);
-        if (this.reconnecting)
-            return;
-        this.reconnecting = true;
-        if (first_delay)
-            await delay(first_delay);
-        for (;;) {
-            if (this.lwebsocket.resource?.readyState !== WebSocketOpen)
-                try {
-                    if (func)
-                        await this.call(func, args);
-                    else
-                        await this.connect();
-                    this.reconnecting = false;
-                    break;
-                }
-                catch (error) {
-                    on_error?.(error);
-                }
-            else {
-                this.reconnecting = false;
-                break;
-            }
-            await delay(interval);
-        }
-    }
 }
 /** 为连接到 server 的 client 创建 RemoteClient，以便后续调用 client 中方法 */
 export class RemoteClient {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xshell",
-    "version": "1.0.112",
+    "version": "1.0.114",
     "type": "module",
     "main": "./index.js",
     "bin": {
@@ -99,7 +99,7 @@
         "tslib": "^2.6.2",
         "typescript": "^5.4.5",
         "ua-parser-js": "^2.0.0-beta.2",
-        "undici": "^6.18.1",
+        "undici": "^6.18.2",
         "vinyl": "^3.0.0",
         "vinyl-fs": "^4.0.0",
         "ws": "^8.17.0"
@@ -118,7 +118,7 @@
         "@types/koa-compress": "^4.0.6",
         "@types/lodash": "^4.17.4",
         "@types/mime-types": "^2.1.4",
-        "@types/node": "^20.12.12",
+        "@types/node": "^20.12.13",
         "@types/react": "^18.3.3",
         "@types/through2": "^2.0.41",
         "@types/tough-cookie": "^4.0.5",

package/path.d.ts

@@ -54,7 +54,7 @@ export declare function extname(path: string): string;
 /** `/` */
 export declare const sep = "/";
 /** The platform-specific file delimiter. ';' or ':'. */
-export declare const delimiter: ":" | ";";
+export declare const delimiter: ";" | ":";
 /** Returns an object from a path string - the opposite of format().
     @param path path to evaluate.
     @throws {TypeError} if `path` is not a string. */
@@ -81,7 +81,7 @@ export declare let path: {
     basename: typeof basename;
     extname: typeof extname;
     sep: string;
-    delimiter: ":" | ";";
+    delimiter: ";" | ":";
     parse: typeof parse;
     format: typeof format;
     toNamespacedPath: typeof toNamespacedPath;

package/utils.browser.d.ts

@@ -63,7 +63,7 @@ export declare function encode(str: string): Uint8Array;
     在流式处理 (buffer 可能不完整) 时，应使用独立的 TextDecoder 实例调用 decode(buffer, { stream: true }) */
 export declare function decode(buffer: Uint8Array): string;
 /** 字符串字典序比较 */
-export declare function strcmp(l: string, r: string): 0 | 1 | -1;
+export declare function strcmp(l: string, r: string): 1 | 0 | -1;
 /** 比较 1.10.02 这种版本号 */
 export declare function vercmp(l: string, r: string): number;
 export declare function get<TReturn = any>(obj: any, keypath: string): TReturn;

package/utils.d.ts

@@ -39,7 +39,7 @@ export declare function filter_values<TObj extends Record<string, any>>(obj: TOb
 /** 忽略对象中的 keys, 返回新对象 */
 export declare function omit<TObj>(obj: TObj, omit_keys: string[]): TObj;
 /** 字符串字典序比较 */
-export declare function strcmp(l: string, r: string): 0 | 1 | -1;
+export declare function strcmp(l: string, r: string): 1 | 0 | -1;
 /** 比较 1.10.02 这种版本号 */
 export declare function vercmp(l: string, r: string): number;
 export declare function get<TReturn = any>(obj: any, keypath: string): TReturn;