xshell 1.3.4 → 1.3.6

package/net.d.ts

@@ -1,8 +1,8 @@
-import type net from 'node:net';
+import net from 'node:net';
 import { type Readable } from 'node:stream';
 import type { Cookie, CookieJar, MemoryCookieStore } from 'tough-cookie';
 import type { Encoding } from './file.ts';
-import { inspect } from './utils.ts';
+import { inspect, type Deferred2, type OnTimeout } from './utils.ts';
 import { type BasicAuth, type BearerAuth } from './net.common.ts';
 export * from './net.common.ts';
 export declare enum MyProxy {
@@ -110,4 +110,25 @@ export declare function request(url: string | URL, options: RequestOptions & {
 export declare function request(url: string | URL, options: RequestOptions): Promise<string>;
 /** 发起 http 请求并将响应体作为 json 解析 */
 export declare function request_json<T = any>(url: string | URL, options?: RequestOptions): Promise<T>;
+export interface ConnectOptions {
+    local_port?: number;
+    timeout?: number;
+    on_timeout?: OnTimeout;
+    print?: {
+        error: boolean;
+        connect: boolean;
+    };
+}
+/** 建立 tcp 连接，超时时间为 2 秒 (timeout 选项)，返回已连接的 socket
+    连接中遇到的错误会 reject，之后取消监听 error 事件，由调用者 attach 处理
+    连接超时则自动 socket.resetAndDestroy
+    - hostname: 要连接到的 ip 或域名
+    - port: 要连接的端口
+    - options?:
+        - local_port?: `随机端口` 使用的本地端口
+        - timeout?: `2000` 超时时间
+        - 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 get_socket_ip(socket: net.Socket): string;

package/net.js

@@ -1,8 +1,9 @@
 import zlib from 'node:zlib';
+import net from 'node:net';
 import { buffer as stream_to_buffer, text as stream_to_text } from 'node:stream/consumers';
 import { pipeline, isReadable } from 'node:stream';
 import { noop } from "./prototype.js";
-import { inspect, assert, delay, map_values, unique, timeout, check, colored, encode, TimeoutError } from "./utils.js";
+import { inspect, assert, delay, map_values, unique, timeout, check, colored, encode, TimeoutError, set_error_message, defer2 } from "./utils.js";
 import { drop_request_headers } from "./net.common.js";
 export * from "./net.common.js";
 export var MyProxy;
@@ -292,6 +293,75 @@ export async function request_json(url, options) {
         throw error;
     }
 }
+/** 建立 tcp 连接，超时时间为 2 秒 (timeout 选项)，返回已连接的 socket
+    连接中遇到的错误会 reject，之后取消监听 error 事件，由调用者 attach 处理
+    连接超时则自动 socket.resetAndDestroy
+    - hostname: 要连接到的 ip 或域名
+    - port: 要连接的端口
+    - options?:
+        - local_port?: `随机端口` 使用的本地端口
+        - timeout?: `2000` 超时时间
+        - print?: 打印连接日志，错误日志
+            - error?: `true`
+            - connect: `false` */
+export function connect(hostname, port, { local_port, timeout: _timeout = 2000, on_timeout, print = { error: true, connect: false } } = {}) {
+    let pconnected = defer2();
+    let timeouted = false;
+    function get_message(message) {
+        return `tcp://${hostname}:${port}  ${message}`;
+    }
+    let socket = net.connect({
+        host: hostname,
+        port,
+        localPort: local_port,
+        noDelay: true
+    }, () => {
+        if (pconnected.settled) {
+            if (print)
+                console.warn(get_message('连接建立了，但是已超时'.yellow));
+            socket.resetAndDestroy();
+        }
+        else {
+            clearTimeout(timeout);
+            socket.off('error', on_error);
+            if (print.connect)
+                console.log(get_message('已连接'));
+            pconnected.resolve(socket);
+        }
+    });
+    const on_error = (error) => {
+        if (pconnected.settled) {
+            // 超时后可能会走到这里
+            if (timeouted && error.code === 'ERR_SOCKET_CLOSED')
+                return;
+            // 待观察：不太可能走到这里
+            if (print.error)
+                console.error(get_message(error.message.red));
+        }
+        else {
+            clearTimeout(timeout);
+            pconnected.reject(set_error_message(error, get_message(error.message)));
+        }
+    };
+    socket.once('error', on_error);
+    let timeout = setTimeout(async () => {
+        // 执行到这里一定没有 settled
+        timeouted = true;
+        socket.resetAndDestroy();
+        if (typeof on_timeout === 'function') {
+            pconnected.resolve(null);
+            try {
+                await on_timeout(new TimeoutError(get_message('超时了')));
+            }
+            catch (error) {
+                pconnected.reject(error);
+            }
+        }
+        else
+            pconnected.reject(new TimeoutError(on_timeout || get_message('超时了')));
+    }, _timeout);
+    return pconnected;
+}
 export function get_socket_ip(socket) {
     return socket.remoteAddress.strip_if_start('::ffff:');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xshell",
-    "version": "1.3.4",
+    "version": "1.3.6",
     "type": "module",
     "main": "./index.js",
     "bin": {

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/process.d.ts

@@ -31,10 +31,10 @@ interface BaseOptions {
     envs?: Record<string, string>;
     /** 创建子进程时添加 http_proxy, https_proxy, no_proxy 环境变量以启用代理 */
     proxy?: MyProxy | true;
-    /** 控制子进程 stdin，默认为 `false` (读空设备)，除非传入了 {@link CallOptions.input} 属性
+    /** 控制子进程 stdin，默认为 `Boolean(input)` (false 时读空设备)，除非传入了 {@link CallOptions.input} 属性
         - 默认值:
             - start(): false ('ignore', 空设备)
-            - (call|launch)(): true (pipe, 作为 child.stdout 可读流)
+            - (call|launch)(): false (pipe, 作为 child.stdin)
         - `true` 设置子进程 stdin 为 'pipe'
         - `false` 设置子进程 stdin 为 'ignore' (空设备)
         - `string` 设置子进程 stdin 为某个文件路径 (打开文件，将句柄设置为子进程 stdin) */
@@ -42,8 +42,8 @@ interface BaseOptions {
     /** 控制子进程 stdout
         - 默认值:
             - start(): false ('ignore', 空设备)
-            - (call|launch)(): true (pipe, 作为 child.stdout 可读流)
-        - `true` 设置子进程 stdout 为 'pipe' (作为 child.stdout 可读流)
+            - (call|launch)(): true (pipe, 作为 child.stdout)
+        - `true` 设置子进程 stdout 为 'pipe' (作为 child.stdout)
         - `false` 设置子进程 stdout 为 'ignore' (空设备)
         - `string` 设置子进程 stdout 某个文件路径 (打开文件，将句柄设置为子进程 stdout) */
     stdout?: boolean | string;

package/utils.common.d.ts

@@ -63,15 +63,19 @@ export declare function decode(buffer: Uint8Array): string;
 /** 比较两个 buffer 内容是否相同，第二个可以传入 string 自动编码转换后比较，
     高频调用时建议提前编码 right 并缓存 */
 export declare function buffer_equals(left: Uint8Array, right: Uint8Array | string): boolean;
+export type OnTimeout = string | ((error: TimeoutError) => void | Promise<void>);
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后抛出错误或调用 on_timeout
     - milliseconds: 限时毫秒数
     - action?: 要等待运行的任务, async function 或 promise
-    - on_timeout?: 超时后调用的函数
-        - 若传: 超时时调用会调用 on_timeout，参数为 TimeoutError，然后等待 on_timeout 执行完成
-            最后 timeout 函数正常返回 null，如果 on_timeout 报错，同样会 reject
+    - on_timeout?: 超时后调用的函数，或者设置错误消息
+        - 若传:
+            - 传 string: 作为 TimeoutError 的 error message
+            - 传 function: 超时时调用会调用 on_timeout，参数为 TimeoutError，然后等待 on_timeout 执行完成
+                - on_timeout 函数正常运行: timeout 函数返回 null
+                - on_timeout 报错: timeout 函数最终抛出这个错误
         - 若不传: 直接抛出 TimeoutError
     - print?: `true` 打印已超时任务的错误 */
-export declare function timeout<TReturn>(milliseconds: number, action: Promise<TReturn> | (() => Promise<TReturn>), on_timeout?: (error: TimeoutError) => void | Promise<void>, print?: boolean): Promise<TReturn>;
+export declare function timeout<TReturn>(milliseconds: number, action: Promise<TReturn> | (() => Promise<TReturn>), on_timeout?: OnTimeout, print?: boolean): Deferred2<TReturn>;
 /** 轮询尝试 action 共 times 次，每次间隔 duration
     action 返回 trusy 值时认为成功，返回 action 的结果
     如果次数用尽仍然失败，返回 null */

package/utils.common.js

@@ -186,17 +186,20 @@ export function buffer_equals(left, right) {
 /** 在指定的时间 (milliseconds) 内运行某个任务，超时之后抛出错误或调用 on_timeout
     - milliseconds: 限时毫秒数
     - action?: 要等待运行的任务, async function 或 promise
-    - on_timeout?: 超时后调用的函数
-        - 若传: 超时时调用会调用 on_timeout，参数为 TimeoutError，然后等待 on_timeout 执行完成
-            最后 timeout 函数正常返回 null，如果 on_timeout 报错，同样会 reject
+    - on_timeout?: 超时后调用的函数，或者设置错误消息
+        - 若传:
+            - 传 string: 作为 TimeoutError 的 error message
+            - 传 function: 超时时调用会调用 on_timeout，参数为 TimeoutError，然后等待 on_timeout 执行完成
+                - on_timeout 函数正常运行: timeout 函数返回 null
+                - on_timeout 报错: timeout 函数最终抛出这个错误
         - 若不传: 直接抛出 TimeoutError
     - print?: `true` 打印已超时任务的错误 */
-export async function timeout(milliseconds, action, on_timeout, print = true) {
-    const error = new TimeoutError();
+export function timeout(milliseconds, action, on_timeout, print = true) {
+    const error = new TimeoutError(typeof on_timeout === 'string' ? on_timeout : undefined);
     let presult = defer2();
     let waiting_on_timeout = false;
     let timeout = setTimeout(async () => {
-        if (on_timeout) {
+        if (typeof on_timeout === 'function')
             try {
                 waiting_on_timeout = true;
                 await on_timeout(error);
@@ -205,7 +208,6 @@ export async function timeout(milliseconds, action, on_timeout, print = true) {
             catch (error) {
                 presult.reject(error);
             }
-        }
         else
             presult.reject(error);
     }, milliseconds);

package/xlint.js

@@ -787,9 +787,6 @@ export const xlint_config = {
         '@typescript-eslint/dot-notation': 'error',
         // 必须 throw Error
         '@typescript-eslint/only-throw-error': 'error',
-        // ------------ async
-        // 返回 Promise 的函数一定要标记为 async 函数
-        '@typescript-eslint/promise-function-async': 'error',
         // 不要 return await promise, 直接 return promise, 除非外面有 try catch
         '@typescript-eslint/return-await': 'error',
         // ------------ 括号