@hile/message-ws 3.0.0 → 4.0.0

package/dist/codec.d.ts

@@ -0,0 +1,11 @@
+import { type MessageTransferFormat } from '@hile/message-modem';
+export declare const HILE_MESSAGE_FRAME_MAGIC: Buffer<ArrayBuffer>;
+export declare const HILE_MESSAGE_FRAME_VERSION = 1;
+export declare const HILE_MESSAGE_FRAME_HEADER_SIZE: number;
+export type MessageFrameErrorCode = 'ERR_MESSAGE_FRAME_JSON' | 'ERR_MESSAGE_FRAME_TRUNCATED' | 'ERR_MESSAGE_FRAME_MAGIC' | 'ERR_MESSAGE_FRAME_VERSION' | 'ERR_MESSAGE_FRAME_HEADER_LENGTH' | 'ERR_MESSAGE_FRAME_ENVELOPE';
+export declare class MessageFrameError extends Error {
+    readonly code: MessageFrameErrorCode;
+    constructor(code: MessageFrameErrorCode, message: string);
+}
+export declare function encodeMessageFrame(message: MessageTransferFormat): string | Buffer;
+export declare function decodeMessageFrame(raw: Buffer | ArrayBuffer | Buffer[] | Uint8Array | string, isBinary: boolean): MessageTransferFormat;

package/dist/codec.js

