xshell 1.3.8 → 1.3.9

package/net.common.d.ts

@@ -1,5 +1,11 @@
+import type { Socket } from 'node:net';
 import { type Message } from './io.common.ts';
 import { Lock, TimeoutError } from './utils.common.ts';
+declare global {
+    interface WebSocket {
+        _socket?: Socket;
+    }
+}
 /** 对于 request() 函数来说无意义的 headers，会自动过滤掉 */
 export declare const drop_request_headers: Set<string>;
 export interface BasicAuth {
@@ -42,6 +48,7 @@ export interface ConnectWebsocketOptions {
     protocols?: string[];
     max_payload?: number;
     proxy?: string;
+    keep_alive_duration?: number;
     on_message(data: ArrayBuffer | string, websocket: WebSocket): any;
     on_error?(error: WebSocketConnectionError, websocket: WebSocket): any;
     on_close?(event: CloseEvent, websocket: WebSocket): any;
@@ -61,6 +68,7 @@ export interface ConnectWebsocketOptions {
         - protocols?
         - max_payload?: `8 gb` (仅 nodejs 环境有效)
         - proxy?: string (仅 nodejs 环境有效)
+        - keep_alive_duration?: 毫秒数，设置后启用操作系统级的 keep alive (仅 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，
@@ -69,7 +77,7 @@ export interface ConnectWebsocketOptions {
             https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes
         - connect?: nodejs 环境下需要指定 ip, port 手动连接 tls server 时使用，有 agent 时不生效 */
 export declare function connect_websocket(url: string | URL, { print, protocols, max_payload, // 8 GB
-proxy, on_message, on_error, on_close, connect }: ConnectWebsocketOptions): Promise<WebSocket>;
+proxy, keep_alive_duration, on_message, on_error, on_close, connect }: ConnectWebsocketOptions): Promise<WebSocket>;
 /** 接收到消息后的处理函数
     返回值会自动被 await，然后可能被封装为 message 回传 */
 export type MessageHandler<TData = any> = (message: Message<TData>, remote: Remote) => void | any | Promise<void | any>;
@@ -82,8 +90,12 @@ export interface RemoteOptions {
     websocket?: WebSocket;
     /** 能被对端调用的函数 */
     funcs?: Remote['funcs'];
-    /** `false` 是否启用主动探测连接，在连接状态下以 30s 间隔发送心跳包确保连接状态 */
-    probe?: boolean;
+    /** 设置后启用操作系统级的 keep alive (仅 nodejs 环境可设置)
+        - 浏览器端有默认 tcp keep alive 心跳机制，禁止设置这个参数
+        - nodejs 端
+            - 作为连接发起方: 在 websocket 连接建立时启用
+            - 作为连接接收方: 在根据传入 websocket 创建 Remote 时启用 */
+    alive?: boolean;
     /** websocket 连接建立成功时调用对端 register 函数的参数 (仅发起方有效) */
     args?: any[];
     /** `true` 是否打印连接信息、错误信息 */
@@ -95,7 +107,8 @@ export interface RemoteOptions {
     on_error?(error: WebSocketConnectionError | Error, remote: Remote): void;
     /** 使用者自定义的，在重连之前调用的函数，比如可以修改 url，仅连接发起方有效 */
     on_reconnect?(this: Remote): Promise<void>;
-    /** 使用者自定义的，在连接建立，包括首次连接和重连 之后调用的函数，比如可以重新调用一些函数，仅连接发起方有效 */
+    /** 使用者自定义的，在连接建立，包括首次连接和重连 之后调用的函数，
+        比如可以重新调用一些函数，仅连接发起方有效 */
     on_connected?(this: Remote): void;
 }
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
@@ -120,8 +133,8 @@ export declare class Remote {
     url?: string;
     /** 能被对端调用的函数 */
     funcs: Record<string, MessageHandler>;
-    /** `false` 是否启用主动探测连接，在连接状态下以 30s 间隔发送心跳包确保连接状态 */
-    probe: boolean;
+    /** tcp keep alive */
+    alive: boolean;
     /** websocket 连接建立成功时调用对端 register 函数的参数 (仅发起方有效) */
     args?: any[];
     /** `true` 是否打印连接信息、错误信息 */
@@ -133,8 +146,6 @@ export declare class Remote {
     /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
         一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers: Map<number, MessageHandler<any>>;
-    /** 是否正在定时主动检测重连 */
-    probing: boolean;
     /** websocket 检测到错误，_on_error 被调用，此时会尝试一段时间后重连 */
     reconnecting: NodeJS.Timeout;
     /** 用户是否手动调用了 disconnect() 主动断开了连接 (仅发起方有效) */
@@ -143,7 +154,7 @@ export declare class Remote {
     error: WebSocketConnectionError | Error;
     /** 作为 websocket 连接发起方，传入 url
         作为 websocket 连接接收方，传入 websocket + name */
-    constructor({ name, url, websocket, funcs, print, verbose, probe, args, on_error, on_reconnect, on_connected }?: RemoteOptions);
+    constructor({ name, url, websocket, funcs, print, verbose, alive, args, on_error, on_reconnect, on_connected }?: RemoteOptions);
     /** 统一处理首次连接和连接后的 websocket 错误 */
     _on_error: (error: WebSocketConnectionError | Error) => void;
     on_reconnect?: (this: Remote) => Promise<void>;
@@ -168,13 +179,13 @@ export declare class Remote {
     /** 尝试建立连接，通常用于开始保活
         重连错误会在 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>;
+    /** node.js 下连接接收方在 Remote 创建后手动启用 tcp keep alive */
+    keep_alive(): void;
     /** 手动关闭到对端的 websocket 连接 */
     disconnect(): void;
     /** 发送 message 到对端 remote

package/net.common.js

@@ -1,7 +1,7 @@
 import { platform } from "./platform.common.js";
 import { rethrow } from "./prototype.common.js"; // .bracket()
 import { message_symbol, pack, parse } from "./io.common.js";
-import { check, defer, defer2, delay, genid, Lock, nowstr, set_error_message, timeout, TimeoutError } from "./utils.common.js";
+import { check, defer, defer2, genid, Lock, nowstr, set_error_message, timeout, TimeoutError } from "./utils.common.js";
 import { t } from "./i18n/instance.js";
 /** 对于 request() 函数来说无意义的 headers，会自动过滤掉 */
 export const drop_request_headers = new Set([
@@ -94,6 +94,7 @@ let websocket_proxy_agents = {};
         - protocols?
         - max_payload?: `8 gb` (仅 nodejs 环境有效)
         - proxy?: string (仅 nodejs 环境有效)
+        - keep_alive_duration?: 毫秒数，设置后启用操作系统级的 keep alive (仅 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，
@@ -106,7 +107,7 @@ export async function connect_websocket(url, { print = {
     error: true,
     close: true
 }, protocols, max_payload = 2 ** 33, // 8 GB
-proxy, on_message, on_error, on_close, connect }) {
+proxy, keep_alive_duration, on_message, on_error, on_close, connect }) {
     const { nodejs } = platform;
     if (typeof print === 'boolean')
         print = {
@@ -114,6 +115,8 @@ proxy, on_message, on_error, on_close, connect }) {
             error: print,
             close: print
         };
+    if (keep_alive_duration)
+        check(nodejs, 'keep_alive_duration 仅 nodejs 环境有效');
     let websocket = new (await platform.get_websocket())(url, protocols, 
     // @ts-ignore
     nodejs ?
@@ -136,6 +139,8 @@ proxy, on_message, on_error, on_close, connect }) {
             console.log(websocket.url +
                 (websocket.protocol ? ' ' + websocket.protocol.bracket() : '') +
                 t(' 已连接'));
+        if (keep_alive_duration)
+            websocket._socket.setKeepAlive(true, keep_alive_duration);
         pwebsocket.resolve(websocket);
     }, { once: true });
     // websocket error, close 事件只选一个最详细的构造 WebSocketConnectionError 并调用 on_error
@@ -200,8 +205,8 @@ export class Remote {
     url;
     /** 能被对端调用的函数 */
     funcs;
-    /** `false` 是否启用主动探测连接，在连接状态下以 30s 间隔发送心跳包确保连接状态 */
-    probe = false;
+    /** tcp keep alive */
+    alive = false;
     /** websocket 连接建立成功时调用对端 register 函数的参数 (仅发起方有效) */
     args;
     /** `true` 是否打印连接信息、错误信息 */
@@ -214,8 +219,6 @@ export class Remote {
     /** map<id, message handler>: 通过 (rpc message).id 找到对应的 handler
         一元 rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers = new Map();
-    /** 是否正在定时主动检测重连 */
-    probing = false;
     /** websocket 检测到错误，_on_error 被调用，此时会尝试一段时间后重连 */
     reconnecting;
     /** 用户是否手动调用了 disconnect() 主动断开了连接 (仅发起方有效) */
@@ -224,9 +227,13 @@ export class Remote {
     error;
     /** 作为 websocket 连接发起方，传入 url
         作为 websocket 连接接收方，传入 websocket + name */
-    constructor({ name, url, websocket, funcs, print, verbose, probe, args, on_error, on_reconnect, on_connected } = {}) {
+    constructor({ name, url, websocket, funcs, print, verbose, alive, args, on_error, on_reconnect, on_connected } = {}) {
         if (name)
             this.name = name;
+        if (alive) {
+            check(!platform.browser, '浏览器端有默认 tcp keep alive 心跳机制，禁止设置 alive 选项');
+            this.alive = true;
+        }
         if (url) {
             check(!websocket, '构建 Remote 时 url 和 websocket 只能传其中一个');
             this.url = url;
@@ -237,8 +244,10 @@ export class Remote {
         }
         else { // 连接接收方，一定是 nodejs 环境
             check(websocket, '构建 Remote 时需传入 url 或者 websocket');
-            this.lwebsocket.resource = websocket;
             websocket.binaryType = 'arraybuffer';
+            if (this.alive)
+                websocket._socket.setKeepAlive(true, 30_000);
+            this.lwebsocket.resource = websocket;
             // 参考 connect_websocket 实现
             let errored;
             const on_close_or_error = (event) => {
@@ -265,8 +274,6 @@ export class Remote {
             check(!funcs.echo);
             this.funcs = funcs;
         }
-        if (probe !== undefined)
-            this.probe = probe;
         if (args)
             this.args = args;
         if (print !== undefined)
@@ -287,7 +294,7 @@ export class Remote {
         if (error instanceof WebSocketConnectionError &&
             !this.reconnecting &&
             this.url &&
-            (this.funcs || this.probe)) {
+            this.funcs) {
             this.reconnecting = setTimeout(this.reconnect, this.error ? 20_000 : 2_000);
             this.error = error;
         }
@@ -335,9 +342,6 @@ export class Remote {
     async connect() {
         if (this.disconnected)
             throw new Error(`remote (${this.name || this.url}) 已调用过 disconnect 断开连接，无法再次 connect`);
-        // 首次 connect 开始探测
-        if (this.probe && !this.probing)
-            this.probe_connection();
         if (this.check_connection())
             return;
         try {
@@ -363,7 +367,8 @@ export class Remote {
         this.lwebsocket.resource = await connect_websocket(this.url, {
             on_message: this._on_message,
             on_error: this._on_error,
-            print: this.print
+            print: this.print,
+            keep_alive_duration: this.alive ? 30_000 : undefined
         });
         this.error = null;
         if (this.args)
@@ -378,21 +383,6 @@ export class Remote {
         }
         catch { }
     }
-    /** 开始心跳保活 */
-    async probe_connection(print_timeout = true) {
-        // 手动调用该函数时也会启用 probe
-        this.probe = true;
-        this.probing = true;
-        for (let timeouted = false;;) {
-            await delay(timeouted ? 5_000 : 30_000);
-            if (this.disconnected || !this.url && !this.check_connection() || !this.probe)
-                break;
-            if (this.reconnecting)
-                continue;
-            // 产生的非 TimeoutError 应该都通过 _on_error 输出了，同时可能触发了重连
-            timeouted = (await this.test(print_timeout)) instanceof TimeoutError;
-        }
-    }
     /** 检测连接，返回连接错误，出错时触发 on_error 打印错误信息
         返回值:
         - 连接正常返回: undefined
@@ -416,6 +406,12 @@ export class Remote {
             return error;
         }
     }
+    /** node.js 下连接接收方在 Remote 创建后手动启用 tcp keep alive */
+    keep_alive() {
+        check(!this.url && platform.nodejs);
+        this.alive = true;
+        this.lwebsocket.resource?._socket.setKeepAlive(true, 30_000);
+    }
     /** 手动关闭到对端的 websocket 连接 */
     disconnect() {
         this.disconnected = true;

package/net.d.ts

@@ -114,6 +114,7 @@ export interface ConnectOptions {
     local_port?: number;
     timeout?: number;
     on_timeout?: OnTimeout;
+    keep_alive_duration?: number;
     print?: {
         error: boolean;
         connect: boolean;
@@ -127,8 +128,9 @@ export interface ConnectOptions {
     - options?:
         - local_port?: `随机端口` 使用的本地端口
         - timeout?: `2000` 超时时间
+        - keep_alive_duration?: 毫秒数，设置后启用操作系统级的 keep alive
         - print?: 打印连接日志，错误日志
             - error?: `true`
             - connect: `false` */
-export declare function connect(hostname: string, port: number, { local_port, timeout: _timeout, on_timeout, print }?: ConnectOptions): Deferred2<net.Socket>;
+export declare function connect(hostname: string, port: number, { local_port, timeout: _timeout, on_timeout, keep_alive_duration, print }?: ConnectOptions): Deferred2<net.Socket>;
 export declare function get_socket_ip(socket: net.Socket): string;

package/net.js

@@ -301,10 +301,11 @@ export async function request_json(url, options) {
     - options?:
         - local_port?: `随机端口` 使用的本地端口
         - timeout?: `2000` 超时时间
+        - keep_alive_duration?: 毫秒数，设置后启用操作系统级的 keep alive
         - print?: 打印连接日志，错误日志
             - error?: `true`
             - connect: `false` */
-export function connect(hostname, port, { local_port, timeout: _timeout = 2000, on_timeout, print = { error: true, connect: false } } = {}) {
+export function connect(hostname, port, { local_port, timeout: _timeout = 2000, on_timeout, keep_alive_duration, print = { error: true, connect: false } } = {}) {
     let pconnected = defer2();
     let timeouted = false;
     function get_message(message) {
@@ -314,7 +315,9 @@ export function connect(hostname, port, { local_port, timeout: _timeout = 2000,
         host: hostname,
         port,
         localPort: local_port,
-        noDelay: true
+        noDelay: true,
+        keepAlive: Boolean(keep_alive_duration),
+        keepAliveInitialDelay: keep_alive_duration
     }, () => {
         if (pconnected.settled) {
             if (print)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xshell",
-    "version": "1.3.8",
+    "version": "1.3.9",
     "type": "module",
     "main": "./index.js",
     "bin": {
@@ -76,9 +76,9 @@
         "mime-types": "^3.0.1",
         "p-map": "^7.0.4",
         "react": "^19.2.0",
-        "react-i18next": "^16.3.4",
+        "react-i18next": "^16.3.5",
         "resolve-path": "^1.4.0",
-        "sass": "^1.94.1",
+        "sass": "^1.94.2",
         "sass-loader": "^16.0.6",
         "source-map-loader": "^5.0.0",
         "strip-ansi": "^7.1.2",

package/utils.d.ts

@@ -1,4 +1,4 @@
-import { Writable, Transform, type Readable, type Duplex, type TransformCallback } from 'node:stream';
+import { Writable, Transform, type Readable, type TransformCallback } from 'node:stream';
 import util from 'node:util';
 import './prototype.ts';
 import './platform.ts';
@@ -31,19 +31,8 @@ export declare namespace inspect {
     const custom: typeof util.inspect.custom;
     const defaultOptions: util.InspectOptions;
 }
-/** npm map-stream
-    filter will reemit the data if cb(err,pass) pass is truthy
-    
-    reduce is more tricky
-    maybe we want to group the reductions or emit progress updates occasionally
-    the most basic reduce just emits one 'data' event after it has recieved 'end'
-    
-    create an event stream and apply function to each .write,
-    emitting each response as data unless it's an empty callback
- */
-export declare function map_stream<Out, In = any>(mapper: (obj: In, cb: Function) => any, options?: {
-    failures?: boolean;
-}): Duplex;
+/** 消费一个可读流 */
+export declare function consume_stream(stream: Readable, ignore_error?: boolean): Promise<void>;
 export declare function stream_to_lines(stream: Readable): AsyncGenerator<string, void, unknown>;
 export declare class WritableMemoryStream extends Writable {
     chunks: Uint8Array[];
@@ -65,8 +54,6 @@ export declare class DecoderStream extends Transform {
     _transform(chunk: Uint8Array, encoding: BufferEncoding, callback: TransformCallback): void;
     _flush(callback: TransformCallback): void;
 }
-/** 消费一个可读流 */
-export declare function consume_stream(stream: Readable, ignore_error?: boolean): Promise<void>;
 /** 根据 range 生成整数序列 (iterable)
     - range: 取值为逗号分割的多个可用值或值区间 (不能含有空格)，比如：`8321,8322,8300-8310,11000-11999`
     - reverse?: `false` 在 range 内从后往前生成 */

package/utils.js

@@ -1,4 +1,4 @@
-import { Stream, Writable, Transform } from 'node:stream';
+import { Writable, Transform } from 'node:stream';
 import util from 'node:util';
 import ncrypto from 'node:crypto';
 import "./prototype.js";
@@ -94,120 +94,16 @@ export function colored(str, color, enabled = inspect.defaultOptions.colors) {
     inspect.defaultOptions = util.inspect.defaultOptions;
 })(inspect || (inspect = {}));
 // ------------------------------------ stream
-/** npm map-stream
-    filter will reemit the data if cb(err,pass) pass is truthy
-    
-    reduce is more tricky
-    maybe we want to group the reductions or emit progress updates occasionally
-    the most basic reduce just emits one 'data' event after it has recieved 'end'
-    
-    create an event stream and apply function to each .write,
-    emitting each response as data unless it's an empty callback
- */
-export function map_stream(mapper, options) {
-    options = options || {};
-    let inputs = 0, outputs = 0, ended = false, paused = false, destroyed = false, last_written = 0, in_next = false;
-    let stream = Object.assign(new Stream(), {
-        readable: true,
-        writable: true,
-        write(data) {
-            if (ended)
-                throw new Error('map stream is not writable');
-            in_next = false;
-            inputs++;
-            try {
-                // catch sync errors and handle them like async errors
-                const written = wrapped_mapper(data, inputs, next);
-                paused = (written === false);
-                return !paused;
-            }
-            catch (err) {
-                // if the callback has been called syncronously, and the error has occured in an listener, throw it again.
-                if (in_next)
-                    throw err;
-                next(err);
-                return !paused;
-            }
-        },
-        end(data) {
-            if (ended)
-                return;
-            _end(data);
-        },
-        destroy() {
-            ended = destroyed = true;
-            stream.writable = stream.readable = paused = false;
-            process.nextTick(function () {
-                stream.emit('close');
-            });
-        },
-        pause() {
-            paused = true;
-        },
-        resume() {
-            paused = false;
-        }
-    });
-    let error_event_name = options.failures ? 'failure' : 'error';
-    // Items that are not ready to be written yet (because they would come out of order) get stuck in a queue for later.
-    let write_queue = {};
-    function queue_data(data, number) {
-        let next_to_write = last_written + 1;
-        if (number === next_to_write) {
-            // If it's next, and its not undefined write it
-            if (data !== undefined)
-                stream.emit('data', data);
-            last_written++;
-            next_to_write++;
-        }
-        else
-            // Otherwise queue it for later.
-            write_queue[number] = data;
-        // If the next value is in the queue, write it
-        if (Object.prototype.hasOwnProperty.call(write_queue, next_to_write)) {
-            let data_to_write = write_queue[next_to_write];
-            delete write_queue[next_to_write];
-            return queue_data(data_to_write, next_to_write);
-        }
-        outputs++;
-        if (inputs === outputs) {
-            if (paused) {
-                paused = false;
-                stream.emit('drain'); // written all the incoming events
-            }
-            if (ended)
-                _end();
-        }
-    }
-    function next(err, data, number) {
-        if (destroyed)
-            return;
-        in_next = true;
-        if (!err || options.failures)
-            queue_data(data, number);
-        if (err)
-            stream.emit(error_event_name, err);
-        in_next = false;
-    }
-    /** Wrap the mapper function by calling its callback with the order number of the item in the stream. */
-    function wrapped_mapper(input, number, callback) {
-        return mapper.call(null, input, function (err, data) {
-            callback(err, data, number);
-        });
+/** 消费一个可读流 */
+export async function consume_stream(stream, ignore_error = false) {
+    try {
+        for await (const chunk of stream)
+            ;
     }
-    function _end(data) {
-        // if end was called with args, write it, 
-        ended = true; // write will emit 'end' if ended is true
-        stream.writable = false;
-        if (data !== undefined)
-            return queue_data(data, inputs);
-        else if (inputs === outputs) { // wait for processing 
-            stream.readable = false;
-            stream.emit('end');
-            stream.destroy();
-        }
+    catch (error) {
+        if (!ignore_error)
+            throw error;
     }
-    return stream;
 }
 export async function* stream_to_lines(stream) {
     let buf = '';
@@ -269,17 +165,6 @@ export class DecoderStream extends Transform {
         callback();
     }
 }
-/** 消费一个可读流 */
-export async function consume_stream(stream, ignore_error = false) {
-    try {
-        for await (const chunk of stream)
-            ;
-    }
-    catch (error) {
-        if (!ignore_error)
-            throw error;
-    }
-}
 /** 根据 range 生成整数序列 (iterable)
     - range: 取值为逗号分割的多个可用值或值区间 (不能含有空格)，比如：`8321,8322,8300-8310,11000-11999`
     - reverse?: `false` 在 range 内从后往前生成 */