@maiyunnet/kebab 9.17.3 → 9.18.0

package/lib/ws.js

@@ -1,6 +1,7 @@
 import * as net from 'net';
 // --- 第三方 ---
-import * as liws from '@litert/websocket';
+import WebSocket, { WebSocketServer } from 'ws';
+import * as lCore from '#kebab/lib/core.js';
 import * as lText from '#kebab/lib/text.js';
 import * as lUndici from '#kebab/lib/undici.js';
 import * as lCookie from '#kebab/lib/cookie.js';
@@ -21,8 +22,32 @@ export var EOpcode;
     EOpcode[EOpcode["PING"] = 9] = "PING";
     EOpcode[EOpcode["PONG"] = 10] = "PONG";
 })(EOpcode || (EOpcode = {}));
-const liwsServer = liws.createServer({
-    'frameReceiveMode': EFrameReceiveMode.SIMPLE,
+/** --- 单条 WebSocket 消息最大 64 MiB，与原实现保持一致 --- */
+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+/** --- 服务端 Upgrade 响应头，按请求隔离以支持并发握手 --- */
+const upgradeHeaders = new WeakMap();
+/** --- Kebab 复用的无监听端口 WebSocket 服务端 --- */
+const wsServer = new WebSocketServer({
+    'allowSynchronousEvents': false,
+    'autoPong': false,
+    'clientTracking': false,
+    'maxPayload': MAX_MESSAGE_BYTES,
+    'noServer': true,
+    'perMessageDeflate': false,
+});
+wsServer.on('headers', (headers, request) => {
+    const extra = upgradeHeaders.get(request);
+    if (!extra) {
+        return;
+    }
+    for (const [name, value] of Object.entries(extra)) {
+        if (value === undefined) {
+            continue;
+        }
+        for (const item of Array.isArray(value) ? value : [value]) {
+            headers.push(`${name}: ${item}`);
+        }
+    }
 });
 /** --- 未能及时转发的 WebSocket 消息最大缓存量，超过后关闭连接保护进程内存 --- */
 const MAX_PENDING_MESSAGE_BYTES = 8 * 1024 * 1024;
@@ -31,18 +56,44 @@ const MAX_PENDING_MESSAGES = 4_096;
 export class Socket {
     /** --- 当前的 ws 对象 --- */
     _ws;
+    /** --- 当前是否为服务端接入的连接 --- */
+    _isServer = false;
+    /** --- 客户端发出的帧是否掩码 --- */
+    _masking = true;
+    /** --- 等待底层写入回调的消息数量 --- */
+    _pendingWrites = 0;
+    /** --- 是否已经因发送缓存触发背压 --- */
+    _writeBlocked = false;
+    /** --- 是否已由本端主动结束写入 --- */
+    _finished = false;
+    /** --- 是否已由对端结束读取 --- */
+    _ended = false;
+    /** --- 底层 TCP Socket，用于设置和清理空闲超时 --- */
+    _transport;
+    /** --- 底层 TCP Socket 的超时监听器 --- */
+    _transportTimeout;
     constructor(request, socket, head, options = {}) {
         if (!request || !socket) {
             return;
         }
         // --- 一定是 server 模式 ---
-        this._ws = liwsServer.accept({
-            'request': request,
-            'socket': socket,
-            'headers': options.headers,
-            'timeout': options.timeout,
-            'clientEarlyDataPayload': head,
-        });
+        this._isServer = true;
+        this._masking = false;
+        const accepted = {};
+        upgradeHeaders.set(request, options.headers ?? {});
+        try {
+            wsServer.handleUpgrade(request, socket, head ?? Buffer.alloc(0), client => {
+                accepted.socket = client;
+            });
+        }
+        finally {
+            upgradeHeaders.delete(request);
+        }
+        if (!accepted.socket) {
+            throw new Error('WebSocket upgrade failed.');
+        }
+        this._ws = accepted.socket;
+        this._bindTransport(socket, options.timeout ?? 0);
         this._bindEvent();
     }
     /**
@@ -60,12 +111,15 @@ export class Socket {
         const timeout = opt.timeout ?? 10;
         const hosts = opt.hosts ?? {};
         const local = opt.local;
-        const mode = opt.mode ?? EFrameReceiveMode.SIMPLE;
-        const masking = opt.masking ?? true;
+        this._masking = opt.masking ?? true;
         const headers = {};
         if (opt.headers) {
             for (const key in opt.headers) {
-                headers[key.toLowerCase()] = opt.headers[key];
+                const value = opt.headers[key];
+                if (value === undefined) {
+                    continue;
+                }
+                headers[key.toLowerCase()] = Array.isArray(value) ? value.join(', ') : value.toString();
             }
         }
         headers['user-agent'] ??= 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36';
@@ -73,102 +127,171 @@ export class Socket {
         if (opt.cookie) {
             headers['cookie'] = lCookie.buildCookieQuery(opt.cookie, uri);
         }
-        // --- ssl ---
-        const isSsl = puri ?
-            (puri.protocol === 'wss:' ? true : false) :
-            (uri.protocol === 'wss:' ? true : false);
-        if (typeof hosts === 'string' ? hosts : hosts[uri.hostname]) {
-            // --- 要设置额外的 host ---
-            headers['host'] = uri.hostname;
-            if (uri.port) {
-                if (lText.isIPv6(headers['host'])) {
-                    headers['host'] = `[${headers['host']}]`;
-                }
-                headers['host'] += ':' + uri.port;
-            }
-        }
         try {
-            // --- 重定义 IP ---
+            /** --- 实际建立连接的 URL --- */
+            const connectUrl = new URL(puri ? opt.mproxy?.url ?? '' : u);
+            if (puri) {
+                connectUrl.searchParams.set('url', u);
+                connectUrl.searchParams.set('auth', opt.mproxy?.auth ?? '');
+            }
             const host = puri?.hostname ?? uri.hostname ?? '';
             /** --- 真正的连接远程 IP / HOST --- */
             const rhost = typeof hosts === 'string' ? hosts : hosts[host];
-            const port = (puri ? puri.port : uri.port) ?? 443;
-            const path = puri ? puri.path + (puri.path?.includes('?') ? '&' : '?') + lText.queryStringify({
-                'url': u,
-                'auth': opt.mproxy?.auth ?? ''
-            }) : uri.path;
-            const cli = isSsl ?
-                liws.createSecureClient({
-                    'hostname': rhost || host,
-                    'port': port,
-                    'path': path,
-                    'servername': host,
-                    'headers': headers,
-                    'connectTimeout': timeout * 1000,
-                    'frameReceiveMode': mode,
-                    'localAddress': local,
-                }) :
-                liws.createClient({
-                    'hostname': rhost || host,
-                    'port': port,
-                    'path': path,
-                    'headers': headers,
-                    'connectTimeout': timeout * 1000,
-                    'frameReceiveMode': mode,
-                    'localAddress': local,
-                });
-            cli.setMasking(masking);
+            if (rhost) {
+                headers['host'] ??= connectUrl.host;
+                connectUrl.hostname = lText.isIPv6(rhost) ? `[${rhost}]` : rhost;
+            }
+            const clientOptions = {
+                'allowSynchronousEvents': false,
+                'autoPong': false,
+                'handshakeTimeout': timeout * 1000,
+                'headers': headers,
+                'localAddress': local,
+                'maxPayload': MAX_MESSAGE_BYTES,
+                'perMessageDeflate': false,
+                'servername': connectUrl.protocol === 'wss:' ? host : undefined,
+            };
+            const cli = new WebSocket(connectUrl, clientOptions);
             this._ws = cli;
             this._bindEvent();
-            await cli.connect();
+            await new Promise((resolve, reject) => {
+                let onOpen;
+                let onError;
+                let onUnexpectedResponse;
+                const clean = () => {
+                    cli.off('open', onOpen);
+                    cli.off('error', onError);
+                    cli.off('unexpected-response', onUnexpectedResponse);
+                };
+                onOpen = () => {
+                    clean();
+                    resolve();
+                };
+                onError = (error) => {
+                    clean();
+                    reject(error);
+                };
+                onUnexpectedResponse = (_request, response) => {
+                    clean();
+                    response.resume();
+                    cli.terminate();
+                    reject(new Error(`WebSocket handshake failed: ${response.statusCode ?? 0} ${response.statusMessage ?? ''}`.trim()));
+                };
+                cli.once('open', onOpen);
+                cli.once('error', onError);
+                cli.once('unexpected-response', onUnexpectedResponse);
+            });
             return this;
         }
-        catch {
+        catch (e) {
+            opt.onConnectError?.(e);
             return null;
         }
     }
     /** --- 创建成功后第一时间绑定事件 --- */
     _bindEvent() {
-        this._ws.on('message', msg => {
-            if (msg.opcode === EOpcode.CLOSE) {
-                return;
-            }
-            if (!('data' in msg)) {
-                return;
-            }
-            const item = {
-                'opcode': msg.opcode,
-                'data': Buffer.concat(msg.data),
-            };
-            if (this._paused || !this._on.message) {
-                this._queueMessage(item);
-                return;
-            }
-            this._on.message(item);
-        }).on('drain', () => {
-            this._on.drain?.();
+        this._ws.on('message', (data, isBinary) => {
+            this._receive({
+                'opcode': isBinary ? EOpcode.BINARY : EOpcode.TEXT,
+                'data': this._toBuffer(data),
+            });
+        }).on('ping', data => {
+            this._receive({
+                'opcode': EOpcode.PING,
+                'data': data,
+            });
+        }).on('pong', data => {
+            this._receive({
+                'opcode': EOpcode.PONG,
+                'data': data,
+            });
         }).on('error', (e) => {
-            if (this._on.error) {
-                this._on.error(e);
+            this._emitError(e);
+        }).on('close', (code, reason) => {
+            if (!this._finished) {
+                this._ended = true;
+                this._on.end?.();
             }
-            else {
-                this._error = e;
-            }
-        }).on('end', () => {
-            this._on.end?.();
-        }).on('close', () => {
+            this._finished = true;
+            this._ended = true;
             this._waitMsg.length = 0;
             this._waitMsgBytes = 0;
+            this._unbindTransport();
+            const info = {
+                'code': code,
+                'reason': reason.toString(),
+            };
             if (this._on.close) {
-                this._on.close();
+                this._on.close(info);
             }
             else {
-                this._close = true;
+                this._close = info;
             }
-        }).on('timeout', () => {
-            this._on.timeout?.();
         });
     }
+    /**
+     * --- 绑定底层 TCP Socket 的空闲超时 ---
+     * @param socket 底层 TCP Socket
+     * @param timeout 超时毫秒数，0 为不超时
+     */
+    _bindTransport(socket, timeout) {
+        this._transport = socket;
+        socket.setTimeout(timeout);
+        if (!timeout) {
+            return;
+        }
+        this._transportTimeout = () => {
+            this._on.timeout?.();
+            this.destroy();
+        };
+        socket.once('timeout', this._transportTimeout);
+    }
+    /** --- 清理底层 TCP Socket 监听器 --- */
+    _unbindTransport() {
+        if (this._transport && this._transportTimeout) {
+            this._transport.off('timeout', this._transportTimeout);
+        }
+        this._transport = undefined;
+        this._transportTimeout = undefined;
+    }
+    /**
+     * --- 将 ws 的消息数据统一转换为 Buffer ---
+     * @param data ws 原始消息数据
+     * @returns Buffer
+     */
+    _toBuffer(data) {
+        if (Buffer.isBuffer(data)) {
+            return data;
+        }
+        if (Array.isArray(data)) {
+            return Buffer.concat(data);
+        }
+        return Buffer.from(data);
+    }
+    /**
+     * --- 接收并派发消息；上层未就绪或主动暂停时同步暂停底层 TCP 读取 ---
+     * @param msg 消息
+     */
+    _receive(msg) {
+        if (this._paused || !this._on.message) {
+            this._queueMessage(msg);
+            this._ws.pause();
+            return;
+        }
+        this._on.message(msg);
+    }
+    /**
+     * --- 派发错误，监听器尚未绑定时暂存 ---
+     * @param error 错误对象
+     */
+    _emitError(error) {
+        if (this._on.error) {
+            this._on.error(error);
+        }
+        else {
+            this._error = error;
+        }
+    }
     /** --- 还未开启监听时来的数据将存在这里 --- */
     _waitMsg = [];
     /** --- 尚未交给消息监听器的数据量 --- */
@@ -178,7 +301,7 @@ export class Socket {
     /** --- 还未开启 error 监听时产生的 error 错误对象 --- */
     _error = null;
     /** --- 还未开启 close 监听时是不是就已经 close --- */
-    _close = false;
+    _close;
     /** --- 绑定的自定义监听事件（未绑定则默认在 _bindEvent 执行） --- */
     _on = {
         /** --- 消息 --- */
@@ -197,8 +320,15 @@ export class Socket {
         this._waitMsgBytes += msg.data.length;
         if ((this._waitMsgBytes > MAX_PENDING_MESSAGE_BYTES) ||
             (this._waitMsg.length >= MAX_PENDING_MESSAGES)) {
+            const error = new Error(`WebSocket pending message queue overflow: ${this._waitMsgBytes} bytes, ${this._waitMsg.length + 1} messages.`);
             this._waitMsg.length = 0;
             this._waitMsgBytes = 0;
+            if (this._on.error) {
+                this._on.error(error);
+            }
+            else {
+                this._error = error;
+            }
             this.destroy();
             return;
         }
@@ -227,6 +357,9 @@ export class Socket {
         switch (event) {
             case 'message': {
                 this._flushMessages();
+                if (!this._paused) {
+                    this._ws.resume();
+                }
                 break;
             }
             case 'error': {
@@ -237,18 +370,21 @@ export class Socket {
                 break;
             }
             case 'end': {
-                if (!this._ws.ended) {
+                if (!this._ended) {
                     break;
                 }
                 cb();
                 break;
             }
-            default: {
-                // --- drain, close, timeout ---
+            case 'close': {
                 if (!this._close) {
                     break;
                 }
-                cb();
+                cb(this._close);
+                break;
+            }
+            default: {
+                // --- drain, timeout ---
             }
         }
         return this;
@@ -258,79 +394,148 @@ export class Socket {
         this._on[event] = undefined;
         return this;
     }
-    end() {
-        this._ws.end();
+    /**
+     * --- 正常结束 WebSocket 连接 ---
+     * @param code WebSocket 关闭码
+     * @param reason 关闭原因，超过协议上限时自动安全截断
+     */
+    end(code = 1000, reason = '') {
+        if (this._ws.readyState !== WebSocket.OPEN) {
+            return;
+        }
+        this._finished = true;
+        this._ws.close(code, truncateCloseReason(reason));
     }
     destroy() {
-        this._ws.destroy();
+        this._finished = true;
+        this._ws.terminate();
     }
-    /** --- 暂停向消息监听器派发数据，底层仍只保留有界缓存 --- */
+    /** --- 暂停向消息监听器派发数据，并暂停底层 TCP 读取 --- */
     pause() {
         this._paused = true;
+        this._ws.pause();
     }
-    /** --- 恢复向消息监听器派发数据 --- */
+    /** --- 恢复派发缓存消息，并恢复底层 TCP 读取 --- */
     resume() {
         this._paused = false;
         this._flushMessages();
+        if (!this._paused) {
+            this._ws.resume();
+        }
     }
     /** --- 发送文本 --- */
     writeText(data) {
-        if (!this._ws.writable) {
-            return false;
-        }
-        return this._ws.writeText(data);
+        return this._send(data, false);
     }
     /** --- 发送结果对象字符串 --- */
     writeResult(data) {
-        if (!this._ws.writable) {
-            return false;
-        }
-        return this._ws.writeText(lText.stringifyResult(data));
+        return this._send(lText.stringifyResult(data), false);
     }
     /** --- 发送二进制 --- */
     writeBinary(data) {
-        if (!this._ws.writable) {
+        return this._send(data, true);
+    }
+    /**
+     * --- 发送消息并将 ws 的发送缓存转换为 Kebab 的背压布尔值 ---
+     * @param data 消息数据
+     * @param binary 是否为二进制消息
+     * @returns 是否已直接写入底层 Socket 缓存
+     */
+    _send(data, binary) {
+        if (!this.writable) {
+            return false;
+        }
+        const content = Array.isArray(data) ? Buffer.concat(data.map(item => Buffer.from(item))) : data;
+        ++this._pendingWrites;
+        try {
+            this._ws.send(content, {
+                'binary': binary,
+                'compress': false,
+                'fin': true,
+                'mask': this._masking,
+            }, error => {
+                --this._pendingWrites;
+                if (error) {
+                    this._emitError(error);
+                }
+                this._emitDrain();
+            });
+        }
+        catch (error) {
+            --this._pendingWrites;
+            this._emitError(error);
             return false;
         }
-        return this._ws.writeBinary(data);
+        if (this._ws.bufferedAmount > 0) {
+            this._writeBlocked = true;
+            return false;
+        }
+        return true;
+    }
+    /** --- 发送缓存完全排空后派发 drain --- */
+    _emitDrain() {
+        if (!this._writeBlocked || this._pendingWrites || this._ws.bufferedAmount) {
+            return;
+        }
+        this._writeBlocked = false;
+        this._on.drain?.();
     }
     /** --- 当前是否是可写状态 --- */
     get writable() {
-        return this._ws.writable;
+        return !this._finished && (this._ws.readyState === WebSocket.OPEN);
     }
     /** --- 当前是否已经结束读取，并且无法继续读取 --- */
     get ended() {
-        return this._ws.ended;
+        return this._ended;
     }
     /** --- 当前是否已经结束写入，并且无法继续写入 --- */
     get finished() {
-        return this._ws.finished;
+        return this._finished || (this._ws.readyState >= WebSocket.CLOSING);
     }
     /**
      * --- 当前连接是不是服务器连接 ---
      */
     get isServer() {
-        return this._ws.isServer;
+        return this._isServer;
     }
     /** --- 发送 ping --- */
     ping(data) {
-        try {
-            this._ws.ping(data);
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return this._sendControl('ping', data);
     }
     /** --- 发送 ping --- */
     pong(data) {
+        return this._sendControl('pong', data);
+    }
+    /**
+     * --- 发送控制帧 ---
+     * @param method 控制帧类型
+     * @param data 控制帧数据
+     * @returns 是否已直接写入底层 Socket 缓存
+     */
+    _sendControl(method, data) {
+        if (!this.writable) {
+            return false;
+        }
+        ++this._pendingWrites;
         try {
-            this._ws.pong(data);
-            return true;
+            this._ws[method](data, this._masking, error => {
+                --this._pendingWrites;
+                if (error) {
+                    this._emitError(error);
+                }
+                this._emitDrain();
+            });
         }
-        catch {
+        catch (error) {
+            --this._pendingWrites;
+            this._emitError(error);
             return false;
         }
+        if (this._ws.bufferedAmount > 0) {
+            this._writeBlocked = true;
+            return false;
+        }
+        return true;
     }
 }
 /**
@@ -350,24 +555,102 @@ export function connect(u, opt = {}) {
 export function createServer(request, socket, head, options = {}) {
     return new Socket(request, socket, head, options);
 }
+/** --- WebSocket 关闭原因最大字节数，控制帧的另外 2 字节用于关闭码 --- */
+const MAX_CLOSE_REASON_BYTES = 123;
+/**
+ * --- 按 UTF-8 字节安全截断 WebSocket 关闭原因 ---
+ * @param reason 原始关闭原因
+ * @returns 可写入关闭帧的原因
+ */
+function truncateCloseReason(reason) {
+    const data = Buffer.from(reason);
+    if (data.length <= MAX_CLOSE_REASON_BYTES) {
+        return reason;
+    }
+    let length = MAX_CLOSE_REASON_BYTES;
+    while (length && ((data[length] & 0xC0) === 0x80)) {
+        --length;
+    }
+    return data.subarray(0, length).toString();
+}
+/**
+ * --- 判断关闭码是否允许写入 WebSocket 关闭帧 ---
+ * @param code 关闭码
+ * @returns 是否有效
+ */
+function isSendableCloseCode(code) {
+    if (code === undefined) {
+        return false;
+    }
+    if ((code === 1000) || ((code >= 3000) && (code <= 4999))) {
+        return true;
+    }
+    return (code >= 1001) && (code <= 1014) && ![1004, 1005, 1006].includes(code);
+}
+/**
+ * --- 获取可安全转发给对端的关闭原因，仅保留关闭帧中已有的内容 ---
+ * @param info 管道关闭信息
+ * @returns 关闭原因
+ */
+function getPipeCloseReason(info) {
+    return info.reason ?? '';
+}
 /**
  * --- 绑定 socket 管道 ---
  * @param s1 第一个 socket
  * @param s2 第二个 socket
  */
-function bindPipe(s1, s2) {
+function bindPipe(s1, s2, closeReason) {
     return new Promise(resolve => {
         /** --- 是否已经完成关闭，防止双向 close 重复处理 --- */
         let closed = false;
-        /** --- 两端一起销毁，避免半开连接继续占用资源 --- */
-        const close = () => {
+        /** --- 来源侧关闭前最后收到的底层事件 --- */
+        let sourceEvent = 'close';
+        /** --- 目标侧关闭前最后收到的底层事件 --- */
+        let targetEvent = 'close';
+        /** --- 来源侧最后一个错误 --- */
+        let sourceError;
+        /** --- 目标侧最后一个错误 --- */
+        let targetError;
+        /** --- 来源侧 WebSocket 关闭信息 --- */
+        let sourceCloseInfo;
+        /** --- 目标侧 WebSocket 关闭信息 --- */
+        let targetCloseInfo;
+        /** --- 销毁已断开侧，并将原因通过关闭帧回传另一侧 --- */
+        const close = (side) => {
             if (closed) {
                 return;
             }
             closed = true;
-            s1.destroy();
-            s2.destroy();
-            resolve();
+            const info = side === 'source' ? {
+                'side': side,
+                'event': sourceEvent,
+                'error': sourceError,
+                ...sourceCloseInfo,
+            } : {
+                'side': side,
+                'event': targetEvent,
+                'error': targetError,
+                ...targetCloseInfo,
+            };
+            const code = isSendableCloseCode(info.code) ? info.code : 1011;
+            let reason;
+            try {
+                reason = closeReason?.(info) ?? getPipeCloseReason(info);
+            }
+            catch (error) {
+                lCore.log({}, `[WS][PIPE][CLOSE REASON ERROR] ${lText.stringifyError(error)}`, '-error');
+                reason = getPipeCloseReason(info);
+            }
+            if (side === 'source') {
+                s1.destroy();
+                s2.end(code, reason);
+            }
+            else {
+                s1.end(code, reason);
+                s2.destroy();
+            }
+            resolve(info);
         };
         // --- 监听发送端的 ---
         s1.on('message', (msg) => {
@@ -385,7 +668,7 @@ function bindPipe(s1, s2) {
                     break;
                 }
                 case EOpcode.CLOSE: {
-                    close();
+                    close('source');
                     break;
                 }
                 case EOpcode.PING: {
@@ -404,7 +687,21 @@ function bindPipe(s1, s2) {
                     // --- EOpcode.CONTINUATION ---
                 }
             }
-        }).on('close', close).on('drain', () => {
+        }).on('error', (error) => {
+            if (sourceEvent !== 'timeout') {
+                sourceEvent = 'error';
+            }
+            sourceError = error;
+        }).on('end', () => {
+            if (sourceEvent === 'close') {
+                sourceEvent = 'end';
+            }
+        }).on('timeout', () => {
+            sourceEvent = 'timeout';
+        }).on('close', (info) => {
+            sourceCloseInfo = info;
+            close('source');
+        }).on('drain', () => {
             s2.resume();
         });
         // --- 监听远程端的 ---
@@ -423,7 +720,7 @@ function bindPipe(s1, s2) {
                     break;
                 }
                 case EOpcode.CLOSE: {
-                    close();
+                    close('target');
                     break;
                 }
                 case EOpcode.PING: {
@@ -442,7 +739,21 @@ function bindPipe(s1, s2) {
                     // --- EOpcode.CONTINUATION ---
                 }
             }
-        }).on('close', close).on('drain', () => {
+        }).on('error', (error) => {
+            if (targetEvent !== 'timeout') {
+                targetEvent = 'error';
+            }
+            targetError = error;
+        }).on('end', () => {
+            if (targetEvent === 'close') {
+                targetEvent = 'end';
+            }
+        }).on('timeout', () => {
+            targetEvent = 'timeout';
+        }).on('close', (info) => {
+            targetCloseInfo = info;
+            close('target');
+        }).on('drain', () => {
             s1.resume();
         });
     });
@@ -494,14 +805,31 @@ export async function rproxy(ctr, url, opt = {}) {
     const headers = Object.assign(lUndici.filterHeaders(req.headers, undefined, opt.filter), opt.headers);
     // --- 发起请求 ---
     /** --- 远程端的双向 socket --- */
+    /** --- 目标连接的握手错误 --- */
+    let connectError;
     const rsocket = await connect(url, {
         ...opt,
-        headers
+        headers,
+        'onConnectError': (error) => {
+            connectError = error;
+            opt.onConnectError?.(error);
+        },
     });
     if (!rsocket) {
+        const target = lText.parseUrl(url);
+        const endpoint = `${target.protocol ?? 'ws:'}//${target.hostname ?? 'unknown'}${target.port ? `:${target.port}` : ''}`;
+        lCore.log(ctr, `[WS][RPROXY][TARGET CONNECT ERROR] ${endpoint}: ${lText.stringifyError(connectError)}`, '-error');
         return false;
     }
-    await bindPipe(socket, rsocket);
+    const info = await bindPipe(socket, rsocket, opt.closeReason);
+    opt.onClose?.(info);
+    if ((info.side === 'target') || (info.event === 'error') || (info.event === 'timeout')) {
+        const target = lText.parseUrl(url);
+        const endpoint = `${target.protocol ?? 'ws:'}//${target.hostname ?? 'unknown'}${target.port ? `:${target.port}` : ''}`;
+        const error = info.error === undefined ? '' : `: ${lText.stringifyError(info.error)}`;
+        const close = info.code === undefined ? '' : ` code=${info.code}${info.reason ? ` reason=${info.reason}` : ''}`;
+        lCore.log(ctr, `[WS][RPROXY][${info.side.toUpperCase()} ${info.event.toUpperCase()}] ${endpoint}${close}${error}`, '-error');
+    }
     return true;
 }
 /**