@@ -0,0 +1,125 @@
+import { MESSAGE_MODEM_TYPE, } from '@hile/message-modem';
+const FRAME_MAGIC_BYTES = Buffer.from([0x48, 0x49, 0x4c, 0x45]);
+const MAX_HEADER_BYTES = 1024 * 1024;
+export const HILE_MESSAGE_FRAME_MAGIC = Buffer.from(FRAME_MAGIC_BYTES);
+export const HILE_MESSAGE_FRAME_VERSION = 1;
+export const HILE_MESSAGE_FRAME_HEADER_SIZE = FRAME_MAGIC_BYTES.length + 1 + 4;
+export class MessageFrameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'MessageFrameError';
+        this.code = code;
+    }
+}
+function fail(code, message) {
+    throw new MessageFrameError(code, message);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isBinaryPayload(value) {
+    return Buffer.isBuffer(value) || value instanceof Uint8Array;
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        fail('ERR_MESSAGE_FRAME_JSON', 'message frame contains invalid JSON');
+    }
+}
+function toBuffer(raw) {
+    if (Buffer.isBuffer(raw))
+        return raw;
+    if (typeof raw === 'string')
+        return Buffer.from(raw);
+    if (Array.isArray(raw))
+        return Buffer.concat(raw);
+    if (raw instanceof ArrayBuffer)
+        return Buffer.from(raw);
+    return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength);
+}
+function isBinaryStreamResponse(message) {
+    return message.mode === MESSAGE_MODEM_TYPE.RESPONSE
+        && message.stream === true
+        && message.streamVersion === 1
+        && isRecord(message.data)
+        && isBinaryPayload(message.data.payload);
+}
+function validateBinaryEnvelope(value) {
+    if (!isRecord(value)) {
+        fail('ERR_MESSAGE_FRAME_ENVELOPE', 'binary frame header must be an object');
+    }
+    if (!Number.isSafeInteger(value.id)
+        || value.id < 0
+        || value.mode !== MESSAGE_MODEM_TYPE.RESPONSE
+        || value.twoway !== false
+        || value.stream !== true
+        || value.streamVersion !== 1
+        || !isRecord(value.data)) {
+        fail('ERR_MESSAGE_FRAME_ENVELOPE', 'binary frame header is not a stream response');
+    }
+    if (Object.prototype.hasOwnProperty.call(value.data, 'payload')) {
+        fail('ERR_MESSAGE_FRAME_ENVELOPE', 'binary frame header must not contain an inline payload');
+    }
+    if (!Number.isSafeInteger(value.data.seq)
+        || value.data.seq < 0
+        || typeof value.data.final !== 'boolean'
+        || !(typeof value.data.status === 'string'
+            || typeof value.data.status === 'number')) {
+        fail('ERR_MESSAGE_FRAME_ENVELOPE', 'binary frame chunk metadata is invalid');
+    }
+}
+export function encodeMessageFrame(message) {
+    if (!isBinaryStreamResponse(message))
+        return JSON.stringify(message);
+    const payload = Buffer.from(message.data.payload.buffer, message.data.payload.byteOffset, message.data.payload.byteLength);
+    const { payload: _payload, ...chunkHeader } = message.data;
+    const header = Buffer.from(JSON.stringify({
+        ...message,
+        data: chunkHeader,
+    }));
+    if (header.length === 0 || header.length > MAX_HEADER_BYTES) {
+        fail('ERR_MESSAGE_FRAME_HEADER_LENGTH', 'binary frame header is too large');
+    }
+    const frame = Buffer.allocUnsafe(HILE_MESSAGE_FRAME_HEADER_SIZE + header.length + payload.length);
+    FRAME_MAGIC_BYTES.copy(frame, 0);
+    frame.writeUInt8(HILE_MESSAGE_FRAME_VERSION, FRAME_MAGIC_BYTES.length);
+    frame.writeUInt32BE(header.length, FRAME_MAGIC_BYTES.length + 1);
+    header.copy(frame, HILE_MESSAGE_FRAME_HEADER_SIZE);
+    payload.copy(frame, HILE_MESSAGE_FRAME_HEADER_SIZE + header.length);
+    return frame;
+}
+export function decodeMessageFrame(raw, isBinary) {
+    const bytes = toBuffer(raw);
+    if (!isBinary) {
+        return parseJson(bytes.toString('utf8'));
+    }
+    if (bytes.length < HILE_MESSAGE_FRAME_HEADER_SIZE) {
+        fail('ERR_MESSAGE_FRAME_TRUNCATED', 'binary frame is shorter than its fixed header');
+    }
+    if (!bytes.subarray(0, FRAME_MAGIC_BYTES.length).equals(FRAME_MAGIC_BYTES)) {
+        fail('ERR_MESSAGE_FRAME_MAGIC', 'binary frame has an invalid magic value');
+    }
+    const version = bytes.readUInt8(FRAME_MAGIC_BYTES.length);
+    if (version !== HILE_MESSAGE_FRAME_VERSION) {
+        fail('ERR_MESSAGE_FRAME_VERSION', `unsupported binary frame version: ${version}`);
+    }
+    const headerLength = bytes.readUInt32BE(FRAME_MAGIC_BYTES.length + 1);
+    if (headerLength === 0
+        || headerLength > MAX_HEADER_BYTES
+        || HILE_MESSAGE_FRAME_HEADER_SIZE + headerLength > bytes.length) {
+        fail('ERR_MESSAGE_FRAME_HEADER_LENGTH', 'binary frame header length is invalid');
+    }
+    const headerEnd = HILE_MESSAGE_FRAME_HEADER_SIZE + headerLength;
+    const envelope = parseJson(bytes.subarray(HILE_MESSAGE_FRAME_HEADER_SIZE, headerEnd).toString('utf8'));
+    validateBinaryEnvelope(envelope);
+    return {
+        ...envelope,
+        data: {
+            ...envelope.data,
+            payload: Buffer.from(bytes.subarray(headerEnd)),
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import { MessageModem, type MessageTransferFormat } from '@hile/message-modem';
 import type WebSocket from 'ws';
+export * from './codec.js';
 /**
  * 基于 `ws` 模块的 WebSocket 通信层。
  * exec 方法由子类实现，本类不做实现。
  *
  * 构造时传入已连接的 WebSocket 实例，自动绑定 message 事件。
- * 消息通过 JSON 序列化/反序列化传输。
+ * 普通消息通过 JSON 传输；二进制 stream response 使用 Hile 二进制帧，避免 Base64 开销。
  *
  * @example
  * class MyWs extends MessageWs {

package/dist/index.js

@@ -1,10 +1,12 @@
 import { MessageModem } from '@hile/message-modem';
+import { decodeMessageFrame, encodeMessageFrame } from './codec.js';
+export * from './codec.js';
 /**
  * 基于 `ws` 模块的 WebSocket 通信层。
  * exec 方法由子类实现，本类不做实现。
  *
  * 构造时传入已连接的 WebSocket 实例，自动绑定 message 事件。
- * 消息通过 JSON 序列化/反序列化传输。
+ * 普通消息通过 JSON 传输；二进制 stream response 使用 Hile 二进制帧，避免 Base64 开销。
  *
  * @example
  * class MyWs extends MessageWs {
@@ -26,12 +28,16 @@ export class MessageWs extends MessageModem {
     constructor(ws) {
         super();
         this.ws = ws;
-        this.listener = (raw) => {
+        this.listener = (raw, isBinary) => {
             try {
-                const msg = JSON.parse(raw.toString());
+                const msg = decodeMessageFrame(raw, isBinary);
                 this.receive(msg);
             }
-            catch { }
+            catch {
+                // A malformed protocol frame is fatal. Keeping the connection alive would
+                // hide peer incompatibility and can leave pending requests unresolved.
+                this.ws.close(1002, 'Invalid Hile message frame');
+            }
         };
         this.ws.on('message', this.listener);
     }
@@ -39,7 +45,7 @@ export class MessageWs extends MessageModem {
         if (this.ws.readyState !== this.ws.OPEN) {
             throw new Error('WebSocket is not open. Current readyState: ' + this.ws.readyState);
         }
-        this.ws.send(JSON.stringify(data));
+        this.ws.send(encodeMessageFrame(data));
     }
     /**
      * 移除消息监听，释放资源

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/message-ws",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -18,13 +18,14 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/node": "^26.2.0",
     "@types/ws": "^8.18.1",
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/message-modem": "^3.0.0",
+    "@hile/message-modem": "^4.0.0",
     "ws": "^8.21.0"
   },
-  "gitHead": "0985b6f8abc1f4de0a36324063585fdc3ac1375b"
+  "gitHead": "b46cb7f3705a226f58e4d65a2ff985ea54b9a159"
 }