@orkestrel/websocket 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @orkestrel/websocket
+
+A dependency-light RFC 6455 WebSocket for Node — native handshake and framing
+over duplex streams, with a typed emitter surface. Part of the `@orkestrel`
+line. Its sole runtime dependency is `@orkestrel/emitter`, used for the typed
+`emitter` every connection exposes.
+
+## Install
+
+```sh
+npm install @orkestrel/websocket
+```
+
+## Requirements
+
+- Node.js >= 24
+- Ships dual ESM + CommonJS builds (see `exports` in `package.json`)
+- Server-only — a single Node-native surface
+
+## Usage
+
+```ts
+import { createServer } from 'node:http'
+import { createNodeWebSocket } from '@orkestrel/websocket'
+
+// A node:http server hands every upgrade request a raw socket; this wrapper takes it
+// from there. Passing the client's `sec-websocket-key` selects SERVER mode — the
+// wrapper writes the 101 handshake, marks the connection open, and decodes frames.
+createServer().on('upgrade', (request, socket, head) => {
+	const ws = createNodeWebSocket({
+		socket,
+		key: request.headers['sec-websocket-key'], // present => server mode + 101 handshake
+		head, // any bytes that arrived bundled with the upgrade request
+		on: { message: (text) => ws.send(`echo: ${text}`) }, // wire listeners at construction
+	})
+
+	ws.emitter.on('close', (code, reason) => console.log('closed', code, reason))
+})
+```
+
+## Guide
+
+The full API — factories, the `NodeWebSocket` class, the pure codec helpers,
+constants, and types — is documented in
+[`guides/src/websocket.md`](https://github.com/orkestrel/websocket/blob/main/guides/src/websocket.md).
+
+## Package
+
+Published as a single Node-only surface per the `exports` field in
+`package.json` — one `.` entry backed by dual ESM (`.js`) and CommonJS
+(`.cjs`) builds of `src/server`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

package/dist/src/server/index.cjs

@@ -0,0 +1,608 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_crypto = require("node:crypto");
+let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/server/constants.ts
+/**
+* The RFC 6455 GUID concatenated to a client's `Sec-WebSocket-Key` before the SHA-1
+* hash that yields the `Sec-WebSocket-Accept` response value.
+*
+* @remarks
+* A fixed, spec-mandated constant (RFC 6455 §4.2.2) — read only by
+* {@link computeWebSocketAccept}.
+*/
+var WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+/** The WebSocket protocol version this wrapper speaks (`Sec-WebSocket-Version: 13`). */
+var WEBSOCKET_VERSION = "13";
+/** Text frame opcode — a UTF-8 payload (RFC 6455 §5.6). */
+var WEBSOCKET_OPCODE_TEXT = 1;
+/** Binary frame opcode — a raw byte payload (RFC 6455 §5.6). */
+var WEBSOCKET_OPCODE_BINARY = 2;
+/** Close frame opcode — a control frame ending the connection (RFC 6455 §5.5.1). */
+var WEBSOCKET_OPCODE_CLOSE = 8;
+/** Ping frame opcode — a control frame the peer must answer with a pong (RFC 6455 §5.5.2). */
+var WEBSOCKET_OPCODE_PING = 9;
+/** Pong frame opcode — a control frame answering a ping (RFC 6455 §5.5.3). */
+var WEBSOCKET_OPCODE_PONG = 10;
+/** Ready state for a connecting WebSocket (before the handshake completes). */
+var WEBSOCKET_READY_CONNECTING = 0;
+/** Ready state for an open WebSocket (the handshake completed; frames flow). */
+var WEBSOCKET_READY_OPEN = 1;
+/** Ready state for a closing WebSocket (a close frame was sent or received). */
+var WEBSOCKET_READY_CLOSING = 2;
+/** Ready state for a closed WebSocket (the socket ended). */
+var WEBSOCKET_READY_CLOSED = 3;
+/** Normal-closure status code (RFC 6455 §7.4.1) — the default `close` code. */
+var WEBSOCKET_CLOSE_NORMAL = 1e3;
+/** Protocol-error status code (RFC 6455 §7.4.1) — a framing/state rule was violated. */
+var WEBSOCKET_CLOSE_PROTOCOL = 1002;
+/** Unsupported-data status code (RFC 6455 §7.4.1) — the endpoint received a data type it cannot accept (e.g. binary on a text-only endpoint). */
+var WEBSOCKET_CLOSE_UNSUPPORTED = 1003;
+/** Invalid-frame-payload-data status code (RFC 6455 §7.4.1) — e.g. non-UTF-8 text or an unparseable close reason. */
+var WEBSOCKET_CLOSE_INVALID = 1007;
+/** Message-too-big status code (RFC 6455 §7.4.1) — a reassembled message exceeded the payload cap. */
+var WEBSOCKET_CLOSE_TOOBIG = 1009;
+/** The default maximum inbound single-frame length AND reassembled-message total byte count (100 MiB — the `ws` package default). */
+var WEBSOCKET_MAX_PAYLOAD = 104857600;
+/** The default close-handshake timeout in milliseconds — how long `close()` waits for the peer's echo before tearing the socket down. */
+var WEBSOCKET_CLOSE_TIMEOUT_MS = 3e4;
+/** The post-`#fail` flush grace in milliseconds — how long a validation-breach close frame is given to flush through the socket's write buffer before the hard `destroy()` fallback fires (the normal path destroys sooner, on the `end()` flush callback). */
+var WEBSOCKET_FAIL_TIMEOUT_MS = 1e3;
+/** The maximum control-frame payload length in bytes (RFC 6455 §5.5). */
+var WEBSOCKET_CONTROL_MAXLEN = 125;
+//#endregion
+//#region src/server/helpers.ts
+/**
+* Compute the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
+*
+* @remarks
+* The base64-encoded SHA-1 of the client's `Sec-WebSocket-Key` concatenated with the
+* fixed {@link WEBSOCKET_GUID} (RFC 6455 §4.2.2) — the proof the server understood the
+* handshake. Pure and deterministic.
+*
+* @param key - The client's `Sec-WebSocket-Key` header value
+* @returns The base64 accept token to send back as `Sec-WebSocket-Accept`
+*/
+function computeWebSocketAccept(key) {
+	return (0, node_crypto.createHash)("sha1").update(key + WEBSOCKET_GUID).digest("base64");
+}
+/**
+* Decode a single RFC 6455 frame from the front of a buffer.
+*
+* @remarks
+* Reads the FIN bit and opcode (byte 0), the mask bit and 7-bit payload length (byte
+* 1) — extended to a 16-bit length when the 7-bit field is `126`, or a 64-bit length
+* when it is `127` — the optional 4-byte mask key, then the payload, XOR-unmasking it
+* against the key when the mask bit is set (client→server frames MUST be masked, RFC
+* 6455 §5.3; an unmasked frame still decodes, leaving the payload as-is, so the caller
+* can enforce policy). Returns `undefined` the moment the buffer is too short for the
+* part it is up to (the length prefix, the mask, or the full payload) — the signal to
+* the caller to read more bytes and retry, exactly like {@link SSEParser} on a partial
+* line. `consumed` is the total bytes the frame occupied, so the caller slices the
+* remainder. Pure; never throws on a short buffer.
+*
+* @param buffer - The accumulation buffer to decode the next frame from
+* @returns The parsed {@link WebSocketFrame}, or `undefined` when the buffer is incomplete
+*/
+function parseWebSocketFrame(buffer) {
+	if (buffer.length < 2) return void 0;
+	const firstByte = buffer[0] ?? 0;
+	const secondByte = buffer[1] ?? 0;
+	const fin = (firstByte & 128) !== 0;
+	const rsv = (firstByte & 112) >> 4;
+	const opcode = firstByte & 15;
+	const masked = (secondByte & 128) !== 0;
+	let length = secondByte & 127;
+	let offset = 2;
+	if (length === 126) {
+		if (buffer.length < offset + 2) return void 0;
+		length = buffer.readUInt16BE(offset);
+		offset += 2;
+	} else if (length === 127) {
+		if (buffer.length < offset + 8) return void 0;
+		const high = buffer.readUInt32BE(offset);
+		const low = buffer.readUInt32BE(offset + 4);
+		length = high * 4294967296 + low;
+		offset += 8;
+	}
+	let mask;
+	if (masked) {
+		if (buffer.length < offset + 4) return void 0;
+		mask = buffer.subarray(offset, offset + 4);
+		offset += 4;
+	}
+	if (buffer.length < offset + length) return void 0;
+	const payload = Buffer.alloc(length);
+	buffer.copy(payload, 0, offset, offset + length);
+	if (mask !== void 0) for (let index = 0; index < length; index += 1) payload[index] = (payload[index] ?? 0) ^ (mask[index % 4] ?? 0);
+	return {
+		fin,
+		opcode,
+		payload,
+		consumed: offset + length,
+		masked,
+		rsv
+	};
+}
+/**
+* Read the declared payload length off the front of a buffer, without buffering or
+* reading the payload itself.
+*
+* @remarks
+* Decodes only byte 1's 7-bit length field, extended by the 16-bit (`126`) or 64-bit
+* (`127`) form exactly like {@link parseWebSocketFrame} — but stops there, so a caller
+* can reject an over-cap frame the moment its length is known, before the payload
+* bytes have even arrived. Returns `undefined` until the length field itself is fully
+* buffered (mirrors the parser's incomplete-buffer contract). Pure; never throws.
+*
+* @param buffer - The accumulation buffer to read the next frame's length from
+* @returns The declared payload length, or `undefined` when the buffer is too short to know it yet
+*
+* @example
+* ```ts
+* const declared = measureWebSocketFrame(buffer)
+* if (declared !== undefined && declared > limit) fail(WEBSOCKET_CLOSE_TOOBIG)
+* ```
+*/
+function measureWebSocketFrame(buffer) {
+	if (buffer.length < 2) return void 0;
+	let length = (buffer[1] ?? 0) & 127;
+	const offset = 2;
+	if (length === 126) {
+		if (buffer.length < 4) return void 0;
+		length = buffer.readUInt16BE(offset);
+	} else if (length === 127) {
+		if (buffer.length < 10) return void 0;
+		const high = buffer.readUInt32BE(offset);
+		const low = buffer.readUInt32BE(6);
+		length = high * 4294967296 + low;
+	}
+	return length;
+}
+/**
+* Decode a byte sequence as strict UTF-8, or signal it is malformed.
+*
+* @remarks
+* Wraps `TextDecoder('utf-8', { fatal: true })` in a try/catch so a malformed sequence
+* returns `undefined` instead of throwing (AGENTS §14 — a guard-adjacent coercer never
+* throws on bad input). Pure.
+*
+* @param bytes - The raw bytes to decode
+* @returns The decoded string, or `undefined` when `bytes` is not valid UTF-8
+*
+* @example
+* ```ts
+* const text = parseUTF8(payload)
+* if (text === undefined) fail(WEBSOCKET_CLOSE_INVALID)
+* ```
+*/
+function parseUTF8(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+}
+/**
+* Whether a numeric value is a valid RFC 6455 close status code to RECEIVE (§7.4.1).
+*
+* @remarks
+* True for `1000`–`1003`, `1007`–`1014`, and the application range `3000`–`4999`; false
+* for anything below `1000`, the reserved-for-local-use-only codes `1004`–`1006` and
+* `1015`, and the unassigned `1016`–`2999` range. The `1012`–`1014` extension of the
+* strict RFC 6455 receivable set is a deliberate IANA-interop choice: those three codes
+* (Service Restart, Try Again Later, Bad Gateway) are IANA-registered in the WebSocket
+* Close Code Number Registry and accepted by the `ws` ecosystem and modern conformance
+* suites, so a peer sending one is not treated as a protocol violation. Pure predicate,
+* never throws.
+*
+* @param code - The close status code to validate
+* @returns `true` when `code` is a valid RFC 6455 close code
+*
+* @example
+* ```ts
+* if (!isCloseCode(code)) fail(WEBSOCKET_CLOSE_PROTOCOL)
+* ```
+*/
+function isCloseCode(code) {
+	if (code >= 1e3 && code <= 1003) return true;
+	if (code >= 1007 && code <= 1014) return true;
+	if (code >= 3e3 && code <= 4999) return true;
+	return false;
+}
+/**
+* Encode a single RFC 6455 frame to its wire bytes — the inverse of
+* {@link parseWebSocketFrame}.
+*
+* @remarks
+* Builds a final (FIN-set) frame: byte 0 is `0x80 | opcode`; the payload length uses
+* the 7-bit form below 126, the `126` + 16-bit form below 65 536, or the `127` +
+* 64-bit form beyond; when `masked` is set the mask bit is set, a 4-byte key (supplied
+* via `options.mask`, else random) is written, and the payload is XOR-masked. Server→
+* client frames are unmasked (the default); pass `masked: true` to encode a CLIENT
+* frame (e.g. to feed the parser in a test). A `string` payload is encoded as UTF-8.
+* Returns one contiguous `Buffer` (header + payload), so the wrapper writes it with a
+* single `socket.write`. Pure.
+*
+* @param opcode - The frame opcode (a `WEBSOCKET_OPCODE_*` value)
+* @param payload - The payload, a `Buffer` or a UTF-8 `string`
+* @param options - Masking control ({@link WebSocketEncodeOptions}); defaults to unmasked
+* @returns The complete frame as wire bytes
+*/
+function encodeWebSocketFrame(opcode, payload, options) {
+	const body = typeof payload === "string" ? Buffer.from(payload, "utf-8") : payload;
+	const length = body.length;
+	const masked = options?.masked === true;
+	const mask = masked ? options?.mask ?? (0, node_crypto.randomBytes)(4) : void 0;
+	const maskBit = masked ? 128 : 0;
+	const extended = length < 126 ? 0 : length < 65536 ? 2 : 8;
+	const header = Buffer.alloc(2 + extended + (mask !== void 0 ? 4 : 0));
+	header[0] = 128 | opcode;
+	if (length < 126) header[1] = maskBit | length;
+	else if (length < 65536) {
+		header[1] = maskBit | 126;
+		header.writeUInt16BE(length, 2);
+	} else {
+		header[1] = maskBit | 127;
+		header.writeUInt32BE(Math.floor(length / 4294967296), 2);
+		header.writeUInt32BE(length % 4294967296, 6);
+	}
+	if (mask === void 0) return Buffer.concat([header, body]);
+	mask.copy(header, header.length - 4);
+	const maskedBody = Buffer.alloc(length);
+	for (let index = 0; index < length; index += 1) maskedBody[index] = (body[index] ?? 0) ^ (mask[index % 4] ?? 0);
+	return Buffer.concat([header, maskedBody]);
+}
+//#endregion
+//#region src/server/NodeWebSocket.ts
+/**
+* A server-native WebSocket over a raw upgraded `node:stream` Duplex — the lean
+* wrapper around the RFC 6455 wire protocol.
+*
+* @remarks
+* Created by `createNodeWebSocket`. When given a client `key` it runs in SERVER mode —
+* it writes the `101 Switching Protocols` handshake (`computeWebSocketAccept(key)`) and
+* emits `open`; given no key it runs in CLIENT mode (no handshake, frames masked). It
+* then listens on the socket's `data`, accumulating bytes in `#buffer` and decoding
+* every complete frame with {@link parseWebSocketFrame} (slicing `consumed` and
+* re-parsing the remainder): a TEXT frame — reassembling continuation fragments across
+* `fin: false` frames — decodes to UTF-8 and emits `message`; a PING is auto-answered
+* with a PONG and emits `ping`; a PONG emits `pong`; a CLOSE is echoed and ends the
+* socket, emitting `close`. `send` writes a text frame, `ping` a ping, `close` a close
+* frame; `destroy` tears down immediately. It owns a typed `#emitter` (AGENTS §13) that
+* isolates a throwing listener and routes the error to its own `error` handler (the `error`
+* option) — the socket never crashes. The untyped socket `data` is narrowed to a `Buffer`
+* with a guard, never an assertion (AGENTS §14).
+*/
+var NodeWebSocket = class {
+	#emitter;
+	#socket;
+	#protocol;
+	#masked;
+	#payload;
+	#timeout;
+	#requireMask;
+	#signal;
+	#buffer = Buffer.alloc(0);
+	#readyState = 0;
+	#code = void 0;
+	#reason = void 0;
+	#fragments = [];
+	#messageOpcode = void 0;
+	#fragmentBytes = 0;
+	#closeTimer = void 0;
+	#destroyed = false;
+	#onData = (chunk) => {
+		if (this.#readyState === 3) return;
+		const bytes = this.#bytes(chunk);
+		if (bytes === void 0) return;
+		this.#ingest(bytes);
+	};
+	#onClose = () => {
+		this.#finish();
+	};
+	#onError = (error) => {
+		this.#emitter.emit("error", error);
+	};
+	#onAbort = () => {
+		this.destroy();
+	};
+	constructor(options) {
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			on: options.on,
+			error: options.error
+		});
+		this.#socket = options.socket;
+		this.#protocol = options.protocol;
+		this.#masked = options.key === void 0;
+		this.#payload = options.payload ?? 104857600;
+		this.#timeout = options.timeout ?? 3e4;
+		this.#requireMask = !this.#masked;
+		this.#signal = options.signal;
+		if (options.key !== void 0) {
+			const protocol = this.#protocol === void 0 ? "" : `Sec-WebSocket-Protocol: ${this.#protocol}\r\n`;
+			this.#socket.write(`HTTP/1.1 101 Switching Protocols\r
+Upgrade: websocket\r
+Connection: Upgrade\r
+Sec-WebSocket-Accept: ${computeWebSocketAccept(options.key)}\r\n` + protocol + "\r\n");
+		}
+		this.#readyState = 1;
+		this.#socket.on("data", this.#onData);
+		this.#socket.on("close", this.#onClose);
+		this.#socket.on("error", this.#onError);
+		this.#emitter.emit("open");
+		const head = options.head;
+		if (head !== void 0 && head.length > 0) this.#ingest(head);
+		if (this.#readyState !== 3) if (this.#signal?.aborted === true) this.destroy();
+		else this.#signal?.addEventListener("abort", this.#onAbort, { once: true });
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get readyState() {
+		return this.#readyState;
+	}
+	send(data) {
+		if (this.#readyState !== 1) return;
+		this.#write(1, Buffer.from(data, "utf-8"));
+	}
+	ping(data) {
+		if (this.#readyState !== 1) return;
+		if (data !== void 0 && Buffer.byteLength(data, "utf-8") > 125) throw new RangeError("ping payload exceeds 125 bytes");
+		this.#write(9, data === void 0 ? Buffer.alloc(0) : Buffer.from(data, "utf-8"));
+	}
+	close(code, reason) {
+		if (this.#readyState === 2 || this.#readyState === 3) return;
+		if (code !== void 0 && !isCloseCode(code)) throw new RangeError("invalid close code");
+		if (reason !== void 0 && Buffer.byteLength(reason, "utf-8") > 123) throw new RangeError("close reason exceeds 123 bytes");
+		this.#readyState = 2;
+		this.#code = code ?? 1e3;
+		this.#reason = reason === void 0 || reason.length === 0 ? void 0 : reason;
+		this.#write(8, this.#encodeClose(this.#code, this.#reason));
+		this.#socket.end();
+		this.#closeTimer = setTimeout(() => this.destroy(), this.#timeout);
+		this.#closeTimer.unref();
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#socket.off("data", this.#onData);
+		this.#socket.off("close", this.#onClose);
+		this.#socket.off("error", this.#onError);
+		this.#signal?.removeEventListener("abort", this.#onAbort);
+		clearTimeout(this.#closeTimer);
+		this.#closeTimer = void 0;
+		if (!this.#socket.destroyed) this.#socket.destroy();
+		this.#finish();
+		this.#emitter.destroy();
+	}
+	#drain() {
+		for (;;) {
+			const frame = parseWebSocketFrame(this.#buffer);
+			if (frame === void 0) return;
+			this.#buffer = this.#buffer.subarray(frame.consumed);
+			this.#dispatch(frame.fin, frame.opcode, frame.payload, frame.masked, frame.rsv);
+			if (this.#readyState === 3) return;
+		}
+	}
+	#dispatch(fin, opcode, payload, masked, rsv) {
+		if (rsv !== 0) {
+			this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+			return;
+		}
+		if (masked !== this.#requireMask) {
+			this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+			return;
+		}
+		if (opcode === 8 || opcode === 9 || opcode === 10) {
+			if (!fin || payload.length > 125) {
+				this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+				return;
+			}
+			if (opcode === 9) {
+				this.#write(10, payload);
+				this.#emitter.emit("ping");
+				return;
+			}
+			if (opcode === 10) {
+				this.#emitter.emit("pong");
+				return;
+			}
+			this.#close(payload);
+			return;
+		}
+		if (opcode === 1 || opcode === 2) {
+			if (this.#messageOpcode !== void 0) {
+				this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+				return;
+			}
+			this.#messageOpcode = opcode;
+		} else if (opcode === 0) {
+			if (this.#messageOpcode === void 0) {
+				this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+				return;
+			}
+		} else {
+			this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+			return;
+		}
+		this.#fragments.push(payload);
+		this.#fragmentBytes += payload.length;
+		if (this.#fragmentBytes > this.#payload) {
+			this.#fail(WEBSOCKET_CLOSE_TOOBIG);
+			return;
+		}
+		if (!fin) return;
+		if (this.#messageOpcode === 2) {
+			this.#fail(WEBSOCKET_CLOSE_UNSUPPORTED);
+			return;
+		}
+		const text = parseUTF8(Buffer.concat(this.#fragments));
+		if (text === void 0) {
+			this.#fail(WEBSOCKET_CLOSE_INVALID);
+			return;
+		}
+		this.#emitter.emit("message", text);
+		this.#messageOpcode = void 0;
+		this.#fragments = [];
+		this.#fragmentBytes = 0;
+	}
+	#close(payload) {
+		if (!this.#decodeClose(payload)) return;
+		if (this.#readyState === 1) {
+			this.#readyState = 2;
+			this.#write(8, payload);
+		}
+		this.#socket.end();
+		this.#socket.off("data", this.#onData);
+		this.#socket.off("close", this.#onClose);
+		this.#socket.off("error", this.#onError);
+		this.#finish();
+	}
+	#fail(code, reason) {
+		if (this.#readyState === 2 || this.#readyState === 3) return;
+		this.#code = code;
+		this.#reason = reason;
+		this.#readyState = 2;
+		this.#socket.off("data", this.#onData);
+		this.#socket.off("close", this.#onClose);
+		this.#socket.off("error", this.#onError);
+		this.#write(8, this.#encodeClose(code, reason));
+		this.#socket.end(() => {
+			if (!this.#socket.destroyed) this.#socket.destroy();
+			clearTimeout(this.#closeTimer);
+			this.#closeTimer = void 0;
+		});
+		this.#messageOpcode = void 0;
+		this.#fragments = [];
+		this.#fragmentBytes = 0;
+		this.#finish();
+		this.#closeTimer = setTimeout(() => {
+			if (!this.#socket.destroyed) this.#socket.destroy();
+		}, WEBSOCKET_FAIL_TIMEOUT_MS);
+		this.#closeTimer.unref();
+	}
+	#write(opcode, payload) {
+		if (this.#socket.destroyed) return;
+		this.#socket.write(encodeWebSocketFrame(opcode, payload, { masked: this.#masked }));
+	}
+	#encodeClose(code, reason) {
+		if (code === void 0) return Buffer.alloc(0);
+		const text = reason === void 0 ? Buffer.alloc(0) : Buffer.from(reason, "utf-8");
+		const payload = Buffer.alloc(2 + text.length);
+		payload.writeUInt16BE(code, 0);
+		text.copy(payload, 2);
+		return payload;
+	}
+	#decodeClose(payload) {
+		if (payload.length === 0) {
+			this.#code = void 0;
+			this.#reason = void 0;
+			return true;
+		}
+		if (payload.length === 1) {
+			this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+			return false;
+		}
+		const code = payload.readUInt16BE(0);
+		if (!isCloseCode(code)) {
+			this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
+			return false;
+		}
+		const reason = payload.length > 2 ? parseUTF8(payload.subarray(2)) : "";
+		if (reason === void 0) {
+			this.#fail(WEBSOCKET_CLOSE_INVALID);
+			return false;
+		}
+		this.#code = code;
+		this.#reason = reason.length === 0 ? void 0 : reason;
+		return true;
+	}
+	#finish() {
+		if (this.#readyState === 3) return;
+		clearTimeout(this.#closeTimer);
+		this.#closeTimer = void 0;
+		this.#signal?.removeEventListener("abort", this.#onAbort);
+		this.#readyState = 3;
+		this.#emitter.emit("close", this.#code, this.#reason);
+	}
+	#ingest(bytes) {
+		this.#buffer = Buffer.concat([this.#buffer, bytes]);
+		const declared = measureWebSocketFrame(this.#buffer);
+		if (declared !== void 0 && declared > this.#payload) {
+			this.#fail(WEBSOCKET_CLOSE_TOOBIG);
+			return;
+		}
+		this.#drain();
+	}
+	#bytes(chunk) {
+		if (Buffer.isBuffer(chunk)) return chunk;
+		if (typeof chunk === "string") return Buffer.from(chunk, "utf-8");
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* Create a server-native WebSocket over a raw upgraded `node:stream` Duplex socket.
+*
+* @remarks
+* The construction entry point for the {@link NodeWebSocketInterface} (AGENTS §8). Pass
+* the upgraded `socket` plus the client's `Sec-WebSocket-Key` as `key` to run in SERVER
+* mode — the wrapper writes the `101 Switching Protocols` handshake and sends unmasked
+* frames; omit `key` for CLIENT mode (no handshake, masked frames). This is the
+* lean-native handle; it speaks only the WebSocket wire protocol — an MCP transport (the
+* later chunk) is built ON it. It is the WebSocket counterpart to
+* `createSQLiteDatabase` / `createIndexedDBDatabase`.
+*
+* @param options - The {@link NodeWebSocketOptions} (`socket`, optional `key` / `head` /
+*   `protocol` / `on`)
+* @returns A typed {@link NodeWebSocketInterface}
+*
+* @example
+* ```ts
+* import { createNodeWebSocket } from '@src/server'
+*
+* // In a node:http 'upgrade' handler — server mode, identified by the client key:
+* server.on('upgrade', (request, socket, head) => {
+* 	const ws = createNodeWebSocket({
+* 		socket,
+* 		key: request.headers['sec-websocket-key'],
+* 		head,
+* 		on: { message: (text) => ws.send(`echo: ${text}`) },
+* 	})
+* })
+* ```
+*/
+function createNodeWebSocket(options) {
+	return new NodeWebSocket(options);
+}
+//#endregion
+exports.NodeWebSocket = NodeWebSocket;
+exports.WEBSOCKET_CLOSE_INVALID = WEBSOCKET_CLOSE_INVALID;
+exports.WEBSOCKET_CLOSE_NORMAL = WEBSOCKET_CLOSE_NORMAL;
+exports.WEBSOCKET_CLOSE_PROTOCOL = WEBSOCKET_CLOSE_PROTOCOL;
+exports.WEBSOCKET_CLOSE_TIMEOUT_MS = WEBSOCKET_CLOSE_TIMEOUT_MS;
+exports.WEBSOCKET_CLOSE_TOOBIG = WEBSOCKET_CLOSE_TOOBIG;
+exports.WEBSOCKET_CLOSE_UNSUPPORTED = WEBSOCKET_CLOSE_UNSUPPORTED;
+exports.WEBSOCKET_CONTROL_MAXLEN = WEBSOCKET_CONTROL_MAXLEN;
+exports.WEBSOCKET_FAIL_TIMEOUT_MS = WEBSOCKET_FAIL_TIMEOUT_MS;
+exports.WEBSOCKET_GUID = WEBSOCKET_GUID;
+exports.WEBSOCKET_MAX_PAYLOAD = WEBSOCKET_MAX_PAYLOAD;
+exports.WEBSOCKET_OPCODE_BINARY = WEBSOCKET_OPCODE_BINARY;
+exports.WEBSOCKET_OPCODE_CLOSE = WEBSOCKET_OPCODE_CLOSE;
+exports.WEBSOCKET_OPCODE_PING = WEBSOCKET_OPCODE_PING;
+exports.WEBSOCKET_OPCODE_PONG = WEBSOCKET_OPCODE_PONG;
+exports.WEBSOCKET_OPCODE_TEXT = WEBSOCKET_OPCODE_TEXT;
+exports.WEBSOCKET_READY_CLOSED = WEBSOCKET_READY_CLOSED;
+exports.WEBSOCKET_READY_CLOSING = WEBSOCKET_READY_CLOSING;
+exports.WEBSOCKET_READY_CONNECTING = WEBSOCKET_READY_CONNECTING;
+exports.WEBSOCKET_READY_OPEN = WEBSOCKET_READY_OPEN;
+exports.WEBSOCKET_VERSION = WEBSOCKET_VERSION;
+exports.computeWebSocketAccept = computeWebSocketAccept;
+exports.createNodeWebSocket = createNodeWebSocket;
+exports.encodeWebSocketFrame = encodeWebSocketFrame;
+exports.isCloseCode = isCloseCode;
+exports.measureWebSocketFrame = measureWebSocketFrame;
+exports.parseUTF8 = parseUTF8;
+exports.parseWebSocketFrame = parseWebSocketFrame;
+
+//# sourceMappingURL=index.cjs.map