@orkestrel/websocket 0.0.10 → 0.0.12

package/dist/src/server/index.cjs

@@ -3,180 +3,259 @@ 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.
+* Names the accept GUID concatenated to a client's `Sec-WebSocket-Key` before the accept
+* hash, '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'.
 *
 * @remarks
-* A fixed, spec-mandated constant (RFC 6455 §4.2.2) — read only by
+* The base64-encoded SHA-1 of that concatenation is the `Sec-WebSocket-Accept` response
+* value. 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`). */
+/**
+* Names the supported protocol version, '13'.
+*
+* @remarks
+* The value this wrapper speaks, carried by the `Sec-WebSocket-Version` handshake header.
+*/
 var WEBSOCKET_VERSION = "13";
-/** Text frame opcode — a UTF-8 payload (RFC 6455 §5.6). */
+/**
+* Names the text frame opcode, 0x01.
+*
+* @remarks
+* A UTF-8 payload (RFC 6455 §5.6).
+*/
 var WEBSOCKET_OPCODE_TEXT = 1;
-/** Binary frame opcode — a raw byte payload (RFC 6455 §5.6). */
+/**
+* Names the binary frame opcode, 0x02.
+*
+* @remarks
+* A raw byte payload (RFC 6455 §5.6).
+*/
 var WEBSOCKET_OPCODE_BINARY = 2;
-/** Continuation frame opcode — the next fragment of an open data message (RFC 6455 §5.4). */
+/**
+* Names the continuation frame opcode, 0x00.
+*
+* @remarks
+* The next fragment of an open data message (RFC 6455 §5.4).
+*/
 var WEBSOCKET_OPCODE_CONTINUATION = 0;
-/** Close frame opcode — a control frame ending the connection (RFC 6455 §5.5.1). */
+/**
+* Names the close frame opcode, 0x08.
+*
+* @remarks
+* 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). */
+/**
+* Names the ping frame opcode, 0x09.
+*
+* @remarks
+* 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). */
+/**
+* Names the pong frame opcode, 0x0a.
+*
+* @remarks
+* 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). */
+/**
+* Names the connecting ready state, 0.
+*
+* @remarks
+* The state a WebSocket holds before its handshake completes.
+*/
 var WEBSOCKET_READY_CONNECTING = 0;
-/** Ready state for an open WebSocket (the handshake completed; frames flow). */
+/**
+* Names the open ready state, 1.
+*
+* @remarks
+* The state a WebSocket holds after the handshake completes and while frames flow.
+*/
 var WEBSOCKET_READY_OPEN = 1;
-/** Ready state for a closing WebSocket (a close frame was sent or received). */
+/**
+* Names the closing ready state, 2.
+*
+* @remarks
+* The state a WebSocket holds after a close frame is sent or received.
+*/
 var WEBSOCKET_READY_CLOSING = 2;
-/** Ready state for a closed WebSocket (the socket ended). */
+/**
+* Names the closed ready state, 3.
+*
+* @remarks
+* The state a WebSocket holds after the socket ends.
+*/
 var WEBSOCKET_READY_CLOSED = 3;
-/** Normal-closure status code (RFC 6455 §7.4.1) — the default `close` code. */
+/**
+* Names the normal-closure status code, 1000.
+*
+* @remarks
+* The default `close` code (RFC 6455 §7.4.1).
+*/
 var WEBSOCKET_CLOSE_NORMAL = 1e3;
-/** Protocol-error status code (RFC 6455 §7.4.1) — a framing/state rule was violated. */
+/**
+* Names the protocol-error status code, 1002.
+*
+* @remarks
+* Sent when a framing or state rule was violated (RFC 6455 §7.4.1).
+*/
 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). */
+/**
+* Names the unsupported-data status code, 1003.
+*
+* @remarks
+* Sent when the endpoint received a data type it cannot accept (RFC 6455 §7.4.1), for
+* example 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. */
+/**
+* Names the invalid-frame-payload-data status code, 1007.
+*
+* @remarks
+* Sent for non-UTF-8 text or an unparseable close reason (RFC 6455 §7.4.1).
+*/
 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). */
+/**
+* Names the message-too-big status code, 1009.
+*
+* @remarks
+* Sent when a reassembled message exceeded the payload cap (RFC 6455 §7.4.1).
+*/
+var WEBSOCKET_CLOSE_TOO_BIG = 1009;
+/**
+* Names the default cap on both an inbound frame's declared length and a reassembled
+* message's total byte count, 104,857,600 bytes (100 MiB).
+*
+* @remarks
+* The same value the `ws` package defaults to. Either breach closes
+* {@link WEBSOCKET_CLOSE_TOO_BIG}.
+*/
 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. */
+/**
+* Names the default close-handshake timeout, 30,000 milliseconds — how long `close` waits
+* for the peer's echo.
+*
+* @remarks
+* After it expires the wrapper tears the socket down, so a silent peer cannot leak the
+* handle open.
+*/
 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;
-/** The maximum UTF-8 close-reason length after the two-byte status code. */
-var WEBSOCKET_CLOSE_REASON_MAXLEN = 123;
-//#endregion
-//#region src/server/helpers.ts
 /**
-* Compute the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
+* Names the flush grace, 1,000 milliseconds, a validation-breach close frame is given
+* before the hard teardown fallback destroys the socket.
 *
 * @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.
+* Armed after `#fail` writes the close frame, so the frame drains through the socket's
+* write buffer rather than being discarded. The normal path destroys sooner, on the
+* `end()` flush callback.
+*/
+var WEBSOCKET_FAIL_TIMEOUT_MS = 1e3;
+/**
+* Names the maximum control-frame payload length, 125 bytes.
 *
-* @param key - The client's `Sec-WebSocket-Key` header value
-* @returns The base64 accept token to send back as `Sec-WebSocket-Accept`
+* @remarks
+* The cap RFC 6455 §5.5 sets on every control frame's payload.
 */
