xshell 0.0.58 → 0.0.60

package/net.d.ts

@@ -101,70 +101,75 @@ on_open, on_close, on_error, on_message }: {
         data: ArrayBuffer | string;
     }, websocket: WebSocket): any;
 }): Promise<WebSocket>;
+/** 接收到消息后的处理函数
+    返回值可以是:
+    - 数组: 会自动被封装为 { id: 相同, data: 返回值, done: true } 这样的消息并调用 websocket.send 将其发送
+    - void: 什么都不做
+    - 以上的 promise */
+export declare type MessageHandler = (message: Message, websocket?: WebSocket) => void | any[] | Promise<void | any[]>;
 /** 二进制消息格式
     - json.length (小端序): 4 字节
     - json 数据
     - binary 数据
 */
-export interface Message<T extends any[] = any[]> {
-    /** 本次 rpc 的 id */
+export interface Message<TData extends any[] = any[]> {
+    /** rpc id: 在 rpc 系统中认为是唯一的。用来在单个 websocket 连接上复用多个 rpc 请求。多个相同 id 的 message 组成一个请求流 */
     id?: number;
-    /** rpc 发起方指定被调用的 function name, 多个相同 id, func 的 message 组成一个请求流 */
+    /** 只在 rpc 发起时指定被调用的 function name，发起时 rpc 时必传 */
     func?: string;
-    /** 等待执行，但不要序列化返回 func 的执行结果 (message 中无 args) */
-    ignore?: boolean;
-    /** 不等待 func 执行，remote 收到后直接确认返回 (message 中 done = true) */
-    async?: boolean;
-    /** 这个数组里面要么是对应的 JS 参数，要么是 Uint8Array 参数对应的 binary length
-        args 可以是:
+    /** 通过这个 flag 主动表明这是发往对方的最后一个 message, 对方可以销毁 handler 了
+        并非强制，可以不说明，由双方的函数自己约定
+    */
+    done?: boolean;
+    /** 通知对方这里产生的错误，本质上类似 data 也是一种数据，并不代表 rpc 的结束，后续可能继续有 rpc message 交换 */
+    error?: Error;
+    /** data 是一个数组, 作为:
         - rpc 发起方调用 func 的参数，或者请求流 message 携带的数据
-        - 作为结果或者响应流的 message 数据，传给请求发起方
+        - 结果或者响应流的数据，传给请求发起方
+        
+        里面是可序列化为 json 的 js 变量，或者是 Uint8Array
+        Uint8Array 的参数处理后被替换为 Uint8Array.byteLength, 并将下标记录在 bins 中
+        
+        注意: 数组中如果有 undefined 值，传输到对面会变成 null 值
     */
-    args?: T;
-    /** bins: 哪几个 arg 是 Uint8Array 类型的，如: [0, 3] */
+    data?: TData;
+    /** bins: data 中哪些下标对应的原始值是 Uint8Array 类型的，如: [0, 3] */
     bins?: number[];
-    /** 被调方执行 func 产生的错误 */
-    error?: Error;
-    /** 如果请求或者响应是一个流，通过这个 flag 表明是最后一个 message, 并且可以销毁 handler 了 */
-    done?: boolean;
 }
-/** 通过创建 Remote 对象对 WebSocket RPC 进行抽象
+/** 通过创建 remote 对象对 websocket rpc 进行抽象
     调用方使用 remote.call 进行调用
-    被调方在创建 Remote 对象时传入 funcs 注册处理函数，并使用 Remote.handle 方法处理 WebSocket message
-*/
+    被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
+    未连接时自动连接，断开后自动重连 */
 export declare class Remote {
     url: string;
-    websocket: WebSocket;
-    id: number;
-    /** 被调方的 message 处理器 */
-    funcs: Record<string, (message: Message, websocket?: WebSocket) => void | Promise<void>>;
-    /** 调用方发起的 rpc 对应响应的 message 处理器 */
-    handlers: ((message: Message) => any)[];
+    /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
+    websocket?: WebSocket;
+    /** 通过 rpc message.func 被调用的 rpc 函数 */
+    funcs: Record<string, MessageHandler>;
+    /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
+    handlers: Map<number, MessageHandler>;
     print: boolean;
-    /** 在未连接时或连接断开后，调用 call 是否自动连接到 remote */
-    autoconnect: boolean;
     pconnect: Promise<any>;
     get connected(): boolean;
-    static parse<T extends any[] = any[]>(array_buffer: ArrayBuffer): Message<T>;
-    static pack({ id, func, ignore, async: _async, done, error, args: _args, }: Message): Uint8Array;
-    constructor({ url, funcs, websocket, autoconnect }?: {
+    static parse<TData extends any[] = any[]>(array_buffer: ArrayBuffer): Message<TData>;
+    static pack({ id, func, data, done, error }: Message): Uint8Array;
+    constructor({ url, funcs, websocket }?: {
         url?: string;
         funcs?: Remote['funcs'];
         websocket?: WebSocket;
-        autoconnect?: boolean;
     });
+    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连 */
     connect(): Promise<void>;
     disconnect(): void;
-    send(message: Message, websocket?: WebSocket): void;
-    /** 调用 remote 中的 func, 中间消息及返回结果可由 handler 处理，处理 done message 之后的返回值作为 call 函数的返回值
-        如果为 unary rpc, 可以不传 handler, await call 之后可以得到响应 message 的 args
-    */
-    call<T extends any[] = any[]>(message: Message, handler?: (message: Message<T>) => any): Promise<T>;
-    /** 处理接收到的 WebSocket message
-        1. 被调用方接收 message 并开始处理
-        2. 调用方处理 message 响应
-    */
+    /** 接收 websocket 连接的 remote 端必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket
+        发送或连接出错时自动清理 message.id 对应的 handler */
+    send(message: Message, websocket?: WebSocket): Promise<void>;
+    /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
+        如果 message.done == true 则清理 handler
+        如果 handler 返回了值，则包装为 message 发送 */
     handle(event: {
         data: ArrayBuffer;
     }, websocket: WebSocket): Promise<void>;
+    /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
+    call<TReturn extends any[] = any[]>(func: string, args?: any[]): Promise<TReturn>;
 }

package/net.js

@@ -6,7 +6,7 @@ import iconv from 'iconv-lite';
 import qs from 'qs';
 import { Cookie, MemoryCookieStore } from 'tough-cookie';
 import './prototype.js';
-import { inspect, output_width, concat } from './utils.js';
+import { inspect, output_width, concat, assert, genid } from './utils.js';
 export var MyProxy;
 (function (MyProxy) {
     MyProxy["socks5"] = "http://localhost:10080";
@@ -263,16 +263,22 @@ on_open, on_close, on_error, on_message }) {
     websocket.binaryType = 'arraybuffer';
     return new Promise((resolve, reject) => {
         websocket.addEventListener('open', async (event) => {
-            console.log(`${websocket.url} opened`);
+            console.log(new Date().toLocaleTimeString() + ': ' +
+                'websocket connected: ' +
+                (protocols ?
+                    typeof protocols === 'string' ? `protocol: ${protocols}, url: ` : `protocol: [${protocols.join(', ')}], url: `
+                    :
+                        '') +
+                websocket.url);
             await on_open?.(event, websocket);
             resolve(websocket);
         });
         websocket.addEventListener('close', event => {
-            console.log(`${websocket.url} closed with code = ${event.code}, reason = '${event.reason}'`);
+            console.log(`${new Date().toLocaleTimeString()}: websocket closed: url: ${websocket.url}, code: ${event.code}, reason: ${event.reason}`);
             on_close?.(event, websocket);
         });
         websocket.addEventListener('error', event => {
-            const message = `${websocket.url} errored`;
+            const message = `${new Date().toLocaleTimeString()} websocket errored: ${websocket.url}`;
             on_error?.(event, websocket);
             reject(Object.assign(new Error(message), { event }));
         });
@@ -281,21 +287,19 @@ on_open, on_close, on_error, on_message }) {
         });
     });
 }
