xshell 1.0.19 → 1.0.20

package/i18n/dict.json

@@ -292,5 +292,20 @@
     },
     "连接被关闭": {
         "en": "connection closed"
+    },
+    "状态码 {{status}}, 非 2xx": {
+        "en": "Status code {{status}}, not 2xx"
+    },
+    "构建 Remote 时 url 和 websocket 最多只能传一个": {
+        "en": "When building Remote, only one url and websocket can be passed at most"
+    },
+    "创建 Remote 时传入的 websocket 连接已断开": {
+        "en": "The incoming websocket connection was broken while creating the Remote"
+    },
+    "传入的 websocket 连接已断开": {
+        "en": "The incoming websocket connection was disconnected"
+    },
+    "尝试释放未锁定的锁，这不应该发生": {
+        "en": "Attempt to release an unlocked lock, this should not happen"
     }
 }

package/net.browser.d.ts

@@ -1,4 +1,5 @@
 import './prototype.browser.js';
+import { Lock } from './utils.browser.js';
 export interface BasicAuth {
     type: 'basic';
     username: string;
@@ -14,12 +15,12 @@ export interface RequestOptions {
     headers?: Record<string, string> | Headers;
     body?: string | Record<string, any> | ArrayBufferView | ArrayBuffer | Blob | URLSearchParams | FormData;
     type?: 'application/json' | 'application/x-www-form-urlencoded' | 'multipart/form-data';
+    encoding?: 'binary';
     retries?: true | number;
     timeout?: number;
     auth?: BasicAuth | BearerAuth;
     cookies?: Record<string, string>;
     cors?: boolean;
-    by?: 'fetch' | 'GM_xmlhttpRequest';
 }
 export interface RequestRawOptions extends RequestOptions {
     raw: true;
@@ -47,11 +48,11 @@ export interface RequestError extends Error {
         - body?: http 请求体，可以是 string, Record<string, any> (会自动 JSON.stringify), ArrayBuffer(View), Blob,
             URLSearchParams (type 为 x-www-form-urlencoded), FormData (type 为 form-data)
         - type?: `'application/json'` 有 body 时设置 http 请求头中的 content-type 头
+        - encoding?: 设置为 'binary' 时返回 ArrayBuffer 的 body
         - retries?: `false` 可以传入 true (默认 2 次) 或 重试次数
         - timeout?: `5 * 1000`
         - auth?: BasicAuth | BearerAuth
-        - raw?: `false` 传入后返回整个 response
-        - by: `window.GM_xmlhttpRequest ? 'GM_xmlhttpRequest' : 'fetch'` 发起请求所使用的底层方法 */
+        - raw?: `false` 传入后返回整个 response  */
 export declare function request(url: string | URL): Promise<string>;
 export declare function request(url: string | URL, options: RequestRawOptions): Promise<Response>;
 export declare function request(url: string | URL, options: RequestOptions & {
@@ -99,8 +100,7 @@ export type MessageHandler = (message: Message, websocket?: WebSocket) => void |
 /** 二进制消息格式
     - json.length (小端序): 4 字节
     - json 数据
-    - binary 数据
-*/
+    - binary 数据 */
 export interface Message<TData extends any[] = any[]> {
     /** rpc id: 在 rpc 系统中认为是唯一的。用来在单个 websocket 连接上复用多个 rpc 请求。多个相同 id 的 message 组成一个请求流 */
     id?: number;
@@ -119,8 +119,7 @@ export interface Message<TData extends any[] = any[]> {
         里面是可序列化为 json 的 js 变量，或者是 Uint8Array
         Uint8Array 的参数处理后被替换为 Uint8Array.byteLength, 并将下标记录在 bins 中
         
-        注意: 数组中如果有 undefined 值，传输到对面会变成 null 值
-    */
+        注意: 数组中如果有 undefined 值，传输到对面会变成 null 值 */
     data?: TData;
     /** bins: data 中哪些下标对应的原始值是 Uint8Array 类型的，如: [0, 3] */
     bins?: number[];
@@ -128,35 +127,60 @@ export interface Message<TData extends any[] = any[]> {
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
     调用方使用 remote.call 进行调用
     被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
-    未连接时自动连接，断开后自动重连 */
+    未连接时自动连接，断开后自动重连 (保证执行 send 时已连接，否则报错)
+    从设计上与 rpc 状态与底层连接的状态无关 (通过传入 url 创建的)，底层连接断开后，只要检测到断线，会尝试重连，如果重连成功，则不影响调用的状态
+    @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 declare class Remote {
-    url: string;
+    /** 是否为建立 rpc 连接的发起方 */
+    initiator: boolean;
+    /** websocket url */
+    url?: string;
     /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
-    websocket?: WebSocket;
+    lwebsocket?: Lock<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;
     pconnect: Promise<any>;
-    get connected(): boolean;
-    static parse<TData extends any[] = any[]>(array_buffer: ArrayBuffer): Message<TData>;
+    /** 使用 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;
-    constructor({ url, funcs, websocket }?: {
+    /** 作为 rpc 发起方，可以通过传入 url 或者 websocket 定义远程 Remote
+        作为 rpc 接收方，可以不传 url 和 websocket 定义本地 Remote */
+    constructor({ url, funcs, websocket, on_error }?: {
         url?: string;
         funcs?: Remote['funcs'];
         websocket?: WebSocket;
+        on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
     });
-    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连 */
-    connect(): Promise<void>;
+    on_error?(error: WebSocketConnectionError, websocket: WebSocket): void;
+    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连
+        作为接收方需要传入使用的 websocket 连接，确保这个这个连接的状态 */
+    connect(websocket?: WebSocket): Promise<void>;
     disconnect(): void;
-    /** 接收 websocket 连接的 remote 端必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket
+    /** 接收 websocket 连接的本地 remote 必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket_lock.resource
         发送或连接出错时自动清理 message.id 对应的 handler */
     send(message: Message, websocket?: WebSocket): Promise<void>;
     /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
         如果 message.done == true 则清理 handler
-        如果 handler 返回了值，则包装为 message 发送 */
-    handle(data: ArrayBuffer, websocket: WebSocket): Promise<void>;
+        如果 handler 返回了值，则包装为 message 发送
+        使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214  */
+    handle(data: Uint8Array, websocket: WebSocket): Promise<void>;
     /** 调用 remote 中的 func, 只适用于最简单的一元 rpc (请求, 响应) */
     call<TReturn extends any[] = any[]>(func: string, args?: any[]): Promise<TReturn>;
 }

package/net.browser.js

@@ -1,7 +1,6 @@
-/// <reference types='tampermonkey' />
 import { t } from './i18n/instance.js';
 import './prototype.browser.js'; // to_time_str()
-import { assert, concat, genid, delay } from './utils.browser.js';
+import { assert, concat, genid, delay, Lock } from './utils.browser.js';
 async function fetch_retry(url, options, timeout, retries = 0, count = 0) {
     try {
         options.signal = AbortSignal.timeout(timeout);
@@ -19,7 +18,7 @@ async function fetch_retry(url, options, timeout, retries = 0, count = 0) {
         }
     }
 }
-export async function request(url, { method, queries, headers: _headers, body, type = 'application/json', retries, timeout = 5 * 1000, auth, raw = false, cors, by = window.GM_xmlhttpRequest ? 'GM_xmlhttpRequest' : 'fetch', } = {}) {
+export async function request(url, { method, queries, headers: _headers, body, type = 'application/json', encoding, retries, timeout = 5 * 1000, auth, raw = false, cors, } = {}) {
     url = new URL(url, location.href);
     if (queries)
         for (const key in queries) {
@@ -51,117 +50,71 @@ export async function request(url, { method, queries, headers: _headers, body, t
                     headers[key] = value;
                 }
             }
-    if (by === 'fetch') {
-        let options = {
-            ...method ? { method } : {},
-            keepalive: true,
-            redirect: 'follow',
-            credentials: 'include',
-            ...cors ? { mode: 'cors' } : {},
-            headers,
-            // --- body
-            body: (() => {
-                if (body === undefined)
-                    return;
-                switch (type) {
-                    case 'application/json':
-                        return typeof body === 'string' ||
-                            ArrayBuffer.isView(body) ||
-                            body instanceof ArrayBuffer ||
-                            body instanceof Blob ?
-                            body
-                            :
-                                JSON.stringify(body);
-                    case 'application/x-www-form-urlencoded':
-                        return body instanceof URLSearchParams ? body : new URLSearchParams(body);
-                    case 'multipart/form-data':
-                        if (body instanceof FormData)
-                            return body;
-                        else {
-                            let form = new FormData();
-                            for (const key in body) {
-                                let value = body[key];
-                                form.set(key, value);
-                            }
-                            return form;
+    let options = {
+        ...method ? { method } : {},
+        keepalive: true,
+        redirect: 'follow',
+        credentials: 'include',
+        ...cors ? { mode: 'cors' } : {},
+        headers,
+        // --- body
+        body: (() => {
+            if (body === undefined)
+                return;
+            switch (type) {
+                case 'application/json':
+                    return typeof body === 'string' ||
+                        ArrayBuffer.isView(body) ||
+                        body instanceof ArrayBuffer ||
+                        body instanceof Blob ?
+                        body
+                        :
+                            JSON.stringify(body);
+                case 'application/x-www-form-urlencoded':
+                    return body instanceof URLSearchParams ? body : new URLSearchParams(body);
+                case 'multipart/form-data':
+                    if (body instanceof FormData)
+                        return body;
+                    else {
+                        let form = new FormData();
+                        for (const key in body) {
+                            let value = body[key];
+                            form.set(key, value);
                         }
-                }
-            })(),
-        };
-        let response;
-        try {
-            response = await fetch_retry(url, options, timeout, retries);
-            if (!response.ok)
-                throw Object.assign(new Error(`状态码 ${response.status}, 非 2xx`), { name: 'StatusCodeError' });
-        }
-        catch (error) {
-            error.url = url;
-            error.options = options;
-            if (response)
-                error.response = {
-                    status: response.status,
-                    url: response.url,
-                    headers: response.headers,
-                    ok: response.ok,
-                    type: response.type,
-                    text: await response.text(),
-                    redirected: response.redirected
-                };
-            throw error;
-        }
-        if (raw)
-            return response;
-        if (!response.body)
-            return response.body;
-        return response.text();
+                        return form;
+                    }
+            }
+        })(),
+    };
+    let response;
+    try {
+        response = await fetch_retry(url, options, timeout, retries);
+        if (!response.ok)
+            throw Object.assign(new Error(t('状态码 {{status}}, 非 2xx', { status: response.status })), { name: 'StatusCodeError' });
     }
-    else
-        return new Promise((resolve, reject) => {
-            const options = {
-                ...method ? { method: method } : {},
-                url: url.toString(),
-                // @ts-ignore ts 类型不支持，实际上已经有了
-                headers: Object.fromEntries(headers),
-                ...body ? {
-                    data: typeof body === 'string' ? body : JSON.stringify(body)
-                } : {},
-                onload(response) {
-                    if (200 <= response.status && response.status <= 299)
-                        resolve(response.responseText);
-                    else
-                        reject(Object.assign(new Error(`状态码 ${response.status}, 非 2xx`), {
-                            name: 'StatusCodeError',
-                            url,
-                            options,
-                            response: {
-                                stauts: response.status,
-                                url: url.toString(),
-                                headers: response.responseHeaders,
-                                ok: false,
-                                text: response.responseText
-                            }
-                        }));
-                },
-                onerror(response) {
-                    reject(Object.assign(new Error(response.error), {
-                        name: 'TimeoutError',
-                        url: url,
-                        options,
-                        response: {
-                            stauts: response.status,
-                            url: url.toString(),
-                            headers: response.responseHeaders,
-                            ok: false,
-                            text: response.responseText
-                        }
-                    }));
-                },
-                ontimeout() {
-                    reject(Object.assign(new Error('GM_xmlhttpRequest 超时'), { name: 'TimeoutError', url, options }));
-                },
+    catch (error) {
+        error.url = url;
+        error.options = options;
+        if (response)
+            error.response = {
+                status: response.status,
+                url: response.url,
+                headers: response.headers,
+                ok: response.ok,
+                type: response.type,
+                text: await response.text(),
+                redirected: response.redirected
             };
-            GM_xmlhttpRequest(options);
-        });
+        throw error;
+    }
+    if (raw)
+        return response;
+    if (!response.body)
+        return response.body;
+    if (encoding === 'binary')
+        return response.arrayBuffer();
+    else
+        return response.text();
 }
 /** 发起 http 请求并将响应体作为 json 解析 */
 export async function request_json(url, options) {
@@ -272,32 +225,48 @@ export async function connect_websocket(url, { protocols, on_message, on_error,
 /** 通过创建 remote 对象对 websocket rpc 进行抽象
     调用方使用 remote.call 进行调用
     被调方在创建 remote 对象时传入 funcs 注册处理函数，并使用 remote.handle 方法处理 websocket message
-    未连接时自动连接，断开后自动重连 */
+    未连接时自动连接，断开后自动重连 (保证执行 send 时已连接，否则报错)
+    从设计上与 rpc 状态与底层连接的状态无关 (通过传入 url 创建的)，底层连接断开后，只要检测到断线，会尝试重连，如果重连成功，则不影响调用的状态
+    @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 {
+    /** 是否为建立 rpc 连接的发起方 */
+    initiator;
+    /** websocket url */
     url;
     /** 主动发起 websocket 连接的客户端 (构造函数传 url) 有这个属性 */
-    websocket;
+    lwebsocket;
     /** 通过 rpc message.func 被调用的 rpc 函数 */
     funcs;
     /** map<id, message handler>: 通过 rpc message.id 找到对应的 handler, unary rpc 接收方不需要设置 handlers, 发送方需要 */
     handlers = new Map();
     print = false;
     pconnect;
-    get connected() {
-        return this.websocket?.readyState === WebSocket.OPEN;
-    }
-    static parse(array_buffer) {
-        const buf = new Uint8Array(array_buffer);
-        const dv = new DataView(array_buffer);
+    /** 使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214 */
+    static parse(buffer) {
+        const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         const len_json = dv.getUint32(0, true);
         let offset = 4 + len_json;
-        let message = JSON.parse(decoder.decode(buf.subarray(4, offset)));
+        let message = JSON.parse(decoder.decode(buffer.subarray(4, offset)));
         if (message.bins) {
             const { bins } = message;
             let { data } = message;
             for (const ibin of bins) {
                 const len_buf = data[ibin];
-                data[ibin] = buf.subarray(offset, offset + len_buf);
+                data[ibin] = buffer.subarray(offset, offset + len_buf);
                 offset += len_buf;
             }
         }
@@ -332,50 +301,69 @@ export class Remote {
         dv.setUint32(0, str_json.length, true);
         return concat([dv, str_json, ...bufs]);
     }
-    constructor({ url, funcs = {}, websocket } = {}) {
+    /** 作为 rpc 发起方，可以通过传入 url 或者 websocket 定义远程 Remote
+        作为 rpc 接收方，可以不传 url 和 websocket 定义本地 Remote */
+    constructor({ url, funcs = {}, websocket, on_error } = {}) {
+        assert(!(url && websocket), t('构建 Remote 时 url 和 websocket 最多只能传一个'));
+        this.initiator = Boolean(url || websocket);
         this.url = url;
         this.funcs = funcs;
-        this.websocket = websocket;
+        if (on_error)
+            this.on_error = on_error;
+        this.lwebsocket = new Lock(websocket || null);
+    }
+    on_error(error, websocket) {
+        throw error;
     }
-    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连 */
-    async connect() {
-        if (this.connected)
+    /** 幂等，保证 websocket 已连接，否则抛出异常，不需要手动调用，在其它方法中已默认自动重连
+        作为接收方需要传入使用的 websocket 连接，确保这个这个连接的状态 */
+    async connect(websocket) {
+        if (this.initiator) {
+            if (this.lwebsocket.resource?.readyState === WebSocket.OPEN)
+                return;
+            else if (!this.url)
+                throw new Error(t('创建 Remote 时传入的 websocket 连接已断开'));
+            // else 等待重连
+        }
+        else if (websocket.readyState === WebSocket.OPEN)
             return;
-        const ptail = this.pconnect;
-        let resolve;
-        this.pconnect = new Promise((_resolve, _reject) => {
-            resolve = _resolve;
+        else
+            throw new Error(t('传入的 websocket 连接已断开'));
+        // 假设有多个请求想要并发连接 websocket, 且此时 websocket 是断开的状态
+        // 应该排队依次连接，而不是后续的连接直接使用第一次连接的 promise，后续调用还是应该尝试重连（不止连接一次）
+        return this.lwebsocket.request(async (websocket) => {
+            // 保存的 rpc 状态在 this.handlers, 与 websocket 无关，因此即使断开重连也不影响 rpc 的运行，即
+            // 底层连接断开后自动重连对上层应该是无感知的，除非再次连接时失败
+            if (websocket?.readyState === WebSocket.OPEN)
+                return;
+            else if (!this.url)
+                throw new Error(t('创建 Remote 时传入的 websocket 连接已断开'));
+            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)
+                });
         });
-        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.lwebsocket.resource?.close(1000);
     }
-    /** 接收 websocket 连接的 remote 端必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket
+    /** 接收 websocket 连接的本地 remote 必传 websocket 参数；发起端选传，如果传了必须等于 this.websocket_lock.resource
         发送或连接出错时自动清理 message.id 对应的 handler */
     async send(message, websocket) {
         try {
-            if (this.url) {
-                assert(!websocket || websocket === this.websocket);
+            if (this.initiator) {
+                assert(!websocket || websocket === this.lwebsocket.resource);
                 await this.connect();
-                websocket = this.websocket;
-            }
-            else {
-                assert(websocket);
-                if (websocket.readyState !== WebSocket.OPEN)
-                    throw new Error(t('remote.send(): websocket client 已断开'));
+                websocket = this.lwebsocket.resource;
             }
+            else
+                await this.connect(websocket);
             if (!message.id)
                 message.id = genid();
+            // 不需要独占 websocket
             websocket.send(Remote.pack(message));
         }
         catch (error) {
@@ -386,7 +374,8 @@ export class Remote {
     }
     /** 处理接收到的 websocket message 并解析, 根据 id dispatch 到对应的 handler 进行处理
         如果 message.done == true 则清理 handler
-        如果 handler 返回了值，则包装为 message 发送 */
+        如果 handler 返回了值，则包装为 message 发送
+        使用 Uint8Array 作为参数更灵活 https://stackoverflow.com/a/74505197/7609214  */
     async handle(data, websocket) {
         const message = Remote.parse(data);
         const { id, func, done } = message;