-function computeWebSocketAccept(key) {
-	return (0, node_crypto.createHash)("sha1").update(key + WEBSOCKET_GUID).digest("base64");
-}
+var WEBSOCKET_CONTROL_MAX_LENGTH = 125;
 /**
-* Whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`.
+* Names the maximum UTF-8 close-reason length after the two-byte status code, 123.
 *
 * @remarks
-* A valid key is exactly 16 random bytes encoded as 24 characters of base64, ending
-* in `==` (RFC 6455 §4.1). This predicate is suitable at an HTTP upgrade boundary:
-* malformed or non-canonical encodings return `false`; nothing is thrown.
+* What is left of {@link WEBSOCKET_CONTROL_MAX_LENGTH} after the close frame's status
+* code.
+*/
+var WEBSOCKET_CLOSE_REASON_MAX_LENGTH = 123;
+//#endregion
+//#region src/server/errors.ts
+/**
+* Represents an error the WebSocket wrapper throws for a refused caller-supplied value,
+* carrying a machine-readable `code` and an optional `context`.
 *
-* @param key - The proposed `Sec-WebSocket-Key` header value
-* @returns `true` when `key` is the canonical base64 encoding of 16 bytes
+* @remarks
+* The `code` is a {@link WebSocketErrorCode}; the `context` record holds the refused
+* value under a key naming it: an `'OPTION'` carries the offending option (`payload`,
+* `timeout`, `key`, or `protocol`), a `'LIMIT'` carries `size` and the `limit` it
+* exceeded, a `'CLOSE'` carries the refused close `code`, and a `'FRAME'` carries
+* `opcode` or the mask's `size`. Narrow a caught value with {@link isWebSocketError}.
 *
 * @example
 * ```ts
-* const key = request.headers['sec-websocket-key']
-* if (typeof key !== 'string' || !isWebSocketKey(key)) socket.destroy()
+* import { createNodeWebSocket, isWebSocketError } from '@src/server'
+*
+* try {
+* 	createNodeWebSocket({ socket, key: 'not-base64' })
+* } catch (error) {
+* 	if (isWebSocketError(error) && error.code === 'OPTION') socket.destroy()
+* }
 * ```
 */
