@znight/websocket 0.0.0 → 0.6.0

package/dist/testing.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.mjs","names":[],"sources":["../src/testing/index.ts"],"sourcesContent":["/**\n * `@znight/websocket/testing` (RFC 0003 §5.10): fakes for unit tests of gateways and services.\n * `createTestConnection()` is a `WsConnection` recording what the code under test sends to it;\n * `createTestServer()` is a `WsServer` recording broadcasts instead of delivering them.\n *\n * ```ts\n * const server = createTestServer({ paths: [[ChatGateway, '/chat']] })\n * const { instance } = await TestBed.create(ChatGateway, { metadata, overrides: [[WsServer, server]] })\n * const conn = createTestConnection<ChatData, ChatEvents>({ data: { user: ALICE }, rooms: ['general'] })\n * await instance.send(conn, { room: 'general', text: 'hi' })\n * expect(server.broadcasts).toEqual([{ gateway: '/chat', rooms: ['general'], except: [], event: 'message.new', data: MESSAGE }])\n * ```\n */\nimport type { HttpContext } from '@znight/http'\nimport type { WsCloseInfo, WsConnection, WsSendResult } from '../connection.ts'\nimport type { Broadcast } from '../rooms.ts'\nimport type { GatewayChannel, GatewayRef } from '../server.ts'\n\nimport { WsServer } from '../server.ts'\n\n/** One recorded broadcast (or a `close`, `join` or `leave` of a selection). */\nexport interface RecordedBroadcast {\n  /** The gateway path, or the class name when no path was given for it. */\n  readonly gateway: string\n  /** Selected rooms, `[]` for every connection of the gateway. */\n  readonly rooms: readonly string[]\n  /** Excluded connection ids. */\n  readonly except: readonly string[]\n  /** Excluded rooms (omitted when none). */\n  readonly exceptRooms?: readonly string[]\n  /** The emitted event, `undefined` for `send()` and the selection operations. */\n  readonly event?: string\n  readonly data?: unknown\n  /** A raw frame (`send()`). */\n  readonly frame?: string | Uint8Array\n  /** `join`, `leave` or `close` of the selection. */\n  readonly action?: 'join' | 'leave' | 'close'\n  readonly room?: string\n}\n\n/** Options of {@link createTestConnection}. */\nexport interface TestConnectionOptions<TData extends object> {\n  readonly id?: string\n  /** Gateway path. Default: `'/'`. */\n  readonly gateway?: string\n  readonly data?: TData\n  readonly rooms?: readonly string[]\n  readonly params?: Readonly<Record<string, string>>\n  readonly protocol?: string\n  readonly requestId?: string\n  /** The handshake context. Default: a minimal object with `params`, `query`, `headers` and `state`. */\n  readonly handshake?: Partial<HttpContext>\n}\n\n/** A fake connection: a `WsConnection` with the record of what it was sent. */\nexport interface TestConnection<\n  TData extends object = Record<string, unknown>,\n  E extends object = Record<string, unknown>,\n> extends WsConnection<TData, E> {\n  /** Events emitted to this connection only (`conn.emit`), in order. */\n  readonly emitted: { readonly event: string; readonly data: unknown }[]\n  /** Raw frames sent to this connection (`conn.send`). */\n  readonly sent: (string | Uint8Array)[]\n  /** Broadcasts made through `conn.to()` (the connection itself is in `except`). */\n  readonly broadcasts: RecordedBroadcast[]\n}\n\n/** A fake server: a `WsServer` recording broadcasts. */\nexport interface TestServer extends WsServer {\n  readonly broadcasts: RecordedBroadcast[]\n}\n\ntype Record_ = (entry: RecordedBroadcast) => void\n\n/** A selection recording what is done with it. */\nclass RecordingBroadcast<E extends object> implements Broadcast<E> {\n  readonly #gateway: string\n  readonly #rooms: readonly string[]\n  readonly #except: readonly string[]\n  readonly #exceptRooms: readonly string[]\n  readonly #record: Record_\n\n  constructor(\n    gateway: string,\n    rooms: readonly string[],\n    except: readonly string[],\n    exceptRooms: readonly string[],\n    record: Record_,\n  ) {\n    this.#gateway = gateway\n    this.#rooms = rooms\n    this.#except = except\n    this.#exceptRooms = exceptRooms\n    this.#record = record\n  }\n\n  to(room: string | readonly string[]): Broadcast<E> {\n    return new RecordingBroadcast(\n      this.#gateway,\n      [...this.#rooms, ...list(room)],\n      this.#except,\n      this.#exceptRooms,\n      this.#record,\n    )\n  }\n\n  except(target: string | { readonly id: string } | readonly (string | { readonly id: string })[]): Broadcast<E> {\n    const refs = Array.isArray(target) ? target : [target]\n    const ids = refs.map(ref => (typeof ref === 'string' ? ref : (ref as { readonly id: string }).id))\n    return new RecordingBroadcast(\n      this.#gateway,\n      this.#rooms,\n      [...this.#except, ...ids],\n      this.#exceptRooms,\n      this.#record,\n    )\n  }\n\n  exceptRoom(room: string | readonly string[]): Broadcast<E> {\n    return new RecordingBroadcast(\n      this.#gateway,\n      this.#rooms,\n      this.#except,\n      [...this.#exceptRooms, ...list(room)],\n      this.#record,\n    )\n  }\n\n  emit<K extends keyof E & string>(event: K, data: E[K]): void {\n    this.#record({ ...this.#base(), event, data })\n  }\n\n  send(frame: string | Uint8Array): void {\n    this.#record({ ...this.#base(), frame })\n  }\n\n  join(room: string): void {\n    this.#record({ ...this.#base(), action: 'join', room })\n  }\n\n  leave(room: string): void {\n    this.#record({ ...this.#base(), action: 'leave', room })\n  }\n\n  close(): void {\n    this.#record({ ...this.#base(), action: 'close' })\n  }\n\n  #base(): RecordedBroadcast {\n    return {\n      gateway: this.#gateway,\n      rooms: [...this.#rooms],\n      except: [...this.#except],\n      ...(this.#exceptRooms.length === 0 ? {} : { exceptRooms: [...this.#exceptRooms] }),\n    }\n  }\n}\n\nfunction list(value: string | readonly string[]): readonly string[] {\n  return typeof value === 'string' ? [value] : value\n}\n\n/** Creates a fake connection for unit tests. */\nexport function createTestConnection<\n  TData extends object = Record<string, unknown>,\n  E extends object = Record<string, unknown>,\n>(options: TestConnectionOptions<TData> = {}): TestConnection<TData, E> {\n  const id = options.id ?? crypto.randomUUID()\n  const gateway = options.gateway ?? '/'\n  const rooms = new Set(options.rooms ?? [])\n  const abort = new AbortController()\n  const params = options.params ?? {}\n  const handshake = {\n    params,\n    query: {},\n    headers: {},\n    state: new Map(),\n    requestId: options.requestId ?? 'test-request',\n    ...options.handshake,\n  } as unknown as HttpContext\n  let state: 'open' | 'closing' | 'closed' = 'open'\n  let closeInfo: WsCloseInfo | undefined\n  const emitted: { event: string; data: unknown }[] = []\n  const sent: (string | Uint8Array)[] = []\n  const broadcasts: RecordedBroadcast[] = []\n  const result = (): WsSendResult => (state === 'open' ? 'sent' : 'dropped')\n  const connection: TestConnection<TData, E> = {\n    id,\n    gateway,\n    requestId: options.requestId ?? 'test-request',\n    handshake,\n    params,\n    protocol: options.protocol ?? '',\n    data: (options.data ?? {}) as TData,\n    rooms,\n    get readyState() {\n      return state\n    },\n    bufferedAmount: 0,\n    signal: abort.signal,\n    get closeInfo() {\n      return closeInfo\n    },\n    emitted,\n    sent,\n    broadcasts,\n    emit(event, data) {\n      if (state === 'open') emitted.push({ event, data })\n      return result()\n    },\n    send(frame) {\n      if (state === 'open') sent.push(frame)\n      return result()\n    },\n    join(room) {\n      for (const name of list(room)) rooms.add(name)\n    },\n    leave(room) {\n      rooms.delete(room)\n    },\n    to(room) {\n      return new RecordingBroadcast<E>(gateway, list(room), [id], [], entry => broadcasts.push(entry))\n    },\n    drained() {\n      return state === 'open' ? Promise.resolve() : Promise.reject(new Error('The WebSocket connection is closed'))\n    },\n    close(code = 1000, reason = '') {\n      if (state !== 'open') return\n      state = 'closed'\n      closeInfo = { code, reason, initiator: 'server' }\n      abort.abort()\n    },\n    terminate() {\n      if (state !== 'open') return\n      state = 'closed'\n      closeInfo = { code: 1006, reason: '', initiator: 'server' }\n      abort.abort()\n    },\n  }\n  return connection\n}\n\n/** Options of {@link createTestServer}. */\nexport interface TestServerOptions {\n  /** Paths of gateway classes, for the `gateway` of recorded broadcasts (`[[ChatGateway, '/chat']]`). */\n  readonly paths?: readonly (readonly [abstract new (...args: never[]) => object, string])[]\n}\n\n/** Creates a fake `WsServer` recording broadcasts (no connection, every room empty). */\nexport function createTestServer(options: TestServerOptions = {}): TestServer {\n  const paths = new Map<unknown, string>(options.paths ?? [])\n  const broadcasts: RecordedBroadcast[] = []\n  const record: Record_ = entry => broadcasts.push(entry)\n  class FakeServer extends WsServer {\n    readonly broadcasts: RecordedBroadcast[] = broadcasts\n\n    override get connections(): number {\n      return 0\n    }\n\n    override of<E extends object = Record<string, unknown>>(gateway: GatewayRef): GatewayChannel<E> {\n      const path = typeof gateway === 'string' ? gateway : (paths.get(gateway) ?? gateway.name)\n      const all = (): RecordingBroadcast<E> => new RecordingBroadcast<E>(path, [], [], [], record)\n      return {\n        path,\n        size: 0,\n        connection: () => undefined,\n        connections: () => [][Symbol.iterator](),\n        members: () => new Set(),\n        rooms: () => new Map(),\n        to: room => all().to(room),\n        except: target => all().except(target as never),\n        emit: (event, data) => all().emit(event, data),\n        send: frame => all().send(frame),\n      }\n    }\n  }\n  return new FakeServer()\n}\n"],"mappings":"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"}

package/dist/transport-xnJqvB93.d.mts

@@ -0,0 +1,63 @@
+import { BunUpgrade, HeaderValue, MemoryUpgrade, NodeUpgrade } from "@znight/http";
+/** Server-wide settings given once at bootstrap. */
+interface TransportSettings {
+  /** The largest inbound message any gateway accepts, in bytes. */
+  readonly maxPayload: number;
+  /** The largest outbound buffer any gateway tolerates, in bytes. */
+  readonly backpressureLimit: number;
+  /** Heartbeat interval in ms, `0` when disabled. */
+  readonly heartbeatMs: number;
+}
+/** What {@link WebSocketTransport.accept} receives besides the native upgrade. */
+interface AcceptInit {
+  /** The selected subprotocol, `''` when none. */
+  readonly protocol: string;
+  /** Extra headers of the `101` response. */
+  readonly headers: Readonly<Record<string, HeaderValue>>;
+  /** The largest inbound message of the gateway, in bytes. */
+  readonly maxPayload: number;
+}
+/** The socket events of one connection, given to the transport by the plugin. */
+interface SocketEvents {
+  message(frame: string | Uint8Array, binary: boolean): void;
+  pong(): void;
+  /**
+   * The outbound buffer may have shrunk (after a write, or Bun's `drain`): the connection compares it
+   * with its own threshold, and polls the buffer while `conn.drained()` waits.
+   */
+  drain(): void;
+  close(code: number, reason: string): void;
+}
+/** The result of {@link TransportSocket.send}. */
+type SendStatus = "sent" | "queued" | "dropped";
+/** One accepted connection, the only object holding native handles. */
+interface TransportSocket {
+  send(frame: string | Uint8Array, binary: boolean): SendStatus;
+  readonly bufferedAmount: number;
+  ping(): void;
+  /** Stops reading; `false` when the transport cannot pause. */
+  pause(): boolean;
+  resume(): void;
+  close(code: number, reason: string): void;
+  terminate(): void;
+  /** Negotiated extensions (`permessage-deflate`...), `''` when none. */
+  readonly extensions: string;
+}
+/** A transport: `ws` on `node:http` servers, Bun's built-in WebSocket on `Bun.serve()`, or memory. */
+interface WebSocketTransport {
+  readonly name: string;
+  /** Which native upgrade it completes. */
+  readonly accepts: "node" | "bun" | "memory";
+  configure(settings: TransportSettings): void;
+  accept(native: NodeUpgrade | BunUpgrade | MemoryUpgrade, init: AcceptInit, events: SocketEvents): TransportSocket | Promise<TransportSocket>;
+  /**
+   * Loads what the transport needs before the server listens (the `ws` package), so that a missing
+   * dependency fails the startup (ZNIGHT051) rather than the first handshake.
+   */
+  ready?(): Promise<void>;
+  /** `Bun.serve()` transports only: the settings of its `websocket` option. */
+  bunWebSocket?(): Readonly<Record<string, unknown>>;
+  close(): Promise<void>;
+}
+export { TransportSocket as a, TransportSettings as i, SendStatus as n, WebSocketTransport as o, SocketEvents as r, AcceptInit as t };
+//# sourceMappingURL=transport-xnJqvB93.d.mts.map

package/dist/ws.d.mts

@@ -0,0 +1,9 @@
+import { o as WebSocketTransport } from "./transport-xnJqvB93.mjs";
+/** Options of {@link wsTransport}. */
+export interface WsTransportOptions {
+  /** `permessage-deflate` (`ws` option). Default: `false`. */
+  readonly perMessageDeflate?: boolean | Record<string, unknown>;
+}
+/** The `ws` transport: completes the `node` upgrades of `node:http` servers. */
+export declare function wsTransport(options?: WsTransportOptions): WebSocketTransport;
+//# sourceMappingURL=ws.d.mts.map

package/dist/ws.mjs

@@ -0,0 +1,143 @@
+import { ErrorCode, ZnightError } from "@znight/core";
+import { HttpException } from "@znight/http";
+// src/transports/ws.ts
+let loading;
+function loadWs() {
+	loading ??= import("ws").then((module) => module.WebSocketServer === void 0 && module.default !== void 0 ? module.default : module, (cause) => {
+		loading = void 0;
+		throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, "The \"ws\" package is required to serve WebSocket gateways on Node.js", {
+			hints: ["Install it: npm install ws"],
+			cause
+		});
+	});
+	return loading;
+}
+function toFrame(data, binary) {
+	let bytes;
+	if (Array.isArray(data)) bytes = Buffer.concat(data);
+	else if (data instanceof ArrayBuffer) bytes = new Uint8Array(data);
+	else bytes = data;
+	return binary ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength) : Buffer.from(bytes).toString("utf8");
+}
+/** One `ws` connection. */
+var WsTransportSocket = class {
+	#ws;
+	#limit;
+	/** `drain` after every write: the connection compares the buffer with its own threshold. */
+	#events;
+	constructor(ws, limit, events) {
+		this.#ws = ws;
+		this.#limit = limit;
+		this.#events = events;
+	}
+	get bufferedAmount() {
+		return this.#ws.bufferedAmount;
+	}
+	get extensions() {
+		return this.#ws.extensions;
+	}
+	send(frame, binary) {
+		if (this.#ws.readyState !== 1) return "dropped";
+		this.#ws.send(frame, { binary }, () => this.#events.drain());
+		return this.#ws.bufferedAmount <= this.#limit ? "sent" : "queued";
+	}
+	ping() {
+		this.#ws.ping();
+	}
+	pause() {
+		this.#ws.pause();
+		return true;
+	}
+	resume() {
+		this.#ws.resume();
+	}
+	close(code, reason) {
+		this.#ws.close(code, reason);
+	}
+	terminate() {
+		this.#ws.terminate();
+	}
+};
+/** The `ws` transport: completes the `node` upgrades of `node:http` servers. */
+function wsTransport(options = {}) {
+	let settings = {
+		maxPayload: 1048576,
+		backpressureLimit: 1048576,
+		heartbeatMs: 0
+	};
+	let server;
+	const pendingHeaders = /* @__PURE__ */ new WeakMap();
+	const sockets = /* @__PURE__ */ new Set();
+	async function serverOf() {
+		if (server !== void 0) return server;
+		const { WebSocketServer } = await loadWs();
+		server ??= new WebSocketServer({
+			noServer: true,
+			maxPayload: settings.maxPayload,
+			perMessageDeflate: options.perMessageDeflate ?? false,
+			clientTracking: false,
+			handleProtocols: (protocols, request) => {
+				const selected = request.znightProtocol ?? "";
+				return selected !== "" && protocols.has(selected) ? selected : false;
+			}
+		});
+		server.on("headers", (lines, request) => {
+			const extra = pendingHeaders.get(request);
+			if (extra === void 0) return;
+			for (const [name, value] of Object.entries(extra)) for (const item of typeof value === "string" ? [value] : value) lines.push(`${name}: ${item}`);
+		});
+		return server;
+	}
+	return {
+		name: "ws",
+		accepts: "node",
+		configure(next) {
+			settings = next;
+		},
+		async ready() {
+			await serverOf();
+		},
+		async accept(native, init, events) {
+			if (native.kind !== "node") throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, `wsTransport() completes node:http upgrades, not ${native.kind} upgrades`, { hints: ["Use bunTransport() with honoAdapter() on Bun"] });
+			const wss = await serverOf();
+			const request = native.request;
+			const raw = native.socket;
+			if (init.protocol === "") delete request.headers["sec-websocket-protocol"];
+			else request.headers["sec-websocket-protocol"] = init.protocol;
+			request.znightProtocol = init.protocol;
+			pendingHeaders.set(request, init.headers);
+			const ws = await new Promise((resolve, reject) => {
+				const aborted = () => reject(new HttpException(400, "The WebSocket handshake was aborted"));
+				if (raw.destroyed || !raw.writable) {
+					aborted();
+					return;
+				}
+				raw.once("close", aborted);
+				wss.handleUpgrade(request, raw, native.head, (accepted) => {
+					raw.removeListener("close", aborted);
+					resolve(accepted);
+				});
+			}).finally(() => pendingHeaders.delete(request));
+			sockets.add(ws);
+			const socket = new WsTransportSocket(ws, settings.backpressureLimit, events);
+			ws.on("error", () => void 0);
+			ws.on("message", (data, binary) => events.message(toFrame(data, binary), binary));
+			ws.on("pong", () => events.pong());
+			ws.on("close", (code, reason) => {
+				sockets.delete(ws);
+				events.close(code, reason.toString("utf8"));
+			});
+			return socket;
+		},
+		close() {
+			for (const ws of sockets) ws.terminate();
+			sockets.clear();
+			server?.close();
+			server = void 0;
+			return Promise.resolve();
+		}
+	};
+}
+export { wsTransport };
+
+//# sourceMappingURL=ws.mjs.map