-/** 通过创建 Remote 对象对 WebSocket RPC 进行抽象
+/** 通过创建 remote 对象对 websocket rpc 进行抽象
     调用方使用 remote.call 进行调用
-    被调方在创建 Remote 对象时传入 funcs 注册处理函数，并使用 Remote.handle 方法处理 WebSocket message
-*/
+    被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
+    未连接时自动连接，断开后自动重连 */
 export class Remote {
     url;
+    /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
     websocket;
-    id = 0;
-    /** 被调方的 message 处理器 */
-    funcs = {};
-    /** 调用方发起的 rpc 对应响应的 message 处理器 */
-    handlers = [];
+    /** 通过 rpc message.func 被调用的 rpc 函数 */
+    funcs;
+    /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
+    handlers = new Map();
     print = false;
-    /** 在未连接时或连接断开后，调用 call 是否自动连接到 remote */
-    autoconnect = true;
     pconnect;
     get connected() {
         return this.websocket?.readyState === WebSocket.OPEN;
@@ -308,154 +312,151 @@ export class Remote {
         let message = JSON.parse(decoder.decode(buf.subarray(4, offset)));
         if (message.bins) {
             const { bins } = message;
-            let { args } = message;
+            let { data } = message;
             for (const ibin of bins) {
-                const len_buf = args[ibin];
-                args[ibin] = buf.subarray(offset, offset + len_buf);
+                const len_buf = data[ibin];
+                data[ibin] = buf.subarray(offset, offset + len_buf);
                 offset += len_buf;
             }
         }
+        if (message.error)
+            message.error = Object.assign(new Error(), message.error);
         return message;
     }
-    static pack({ id, func, ignore, async: _async, done, error, args: _args = [], }) {
-        let args = [..._args];
+    static pack({ id, func, data = [], done, error }) {
+        let data_ = new Array(data.length);
         let bins = [];
         let bufs = [];
-        for (let i = 0; i < args.length; i++) {
-            const arg = args[i];
-            if (arg instanceof Uint8Array) {
+        for (let i = 0; i < data.length; i++) {
+            const item = data[i];
+            if (item instanceof Uint8Array) {
                 bins.push(i);
-                bufs.push(arg);
-                args[i] = arg.length;
+                bufs.push(item);
+                data_[i] = item.length;
             }
+            else
+                data_[i] = item;
         }
         const data_json = {
             id,
             ...func ? { func } : {},
-            ...ignore ? { ignore } : {},
-            ..._async ? { async: _async } : {},
             ...done ? { done } : {},
             ...error ? { error } : {},
-            ...args.length ? { args } : {},
+            ...data_.length ? { data: data_ } : {},
             ...bins.length ? { bins } : {},
         };
         const str_json = encoder.encode(JSON.stringify(data_json));
         let dv = new DataView(new ArrayBuffer(4));
         dv.setUint32(0, str_json.length, true);
-        return concat([
-            dv,
-            str_json,
-            ...bufs
-        ]);
+        return concat([dv, str_json, ...bufs]);
     }
-    constructor({ url, funcs, websocket, autoconnect } = {}) {
+    constructor({ url, funcs = {}, websocket } = {}) {
         this.url = url;
-        if (funcs)
-            this.funcs = funcs;
+        this.funcs = funcs;
         this.websocket = websocket;
-        if (typeof autoconnect !== 'undefined')
-            this.autoconnect = autoconnect;
     }
+    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连 */
     async connect() {
-        this.websocket = await connect_websocket(this.url, {
-            on_message: this.handle.bind(this),
-            on_close: () => {
-                this.id = 0;
-                this.handlers = [];
-            },
+        if (this.connected)
+            return;
+        const ptail = this.pconnect;
+        let resolve;
+        this.pconnect = new Promise((_resolve, _reject) => {
+            resolve = _resolve;
         });
+        await ptail;
+        try {
+            if (!this.connected)
+                // 保存的 rpc 状态在 this.handlers, 与 websocket 无关，因此即使断开重连也不影响 rpc 的运行，即
+                // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
+                this.websocket = await connect_websocket(this.url, { on_message: this.handle.bind(this) });
+        }
+        finally {
+            resolve();
+        }
     }
     disconnect() {
         this.websocket?.close();
-        this.id = 0;
-        this.handlers = [];
-    }
-    send(message, websocket = this.websocket) {
-        if (websocket?.readyState !== WebSocket.OPEN)
-            throw new Error(`${websocket?.url || 'websocket'} 已断开，无法调用 remote.send`);
-        if (!('id' in message))
-            message.id = this.id;
-        websocket.send(Remote.pack(message));
     }
-    /** 调用 remote 中的 func, 中间消息及返回结果可由 handler 处理，处理 done message 之后的返回值作为 call 函数的返回值
-        如果为 unary rpc, 可以不传 handler, await call 之后可以得到响应 message 的 args
-    */
-    async call(message, handler) {
-        if (!this.connected)
-            if (this.autoconnect) {
-                // 临界区：保证多个 call 并发时只连接一次
-                const ptail = this.pconnect;
-                let resolve;
-                this.pconnect = new Promise((_resolve, _reject) => {
-                    resolve = _resolve;
-                });
-                try {
-                    await ptail;
-                }
-                catch { }
-                // 临界区结束，只有一个 call 调用运行到这里，可以开始连接 WebSocket
-                if (!this.connected) {
-                    if (this.websocket)
-                        console.log(`${this.url} 已断开，尝试自动重连`);
-                    else
-                        console.log(`${this.url} 未连接，尝试自动连接`);
-                    try {
-                        await this.connect();
-                    }
-                    finally {
-                        resolve();
-                    }
-                }
+    /** 接收 websocket 连接的 remote 端必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket
+        发送或连接出错时自动清理 message.id 对应的 handler */
+    async send(message, websocket) {
+        try {
+            if (this.url) {
+                assert(!websocket || websocket === this.websocket);
+                await this.connect();
+                websocket = this.websocket;
             }
-            else
-                throw new Error(`${this.url} 未连接或已断开，无法调用 remote.call`);
-        return new Promise((resolve, reject) => {
-            this.handlers[this.id] = async (message) => {
-                const { error, done } = message;
-                if (error) {
-                    reject(Object.assign(new Error(), error));
-                    return;
-                }
-                const result = handler ?
-                    await handler(message)
-                    :
-                        message.args;
-                if (done)
-                    resolve(result);
-            };
-            this.send(message);
-            this.id++;
-        });
+            else {
+                assert(websocket);
+                assert(!websocket.url, `The websocket received by the server should have no url attribute, websocket.url: ${websocket.url}`);
+                if (websocket.readyState !== WebSocket.OPEN)
+                    throw new Error(`remote.send(): websocket client disconnected`);
+            }
+            if (!message.id)
+                message.id = genid();
+            websocket.send(Remote.pack(message));
+        }
+        catch (error) {
+            if (message.id)
+                this.handlers.delete(message.id);
+            throw error;
+        }
     }
-    /** 处理接收到的 WebSocket message
-        1. 被调用方接收 message 并开始处理
-        2. 调用方处理 message 响应
-    */
+    /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
+        如果 message.done == true 则清理 handler
+        如果 handler 返回了值，则包装为 message 发送 */
     async handle(event, websocket) {
         const message = Remote.parse(event.data);
-        const { func, id, done } = message;
+        const { id, func, done } = message;
         if (this.print)
             console.log(message);
-        if (func) // 作为被调方
-            try {
-                const handler = this.funcs[func];
-                if (!handler)
-                    throw new Error(`找不到 rpc handler for '${func}'`);
-                await handler(message, websocket);
-            }
-            catch (error) {
-                this.send({
-                    id,
-                    error,
-                    done: true
-                }, websocket);
-                throw error;
-            }
-        else { // 作为发起方
-            this.handlers[id](message);
+        let handler;
+        if (func)
+            handler = this.funcs[func];
+        else {
+            handler = this.handlers.get(id);
             if (done)
-                this.handlers[id] = null;
+                this.handlers.delete(id);
         }
+        try {
+            if (handler) {
+                const data = await handler(message, websocket);
+                if (data)
+                    await this.send({ id, data }, websocket);
+            }
+            else if (message.error)
+                throw message.error;
+            else
+                throw new Error(`rpc handler not found: ${func ? `func: ${func.quote()}` : `id: ${id}`}`);
+        }
+        catch (error) {
+            // handle 出错并不意味着 rpc 一定会结束，可能 error 是运行中的正常数据，所以不能清理 handler
+            if (websocket.readyState === WebSocket.OPEN &&
+                !message.error // 防止无限循环往对方发送 error, 只有在对方无错误时才可以发送
+            )
+                try {
+                    await this.send({ id, error, /* 不能设置 done 清理对面 handler, 理由同上 */ }, websocket);
+                }
+                catch { }
+            // 再往上层抛出错误没有意义了，上层调用栈是 websocket.on('message') 之类的
+            console.log(error);
+        }
+    }
+    /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
+    async call(func, args) {
+        return new Promise(async (resolve, reject) => {
+            const id = genid();
+            this.handlers.set(id, (message) => {
+                const { error, data } = message;
+                if (error)
+                    reject(error);
+                else
+                    resolve(data);
+                this.handlers.delete(id);
+            });
+            await this.send({ id, func, data: args }); // 不需要 done: true, 因为对面的 remote.handlers 中不会有这个 id 的 handler
+        });
     }
 }
 //# sourceMappingURL=net.js.map