-function isWebSocketKey(key) {
-	if (!/^[A-Za-z0-9+/]{22}==$/.test(key)) return false;
-	return Buffer.from(key, "base64").length === 16;
-}
+var WebSocketError = class extends Error {
+	code;
+	context;
+	/**
+	* Creates a WebSocket error carrying a machine-readable code.
+	*
+	* @param code - The machine-readable {@link WebSocketErrorCode} a `catch` branches on
+	* @param message - The human-readable description, carried as the `Error` message
+	* @param context - The refused value keyed by name; omitted leaves `context` `undefined`
+	*/
+	constructor(code, message, context) {
+		super(message);
+		this.name = "WebSocketError";
+		this.code = code;
+		if (context !== void 0) this.context = context;
+	}
+};
 /**
-* Whether a value is one valid WebSocket subprotocol token.
+* Checks whether a caught value is a {@link WebSocketError}, narrowing it so a `catch` can
+* branch on `error.code`.
 *
-* @remarks
-* Subprotocols use the HTTP `token` grammar. Whitespace, separators, commas, and
-* control characters are rejected, preventing an untrusted value from injecting a
-* second handshake header.
-*
-* @param protocol - The negotiated subprotocol to validate
-* @returns `true` when `protocol` is one non-empty HTTP token
+* @param value - The value to test (typically a `catch` binding)
+* @returns True if `value` is a `WebSocketError`; false otherwise
 *
 * @example
 * ```ts
-* if (!isWebSocketProtocol(protocol)) throw new RangeError('invalid protocol')
+* import { isWebSocketError } from '@src/server'
+*
+* try {
+* 	ws.close(1000.5)
+* } catch (error) {
+* 	if (isWebSocketError(error) && error.code === 'CLOSE') ws.close()
+* }
 * ```
 */
