@maiyunnet/kebab 9.17.3 → 9.18.1

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.17.3";
+export declare const VER = "9.18.1";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */
@@ -159,6 +159,8 @@ export interface IConfigConst {
     'host': string;
     'hostname': string;
     'hostport': number;
+    /** --- 协议与 host，如 https://example.com:8443 --- */
+    'urlOrigin': string;
     'uri': IUrlParse;
     'rootPath': string;
     'modPath': string;

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.17.3';
+export const VER = '9.18.1';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/ws.d.ts

@@ -43,6 +43,25 @@ export interface IConnectOptions {
         'url': string;
         'auth': string;
     };
+    /** --- WebSocket 握手失败回调 --- */
+    onConnectError?: (error: unknown) => void;
+}
+/** --- WebSocket 管道首先结束的一侧 --- */
+export type TPipeSide = 'source' | 'target';
+/** --- WebSocket 管道结束前最后收到的底层事件 --- */
+export type TPipeCloseEvent = 'close' | 'end' | 'timeout' | 'error';
+/** --- WebSocket 管道关闭信息 --- */
+export interface IPipeCloseInfo {
+    'side': TPipeSide;
+    'event': TPipeCloseEvent;
+    'error'?: unknown;
+    'code'?: number;
+    'reason'?: string;
+}
+/** --- WebSocket 关闭信息 --- */
+export interface ISocketCloseInfo {
+    'code': number;
+    'reason': string;
 }
 /** --- 正向代理请求的传入参数选项 --- */
 export interface IMproxyOptions {
@@ -78,10 +97,32 @@ export interface IRproxyOptions {
         'url': string;
         'auth': string;
     };
+    /** --- 连接目标 WebSocket 失败回调 --- */
+    onConnectError?: (error: unknown) => void;
+    /** --- 管道关闭回调，返回首先关闭的一侧及其底层事件 --- */
+    onClose?: (info: IPipeCloseInfo) => void;
+    /** --- 生成回传给另一侧的 WebSocket 关闭原因，仅在管道断开时调用 --- */
+    closeReason?: (info: IPipeCloseInfo) => string;
 }
 export declare class Socket {
     /** --- 当前的 ws 对象 --- */
     private _ws;
+    /** --- 当前是否为服务端接入的连接 --- */
+    private readonly _isServer;
+    /** --- 客户端发出的帧是否掩码 --- */
+    private _masking;
+    /** --- 等待底层写入回调的消息数量 --- */
+    private _pendingWrites;
+    /** --- 是否已经因发送缓存触发背压 --- */
+    private _writeBlocked;
+    /** --- 是否已由本端主动结束写入 --- */
+    private _finished;
+    /** --- 是否已由对端结束读取 --- */
+    private _ended;
+    /** --- 底层 TCP Socket，用于设置和清理空闲超时 --- */
+    private _transport?;
+    /** --- 底层 TCP Socket 的超时监听器 --- */
+    private _transportTimeout?;
     constructor(request?: http.IncomingMessage, socket?: net.Socket, head?: Buffer, options?: {
         'headers'?: http.OutgoingHttpHeaders;
         'timeout'?: number;
@@ -94,6 +135,30 @@ export declare class Socket {
     connect(u: string, opt?: IConnectOptions): Promise<this | null>;
     /** --- 创建成功后第一时间绑定事件 --- */
     private _bindEvent;
+    /**
+     * --- 绑定底层 TCP Socket 的空闲超时 ---
+     * @param socket 底层 TCP Socket
+     * @param timeout 超时毫秒数，0 为不超时
+     */
+    private _bindTransport;
+    /** --- 清理底层 TCP Socket 监听器 --- */
+    private _unbindTransport;
+    /**
+     * --- 将 ws 的消息数据统一转换为 Buffer ---
+     * @param data ws 原始消息数据
+     * @returns Buffer
+     */
+    private _toBuffer;
+    /**
+     * --- 接收并派发消息；上层未就绪或主动暂停时同步暂停底层 TCP 读取 ---
+     * @param msg 消息
+     */
+    private _receive;
+    /**
+     * --- 派发错误，监听器尚未绑定时暂存 ---
+     * @param error 错误对象
+     */
+    private _emitError;
     /** --- 还未开启监听时来的数据将存在这里 --- */
     private readonly _waitMsg;
     /** --- 尚未交给消息监听器的数据量 --- */
@@ -103,7 +168,7 @@ export declare class Socket {
     /** --- 还未开启 error 监听时产生的 error 错误对象 --- */
     private _error;
     /** --- 还未开启 close 监听时是不是就已经 close --- */
-    private _close;
+    private _close?;
     /** --- 绑定的自定义监听事件（未绑定则默认在 _bindEvent 执行） --- */
     private _on;
     /**
@@ -119,14 +184,20 @@ export declare class Socket {
         'data': Buffer;
     }) => void | Promise<void>): this;
     on(event: 'error', cb: (error: any) => void | Promise<void>): this;
-    on(event: 'drain' | 'close' | 'end' | 'timeout', cb: () => void | Promise<void>): this;
+    on(event: 'close', cb: (info: ISocketCloseInfo) => void | Promise<void>): this;
+    on(event: 'drain' | 'end' | 'timeout', cb: () => void | Promise<void>): this;
     /** --- 取消监听 --- */
     off(event: 'message' | 'drain' | 'error' | 'close' | 'end' | 'timeout'): this;
-    end(): void;
+    /**
+     * --- 正常结束 WebSocket 连接 ---
+     * @param code WebSocket 关闭码
+     * @param reason 关闭原因，超过协议上限时自动安全截断
+     */
+    end(code?: number, reason?: string): void;
     destroy(): void;
-    /** --- 暂停向消息监听器派发数据，底层仍只保留有界缓存 --- */
+    /** --- 暂停向消息监听器派发数据，并暂停底层 TCP 读取 --- */
     pause(): void;
-    /** --- 恢复向消息监听器派发数据 --- */
+    /** --- 恢复派发缓存消息，并恢复底层 TCP 读取 --- */
     resume(): void;
     /** --- 发送文本 --- */
     writeText(data: Buffer | string | Array<Buffer | string>): boolean;
@@ -134,6 +205,15 @@ export declare class Socket {
     writeResult(data: kebab.Json): boolean;
     /** --- 发送二进制 --- */
     writeBinary(data: string | Buffer | Array<string | Buffer>): boolean;
+    /**
+     * --- 发送消息并将 ws 的发送缓存转换为 Kebab 的背压布尔值 ---
+     * @param data 消息数据
+     * @param binary 是否为二进制消息
+     * @returns 是否已直接写入底层 Socket 缓存
+     */
+    private _send;
+    /** --- 发送缓存完全排空后派发 drain --- */
+    private _emitDrain;
     /** --- 当前是否是可写状态 --- */
     get writable(): boolean;
     /** --- 当前是否已经结束读取，并且无法继续读取 --- */
@@ -148,6 +228,13 @@ export declare class Socket {
     ping(data?: Buffer | string): boolean;
     /** --- 发送 ping --- */
     pong(data?: Buffer | string): boolean;
+    /**
+     * --- 发送控制帧 ---
+     * @param method 控制帧类型
+     * @param data 控制帧数据
+     * @returns 是否已直接写入底层 Socket 缓存
+     */
+    private _sendControl;
 }
 /**
  * --- 创建一个 ws 客户端发起 ws 请求 ---