@orkestrel/websocket 0.0.1

package/dist/src/server/index.d.ts

@@ -0,0 +1,399 @@
+import { Duplex } from 'node:stream';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * 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`
+ */
+export declare function computeWebSocketAccept(key: string): string;
+
+/**
+ * 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}`) },
+ * 	})
+ * })
+ * ```
+ */
+export declare function createNodeWebSocket(options: NodeWebSocketOptions): NodeWebSocketInterface;
+
+/**
+ * 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
+ */
+export declare function encodeWebSocketFrame(opcode: number, payload: Buffer | string, options?: WebSocketEncodeOptions): Buffer;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function isCloseCode(code: number): boolean;
+
+/**
+ * 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)
+ * ```
+ */
+export declare function measureWebSocketFrame(buffer: Buffer): number | undefined;
+
+/**
+ * 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).
+ */
+export declare class NodeWebSocket implements NodeWebSocketInterface {
+    #private;
+    constructor(options: NodeWebSocketOptions);
+    get emitter(): EmitterInterface<NodeWebSocketEventMap>;
+    get readyState(): WebSocketReadyState;
+    send(data: string): void;
+    ping(data?: string): void;
+    close(code?: number, reason?: string): void;
+    destroy(): void;
+}
+
+/**
+ * The event map of a {@link NodeWebSocketInterface} (AGENTS §13).
+ *
+ * @remarks
+ * `open` — the handshake completed and the socket is ready. `message` — a text frame
+ * arrived (its decoded UTF-8 string). `close` — the connection ended (its
+ * {@link WebSocketClose} metadata). `error` — the underlying socket faulted (a DOMAIN
+ * event). `ping` / `pong` — a control frame arrived (a ping is auto-answered with a pong).
+ * Listener isolation is the emitter's (AGENTS §13): a listener throw is routed to the
+ * emitter's `error` handler (the `error` option), never onto this map, so a buggy observer
+ * never breaks the socket.
+ */
+export declare type NodeWebSocketEventMap = {
+    open: [];
+    message: [message: string];
+    close: [code: number | undefined, reason: string | undefined];
+    error: [error: unknown];
+    ping: [];
+    pong: [];
+};
+
+/**
+ * A server-native WebSocket over a raw upgraded socket — the behavioral contract.
+ *
+ * @remarks
+ * Created by `createNodeWebSocket`. In server mode it writes the RFC 6455 handshake
+ * and emits `open`; thereafter it buffers incoming `data`, decodes each frame, and
+ * dispatches: a text frame (reassembling continuation fragments) 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` writes a ping; `close` writes a close frame (the 2-byte code + optional
+ * reason); `destroy` tears the socket down immediately. `readyState` tracks the
+ * lifecycle. It owns a typed `emitter` (AGENTS §13) and never throws on a faulty
+ * listener — the emitter routes it to its `error` handler (the `error` option).
+ */
+export declare interface NodeWebSocketInterface {
+    readonly emitter: EmitterInterface<NodeWebSocketEventMap>;
+    readonly readyState: WebSocketReadyState;
+    send(data: string): void;
+    ping(data?: string): void;
+    close(code?: number, reason?: string): void;
+    destroy(): void;
+}
+
+/**
+ * Options for `createNodeWebSocket`.
+ *
+ * @remarks
+ * `socket` is the upgraded `node:stream` Duplex (the raw TCP stream after the HTTP
+ * upgrade). `key` is the client's `Sec-WebSocket-Key`: present it to run in SERVER
+ * mode — the wrapper writes the `101 Switching Protocols` handshake and sends UNMASKED
+ * frames; omit it for CLIENT mode — no handshake is written and frames are MASKED (RFC
+ * 6455 §5.3). `head` is any bytes buffered after the upgrade headers (replayed through
+ * the parser). `protocol` is a negotiated subprotocol to echo in the handshake. `on`
+ * wires initial listeners at construction (AGENTS §8 reserved option); `error` is the
+ * emitter's listener-error handler (§13 — a listener throw routes here). `payload` caps
+ * both a single inbound frame's declared length AND the total bytes of a reassembled
+ * fragmented message (default `WEBSOCKET_MAX_PAYLOAD`) — a breach closes 1009. `timeout`
+ * is how long the wrapper waits, after sending a close frame, for the peer's echo before
+ * it gives up and tears the socket down (default `WEBSOCKET_CLOSE_TIMEOUT_MS`). `signal`
+ * is the external cancellation seam — on abort the socket destroys; composes with the
+ * line's `@orkestrel/abort` and `@orkestrel/timeout` primitives, which expose native
+ * `AbortSignal`s. An already-aborted signal tears the socket down immediately after
+ * construction.
+ */
+export declare interface NodeWebSocketOptions {
+    readonly socket: Duplex;
+    readonly key?: string;
+    readonly head?: Buffer;
+    readonly protocol?: string;
+    readonly on?: EmitterHooks<NodeWebSocketEventMap>;
+    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
+    readonly payload?: number;
+    readonly timeout?: number;
+    readonly signal?: AbortSignal;
+}
+
+/**
+ * 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)
+ * ```
+ */
+export declare function parseUTF8(bytes: Buffer): string | undefined;
+
+/**
+ * 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
+ */
+export declare function parseWebSocketFrame(buffer: Buffer): WebSocketFrame | undefined;
+
+/** Invalid-frame-payload-data status code (RFC 6455 §7.4.1) — e.g. non-UTF-8 text or an unparseable close reason. */
+export declare const WEBSOCKET_CLOSE_INVALID = 1007;
+
+/** Normal-closure status code (RFC 6455 §7.4.1) — the default `close` code. */
+export declare const WEBSOCKET_CLOSE_NORMAL = 1000;
+
+/** Protocol-error status code (RFC 6455 §7.4.1) — a framing/state rule was violated. */
+export declare const WEBSOCKET_CLOSE_PROTOCOL = 1002;
+
+/** The default close-handshake timeout in milliseconds — how long `close()` waits for the peer's echo before tearing the socket down. */
+export declare const WEBSOCKET_CLOSE_TIMEOUT_MS = 30000;
+
+/** Message-too-big status code (RFC 6455 §7.4.1) — a reassembled message exceeded the payload cap. */
+export declare const WEBSOCKET_CLOSE_TOOBIG = 1009;
+
+/** 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). */
+export declare const WEBSOCKET_CLOSE_UNSUPPORTED = 1003;
+
+/** The maximum control-frame payload length in bytes (RFC 6455 §5.5). */
+export declare const WEBSOCKET_CONTROL_MAXLEN = 125;
+
+/** 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). */
+export declare const WEBSOCKET_FAIL_TIMEOUT_MS = 1000;
+
+/**
+ * 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}.
+ */
+export declare const WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+/** The default maximum inbound single-frame length AND reassembled-message total byte count (100 MiB — the `ws` package default). */
+export declare const WEBSOCKET_MAX_PAYLOAD = 104857600;
+
+/** Binary frame opcode — a raw byte payload (RFC 6455 §5.6). */
+export declare const WEBSOCKET_OPCODE_BINARY = 2;
+
+/** Close frame opcode — a control frame ending the connection (RFC 6455 §5.5.1). */
+export declare const WEBSOCKET_OPCODE_CLOSE = 8;
+
+/** Ping frame opcode — a control frame the peer must answer with a pong (RFC 6455 §5.5.2). */
+export declare const WEBSOCKET_OPCODE_PING = 9;
+
+/** Pong frame opcode — a control frame answering a ping (RFC 6455 §5.5.3). */
+export declare const WEBSOCKET_OPCODE_PONG = 10;
+
+/** Text frame opcode — a UTF-8 payload (RFC 6455 §5.6). */
+export declare const WEBSOCKET_OPCODE_TEXT = 1;
+
+/** Ready state for a closed WebSocket (the socket ended). */
+export declare const WEBSOCKET_READY_CLOSED: WebSocketReadyState;
+
+/** Ready state for a closing WebSocket (a close frame was sent or received). */
+export declare const WEBSOCKET_READY_CLOSING: WebSocketReadyState;
+
+/** Ready state for a connecting WebSocket (before the handshake completes). */
+export declare const WEBSOCKET_READY_CONNECTING: WebSocketReadyState;
+
+/** Ready state for an open WebSocket (the handshake completed; frames flow). */
+export declare const WEBSOCKET_READY_OPEN: WebSocketReadyState;
+
+/** The WebSocket protocol version this wrapper speaks (`Sec-WebSocket-Version: 13`). */
+export declare const WEBSOCKET_VERSION = "13";
+
+/**
+ * The metadata of a closed WebSocket — why the connection ended.
+ *
+ * @remarks
+ * `code` is the RFC 6455 close status code (undefined when the peer closed with no
+ * payload); `reason` is the optional UTF-8 reason text (undefined when empty).
+ */
+export declare interface WebSocketClose {
+    readonly code: number | undefined;
+    readonly reason: string | undefined;
+}
+
+/** A WebSocket close status code (RFC 6455 §7.4) — e.g. `WEBSOCKET_CLOSE_NORMAL` (1000). */
+export declare type WebSocketCloseCode = number;
+
+/**
+ * Options for {@link encodeWebSocketFrame} — how a frame is masked on the wire.
+ *
+ * @remarks
+ * `masked` toggles the mask bit (server→client frames are NOT masked, the default;
+ * client→server frames MUST be, RFC 6455 §5.3). `mask` supplies an explicit 4-byte
+ * mask key (deterministic, for tests); when `masked` is true and `mask` is omitted a
+ * random key is generated.
+ */
+export declare interface WebSocketEncodeOptions {
+    readonly masked?: boolean;
+    readonly mask?: Buffer;
+}
+
+/**
+ * A parsed RFC 6455 frame — the structured result of decoding one frame off the wire.
+ *
+ * @remarks
+ * `fin` is the final-fragment bit (false for a continued fragment); `opcode`
+ * identifies the frame kind (one of the `WEBSOCKET_OPCODE_*` values); `payload` is
+ * the already-unmasked application data; `consumed` is the total byte count the frame
+ * occupied (header + mask + payload), so the caller slices it off the front of its
+ * accumulation buffer and re-parses the remainder. `masked` is the mask bit off byte 1
+ * (client→server frames MUST be masked, RFC 6455 §5.1); `rsv` is the three reserved
+ * bits off byte 0 packed into a single 0–7 value (RFC 6455 §5.2) — non-zero means an
+ * extension the wrapper does not negotiate, so the caller rejects it. Produced by
+ * {@link parseWebSocketFrame}.
+ */
+export declare interface WebSocketFrame {
+    readonly fin: boolean;
+    readonly opcode: number;
+    readonly payload: Buffer;
+    readonly consumed: number;
+    readonly masked: boolean;
+    readonly rsv: number;
+}
+
+/** A decoded text message received from, or to send to, a WebSocket peer. */
+export declare interface WebSocketMessage {
+    readonly data: string;
+}
+
+/**
+ * A WebSocket ready state — the four browser-compatible lifecycle values.
+ *
+ * @remarks
+ * `0` connecting, `1` open, `2` closing, `3` closed — the same numbering the DOM
+ * `WebSocket.readyState` uses, so the wrapper reads like the platform API. The named
+ * `WEBSOCKET_READY_*` constants spell each value.
+ */
+export declare type WebSocketReadyState = 0 | 1 | 2 | 3;
+
+export { }