-function isWebSocketProtocol(protocol) {
-	return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(protocol);
+function isWebSocketError(value) {
+	return value instanceof WebSocketError;
 }
+//#endregion
+//#region src/server/helpers.ts
 /**
-* Decode a single RFC 6455 frame from the front of a buffer.
+* Computes the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
 *
 * @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.
+* 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 buffer - The accumulation buffer to decode the next frame from
-* @returns The parsed {@link WebSocketFrame}, or `undefined` when the buffer is incomplete
+* @param key - The client's `Sec-WebSocket-Key` header value
+* @returns The base64 accept token to send back as `Sec-WebSocket-Accept`
 */
-function parseWebSocketFrame(buffer) {
-	if (buffer.length < 2) return void 0;
-	const firstByte = buffer.readUInt8(0);
-	const secondByte = buffer.readUInt8(1);
-	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.readUInt8(index) ^ mask.readUInt8(index % 4);
-	return {
-		fin,
-		opcode,
-		payload,
-		consumed: offset + length,
-		masked,
-		rsv
-	};
+function computeWebSocketAccept(key) {
+	return (0, node_crypto.createHash)("sha1").update(key + WEBSOCKET_GUID).digest("base64");
 }
 /**
-* Read the declared payload length off the front of a buffer, without buffering or
-* reading the payload itself.
+* Reads the declared payload length off the front of a buffer without buffering or
+* reading the payload itself, answering `undefined` until the length field is complete.
 *
 * @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
+* (`127`) form exactly like `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.
+* bytes have even arrived. The incomplete-buffer contract mirrors the parser's. 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
@@ -184,7 +263,7 @@ function parseWebSocketFrame(buffer) {
 * @example
 * ```ts
 * const declared = measureWebSocketFrame(buffer)
-* if (declared !== undefined && declared > limit) fail(WEBSOCKET_CLOSE_TOOBIG)
+* if (declared !== undefined && declared > limit) fail(WEBSOCKET_CLOSE_TOO_BIG)
 * ```
 */
 function measureWebSocketFrame(buffer) {
@@ -203,22 +282,24 @@ function measureWebSocketFrame(buffer) {
 	return length;
 }
 /**
-* Whether the next frame uses the shortest valid RFC 6455 payload-length encoding.
+* Checks whether the next frame uses the shortest valid RFC 6455 payload-length
+* encoding, answering `undefined` until its length prefix is complete.
 *
 * @remarks
-* Returns `undefined` until the complete length prefix is buffered. The 16-bit form
-* is canonical only for lengths at least 126; the 64-bit form only for lengths at
-* least 65,536 and with its most-significant bit clear (RFC 6455 §5.2).
+* The 16-bit form is canonical only for lengths at least 126; the 64-bit form only for
+* lengths at least 65,536 and with its most-significant bit clear (RFC 6455 §5.2). Reads
+* the same length prefix as {@link measureWebSocketFrame}, under the same
+* incomplete-buffer contract. Pure; never throws.
 *
 * @param buffer - The accumulation buffer containing the next frame header
 * @returns Its canonicality, or `undefined` while the length prefix is incomplete
 *
 * @example
 * ```ts
-* if (isWebSocketFrameCanonical(buffer) === false) fail(WEBSOCKET_CLOSE_PROTOCOL)
+* if (matchesWebSocketCanonical(buffer) === false) fail(WEBSOCKET_CLOSE_PROTOCOL)
 * ```
 */
-function isWebSocketFrameCanonical(buffer) {
+function matchesWebSocketCanonical(buffer) {
 	if (buffer.length < 2) return void 0;
 	const lengthCode = buffer.readUInt8(1) & 127;
 	if (lengthCode < 126) return true;
@@ -233,31 +314,95 @@ function isWebSocketFrameCanonical(buffer) {
 	return high > 0 || low >= 65536;
 }
 /**
-* Decode a byte sequence as strict UTF-8, or signal it is malformed.
+* Encodes a single RFC 6455 frame to its wire bytes — the inverse of
+* `parseWebSocketFrame`.
 *
 * @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.
+* 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
+* through `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 (for example 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 bytes - The raw bytes to decode
-* @returns The decoded string, or `undefined` when `bytes` is not valid UTF-8
+* @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
+* @throws A {@link WebSocketError} coded `FRAME` when `opcode` is outside the four-bit wire field, when `options.mask` is not 4 bytes, or when `options.mask` is supplied without `masked: true`
+*/
+function encodeWebSocketFrame(opcode, payload, options) {
+	if (!Number.isInteger(opcode) || opcode < 0 || opcode > 15) throw new WebSocketError("FRAME", "opcode must be an integer between 0 and 15", { opcode });
+	if (options?.mask !== void 0 && options.mask.length !== 4) throw new WebSocketError("FRAME", "mask must contain exactly 4 bytes", { size: options.mask.length });
+	if (options?.mask !== void 0 && options.masked !== true) throw new WebSocketError("FRAME", "mask requires masked: true");
+	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.readUInt8(index) ^ mask.readUInt8(index % 4);
+	return Buffer.concat([header, maskedBody]);
+}
+/**
+* Checks whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`.
+*
+* @remarks
+* A valid key is exactly 16 random bytes encoded as 24 characters of base64, ending
+* in `==` (RFC 6455 §4.1). This predicate is suitable at an HTTP upgrade boundary:
+* malformed or non-canonical encodings return `false`; nothing is thrown.
+*
+* @param key - The proposed `Sec-WebSocket-Key` header value
+* @returns True if `key` is the canonical base64 encoding of 16 bytes; false otherwise
 *
 * @example
 * ```ts
-* const text = parseUTF8(payload)
-* if (text === undefined) fail(WEBSOCKET_CLOSE_INVALID)
+* const key = request.headers['sec-websocket-key']
+* if (typeof key !== 'string' || !isWebSocketKey(key)) socket.destroy()
 * ```
 */
-function parseUTF8(bytes) {
-	try {
-		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-	} catch {
-		return;
-	}
+function isWebSocketKey(key) {
+	if (!/^[A-Za-z0-9+/]{22}==$/.test(key)) return false;
+	return Buffer.from(key, "base64").length === 16;
+}
+/**
+* Checks whether a value is one valid WebSocket subprotocol token.
+*
+* @remarks
+* Subprotocols use the HTTP `token` grammar. Whitespace, separators, commas, and
+* control characters are rejected, preventing an untrusted value from injecting a
+* second handshake header.
+*
+* @param protocol - The negotiated subprotocol to validate
+* @returns True if `protocol` is one non-empty HTTP token; false otherwise
+*
+* @example
+* ```ts
+* if (!isWebSocketProtocol(protocol)) socket.destroy()
+* ```
+*/
+function isWebSocketProtocol(protocol) {
+	return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(protocol);
 }
 /**
-* Whether a numeric value is a valid RFC 6455 close status code to RECEIVE (§7.4.1).
+* Checks whether a numeric value is a close status code an RFC 6455 endpoint may
+* receive (§7.4.1).
 *
 * @remarks
 * True for `1000`–`1003`, `1007`–`1014`, and the application range `3000`–`4999`; false
@@ -270,7 +415,7 @@ function parseUTF8(bytes) {
 * never throws.
 *
 * @param code - The close status code to validate
-* @returns `true` when `code` is a valid RFC 6455 close code
+* @returns True if `code` is a valid RFC 6455 close code; false otherwise
 *
 * @example
 * ```ts
@@ -284,73 +429,133 @@ function isCloseCode(code) {
 	if (code >= 3e3 && code <= 4999) return true;
 	return false;
 }
+//#endregion
+//#region src/server/parsers.ts
 /**
-* Encode a single RFC 6455 frame to its wire bytes — the inverse of
-* {@link parseWebSocketFrame}.
+* Decodes a single RFC 6455 frame from the front of a buffer, answering `undefined`
+* while the buffer is incomplete so the caller accumulates and retries.
 *
 * @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.
+* 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). The incomplete answer comes the moment the buffer is too short
+* for the part it is up to: the length prefix, the mask, or the full payload.
+* `consumed` is the total bytes the frame occupied, so the caller slices the remainder.
+* Pure; never throws on a short buffer.
 *
-* @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
+* @param buffer - The accumulation buffer to decode the next frame from
+* @returns The parsed {@link WebSocketFrame}, or `undefined` when the buffer is incomplete
+*
+* @example
+* ```ts
+* const frame = parseWebSocketFrame(buffer)
+* if (frame === undefined) return // incomplete — wait for more bytes
+* ```
 */
-function encodeWebSocketFrame(opcode, payload, options) {
-	if (!Number.isInteger(opcode) || opcode < 0 || opcode > 15) throw new RangeError("opcode must be an integer between 0 and 15");
-	if (options?.mask !== void 0 && options.mask.length !== 4) throw new RangeError("mask must contain exactly 4 bytes");
-	if (options?.mask !== void 0 && options.masked !== true) throw new RangeError("mask requires masked: true");
-	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);
+function parseWebSocketFrame(buffer) {
+	if (buffer.length < 2) return void 0;
+	const firstByte = buffer.readUInt8(0);
+	const secondByte = buffer.readUInt8(1);
+	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.readUInt8(index) ^ mask.readUInt8(index % 4);
+	return {
+		fin,
+		opcode,
+		payload,
+		consumed: offset + length,
+		masked,
+		rsv
+	};
+}
+/**
+* Decodes a byte sequence as strict UTF-8, answering `undefined` when the sequence is
+* malformed.
+*
+* @remarks
+* Wraps `TextDecoder('utf-8', { fatal: true })` in a try/catch, so a malformed sequence
+* returns rather than throwing — 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;
 	}
-	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.readUInt8(index) ^ mask.readUInt8(index % 4);
-	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.
+* Implements the wrapper contract over a raw upgraded `node:stream` Duplex socket,
+* driving the RFC 6455 handshake, the frame codec, auto-pong, and the close handshake,
+* and surfacing every event on an owned `emitter`.
 *
 * @remarks
-* Created by `createNodeWebSocket`. When given a client `key` it runs in SERVER mode —
+* 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
+* 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
+* 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 frame 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. An underlying socket error emits the domain
-* `error` event and terminates the wrapper. The untyped socket `data` is narrowed to a
-* `Buffer` with a guard, never an assertion (AGENTS §14).
+* frame; `destroy` tears down immediately. It owns a typed `#emitter` by composition, and
+* the emitter isolates a throwing listener and routes the error to its own `error` handler
+* (the `error` option) — the socket never crashes. An underlying socket error emits the
+* domain `error` event and terminates the wrapper. The untyped socket `data` is narrowed
+* to a `Buffer` with a guard, never an assertion.
+*
+* @example
+* ```ts
+* import { NodeWebSocket } from '@src/server'
+*
+* // In a node:http 'upgrade' handler, over the socket the server already handed over:
+* const key = request.headers['sec-websocket-key']
+* if (typeof key !== 'string') {
+* 	socket.destroy()
+* 	return
+* }
+* const ws = new NodeWebSocket({ socket, key, head })
+* ws.emitter.on('message', (text) => ws.send(`echo: ${text}`))
+* ```
 */
 var NodeWebSocket = class {
 	#emitter;
@@ -373,14 +578,25 @@ var NodeWebSocket = class {
 	#closeTimer;
 	#destroyed = false;
 	#detached = false;
+	/**
+	* Creates a WebSocket wrapper over an already-upgraded Duplex socket.
+	*
+	* @remarks
+	* `key` selects the mode: present runs server mode and writes the `101 Switching
+	* Protocols` handshake, omitted runs client mode and masks every outgoing frame.
+	* {@link NodeWebSocketOptions} describes every member.
+	*
+	* @param options - The {@link NodeWebSocketOptions} the wrapper is built from
+	* @throws A {@link WebSocketError} coded `OPTION` when `payload`, `timeout`, `key`, or `protocol` is refused, or when `protocol` is supplied without a server `key`, thrown before the wrapper writes to or assumes ownership of the `socket`
+	*/
 	constructor(options) {
 		const payload = options.payload ?? 104857600;
-		if (!Number.isSafeInteger(payload) || payload < 0) throw new RangeError("payload must be a non-negative safe integer");
+		if (!Number.isSafeInteger(payload) || payload < 0) throw new WebSocketError("OPTION", "payload must be a non-negative safe integer", { payload });
 		const timeout = options.timeout ?? 3e4;
-		if (!Number.isSafeInteger(timeout) || timeout < 0) throw new RangeError("timeout must be a non-negative safe integer");
-		if (options.key !== void 0 && !isWebSocketKey(options.key)) throw new RangeError("key must be the canonical base64 encoding of 16 bytes");
-		if (options.protocol !== void 0 && !isWebSocketProtocol(options.protocol)) throw new RangeError("protocol must be a valid WebSocket subprotocol token");
-		if (options.protocol !== void 0 && options.key === void 0) throw new RangeError("protocol requires a server key");
+		if (!Number.isSafeInteger(timeout) || timeout < 0) throw new WebSocketError("OPTION", "timeout must be a non-negative safe integer", { timeout });
+		if (options.key !== void 0 && !isWebSocketKey(options.key)) throw new WebSocketError("OPTION", "key must be the canonical base64 encoding of 16 bytes", { key: options.key });
+		if (options.protocol !== void 0 && !isWebSocketProtocol(options.protocol)) throw new WebSocketError("OPTION", "protocol must be a valid WebSocket subprotocol token", { protocol: options.protocol });
+		if (options.protocol !== void 0 && options.key === void 0) throw new WebSocketError("OPTION", "protocol requires a server key", { protocol: options.protocol });
 		this.#emitter = new _orkestrel_emitter.Emitter({
 			...options.on === void 0 ? {} : { on: options.on },
 			...options.error === void 0 ? {} : { error: options.error }
@@ -422,19 +638,27 @@ var NodeWebSocket = class {
 	get readyState() {
 		return this.#readyState;
 	}
-	send(data) {
+	send(message) {
 		if (this.#readyState !== 1) return;
-		this.#write(1, Buffer.from(data, "utf-8"));
+		this.#write(1, Buffer.from(message, "utf-8"));
 	}
-	ping(data) {
+	ping(payload) {
 		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"));
+		const size = payload === void 0 ? 0 : Buffer.byteLength(payload, "utf-8");
+		if (size > 125) throw new WebSocketError("LIMIT", `ping payload exceeds 125 bytes`, {
+			size,
+			limit: 125
+		});
+		this.#write(9, payload === void 0 ? Buffer.alloc(0) : Buffer.from(payload, "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`);
+		if (code !== void 0 && !isCloseCode(code)) throw new WebSocketError("CLOSE", "invalid close code", { code });
+		const size = reason === void 0 ? 0 : Buffer.byteLength(reason, "utf-8");
+		if (size > 123) throw new WebSocketError("LIMIT", `close reason exceeds 123 bytes`, {
+			size,
+			limit: 123
+		});
 		this.#readyState = 2;
 		this.#code = code ?? 1e3;
 		this.#reason = reason === void 0 || reason.length === 0 ? void 0 : reason;
@@ -456,13 +680,13 @@ var NodeWebSocket = class {
 	}
 	#drain() {
 		for (;;) {
-			if (isWebSocketFrameCanonical(this.#buffer) === false) {
+			if (matchesWebSocketCanonical(this.#buffer) === false) {
 				this.#fail(WEBSOCKET_CLOSE_PROTOCOL);
 				return;
 			}
 			const declared = measureWebSocketFrame(this.#buffer);
 			if (declared !== void 0 && declared > this.#payload) {
-				this.#fail(WEBSOCKET_CLOSE_TOOBIG);
+				this.#fail(WEBSOCKET_CLOSE_TOO_BIG);
 				return;
 			}
 			const frame = parseWebSocketFrame(this.#buffer);
@@ -516,7 +740,7 @@ var NodeWebSocket = class {
 		this.#fragments.push(payload);
 		this.#fragmentBytes += payload.length;
 		if (this.#fragmentBytes > this.#payload) {
-			this.#fail(WEBSOCKET_CLOSE_TOOBIG);
+			this.#fail(WEBSOCKET_CLOSE_TOO_BIG);
 			return;
 		}
 		if (!fin) return;
@@ -645,33 +869,39 @@ var NodeWebSocket = class {
 //#endregion
 //#region src/server/factories.ts
 /**
-* Create a server-native WebSocket over a raw upgraded `node:stream` Duplex socket.
+* Creates a server-native WebSocket over a raw upgraded `node:stream` Duplex socket —
+* server mode when a `key` is given, client mode otherwise.
 *
 * @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`.
+* The construction entry point for the {@link NodeWebSocketInterface}. In server mode the
+* wrapper writes the `101 Switching Protocols` handshake and sends unmasked frames; in
+* client mode it writes no handshake and masks every outgoing frame. This is the
+* lean-native handle: it speaks the WebSocket wire protocol and nothing above it, so a
+* message transport is built on it rather than into it.
 *
 * @param options - The {@link NodeWebSocketOptions} (`socket`, optional `key` / `head` /
 *   `protocol` / `on`)
 * @returns A typed {@link NodeWebSocketInterface}
+* @throws A `WebSocketError` coded `OPTION` when `payload`, `timeout`, `key`, or `protocol` is refused, thrown before the wrapper writes to or assumes ownership of the `socket`
 *
-* @example
+* @example Accept an upgrade and echo messages (server mode)
 * ```ts
-* import { createNodeWebSocket } from '@src/server'
+* import { createNodeWebSocket } from '@orkestrel/websocket'
 *
-* // In a node:http 'upgrade' handler — server mode, identified by the client key:
 * server.on('upgrade', (request, socket, head) => {
+* 	const key = request.headers['sec-websocket-key']
+* 	if (typeof key !== 'string') {
+* 		socket.destroy()
+* 		return
+* 	}
 * 	const ws = createNodeWebSocket({
 * 		socket,
-* 		key: request.headers['sec-websocket-key'],
-* 		head,
-* 		on: { message: (text) => ws.send(`echo: ${text}`) },
+* 		key,
+* 		head, // any bytes already buffered after the upgrade headers
+* 		on: { message: (text) => ws.send(`echo: ${text}`) }, // wired before the first frame arrives
 * 	})
+* 	ws.emitter.on('message', (text) => log('echoed', text)) // a second observer of the same event
+* 	ws.emitter.on('close', (code, reason) => log('closed', code, reason))
 * })
 * ```
 */
@@ -683,11 +913,11 @@ 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_REASON_MAXLEN = WEBSOCKET_CLOSE_REASON_MAXLEN;
+exports.WEBSOCKET_CLOSE_REASON_MAX_LENGTH = WEBSOCKET_CLOSE_REASON_MAX_LENGTH;
 exports.WEBSOCKET_CLOSE_TIMEOUT_MS = WEBSOCKET_CLOSE_TIMEOUT_MS;
-exports.WEBSOCKET_CLOSE_TOOBIG = WEBSOCKET_CLOSE_TOOBIG;
+exports.WEBSOCKET_CLOSE_TOO_BIG = WEBSOCKET_CLOSE_TOO_BIG;
 exports.WEBSOCKET_CLOSE_UNSUPPORTED = WEBSOCKET_CLOSE_UNSUPPORTED;
-exports.WEBSOCKET_CONTROL_MAXLEN = WEBSOCKET_CONTROL_MAXLEN;
+exports.WEBSOCKET_CONTROL_MAX_LENGTH = WEBSOCKET_CONTROL_MAX_LENGTH;
 exports.WEBSOCKET_FAIL_TIMEOUT_MS = WEBSOCKET_FAIL_TIMEOUT_MS;
 exports.WEBSOCKET_GUID = WEBSOCKET_GUID;
 exports.WEBSOCKET_MAX_PAYLOAD = WEBSOCKET_MAX_PAYLOAD;
@@ -702,13 +932,15 @@ 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.WebSocketError = WebSocketError;
 exports.computeWebSocketAccept = computeWebSocketAccept;
 exports.createNodeWebSocket = createNodeWebSocket;
 exports.encodeWebSocketFrame = encodeWebSocketFrame;
 exports.isCloseCode = isCloseCode;
-exports.isWebSocketFrameCanonical = isWebSocketFrameCanonical;
+exports.isWebSocketError = isWebSocketError;
 exports.isWebSocketKey = isWebSocketKey;
 exports.isWebSocketProtocol = isWebSocketProtocol;
+exports.matchesWebSocketCanonical = matchesWebSocketCanonical;
 exports.measureWebSocketFrame = measureWebSocketFrame;
 exports.parseUTF8 = parseUTF8;
 exports.parseWebSocketFrame = parseWebSocketFrame;