@orkestrel/websocket 0.0.10 → 0.0.11

package/dist/src/server/index.cjs

@@ -3,7 +3,7 @@ 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
+* Names 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
@@ -11,52 +11,113 @@ let _orkestrel_emitter = require("@orkestrel/emitter");
 * {@link computeWebSocketAccept}.
 */
 var WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
-/** The WebSocket protocol version this wrapper speaks (`Sec-WebSocket-Version: 13`). */
+/** Names 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). */
+/** Names the 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). */
+/** Names the binary frame opcode — 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 — 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 — 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 — 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 — 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 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). */
+/** Names the 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). */
+/** Names the 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). */
+/** Names the 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. */
+/** Names the 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. */
+/** Names the 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). */
+/** Names the unsupported-data status code (RFC 6455 §7.4.1) — the endpoint received a data type it cannot accept, 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 (RFC 6455 §7.4.1) — for example 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). */
+/** Names the message-too-big status code (RFC 6455 §7.4.1) — a reassembled message exceeded the payload cap. */
+var WEBSOCKET_CLOSE_TOO_BIG = 1009;
+/** Names 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. */
+/** Names 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). */
+/** Names 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;
+/** Names the maximum control-frame payload length in bytes (RFC 6455 §5.5). */
+var WEBSOCKET_CONTROL_MAX_LENGTH = 125;
+/** Names the maximum UTF-8 close-reason length after the two-byte status code. */
+var WEBSOCKET_CLOSE_REASON_MAX_LENGTH = 123;
+//#endregion
+//#region src/server/errors.ts
+/**
+* Represents an error thrown by the WebSocket wrapper for a refused caller-supplied value.
+*
+* @remarks
+* Carries a {@link WebSocketErrorCode} and an optional `context` record holding 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
+* import { createNodeWebSocket, isWebSocketError } from '@src/server'
+*
+* try {
+* 	createNodeWebSocket({ socket, key: 'not-base64' })
+* } catch (error) {
+* 	if (isWebSocketError(error) && error.code === 'OPTION') socket.destroy()
+* }
+* ```
+*/
+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;
+	}
+};
+/**
+* Checks whether a value is a {@link WebSocketError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns True if `value` is a `WebSocketError`; false otherwise
+*
+* @example
+* ```ts
+* import { isWebSocketError } from '@src/server'
+*
+* try {
+* 	ws.close(1000.5)
+* } catch (error) {
+* 	if (isWebSocketError(error) && error.code === 'CLOSE') ws.close()
+* }
+* ```
+*/
+function isWebSocketError(value) {
+	return value instanceof WebSocketError;
+}
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Compute the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade.
+* Computes 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
@@ -70,7 +131,121 @@ function computeWebSocketAccept(key) {
 	return (0, node_crypto.createHash)("sha1").update(key + WEBSOCKET_GUID).digest("base64");
 }
 /**
-* Whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`.
+* Reads 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 `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_TOO_BIG)
+* ```
+*/
+function measureWebSocketFrame(buffer) {
+	if (buffer.length < 2) return void 0;
+	let length = buffer.readUInt8(1) & 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;
+}
+/**
+* Checks whether the next frame uses the shortest valid RFC 6455 payload-length encoding.
+*
+* @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). 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 (matchesWebSocketCanonical(buffer) === false) fail(WEBSOCKET_CLOSE_PROTOCOL)
+* ```
+*/
+function matchesWebSocketCanonical(buffer) {
+	if (buffer.length < 2) return void 0;
+	const lengthCode = buffer.readUInt8(1) & 127;
+	if (lengthCode < 126) return true;
+	if (lengthCode === 126) {
+		if (buffer.length < 4) return void 0;
+		return buffer.readUInt16BE(2) >= 126;
+	}
+	if (buffer.length < 10) return void 0;
+	const high = buffer.readUInt32BE(2);
+	const low = buffer.readUInt32BE(6);
+	if ((high & 2147483648) !== 0) return false;
+	return high > 0 || low >= 65536;
+}
+/**
+* Encodes a single RFC 6455 frame to its wire bytes — the inverse of
+* `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
+* 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 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
@@ -78,7 +253,7 @@ function computeWebSocketAccept(key) {
 * malformed or non-canonical encodings return `false`; nothing is thrown.
 *
 * @param key - The proposed `Sec-WebSocket-Key` header value
-* @returns `true` when `key` is the canonical base64 encoding of 16 bytes
+* @returns True if `key` is the canonical base64 encoding of 16 bytes; false otherwise
 *
 * @example
 * ```ts
@@ -91,7 +266,7 @@ function isWebSocketKey(key) {
 	return Buffer.from(key, "base64").length === 16;
 }
 /**
-* Whether a value is one valid WebSocket subprotocol token.
+* Checks whether a value is one valid WebSocket subprotocol token.
 *
 * @remarks
 * Subprotocols use the HTTP `token` grammar. Whitespace, separators, commas, and
@@ -99,18 +274,48 @@ function isWebSocketKey(key) {
 * second handshake header.
 *
 * @param protocol - The negotiated subprotocol to validate
-* @returns `true` when `protocol` is one non-empty HTTP token
+* @returns True if `protocol` is one non-empty HTTP token; false otherwise
 *
 * @example
 * ```ts
-* if (!isWebSocketProtocol(protocol)) throw new RangeError('invalid protocol')
+* if (!isWebSocketProtocol(protocol)) socket.destroy()
 * ```
 */
 function isWebSocketProtocol(protocol) {
 	return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(protocol);
 }
 /**
-* Decode a single RFC 6455 frame from the front of a buffer.
+* Checks 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 if `code` is a valid RFC 6455 close code; false otherwise
+*
+* @example
+* ```ts
+* if (!isCloseCode(code)) fail(WEBSOCKET_CLOSE_PROTOCOL)
+* ```
+*/
+function isCloseCode(code) {
+	if (!Number.isInteger(code)) return false;
+	if (code >= 1e3 && code <= 1003) return true;
+	if (code >= 1007 && code <= 1014) return true;
+	if (code >= 3e3 && code <= 4999) return true;
+	return false;
+}
+//#endregion
+//#region src/server/parsers.ts
+/**
+* Decodes 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
@@ -120,12 +325,17 @@ function isWebSocketProtocol(protocol) {
 * 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 caller to read more bytes and retry. `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
+*
+* @example
+* ```ts
+* const frame = parseWebSocketFrame(buffer)
+* if (frame === undefined) return // incomplete — wait for more bytes
+* ```
 */
 function parseWebSocketFrame(buffer) {
 	if (buffer.length < 2) return void 0;
@@ -168,77 +378,12 @@ function parseWebSocketFrame(buffer) {
 	};
 }
 /**
-* 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.readUInt8(1) & 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;
-}
-/**
-* Whether the next frame uses the shortest valid RFC 6455 payload-length encoding.
-*
-* @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).
-*
-* @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)
-* ```
-*/
-function isWebSocketFrameCanonical(buffer) {
-	if (buffer.length < 2) return void 0;
-	const lengthCode = buffer.readUInt8(1) & 127;
-	if (lengthCode < 126) return true;
-	if (lengthCode === 126) {
-		if (buffer.length < 4) return void 0;
-		return buffer.readUInt16BE(2) >= 126;
-	}
-	if (buffer.length < 10) return void 0;
-	const high = buffer.readUInt32BE(2);
-	const low = buffer.readUInt32BE(6);
-	if ((high & 2147483648) !== 0) return false;
-	return high > 0 || low >= 65536;
-}
-/**
-* Decode a byte sequence as strict UTF-8, or signal it is malformed.
+* Decodes a byte sequence as strict UTF-8, or signals 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.
+* returns `undefined` instead of 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
@@ -256,84 +401,10 @@ function parseUTF8(bytes) {
 		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 (!Number.isInteger(code)) return false;
-	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) {
-	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);
-	}
-	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
+* Represents a server-native WebSocket over a raw upgraded `node:stream` Duplex — the lean
 * wrapper around the RFC 6455 wire protocol.
 *
 * @remarks
@@ -346,11 +417,25 @@ function encodeWebSocketFrame(opcode, payload, options) {
 * `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. 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 +458,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 +518,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 +560,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 +620,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,10 +749,10 @@ 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.
 *
 * @remarks
-* The construction entry point for the {@link NodeWebSocketInterface} (AGENTS §8). Pass
+* The construction entry point for the {@link NodeWebSocketInterface}. 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
@@ -659,6 +763,7 @@ var NodeWebSocket = class {
 * @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
 * ```ts
@@ -666,9 +771,14 @@ var NodeWebSocket = class {
 *
 * // 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'],
+* 		key, // present => server mode + 101 handshake
 * 		head,
 * 		on: { message: (text) => ws.send(`echo: ${text}`) },
 * 	})
@@ -683,11 +793,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 +812,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;