package/dist/ws.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.mjs","names":[],"sources":["../src/transports/ws.ts"],"sourcesContent":["/**\n * The `ws` transport (RFC 0003 §8.3): completes the upgrades of every `node:http` adapter, on\n * Node.js and on Bun. `ws` is an optional peer dependency, loaded lazily on the first connection.\n *\n * ```ts\n * import { wsTransport } from '@znight/websocket/ws'\n * ```\n */\nimport type { BunUpgrade, HeaderValue, MemoryUpgrade, NodeUpgrade } from '@znight/http'\nimport type {\n  AcceptInit,\n  SendStatus,\n  SocketEvents,\n  TransportSettings,\n  TransportSocket,\n  WebSocketTransport,\n} from '../transport.ts'\n\nimport { ErrorCode, ZnightError } from '@znight/core'\nimport { HttpException } from '@znight/http'\n\n/** The part of a `ws` `WebSocket` the transport uses (no `@types/ws`). */\ninterface WsSocket {\n  /** `1` while open. */\n  readonly readyState: number\n  readonly bufferedAmount: number\n  readonly extensions: string\n  send(data: string | Uint8Array, options: { binary: boolean }, callback: (error?: Error) => void): void\n  ping(): void\n  pause(): void\n  resume(): void\n  close(code: number, reason: string): void\n  terminate(): void\n  on(event: 'message', listener: (data: Buffer | ArrayBuffer | Buffer[], binary: boolean) => void): void\n  on(event: 'pong', listener: () => void): void\n  on(event: 'close', listener: (code: number, reason: Buffer) => void): void\n  on(event: 'error', listener: (error: Error) => void): void\n}\n\n/** The part of a `ws` `WebSocketServer` the transport uses. */\ninterface WsServer {\n  handleUpgrade(request: unknown, socket: unknown, head: Uint8Array, callback: (ws: WsSocket) => void): void\n  on(event: 'headers', listener: (headers: string[], request: unknown) => void): void\n  close(): void\n}\n\n/** The part of the handshake's `net.Socket` the transport watches. */\ninterface NodeSocket {\n  readonly destroyed: boolean\n  readonly writable: boolean\n  once(event: 'close', listener: () => void): void\n  removeListener(event: 'close', listener: () => void): void\n}\n\n/** The part of the handshake's `IncomingMessage` the transport rewrites. */\ninterface NodeRequest {\n  znightProtocol?: string\n  readonly headers: Record<string, string | string[] | undefined>\n}\n\ninterface WsModule {\n  readonly WebSocketServer: new (options: Record<string, unknown>) => WsServer\n}\n\n/** Options of {@link wsTransport}. */\nexport interface WsTransportOptions {\n  /** `permessage-deflate` (`ws` option). Default: `false`. */\n  readonly perMessageDeflate?: boolean | Record<string, unknown>\n}\n\nlet loading: Promise<WsModule> | undefined\n\nfunction loadWs(): Promise<WsModule> {\n  const name = 'ws'\n  loading ??= (import(name) as Promise<WsModule & { default?: WsModule }>).then(\n    module => (module.WebSocketServer === undefined && module.default !== undefined ? module.default : module),\n    (cause: unknown) => {\n      loading = undefined\n      throw new ZnightError(\n        ErrorCode.WebSocketTransportUnavailable,\n        'The \"ws\" package is required to serve WebSocket gateways on Node.js',\n        { hints: ['Install it: npm install ws'], cause },\n      )\n    },\n  )\n  return loading\n}\n\nfunction toFrame(data: Buffer | ArrayBuffer | Buffer[], binary: boolean): string | Uint8Array {\n  let bytes: Uint8Array\n  if (Array.isArray(data)) bytes = Buffer.concat(data)\n  else if (data instanceof ArrayBuffer) bytes = new Uint8Array(data)\n  else bytes = data\n  return binary ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength) : Buffer.from(bytes).toString('utf8')\n}\n\n/** One `ws` connection. */\nclass WsTransportSocket implements TransportSocket {\n  readonly #ws: WsSocket\n  readonly #limit: number\n  /** `drain` after every write: the connection compares the buffer with its own threshold. */\n  readonly #events: SocketEvents\n\n  constructor(ws: WsSocket, limit: number, events: SocketEvents) {\n    this.#ws = ws\n    this.#limit = limit\n    this.#events = events\n  }\n\n  get bufferedAmount(): number {\n    return this.#ws.bufferedAmount\n  }\n\n  get extensions(): string {\n    return this.#ws.extensions\n  }\n\n  send(frame: string | Uint8Array, binary: boolean): SendStatus {\n    if (this.#ws.readyState !== 1) return 'dropped'\n    this.#ws.send(frame, { binary }, () => this.#events.drain())\n    return this.#ws.bufferedAmount <= this.#limit ? 'sent' : 'queued'\n  }\n\n  ping(): void {\n    this.#ws.ping()\n  }\n\n  pause(): boolean {\n    this.#ws.pause()\n    return true\n  }\n\n  resume(): void {\n    this.#ws.resume()\n  }\n\n  close(code: number, reason: string): void {\n    this.#ws.close(code, reason)\n  }\n\n  terminate(): void {\n    this.#ws.terminate()\n  }\n}\n\n/** The `ws` transport: completes the `node` upgrades of `node:http` servers. */\nexport function wsTransport(options: WsTransportOptions = {}): WebSocketTransport {\n  let settings: TransportSettings = { maxPayload: 1024 * 1024, backpressureLimit: 1024 * 1024, heartbeatMs: 0 }\n  let server: WsServer | undefined\n  const pendingHeaders = new WeakMap<object, Readonly<Record<string, HeaderValue>>>()\n  const sockets = new Set<WsSocket>()\n\n  async function serverOf(): Promise<WsServer> {\n    if (server !== undefined) return server\n    const { WebSocketServer } = await loadWs()\n    server ??= new WebSocketServer({\n      noServer: true,\n      maxPayload: settings.maxPayload,\n      perMessageDeflate: options.perMessageDeflate ?? false,\n      clientTracking: false,\n      handleProtocols: (protocols: Set<string>, request: object) => {\n        const selected = (request as { znightProtocol?: string }).znightProtocol ?? ''\n        return selected !== '' && protocols.has(selected) ? selected : false\n      },\n    })\n    server.on('headers', (lines, request) => {\n      const extra = pendingHeaders.get(request as object)\n      if (extra === undefined) return\n      for (const [name, value] of Object.entries(extra)) {\n        for (const item of typeof value === 'string' ? [value] : value) lines.push(`${name}: ${item}`)\n      }\n    })\n    return server\n  }\n\n  return {\n    name: 'ws',\n    accepts: 'node',\n    configure(next: TransportSettings): void {\n      settings = next\n    },\n    async ready(): Promise<void> {\n      await serverOf()\n    },\n    async accept(\n      native: NodeUpgrade | BunUpgrade | MemoryUpgrade,\n      init: AcceptInit,\n      events: SocketEvents,\n    ): Promise<TransportSocket> {\n      if (native.kind !== 'node') {\n        throw new ZnightError(\n          ErrorCode.WebSocketTransportUnavailable,\n          `wsTransport() completes node:http upgrades, not ${native.kind} upgrades`,\n          { hints: ['Use bunTransport() with honoAdapter() on Bun'] },\n        )\n      }\n      const wss = await serverOf()\n      const request = native.request as NodeRequest\n      const raw = native.socket as NodeSocket\n      // the plugin selected the subprotocol: ws would abort (400, no callback) on a header it cannot parse\n      if (init.protocol === '') delete request.headers['sec-websocket-protocol']\n      else request.headers['sec-websocket-protocol'] = init.protocol\n      request.znightProtocol = init.protocol\n      pendingHeaders.set(request, init.headers)\n      // ws destroys the socket without calling back when the client left or a header is malformed\n      const ws = await new Promise<WsSocket>((resolve, reject) => {\n        const aborted = (): void => reject(new HttpException(400, 'The WebSocket handshake was aborted'))\n        if (raw.destroyed || !raw.writable) {\n          aborted()\n          return\n        }\n        raw.once('close', aborted)\n        wss.handleUpgrade(request, raw, native.head, accepted => {\n          raw.removeListener('close', aborted)\n          resolve(accepted)\n        })\n      }).finally(() => pendingHeaders.delete(request))\n      sockets.add(ws)\n      const socket = new WsTransportSocket(ws, settings.backpressureLimit, events)\n      ws.on('error', () => undefined) // reported through 'close'; an unhandled 'error' would kill the process\n      ws.on('message', (data, binary) => events.message(toFrame(data, binary), binary))\n      ws.on('pong', () => events.pong())\n      ws.on('close', (code, reason) => {\n        sockets.delete(ws)\n        events.close(code, reason.toString('utf8'))\n      })\n      return socket\n    },\n    close(): Promise<void> {\n      for (const ws of sockets) ws.terminate()\n      sockets.clear()\n      server?.close()\n      server = undefined\n      return Promise.resolve()\n    },\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -1 +1,102 @@
-{ "name": "@znight/websocket", "version": "0.0.0", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/znight-org/znight.git" } }
+{
+  "name": "@znight/websocket",
+  "version": "0.6.0",
+  "description": "Znight WebSocket gateways served by the HTTP server, validated at build time",
+  "license": "MIT",
+  "author": "Ugho STEPHAN",
+  "homepage": "https://github.com/znight-org/znight/tree/main/packages/websocket#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znight-org/znight.git",
+    "directory": "packages/websocket"
+  },
+  "bugs": "https://github.com/znight-org/znight/issues",
+  "keywords": ["znight", "websocket", "realtime", "gateway"],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "@znight/source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./ws": {
+      "@znight/source": "./src/transports/ws.ts",
+      "types": "./dist/ws.d.mts",
+      "default": "./dist/ws.mjs"
+    },
+    "./bun": {
+      "@znight/source": "./src/transports/bun.ts",
+      "types": "./dist/bun.d.mts",
+      "default": "./dist/bun.mjs"
+    },
+    "./testing": {
+      "@znight/source": "./src/testing/index.ts",
+      "types": "./dist/testing.d.mts",
+      "default": "./dist/testing.mjs"
+    },
+    "./compiler": {
+      "@znight/source": "./src/compiler/index.ts",
+      "types": "./dist/compiler.d.mts",
+      "default": "./dist/compiler.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test": "bun test --conditions=@znight/source test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@znight/core": "0.6.0",
+    "@znight/http": "0.6.0"
+  },
+  "peerDependencies": {
+    "@znight/compiler": "^0.6.0",
+    "ws": "^8.21.0"
+  },
+  "peerDependenciesMeta": {
+    "@znight/compiler": {
+      "optional": true
+    },
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@znight/compiler": "0.6.0",
+    "@znight/testing": "0.6.0",
+    "hono": "4.13.14",
+    "ws": "8.22.0",
+    "zod": "4.6.7"
+  },
+  "znight": {
+    "apiVersion": 1,
+    "compiler": "@znight/websocket/compiler",
+    "provides": [
+      {
+        "export": "WsServer",
+        "plugin": "WebSocketPlugin",
+        "scope": "singleton"
+      },
+      {
+        "export": "WebSocketPlugin",
+        "plugin": "WebSocketPlugin",
+        "scope": "singleton"
+      },
+      {
+        "export": "WsConnection",
+        "plugin": "WebSocketPlugin",
+        "scope": "request"
+      }
+    ]
+  }
+}

package/src/client.ts

@@ -0,0 +1,246 @@
+/**
+ * The client of `WebSocketPlugin.connect()` (RFC 0003 §5.10): an in-memory connection that speaks
+ * the `events` protocol (requests, replies, server events) or sends raw frames, with every received
+ * frame buffered from the start so that tests never race the server.
+ */
+import type { InjectResponse } from '@znight/http'
+import type { MemoryClient, MemoryCloseInfo } from './transports/memory.ts'
+
+/** Options of `WebSocketPlugin.connect()`. */
+export interface WsConnectOptions {
+  /** Query parameters appended to the path. */
+  readonly query?: Readonly<Record<string, string | readonly string[]>>
+  /** Request headers of the handshake. */
+  readonly headers?: Readonly<Record<string, string>>
+  /** Offered subprotocols (`sec-websocket-protocol`), in preference order. */
+  readonly protocols?: readonly string[]
+  /** The `origin` header (a browser's). Default: none, like a non-browser client. */
+  readonly origin?: string
+  /** Cookies of the handshake. */
+  readonly cookies?: Readonly<Record<string, string>>
+}
+
+/** Options of the waiting methods of {@link WsClient}. */
+export interface WsWaitOptions {
+  /** Default: 1 000 ms (`request()`: 5 000 ms). */
+  readonly timeoutMs?: number
+}
+
+/** A refused handshake: the HTTP response the server answered. */
+export class WsHandshakeError extends Error {
+  readonly status: number
+  readonly headers: Readonly<Record<string, string | string[]>>
+  readonly body: string
+  readonly #response: InjectResponse
+
+  constructor(response: InjectResponse) {
+    super(`The WebSocket handshake was refused with ${response.status}: ${response.body}`)
+    this.name = 'WsHandshakeError'
+    this.status = response.status
+    this.headers = response.headers
+    this.body = response.body
+    this.#response = response
+  }
+
+  /** The body parsed as JSON. */
+  json<T = unknown>(): T {
+    return this.#response.json<T>()
+  }
+}
+
+/** The failure reply of a request (`{ id, error }`). */
+export class WsRequestError extends Error {
+  readonly code: string
+  readonly details: unknown
+
+  constructor(
+    event: string,
+    error: { readonly code?: unknown; readonly message?: unknown; readonly details?: unknown },
+  ) {
+    super(typeof error.message === 'string' ? error.message : `The request "${event}" failed`)
+    this.name = 'WsRequestError'
+    this.code = typeof error.code === 'string' ? error.code : 'INTERNAL'
+    this.details = error.details
+  }
+}
+
+interface Entry {
+  readonly frame: string | Uint8Array
+  /** The decoded envelope, `undefined` for a binary or non-JSON frame. */
+  readonly envelope: Readonly<Record<string, unknown>> | undefined
+  /** Taken by `next()` or a request. */
+  consumed: boolean
+  /** Taken by `nextRaw()`. */
+  rawConsumed: boolean
+}
+
+interface Waiter {
+  readonly match: (entry: Entry) => boolean
+  readonly take: (entry: Entry) => void
+}
+
+function decode(frame: string | Uint8Array): Readonly<Record<string, unknown>> | undefined {
+  if (typeof frame !== 'string') return undefined
+  try {
+    const value: unknown = JSON.parse(frame)
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** An in-memory WebSocket client (`WebSocketPlugin.connect()`, `TestApp.connect()`). */
+export class WsClient implements AsyncDisposable {
+  readonly #peer: MemoryClient
+  readonly #entries: Entry[] = []
+  readonly #waiters = new Set<Waiter>()
+  readonly #closed: PromiseWithResolvers<MemoryCloseInfo> = Promise.withResolvers()
+  #nextId = 1
+
+  /** @internal Created by `WebSocketPlugin.connect()` once the handshake succeeded. */
+  constructor(peer: MemoryClient) {
+    this.#peer = peer
+    for (const frame of peer.received) this.#receive(frame)
+    peer.onmessage = frame => this.#receive(frame)
+    const ended = peer.closed
+    if (ended === undefined) {
+      peer.onclose = info => this.#closed.resolve(info)
+    } else {
+      this.#closed.resolve(ended)
+    }
+  }
+
+  /** The negotiated subprotocol, `''` when none. */
+  get protocol(): string {
+    return this.#peer.protocol
+  }
+
+  /** Every frame received, in order: JSON objects decoded, other text frames as strings, binary frames as bytes. */
+  get frames(): readonly unknown[] {
+    return this.#entries.map(entry => entry.envelope ?? entry.frame)
+  }
+
+  /** Resolves once the connection closed (by either side). */
+  get closed(): Promise<MemoryCloseInfo> {
+    return this.#closed.promise
+  }
+
+  /** Sends an event without id (fire and forget). */
+  send(event: string, data?: unknown): void {
+    this.#peer.send(JSON.stringify(data === undefined ? { event } : { event, data }))
+  }
+
+  /** Sends a request and resolves with the `data` of its reply; rejects with {@link WsRequestError}. */
+  request<T = unknown>(event: string, data?: unknown, options: WsWaitOptions = {}): Promise<T> {
+    const id = this.#nextId++
+    const reply = this.#wait<T>(
+      entry => !entry.consumed && entry.envelope?.['id'] === id && entry.envelope['event'] === undefined,
+      (entry, resolve, reject) => {
+        entry.consumed = true
+        const envelope = entry.envelope as Record<string, unknown>
+        if (envelope['error'] === undefined) {
+          resolve(envelope['data'] as T)
+        } else {
+          reject(new WsRequestError(event, envelope['error'] as object))
+        }
+      },
+      options.timeoutMs ?? 5_000,
+      `the reply to "${event}" (id ${id})`,
+    )
+    this.#peer.send(JSON.stringify(data === undefined ? { event, id } : { event, data, id }))
+    return reply
+  }
+
+  /** The `data` of the oldest server event (matching `event`) not taken yet. */
+  next<T = unknown>(event?: string, options: WsWaitOptions = {}): Promise<T> {
+    return this.#wait<T>(
+      entry =>
+        !entry.consumed &&
+        typeof entry.envelope?.['event'] === 'string' &&
+        (event === undefined || entry.envelope['event'] === event),
+      (entry, resolve) => {
+        entry.consumed = true
+        resolve((entry.envelope as Record<string, unknown>)['data'] as T)
+      },
+      options.timeoutMs ?? 1_000,
+      event === undefined ? 'a server event' : `the event "${event}"`,
+    )
+  }
+
+  /** Sends a frame as is (a string is a text frame). */
+  sendRaw(frame: string | Uint8Array): void {
+    this.#peer.send(frame)
+  }
+
+  /** The oldest frame not taken by `nextRaw()` yet, as received. */
+  nextRaw(options: WsWaitOptions = {}): Promise<string | Uint8Array> {
+    return this.#wait<string | Uint8Array>(
+      entry => !entry.rawConsumed,
+      (entry, resolve) => {
+        entry.rawConsumed = true
+        resolve(entry.frame)
+      },
+      options.timeoutMs ?? 1_000,
+      'a frame',
+    )
+  }
+
+  /** Closes the connection and resolves with how it closed. */
+  close(code = 1000, reason = ''): Promise<MemoryCloseInfo> {
+    this.#peer.close(code, reason)
+    return this.#closed.promise
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.close()
+  }
+
+  #wait<T>(
+    match: (entry: Entry) => boolean,
+    take: (entry: Entry, resolve: (value: T) => void, reject: (error: Error) => void) => void,
+    timeoutMs: number,
+    what: string,
+  ): Promise<T> {
+    const { promise, resolve, reject } = Promise.withResolvers<T>()
+    const found = this.#entries.find(match)
+    if (found !== undefined) {
+      take(found, resolve, reject)
+      return promise
+    }
+    if (this.#peer.closed !== undefined) {
+      reject(new Error(`The WebSocket connection is closed: no ${what} will arrive`))
+      return promise
+    }
+    const timer = setTimeout(() => {
+      this.#waiters.delete(waiter)
+      reject(new Error(`Timed out after ${timeoutMs} ms waiting for ${what}`))
+    }, timeoutMs)
+    const waiter: Waiter = {
+      match,
+      take: entry => {
+        clearTimeout(timer)
+        take(entry, resolve, reject)
+      },
+    }
+    this.#waiters.add(waiter)
+    void this.#closed.promise.then(() => {
+      if (!this.#waiters.delete(waiter)) return
+      clearTimeout(timer)
+      reject(new Error(`The WebSocket connection closed while waiting for ${what}`))
+    })
+    return promise
+  }
+
+  #receive(frame: string | Uint8Array): void {
+    const entry: Entry = { frame, envelope: decode(frame), consumed: false, rawConsumed: false }
+    this.#entries.push(entry)
+    // waiters in arrival order; each re-checks the entry, which an earlier waiter may have taken
+    for (const waiter of this.#waiters) {
+      if (!waiter.match(entry)) continue
+      this.#waiters.delete(waiter)
+      waiter.take(entry)
+    }
+  }
+}