stelar-time-real 3.3.0 → 3.3.2

package/src/websocket.ts

@@ -1,10 +1,9 @@
-/**
- * @stelar-time-real WebSocket (RFC 6455)
- */
+/** @stelar-time-real WebSocket (RFC 6455) + permessage-deflate (RFC 7692) */
 
 import { createHash, randomBytes } from 'crypto';
+import { deflateRawSync, inflateRawSync } from 'zlib';
 
-const WS_MAGIC = '258EAFA5-E914-47DA-95CA-5AB5A7E3A741';
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 export const DEFAULT_MAX_WS_FRAME_SIZE = 10 * 1024 * 1024;
 
 export const OP_CONTINUATION = 0x0, OP_TEXT = 0x1, OP_BINARY = 0x2,
@@ -23,21 +22,39 @@ export const computeAcceptKey = (key: string) => createHash('sha1').update(key +
 export const generateWSKey = () => randomBytes(16).toString('base64');
 export const validateWSKey = (key: string): boolean => typeof key === 'string' && Buffer.from(key, 'base64').length === 16;
 
-export function buildUpgradeResponse(key: string, headers?: Record<string, string>): string {
+export function buildUpgradeResponse(key: string, headers?: Record<string, string>, compress = false): string {
   const lines = ['HTTP/1.1 101 Switching Protocols', 'Upgrade: websocket', 'Connection: Upgrade', `Sec-WebSocket-Accept: ${computeAcceptKey(key)}`];
+  if (compress) lines.push('Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; client_no_context_takeover');
   if (headers) for (const [k, v] of Object.entries(headers)) lines.push(`${k}: ${v}`);
   lines.push('', '');
   return lines.join('\r\n');
 }
 
-export interface WSFrame { fin: boolean; opcode: number; payload: Buffer; masked: boolean; }
+/** Parse client's Sec-WebSocket-Extensions header to check for permessage-deflate */
+export function clientWantsCompression(extensionsHeader: string | undefined): boolean {
+  if (!extensionsHeader) return false;
+  return /permessage-deflate/.test(extensionsHeader);
+}
+
+export interface WSFrame { fin: boolean; opcode: number; payload: Buffer; masked: boolean; rsv1: boolean; }
+
+const TAIL = Buffer.from([0x00, 0x00, 0xFF, 0xFF]);
+
+export function wsCompress(data: Buffer): Buffer {
+  const deflated = deflateRawSync(data);
+  return deflated.subarray(0, deflated.length - 4);
+}
+
+export function wsDecompress(data: Buffer): Buffer {
+  return inflateRawSync(Buffer.concat([data, TAIL]));
+}
 
 export function parseWSFrame(buf: Buffer, max = DEFAULT_MAX_WS_FRAME_SIZE): { frame: WSFrame; consumed: number } | null {
   if (buf.length < 2) return null;
   const b0 = buf[0], b1 = buf[1];
-  const fin = !!(b0 & 0x80), rsv = b0 & 0x70, opcode = b0 & 0x0F, masked = !!(b1 & 0x80);
+  const fin = !!(b0 & 0x80), rsv1 = !!(b0 & 0x40), rsv = b0 & 0x30, opcode = b0 & 0x0F, masked = !!(b1 & 0x80);
   let len = b1 & 0x7F, off = 2;
-  if (rsv) throw new WebSocketError('RSV bits set', CLOSE_PROTOCOL_ERROR);
+  if (rsv) throw new WebSocketError('RSV2/RSV3 bits set', CLOSE_PROTOCOL_ERROR);
   if (len === 126) { if (buf.length < 4) return null; len = buf.readUInt16BE(2); off = 4; }
   else if (len === 127) { if (buf.length < 10) return null; len = buf.readUInt32BE(2) * 0x100000000 + buf.readUInt32BE(6); off = 10; }
   if (len > max) throw new WebSocketError(`Frame exceeds max (${max})`, CLOSE_MESSAGE_TOO_BIG);
@@ -46,31 +63,34 @@ export function parseWSFrame(buf: Buffer, max = DEFAULT_MAX_WS_FRAME_SIZE): { fr
   if (buf.length < off + len) return null;
   const payload = Buffer.from(buf.subarray(off, off + len));
   if (masked && mk) for (let i = 0; i < len; i++) payload[i] ^= mk[i & 3];
-  return { frame: { fin, opcode, payload, masked }, consumed: off + len };
+  return { frame: { fin, opcode, payload, masked, rsv1 }, consumed: off + len };
 }
 
-export function createWSFrame(opcode: number, payload: Buffer | string, masked = false): Buffer {
+export function createWSFrame(opcode: number, payload: Buffer | string, masked = false, compress = false): Buffer {
   const d = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
+  const compressed = compress && (opcode === OP_TEXT || opcode === OP_BINARY) ? wsCompress(d) : d;
+  const actualOpcode = compressed !== d ? opcode : opcode;
   const mk = masked ? randomBytes(4) : undefined;
   const base = masked ? 0x80 : 0;
+  const rsv1Bit = (compress && (opcode === OP_TEXT || opcode === OP_BINARY) && compressed !== d) ? 0x40 : 0;
   let h: Buffer;
-  if (d.length < 126) {
-    h = Buffer.alloc(masked ? 6 : 2); h[0] = 0x80 | opcode; h[1] = base | d.length;
+  if (compressed.length < 126) {
+    h = Buffer.alloc(masked ? 6 : 2); h[0] = 0x80 | rsv1Bit | actualOpcode; h[1] = base | compressed.length;
     if (mk) mk.copy(h, 2);
-  } else if (d.length < 65536) {
-    h = Buffer.alloc(masked ? 8 : 4); h[0] = 0x80 | opcode; h[1] = base | 126;
-    h.writeUInt16BE(d.length, 2); if (mk) mk.copy(h, 4);
+  } else if (compressed.length < 65536) {
+    h = Buffer.alloc(masked ? 8 : 4); h[0] = 0x80 | rsv1Bit | actualOpcode; h[1] = base | 126;
+    h.writeUInt16BE(compressed.length, 2); if (mk) mk.copy(h, 4);
   } else {
-    h = Buffer.alloc(masked ? 14 : 10); h[0] = 0x80 | opcode; h[1] = base | 127;
-    h.writeUInt32BE(Math.floor(d.length / 0x100000000), 2);
-    h.writeUInt32BE(d.length & 0xFFFFFFFF, 6); if (mk) mk.copy(h, 10);
+    h = Buffer.alloc(masked ? 14 : 10); h[0] = 0x80 | rsv1Bit | actualOpcode; h[1] = base | 127;
+    h.writeUInt32BE(Math.floor(compressed.length / 0x100000000), 2);
+    h.writeUInt32BE(compressed.length & 0xFFFFFFFF, 6); if (mk) mk.copy(h, 10);
   }
-  if (mk) for (let i = 0; i < d.length; i++) d[i] ^= mk[i & 3];
-  return Buffer.concat([h, d]);
+  if (mk) for (let i = 0; i < compressed.length; i++) compressed[i] ^= mk[i & 3];
+  return Buffer.concat([h, compressed]);
 }
 
 /* Server (unmasked) */
-export const createWSTextFrame = (msg: string) => createWSFrame(OP_TEXT, msg);
+export const createWSTextFrame = (msg: string, compress = false) => createWSFrame(OP_TEXT, msg, false, compress);
 export const createWSBinaryFrame = (data: Buffer) => createWSFrame(OP_BINARY, data);
 export const createWSCloseFrame = (code = CLOSE_NORMAL, reason = '') => {
   const b = Buffer.alloc(2 + Buffer.byteLength(reason)); b.writeUInt16BE(code, 0); if (reason) b.write(reason, 2, 'utf8'); return createWSFrame(OP_CLOSE, b);
@@ -79,7 +99,7 @@ export const createWSPingFrame = (data?: Buffer) => createWSFrame(OP_PING, data
 export const createWSPongFrame = (data?: Buffer) => createWSFrame(OP_PONG, data || Buffer.alloc(0));
 
 /* Client (masked) */
-export const createWSTextFrameMasked = (msg: string) => createWSFrame(OP_TEXT, msg, true);
+export const createWSTextFrameMasked = (msg: string, compress = false) => createWSFrame(OP_TEXT, msg, true, compress);
 export const createWSBinaryFrameMasked = (data: Buffer) => createWSFrame(OP_BINARY, data, true);
 export const createWSCloseFrameMasked = (code = CLOSE_NORMAL, reason = '') => {
   const b = Buffer.alloc(2 + Buffer.byteLength(reason)); b.writeUInt16BE(code, 0); if (reason) b.write(reason, 2, 'utf8'); return createWSFrame(OP_CLOSE, b, true);
@@ -87,29 +107,47 @@ export const createWSCloseFrameMasked = (code = CLOSE_NORMAL, reason = '') => {
 export const createWSPingFrameMasked = () => createWSFrame(OP_PING, Buffer.alloc(0), true);
 export const createWSPongFrameMasked = () => createWSFrame(OP_PONG, Buffer.alloc(0), true);
 
+/** Streaming WS frame parser — O(1) append, avoids Buffer.concat O(n²) */
 export class WSFrameParser {
-  private buf = Buffer.alloc(0);
+  private chunks: Buffer[] = [];
+  private len = 0;
   private max: number;
   private received = 0;
 
   constructor(max = DEFAULT_MAX_WS_FRAME_SIZE) { this.max = max; }
 
+  private _compact(): Buffer {
+    if (this.chunks.length <= 1) return this.chunks[0] || Buffer.alloc(0);
+    const buf = Buffer.concat(this.chunks);
+    this.chunks = [buf];
+    return buf;
+  }
+
   feed(data: Buffer): WSFrame[] {
     this.received += data.length;
-    this.buf = Buffer.concat([this.buf, data]);
-    if (this.buf.length > this.max * 2) { this.buf = Buffer.alloc(0); throw new WebSocketError('Buffer overflow', CLOSE_POLICY_VIOLATION); }
+    this.chunks.push(data);
+    this.len += data.length;
+    if (this.len > this.max * 2) { this.chunks = []; this.len = 0; throw new WebSocketError('Buffer overflow', CLOSE_POLICY_VIOLATION); }
     const frames: WSFrame[] = [];
-    while (this.buf.length > 0) {
+    while (this.len > 0) {
+      const buf = this._compact();
       try {
-        const r = parseWSFrame(this.buf, this.max);
+        const r = parseWSFrame(buf, this.max);
         if (!r) break;
-        this.buf = r.consumed < this.buf.length ? Buffer.from(this.buf.subarray(r.consumed)) : Buffer.alloc(0);
-        if (r.frame.opcode !== OP_CONTINUATION) frames.push(r.frame);
-      } catch (e) { this.buf = Buffer.alloc(0); throw e; }
+        const consumed = r.consumed;
+        if (consumed < buf.length) { this.chunks = [Buffer.from(buf.subarray(consumed))]; this.len = this.chunks[0].length; }
+        else { this.chunks = []; this.len = 0; }
+        if (r.frame.opcode !== OP_CONTINUATION) {
+          if (r.frame.rsv1 && (r.frame.opcode === OP_TEXT || r.frame.opcode === OP_BINARY)) {
+            try { r.frame.payload = wsDecompress(r.frame.payload); r.frame.rsv1 = false; } catch { throw new WebSocketError('Decompression failed', CLOSE_INVALID_PAYLOAD); }
+          }
+          frames.push(r.frame);
+        }
+      } catch (e) { this.chunks = []; this.len = 0; throw e; }
     }
     return frames;
   }
 
-  reset() { this.buf = Buffer.alloc(0); this.received = 0; }
+  reset() { this.chunks = []; this.len = 0; this.received = 0; }
   getBytesReceived() { return this.received; }
 }