@znight/websocket 0.0.0-stage → 0.6.0

package/dist/index.mjs

@@ -0,0 +1,2088 @@
+import { t as WsServer } from "./server-D40_bC88.mjs";
+import { bunTransport } from "./bun.mjs";
+import { wsTransport } from "./ws.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ErrorCode, ZnightError, displayName, resolveOptions } from "@znight/core";
+import { BadRequestException, ForbiddenException, HttpException, ValidationException, parseByteSize, validate } from "@znight/http";
+// src/client.ts
+/** A refused handshake: the HTTP response the server answered. */
+var WsHandshakeError = class extends Error {
+	status;
+	headers;
+	body;
+	#response;
+	constructor(response) {
+		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() {
+		return this.#response.json();
+	}
+};
+/** The failure reply of a request (`{ id, error }`). */
+var WsRequestError = class extends Error {
+	code;
+	details;
+	constructor(event, error) {
+		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;
+	}
+};
+function decode(frame) {
+	if (typeof frame !== "string") return void 0;
+	try {
+		const value = JSON.parse(frame);
+		return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/** An in-memory WebSocket client (`WebSocketPlugin.connect()`, `TestApp.connect()`). */
+var WsClient = class {
+	#peer;
+	#entries = [];
+	#waiters = /* @__PURE__ */ new Set();
+	#closed = Promise.withResolvers();
+	#nextId = 1;
+	/** @internal Created by `WebSocketPlugin.connect()` once the handshake succeeded. */
+	constructor(peer) {
+		this.#peer = peer;
+		for (const frame of peer.received) this.#receive(frame);
+		peer.onmessage = (frame) => this.#receive(frame);
+		const ended = peer.closed;
+		if (ended === void 0) peer.onclose = (info) => this.#closed.resolve(info);
+		else this.#closed.resolve(ended);
+	}
+	/** The negotiated subprotocol, `''` when none. */
+	get protocol() {
+		return this.#peer.protocol;
+	}
+	/** Every frame received, in order: JSON objects decoded, other text frames as strings, binary frames as bytes. */
+	get frames() {
+		return this.#entries.map((entry) => entry.envelope ?? entry.frame);
+	}
+	/** Resolves once the connection closed (by either side). */
+	get closed() {
+		return this.#closed.promise;
+	}
+	/** Sends an event without id (fire and forget). */
+	send(event, data) {
+		this.#peer.send(JSON.stringify(data === void 0 ? { event } : {
+			event,
+			data
+		}));
+	}
+	/** Sends a request and resolves with the `data` of its reply; rejects with {@link WsRequestError}. */
+	request(event, data, options = {}) {
+		const id = this.#nextId++;
+		const reply = this.#wait((entry) => !entry.consumed && entry.envelope?.["id"] === id && entry.envelope["event"] === void 0, (entry, resolve, reject) => {
+			entry.consumed = true;
+			const envelope = entry.envelope;
+			if (envelope["error"] === void 0) resolve(envelope["data"]);
+			else reject(new WsRequestError(event, envelope["error"]));
+		}, options.timeoutMs ?? 5e3, `the reply to "${event}" (id ${id})`);
+		this.#peer.send(JSON.stringify(data === void 0 ? {
+			event,
+			id
+		} : {
+			event,
+			data,
+			id
+		}));
+		return reply;
+	}
+	/** The `data` of the oldest server event (matching `event`) not taken yet. */
+	next(event, options = {}) {
+		return this.#wait((entry) => !entry.consumed && typeof entry.envelope?.["event"] === "string" && (event === void 0 || entry.envelope["event"] === event), (entry, resolve) => {
+			entry.consumed = true;
+			resolve(entry.envelope["data"]);
+		}, options.timeoutMs ?? 1e3, event === void 0 ? "a server event" : `the event "${event}"`);
+	}
+	/** Sends a frame as is (a string is a text frame). */
+	sendRaw(frame) {
+		this.#peer.send(frame);
+	}
+	/** The oldest frame not taken by `nextRaw()` yet, as received. */
+	nextRaw(options = {}) {
+		return this.#wait((entry) => !entry.rawConsumed, (entry, resolve) => {
+			entry.rawConsumed = true;
+			resolve(entry.frame);
+		}, options.timeoutMs ?? 1e3, "a frame");
+	}
+	/** Closes the connection and resolves with how it closed. */
+	close(code = 1e3, reason = "") {
+		this.#peer.close(code, reason);
+		return this.#closed.promise;
+	}
+	async [Symbol.asyncDispose]() {
+		await this.close();
+	}
+	#wait(match, take, timeoutMs, what) {
+		const { promise, resolve, reject } = Promise.withResolvers();
+		const found = this.#entries.find(match);
+		if (found !== void 0) {
+			take(found, resolve, reject);
+			return promise;
+		}
+		if (this.#peer.closed !== void 0) {
+			reject(/* @__PURE__ */ new Error(`The WebSocket connection is closed: no ${what} will arrive`));
+			return promise;
+		}
+		const timer = setTimeout(() => {
+			this.#waiters.delete(waiter);
+			reject(/* @__PURE__ */ new Error(`Timed out after ${timeoutMs} ms waiting for ${what}`));
+		}, timeoutMs);
+		const waiter = {
+			match,
+			take: (entry) => {
+				clearTimeout(timer);
+				take(entry, resolve, reject);
+			}
+		};
+		this.#waiters.add(waiter);
+		this.#closed.promise.then(() => {
+			if (!this.#waiters.delete(waiter)) return;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`The WebSocket connection closed while waiting for ${what}`));
+		});
+		return promise;
+	}
+	#receive(frame) {
+		const entry = {
+			frame,
+			envelope: decode(frame),
+			consumed: false,
+			rawConsumed: false
+		};
+		this.#entries.push(entry);
+		for (const waiter of this.#waiters) {
+			if (!waiter.match(entry)) continue;
+			this.#waiters.delete(waiter);
+			waiter.take(entry);
+		}
+	}
+};
+// src/exceptions.ts
+/** Exceptions of WebSocket handlers and their wire codes (RFC 0003 §5.3, §5.8). */
+/** Built-in error codes of the wire protocol. */
+const WsErrorCode = {
+	BadFrame: "BAD_FRAME",
+	UnsupportedFrame: "UNSUPPORTED_FRAME",
+	BadRequest: "BAD_REQUEST",
+	Unauthorized: "UNAUTHORIZED",
+	Forbidden: "FORBIDDEN",
+	NotFound: "NOT_FOUND",
+	Conflict: "CONFLICT",
+	Unprocessable: "UNPROCESSABLE",
+	RateLimited: "RATE_LIMITED",
+	UnknownEvent: "UNKNOWN_EVENT",
+	Timeout: "TIMEOUT",
+	Internal: "INTERNAL"
+};
+/** Close codes used by the runtime (RFC 0003 §5.8, normative). */
+const WsCloseCode = {
+	Normal: 1e3,
+	GoingAway: 1001,
+	PolicyViolation: 1008,
+	MessageTooBig: 1009,
+	InternalError: 1011,
+	TryAgainLater: 1013
+};
+/**
+* An error a handler or a message guard throws to answer the client: a reply with an `id`, an
+* `$error` event otherwise, then a close when `close` is set.
+*
+* ```ts
+* throw new WsException('FORBIDDEN', 'Join the room first')
+* ```
+*/
+var WsException = class extends Error {
+	code;
+	details;
+	close;
+	constructor(code, message, details, options = {}) {
+		super(message ?? code, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "WsException";
+		this.code = code;
+		this.details = details;
+		this.close = options.close;
+	}
+};
+/** A payload failed its schema: `BAD_REQUEST` with `details: [{ path, message }]`. */
+var WsValidationException = class extends WsException {
+	issues;
+	constructor(issues, message = "Invalid payload") {
+		super(WsErrorCode.BadRequest, message, issues);
+		this.name = "WsValidationException";
+		this.issues = issues;
+	}
+};
+const BY_STATUS = {
+	400: WsErrorCode.BadRequest,
+	401: WsErrorCode.Unauthorized,
+	403: WsErrorCode.Forbidden,
+	404: WsErrorCode.NotFound,
+	409: WsErrorCode.Conflict,
+	422: WsErrorCode.Unprocessable,
+	429: WsErrorCode.RateLimited
+};
+/**
+* The wire code of an HTTP status thrown by a service (`HttpException`): the table of RFC 0003
+* §5.8, `INTERNAL` for 5xx and unknown statuses.
+*/
+function codeOfStatus(status) {
+	return BY_STATUS[status] ?? (status >= 400 && status < 500 ? WsErrorCode.BadRequest : WsErrorCode.Internal);
+}
+// src/connection.ts
+/** How often a pending `conn.drained()` re-reads the outbound buffer (ms). */
+const DRAIN_POLL_MS = 10;
+/** `conn.drained()` rejects with it once the connection is closed. */
+var WsClosedError = class extends Error {
+	constructor(message = "The WebSocket connection is closed") {
+		super(message);
+		this.name = "WsClosedError";
+	}
+};
+/** The mutable counters behind {@link WsStats} (internal). */
+var StatsCounter = class {
+	opened = 0;
+	closed = 0;
+	messagesIn = 0;
+	messagesOut = 0;
+	bytesIn = 0;
+	bytesOut = 0;
+	dropped = 0;
+	slowConsumerCloses = 0;
+	/** A frozen snapshot, with the number of open connections. */
+	snapshot(connections) {
+		return Object.freeze({
+			connections,
+			opened: this.opened,
+			closed: this.closed,
+			messagesIn: this.messagesIn,
+			messagesOut: this.messagesOut,
+			bytesIn: this.bytesIn,
+			bytesOut: this.bytesOut,
+			dropped: this.dropped,
+			slowConsumerCloses: this.slowConsumerCloses
+		});
+	}
+};
+function sizeOf(frame) {
+	return typeof frame === "string" ? Buffer.byteLength(frame) : frame.byteLength;
+}
+/** The implementation of {@link WsConnection} (internal to the package). */
+var WsConnectionImpl = class {
+	id;
+	gateway;
+	handshake;
+	protocol;
+	data = {};
+	roomSet = /* @__PURE__ */ new Set();
+	#limits;
+	#registry;
+	#driver;
+	#stats;
+	#abort = new AbortController();
+	#queue = [];
+	#running = /* @__PURE__ */ new Set();
+	#drainWaiters = [];
+	#finished = Promise.withResolvers();
+	#socket;
+	/** Polls the buffer while `drained()` waits: a transport may only report a drain at its own limit. */
+	#drainPoll;
+	#state = "open";
+	#connecting = true;
+	#connected = false;
+	#paused = false;
+	#closing;
+	#closeInfo;
+	#closeTimer;
+	/** Seen alive (a frame or a pong) since the last heartbeat tick. */
+	#alive = true;
+	constructor(init) {
+		this.id = init.id;
+		this.gateway = init.gateway;
+		this.handshake = init.handshake;
+		this.protocol = init.protocol;
+		this.#limits = init.limits;
+		this.#registry = init.rooms;
+		this.#driver = init.driver;
+		this.#stats = init.stats;
+	}
+	get requestId() {
+		return this.handshake.requestId;
+	}
+	get params() {
+		return this.handshake.params;
+	}
+	get rooms() {
+		return this.roomSet;
+	}
+	get readyState() {
+		return this.#state;
+	}
+	get bufferedAmount() {
+		return this.#socket?.bufferedAmount ?? 0;
+	}
+	get signal() {
+		return this.#abort.signal;
+	}
+	get closeInfo() {
+		return this.#closeInfo;
+	}
+	/** Resolves once the connection is fully closed. */
+	get finished() {
+		return this.#finished.promise;
+	}
+	/** The socket events to give to the transport. */
+	socketEvents() {
+		return {
+			message: (frame, binary) => this.#receive(frame, binary),
+			pong: () => {
+				this.#alive = true;
+			},
+			drain: () => this.#drain(),
+			close: (code, reason) => this.#socketClosed(code, reason)
+		};
+	}
+	/** Binds the accepted socket, joins the gateway and runs `@OnConnect` as the first task. */
+	start(socket) {
+		this.#socket = socket;
+		this.#registry.add(this);
+		const task = this.#driver.connect(this).then(() => {
+			this.#connected = true;
+			this.#connecting = false;
+			this.#pump();
+		}, (error) => {
+			this.#connecting = false;
+			const { code, reason } = this.#driver.connectFailure(error);
+			this.#beginClose(code, reason, "server", true);
+		});
+		this.#track(task);
+	}
+	emit(event, data) {
+		return this.sendFrame(this.#registry.codec.encode({
+			kind: "event",
+			event,
+			data
+		}));
+	}
+	send(frame) {
+		return this.sendFrame(frame);
+	}
+	/** Sends an encoded frame through the backpressure policy. */
+	sendFrame(frame) {
+		const socket = this.#socket;
+		if (this.#state !== "open" || socket === void 0) return "dropped";
+		const size = sizeOf(frame);
+		const stats = this.#stats;
+		if (socket.bufferedAmount + size > this.#limits.backpressureLimit) {
+			if (stats !== void 0) stats.dropped++;
+			if (this.#limits.onBackpressure === "drop") return "dropped";
+			if (stats !== void 0) stats.slowConsumerCloses++;
+			this.#beginClose(WsCloseCode.TryAgainLater, "Slow consumer", "backpressure", true);
+			return "dropped";
+		}
+		const status = socket.send(frame, typeof frame !== "string");
+		if (stats !== void 0) {
+			if (status === "dropped") stats.dropped++;
+			else {
+				stats.messagesOut++;
+				stats.bytesOut += size;
+			}
+		}
+		return status;
+	}
+	join(room) {
+		for (const name of typeof room === "string" ? [room] : room) this.#registry.join(this, name);
+	}
+	leave(room) {
+		this.#registry.leave(this, room);
+	}
+	to(room) {
+		return this.#registry.select(room, [this.id]);
+	}
+	drained() {
+		if (this.#state !== "open") return Promise.reject(new WsClosedError());
+		if (this.bufferedAmount <= this.#limits.backpressureLimit / 4) return Promise.resolve();
+		const { promise, resolve, reject } = Promise.withResolvers();
+		this.#drainWaiters.push({
+			resolve,
+			reject
+		});
+		if (this.#drainPoll === void 0) {
+			this.#drainPoll = setInterval(() => this.#drain(), DRAIN_POLL_MS);
+			this.#drainPoll.unref?.();
+		}
+		return promise;
+	}
+	close(code = WsCloseCode.Normal, reason = "") {
+		this.#beginClose(code, reason, "server", true);
+	}
+	/** Closes with an initiator (shutdown, heartbeat...). */
+	closeWith(code, reason, initiator) {
+		this.#beginClose(code, reason, initiator, true);
+	}
+	terminate() {
+		this.terminateWith("server");
+	}
+	/** Terminates without close frame (heartbeat timeout, shutdown deadline...): local code `1006`. */
+	terminateWith(initiator) {
+		this.#beginClose(1006, "", initiator, false);
+		this.#socket?.terminate();
+	}
+	/**
+	* One heartbeat tick (RFC 0003 §8.7): a connection not seen alive since the previous tick is
+	* terminated, the others are marked and pinged.
+	*/
+	heartbeat() {
+		if (this.#state !== "open" || this.#socket === void 0) return;
+		if (!this.#alive) {
+			this.terminateWith("heartbeat");
+			return;
+		}
+		this.#alive = false;
+		this.#socket.ping();
+	}
+	#receive(frame, binary) {
+		if (this.#state !== "open") return;
+		this.#alive = true;
+		const size = sizeOf(frame);
+		const stats = this.#stats;
+		if (stats !== void 0) {
+			stats.messagesIn++;
+			stats.bytesIn += size;
+		}
+		if (size > this.#limits.maxPayload) {
+			this.#beginClose(WsCloseCode.MessageTooBig, "Message too big", "server", true);
+			return;
+		}
+		const rate = this.#limits.rateLimit;
+		if (rate !== void 0 && !rate.bucket.take()) {
+			if (rate.onLimit === "close") this.#beginClose(4429, "Rate limited", "server", true);
+			else this.#driver.rateLimited(this, frame, binary);
+			return;
+		}
+		this.#queue.push({
+			frame,
+			binary
+		});
+		const max = this.#limits.maxPendingMessages;
+		if (this.#queue.length >= max && !this.#paused) {
+			this.#paused = this.#socket?.pause() ?? false;
+			if (!this.#paused && this.#queue.length >= max * 2) {
+				this.#beginClose(WsCloseCode.PolicyViolation, "Too many pending messages", "server", true);
+				return;
+			}
+		}
+		this.#pump();
+	}
+	#pump() {
+		while (this.#state === "open" && !this.#connecting && this.#running.size < this.#limits.concurrency && this.#queue.length > 0) {
+			const next = this.#queue.shift();
+			this.#track(this.#driver.dispatch(this, next.frame, next.binary));
+		}
+		if (this.#paused && this.#queue.length <= this.#limits.maxPendingMessages / 2) {
+			this.#paused = false;
+			this.#socket?.resume();
+		}
+	}
+	/** Counts a running task until it settles, then dispatches the next messages. */
+	#track(task) {
+		const tracked = task.catch(() => void 0).then(() => {
+			this.#running.delete(tracked);
+			this.#pump();
+		});
+		this.#running.add(tracked);
+	}
+	#drain() {
+		if (this.bufferedAmount > this.#limits.backpressureLimit / 4) return;
+		this.#stopDrainPoll();
+		for (const waiter of this.#drainWaiters.splice(0)) waiter.resolve();
+	}
+	#stopDrainPoll() {
+		if (this.#drainPoll !== void 0) clearInterval(this.#drainPoll);
+		this.#drainPoll = void 0;
+	}
+	#beginClose(code, reason, initiator, frame) {
+		if (this.#state !== "open") return;
+		this.#state = "closing";
+		this.#closing = {
+			code,
+			reason,
+			initiator
+		};
+		this.#abort.abort(new WsClosedError());
+		this.#queue.length = 0;
+		if (!frame) return;
+		this.#socket?.close(code, reason);
+		this.#closeTimer = setTimeout(() => this.#socket?.terminate(), this.#limits.closeTimeoutMs);
+		this.#closeTimer.unref?.();
+	}
+	#socketClosed(code, reason) {
+		if (this.#state === "closed") return;
+		if (this.#state === "open") this.#beginClose(code, reason, "client", false);
+		if (this.#closeTimer !== void 0) clearTimeout(this.#closeTimer);
+		this.#finish();
+	}
+	async #finish() {
+		const info = this.#closing ?? {
+			code: 1006,
+			reason: "",
+			initiator: "error"
+		};
+		this.#closeInfo = info;
+		while (this.#running.size > 0) await Promise.all([...this.#running]);
+		if (this.#connected) await this.#driver.disconnect(this).catch(() => void 0);
+		this.#registry.remove(this);
+		this.#state = "closed";
+		this.#stopDrainPoll();
+		for (const waiter of this.#drainWaiters.splice(0)) waiter.reject(new WsClosedError());
+		this.#driver.closed(this, info);
+		this.#finished.resolve(info);
+	}
+};
+// src/decorators.ts
+function marker() {}
+/**
+* A provider whose methods handle the WebSocket connections of `path` (default `/`), joined to the
+* `HttpPlugin` prefix.
+*
+* ```ts
+* @Gateway({ path: '/chat', protocols: ['chat.v1'] })
+* export class ChatGateway {}
+* ```
+*/
+function Gateway(_pathOrOptions) {
+	return marker;
+}
+/** Runs once the handshake succeeded, before any message. Throwing closes the connection. */
+function OnConnect() {
+	return marker;
+}
+/**
+* Handles an event (`events` protocol). Without `event`: the default handler (unknown events, every
+* message of a `raw` gateway). Repeatable.
+*/
+function OnMessage(_event) {
+	return marker;
+}
+/** Runs once per connection whose `@OnConnect` completed, before rooms are left and the scope closes. */
+function OnDisconnect() {
+	return marker;
+}
+/** The message `data` (`events`) or the raw frame (`raw`), validated by `schema` (a Standard Schema). */
+function Payload(_schema) {
+	return marker;
+}
+/** The `WsConnection` of the message or of the lifecycle method. */
+function Conn() {
+	return marker;
+}
+/** The `WsMessageContext` (`@OnMessage` handlers only). */
+function Ctx() {
+	return marker;
+}
+/** Extra HTTP guards (`CanActivate`) of the handshake, after the `HttpPlugin` global guards. */
+function UseHandshakeGuard(..._guards) {
+	return marker;
+}
+/** Message guards (`WsGuard`) run before each handler: global, then class, then method. */
+function UseMessageGuard(..._guards) {
+	return marker;
+}
+// src/envelope.ts
+/** The envelope of `events` gateways (RFC 0003 §5.3): decoding inbound frames, encoding outbound ones. */
+/** Event names: `^[A-Za-z][\w.:/-]{0,127}$`; names starting with `$` are reserved. */
+const EVENT_NAME = /^[A-Za-z][\w.:/-]{0,127}$/;
+/** Whether `value` is a valid message id. */
+function isMessageId(value) {
+	return typeof value === "string" && value.length <= 64 || Number.isSafeInteger(value);
+}
+/**
+* Decodes an inbound frame of an `events` gateway with the JSON codec: a binary frame is
+* `UNSUPPORTED_FRAME`, anything but a JSON object with a string `event` is `BAD_FRAME`. Unknown
+* fields are ignored.
+*/
+function decodeFrame(frame) {
+	if (typeof frame !== "string") return {
+		error: WsErrorCode.UnsupportedFrame,
+		message: "Binary frames are not supported",
+		id: void 0
+	};
+	let value;
+	try {
+		value = JSON.parse(frame);
+	} catch {
+		return {
+			error: WsErrorCode.BadFrame,
+			message: "The frame is not valid JSON",
+			id: void 0
+		};
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {
+		error: WsErrorCode.BadFrame,
+		message: "The frame must be a JSON object",
+		id: void 0
+	};
+	const record = value;
+	const rawId = record["id"];
+	const id = isMessageId(rawId) ? rawId : void 0;
+	if (rawId !== void 0 && id === void 0) return {
+		error: WsErrorCode.BadFrame,
+		message: "Invalid message id",
+		id: void 0
+	};
+	const event = record["event"];
+	if (typeof event !== "string") return {
+		error: WsErrorCode.BadFrame,
+		message: "Missing event name",
+		id
+	};
+	return {
+		event,
+		data: record["data"],
+		id
+	};
+}
+/** Whether a decoded frame is a failure. */
+function isFailure(decoded) {
+	return "error" in decoded;
+}
+/** A success reply: `{ id, data }`, `data` omitted when `undefined`. */
+function encodeReply(id, data) {
+	return data === void 0 ? JSON.stringify({ id }) : JSON.stringify({
+		id,
+		data
+	});
+}
+/** A failure reply: `{ id, error }`. */
+function encodeErrorReply(id, error) {
+	return JSON.stringify({
+		id,
+		error: wireError(error)
+	});
+}
+/** A server event: `{ event, data }`. */
+function encodeEvent(event, data) {
+	return data === void 0 ? JSON.stringify({ event }) : JSON.stringify({
+		event,
+		data
+	});
+}
+/** The failure of a message without id: `{ event: '$error', data: { event, code, message, details? } }`. */
+function encodeErrorEvent(event, error) {
+	return JSON.stringify({
+		event: "$error",
+		data: {
+			...event === void 0 ? {} : { event },
+			...wireError(error)
+		}
+	});
+}
+function wireError(error) {
+	return error.details === void 0 ? {
+		code: error.code,
+		message: error.message
+	} : {
+		code: error.code,
+		message: error.message,
+		details: error.details
+	};
+}
+/** The default codec: UTF-8 JSON text frames (RFC 0003 §5.3); binary frames are `UNSUPPORTED_FRAME`. */
+const jsonCodec = Object.freeze({
+	decode: (frame) => decodeFrame(frame),
+	encode(message) {
+		switch (message.kind) {
+			case "event": return encodeEvent(message.event, message.data);
+			case "reply": return encodeReply(message.id, message.data);
+			case "error": return message.id === void 0 ? encodeErrorEvent(message.event, message.error) : encodeErrorReply(message.id, message.error);
+		}
+	}
+});
+// src/dispatcher.ts
+const MESSAGE_HOOK = "websocket:message";
+const OK = Object.freeze({ outcome: "ok" });
+var TimeoutError = class extends Error {};
+/** Converts what a handler or a guard threw to a wire error. */
+function toWireError(error, exposeErrors) {
+	if (error instanceof WsException) return {
+		code: error.code,
+		message: error.message,
+		...error.details === void 0 ? {} : { details: error.details }
+	};
+	if (error instanceof HttpException) {
+		const code = codeOfStatus(error.status);
+		return {
+			code,
+			message: code === WsErrorCode.Internal && !exposeErrors ? "Internal error" : error.message,
+			...error.details === void 0 ? {} : { details: error.details }
+		};
+	}
+	if (error instanceof TimeoutError) return {
+		code: WsErrorCode.Timeout,
+		message: "The handler timed out"
+	};
+	const message = exposeErrors && error instanceof Error ? error.message : "Internal error";
+	return {
+		code: WsErrorCode.Internal,
+		message
+	};
+}
+function isForbidden(error) {
+	if (error instanceof WsException) return error.code === WsErrorCode.Forbidden || error.code === WsErrorCode.Unauthorized;
+	return error instanceof HttpException && (error.status === 401 || error.status === 403);
+}
+function isExpected(error) {
+	if (error instanceof WsException || error instanceof TimeoutError) return true;
+	return error instanceof HttpException && error.status < 500;
+}
+/** The close code of an `@OnConnect` failure (§5.8). */
+function connectFailureCode(error) {
+	if (error instanceof WsValidationException) return {
+		code: 4400,
+		reason: error.message
+	};
+	if (error instanceof WsException) return {
+		code: error.close ?? WsCloseCode.PolicyViolation,
+		reason: error.message
+	};
+	if (error instanceof HttpException) return {
+		code: 4e3 + error.status,
+		reason: error.message
+	};
+	return {
+		code: WsCloseCode.InternalError,
+		reason: "Internal error"
+	};
+}
+/** One gateway's message pipeline, shared by its connections. */
+var GatewayDispatcher = class {
+	#options;
+	#byEvent = /* @__PURE__ */ new Map();
+	#fallback;
+	#codec;
+	#ignored = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.#options = options;
+		this.#codec = options.codec ?? jsonCodec;
+		let fallback;
+		for (const plan of options.handlers) if (plan.definition.event === void 0) fallback = plan;
+		else this.#byEvent.set(plan.definition.event, plan);
+		this.#fallback = fallback;
+	}
+	get raw() {
+		return this.#options.definition.protocol === "raw";
+	}
+	async connect(conn) {
+		const lifecycle = this.#options.definition.onConnect;
+		if (lifecycle === void 0) return;
+		const gateway = await this.#options.instance(conn);
+		await this.#bounded(Promise.resolve(lifecycle.invoke(gateway, conn)), void 0);
+	}
+	connectFailure(error) {
+		return connectFailureCode(error);
+	}
+	async disconnect(conn) {
+		const lifecycle = this.#options.definition.onDisconnect;
+		if (lifecycle === void 0) return;
+		try {
+			await lifecycle.invoke(await this.#options.instance(conn), conn);
+		} catch (error) {
+			this.#options.logError(`@OnDisconnect ${lifecycle.method} failed`, error, conn);
+		}
+	}
+	closed(conn, info) {
+		this.#options.closed(conn, info);
+	}
+	rateLimited(conn, frame, binary) {
+		if (this.raw) return;
+		const decoded = this.#codec.decode(frame, binary);
+		const id = decoded.id;
+		const event = isFailure(decoded) ? void 0 : decoded.event;
+		this.#fail(conn, id, event, {
+			code: WsErrorCode.RateLimited,
+			message: "Too many messages"
+		});
+	}
+	async dispatch(conn, frame, binary) {
+		const receivedAt = performance.now();
+		let event;
+		let id;
+		let data = frame;
+		let failure;
+		if (!this.raw) {
+			const decoded = this.#codec.decode(frame, binary);
+			if (isFailure(decoded)) {
+				id = decoded.id;
+				failure = {
+					code: decoded.error,
+					message: decoded.message
+				};
+			} else {
+				({event, id, data} = decoded);
+				if (event === "$ping") {
+					if (id !== void 0) conn.sendFrame(this.#codec.encode({
+						kind: "reply",
+						id,
+						data: { t: Date.now() }
+					}));
+					return;
+				}
+			}
+		}
+		const plan = failure === void 0 ? (event === void 0 ? void 0 : this.#byEvent.get(event)) ?? this.#fallback : void 0;
+		const abort = new AbortController();
+		const onClose = () => abort.abort(conn.signal.reason);
+		conn.signal.addEventListener("abort", onClose, { once: true });
+		const ctx = {
+			connection: conn,
+			event,
+			id,
+			data,
+			binary,
+			bytes: typeof frame === "string" ? frame.length : frame.byteLength,
+			receivedAt,
+			signal: abort.signal,
+			state: /* @__PURE__ */ new Map(),
+			route: {
+				path: this.#options.path,
+				gateway: this.#options.definition.token,
+				handler: plan?.definition.method,
+				event,
+				meta: plan?.meta ?? this.#options.definition.meta
+			}
+		};
+		try {
+			const hooks = this.#options.hooks;
+			if (hooks === void 0 || !hooks.hasWrappers(MESSAGE_HOOK) && !hooks.hasListeners(MESSAGE_HOOK)) {
+				await this.#handle(plan, conn, ctx, failure, abort);
+				return;
+			}
+			const hookEvent = {
+				gateway: this.#options.name ?? String(this.#options.definition.token),
+				path: this.#options.path,
+				event,
+				handler: plan?.definition.method,
+				connectionId: conn.id,
+				requestId: conn.requestId,
+				bytes: ctx.bytes,
+				context: ctx,
+				startTime: receivedAt
+			};
+			try {
+				await hooks.run(MESSAGE_HOOK, hookEvent, async () => {
+					const settled = await this.#handle(plan, conn, ctx, failure, abort);
+					hookEvent.outcome = settled.outcome;
+					if (settled.error !== void 0) hookEvent.error = settled.error;
+				});
+			} catch (error) {
+				this.#options.logError("A \"websocket:message\" hook wrapper failed", error, conn);
+			}
+			if (hooks.hasListeners(MESSAGE_HOOK)) hooks.emit(MESSAGE_HOOK, hookEvent);
+		} finally {
+			conn.signal.removeEventListener("abort", onClose);
+		}
+	}
+	/** Guards, handler, reply and error mapping of one message. Never rejects. */
+	async #handle(plan, conn, ctx, failure, abort) {
+		if (failure !== void 0) {
+			this.#fail(conn, ctx.id, void 0, failure);
+			return {
+				outcome: "error",
+				error: new WsException(failure.code, failure.message)
+			};
+		}
+		if (plan === void 0) {
+			this.#fail(conn, ctx.id, ctx.event, {
+				code: WsErrorCode.UnknownEvent,
+				message: `Unknown event "${ctx.event}"`
+			});
+			return { outcome: "unhandled" };
+		}
+		let rejected = false;
+		try {
+			const result = await this.#bounded(this.#run(plan, conn, ctx, () => {
+				rejected = true;
+			}), abort);
+			if (ctx.id !== void 0 && conn.readyState === "open") conn.sendFrame(this.#codec.encode({
+				kind: "reply",
+				id: ctx.id,
+				data: result
+			}));
+			else if (ctx.id === void 0 && result !== void 0 && !this.raw) this.#ignoredResult(plan.definition.method, ctx.event);
+			return OK;
+		} catch (thrown) {
+			const error = await this.#map(thrown, ctx, conn);
+			if (!isExpected(error)) this.#options.logError(`Handler ${plan.definition.method} failed`, error, conn);
+			if (!this.raw) this.#fail(conn, ctx.id, ctx.event, toWireError(error, this.#options.exposeErrors));
+			if (error instanceof WsException && error.close !== void 0) conn.close(error.close, error.message);
+			let outcome = "error";
+			if (thrown instanceof TimeoutError) outcome = "timeout";
+			else if (rejected && isForbidden(error)) outcome = "rejected";
+			return {
+				outcome,
+				error: thrown
+			};
+		}
+	}
+	#ignoredResult(method, event) {
+		const report = this.#options.ignoredResult;
+		if (report === void 0 || this.#ignored.has(method)) return;
+		this.#ignored.add(method);
+		report(method, event);
+	}
+	/** Runs the plugin exception mappers, in order: the first `WsException` wins. */
+	async #map(error, ctx, conn) {
+		const mappers = this.#options.mappers;
+		if (mappers === void 0 || mappers.length === 0 || error instanceof TimeoutError) return error;
+		for (const mapper of mappers) try {
+			const mapped = await mapper.map(error, ctx);
+			if (mapped !== void 0) return mapped;
+		} catch (failure) {
+			this.#options.logError("A WebSocket exception mapper failed", failure, conn);
+			return failure;
+		}
+		return error;
+	}
+	async #run(plan, conn, ctx, refused) {
+		for (const guard of plan.guards) {
+			let allowed;
+			try {
+				allowed = await guard.canHandle(ctx) === true;
+			} catch (error) {
+				refused();
+				throw error;
+			}
+			if (!allowed) {
+				refused();
+				throw new WsException(WsErrorCode.Forbidden, "Forbidden");
+			}
+		}
+		const gateway = await this.#options.instance(conn);
+		return await plan.definition.invoke(gateway, ctx);
+	}
+	/** Races a task with the handler timeout; aborts `abort` on timeout. */
+	#bounded(task, abort) {
+		const ms = this.#options.handlerTimeoutMs;
+		if (!Number.isFinite(ms)) return task;
+		let timer;
+		const timeout = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				const error = new TimeoutError("The handler timed out");
+				abort?.abort(error);
+				reject(error);
+			}, ms);
+		});
+		task.catch(() => void 0);
+		return Promise.race([task, timeout]).finally(() => clearTimeout(timer));
+	}
+	#fail(conn, id, event, error) {
+		if (this.raw || conn.readyState !== "open") return;
+		conn.sendFrame(this.#codec.encode({
+			kind: "error",
+			id,
+			event,
+			error
+		}));
+	}
+};
+// src/options.ts
+const OPTION_KEYS = /* @__PURE__ */ new Set([
+	"transport",
+	"origins",
+	"maxPayload",
+	"maxConnections",
+	"maxPendingMessages",
+	"backpressure",
+	"heartbeat",
+	"handshakeTimeoutMs",
+	"handlerTimeoutMs",
+	"closeTimeoutMs",
+	"codec",
+	"messageGuards",
+	"exceptionMappers",
+	"exposeErrors",
+	"shutdown"
+]);
+/** `ZNIGHT050: WebSocketPlugin: option "<name>" must be <expected> (received <value>)`. */
+function invalidOption(name, expected, value, hints) {
+	return new ZnightError(ErrorCode.InvalidGateway, `WebSocketPlugin: option "${name}" must be ${expected} (received ${describe(value)})`, hints === void 0 ? {} : { hints });
+}
+function describe(value) {
+	if (typeof value === "function") return "a function";
+	if (value instanceof RegExp) return String(value);
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return typeof value;
+	}
+}
+function positiveInteger(name, value, fallback, infinite = false) {
+	if (value === void 0) return fallback;
+	if (infinite && value === Number.POSITIVE_INFINITY) return value;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw invalidOption(name, `a positive integer${infinite ? " or Infinity" : ""}`, value);
+	return value;
+}
+function byteSize(name, value, fallback) {
+	if (value === void 0) return fallback;
+	const bytes = parseByteSize(value);
+	if (bytes === void 0 || bytes === 0 || bytes === Number.POSITIVE_INFINITY) throw invalidOption(name, "a positive byte size ('64kb', 65536)", value);
+	return bytes;
+}
+/** Validates the options of `WebSocketPlugin.configure()` (ZNIGHT050). */
+function resolveWebSocketOptions(options) {
+	if (options === null || typeof options !== "object" || Array.isArray(options)) throw invalidOption("options", "an object", options);
+	for (const key of Object.keys(options)) if (!OPTION_KEYS.has(key)) throw new ZnightError(ErrorCode.InvalidGateway, `WebSocketPlugin: unknown option "${key}"`, { hints: [`Known options: ${[...OPTION_KEYS].join(", ")}`] });
+	const o = options;
+	const transport = o.transport ?? "auto";
+	if (transport !== "auto" && (transport === null || typeof transport !== "object" || typeof transport.accept !== "function")) throw invalidOption("transport", "'auto', wsTransport() or bunTransport()", transport);
+	const backpressure = o.backpressure ?? {};
+	if (backpressure === null || typeof backpressure !== "object") throw invalidOption("backpressure", "{ limit?, onLimit?: 'close' | 'drop' }", backpressure);
+	const onLimit = backpressure.onLimit ?? "close";
+	if (onLimit !== "close" && onLimit !== "drop") throw invalidOption("backpressure.onLimit", "'close' or 'drop'", onLimit);
+	const heartbeat = o.heartbeat ?? { intervalMs: 3e4 };
+	let heartbeatMs = 0;
+	if (heartbeat !== false) {
+		if (heartbeat === null || typeof heartbeat !== "object") throw invalidOption("heartbeat", "{ intervalMs } or false", heartbeat);
+		heartbeatMs = positiveInteger("heartbeat.intervalMs", heartbeat.intervalMs, 3e4);
+	}
+	const shutdown = o.shutdown ?? {};
+	if (shutdown === null || typeof shutdown !== "object") throw invalidOption("shutdown", "{ code?, reason?, timeoutMs? }", shutdown);
+	const code = shutdown.code ?? 1001;
+	if (!isCloseCode(code)) throw invalidOption("shutdown.code", "a close code (1000, 1001, 1012, 3000-4999)", code);
+	const reason = shutdown.reason ?? "Server shutting down";
+	if (typeof reason !== "string" || Buffer.byteLength(reason) > 123) throw invalidOption("shutdown.reason", "a string of at most 123 bytes", reason);
+	const codec = o.codec ?? jsonCodec;
+	if (codec === null || typeof codec !== "object" || typeof codec.decode !== "function" || typeof codec.encode !== "function") throw invalidOption("codec", "{ decode(frame, binary), encode(message) }", codec);
+	if (o.exposeErrors !== void 0 && typeof o.exposeErrors !== "boolean") throw invalidOption("exposeErrors", "a boolean", o.exposeErrors);
+	return Object.freeze({
+		transport,
+		origins: resolveOrigins(o.origins ?? "same-origin"),
+		maxPayload: byteSize("maxPayload", o.maxPayload, 1048576),
+		maxConnections: positiveInteger("maxConnections", o.maxConnections, Number.POSITIVE_INFINITY, true),
+		maxPendingMessages: positiveInteger("maxPendingMessages", o.maxPendingMessages, 32),
+		backpressure: Object.freeze({
+			limit: byteSize("backpressure.limit", backpressure.limit, 1048576),
+			onLimit
+		}),
+		heartbeatMs,
+		handshakeTimeoutMs: positiveInteger("handshakeTimeoutMs", o.handshakeTimeoutMs, 1e4, true),
+		handlerTimeoutMs: positiveInteger("handlerTimeoutMs", o.handlerTimeoutMs, 3e4, true),
+		closeTimeoutMs: positiveInteger("closeTimeoutMs", o.closeTimeoutMs, 2e3),
+		codec,
+		messageGuards: refs("messageGuards", o.messageGuards, "canHandle"),
+		exceptionMappers: refs("exceptionMappers", o.exceptionMappers, "map"),
+		exposeErrors: o.exposeErrors ?? false,
+		shutdown: Object.freeze({
+			code,
+			reason,
+			timeoutMs: positiveInteger("shutdown.timeoutMs", shutdown.timeoutMs, 3e3)
+		})
+	});
+}
+/** Whether a close code may be sent by a server (RFC 6455 §7.4). */
+function isCloseCode(code) {
+	if (typeof code !== "number" || !Number.isInteger(code)) return false;
+	if (code >= 3e3 && code <= 4999) return true;
+	return code >= 1e3 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006;
+}
+function refs(name, value, method) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw invalidOption(name, `an array of classes or instances with ${method}()`, value);
+	for (const ref of value) if (!(typeof ref === "function" ? typeof ref.prototype?.[method] === "function" : ref !== null && typeof ref === "object" && typeof ref[method] === "function")) throw invalidOption(name, `an array of classes or instances with ${method}()`, ref);
+	return Object.freeze([...value]);
+}
+/** Validates the `origins` option (RFC 0003 §5.6), with the rules of the `cors.origin` option of `HttpPlugin`. */
+function resolveOrigins(value) {
+	if (value === "same-origin") return {
+		sameOrigin: true,
+		allows: (origin, ctx) => origin === ownOrigin(ctx)
+	};
+	if (typeof value === "function") return {
+		sameOrigin: false,
+		allows: value
+	};
+	const items = Array.isArray(value) ? value : [value];
+	const exact = /* @__PURE__ */ new Set();
+	const patterns = [];
+	for (const item of items) {
+		if (item === "*") return {
+			sameOrigin: false,
+			allows: () => true
+		};
+		if (typeof item === "string") exact.add(checkOrigin(item));
+		else if (item instanceof RegExp) patterns.push(checkPattern(item));
+		else throw invalidOption("origins", ORIGINS, value);
+	}
+	return {
+		sameOrigin: false,
+		allows: (origin) => exact.has(origin) || patterns.some((pattern) => pattern.test(origin))
+	};
+}
+const ORIGINS = "'same-origin', '*', an origin, an anchored RegExp, a list of them or a function";
+/** The origin of the request itself (`trustProxy` applies to `ctx.protocol`). */
+function ownOrigin(ctx) {
+	return `${ctx.protocol}://${ctx.header("host") ?? ""}`;
+}
+function checkOrigin(value) {
+	if (value === "null") throw invalidOption("origins", "a real origin", value, ["The \"null\" origin is shared by sandboxed iframes, local files and redirects: never trust it"]);
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		url = void 0;
+	}
+	if (url === void 0 || url.protocol !== "http:" && url.protocol !== "https:") throw invalidOption("origins", "an http(s) origin such as \"https://app.example.com\"", value);
+	if (url.origin !== value) throw invalidOption("origins", `an origin without path, trailing slash or default port ("${url.origin}")`, value);
+	return value;
+}
+function checkPattern(pattern) {
+	const source = pattern.source;
+	const trailingBackslashes = /\\*\$$/.exec(source)?.[0].length ?? 0;
+	const anchoredEnd = source.endsWith("$") && (trailingBackslashes - 1) % 2 === 0;
+	if (!source.startsWith("^") || !anchoredEnd || /(^|[^\\])\|/.test(source.replace(/\([^)]*\)|\[[^\]]*\]/g, ""))) throw invalidOption("origins", "a RegExp anchored with ^ and $ (around every alternative)", pattern, ["Without anchors, /example\\.com/ also allows https://example.com.evil.net"]);
+	if (pattern.global || pattern.sticky) throw invalidOption("origins", "a RegExp without the g or y flag (test() would be stateful)", pattern);
+	return pattern;
+}
+// src/rate-limit.ts
+/** The token bucket of `@Gateway({ rateLimit })` (RFC 0003 §8.6), one per connection. */
+var TokenBucket = class {
+	#capacity;
+	#perMs;
+	#tokens;
+	#updatedAt;
+	/** `messages` per `intervalMs`, refilled continuously; full at first. */
+	constructor(messages, intervalMs, now = performance.now()) {
+		this.#capacity = messages;
+		this.#perMs = messages / intervalMs;
+		this.#tokens = messages;
+		this.#updatedAt = now;
+	}
+	/** Takes one token: `false` when the bucket is empty. */
+	take(now = performance.now()) {
+		const elapsed = now - this.#updatedAt;
+		if (elapsed > 0) {
+			this.#tokens = Math.min(this.#capacity, this.#tokens + elapsed * this.#perMs);
+			this.#updatedAt = now;
+		}
+		if (this.#tokens < 1) return false;
+		this.#tokens -= 1;
+		return true;
+	}
+};
+// src/rooms.ts
+function list(value) {
+	return typeof value === "string" ? [value] : value;
+}
+/** The members and rooms of one gateway. */
+var RoomRegistry = class {
+	#members = /* @__PURE__ */ new Map();
+	#rooms = /* @__PURE__ */ new Map();
+	/** Encodes the events of broadcasts (once per broadcast). */
+	codec;
+	constructor(codec = jsonCodec) {
+		this.codec = codec;
+	}
+	/** Open members. */
+	get size() {
+		return this.#members.size;
+	}
+	add(member) {
+		this.#members.set(member.id, member);
+	}
+	/** Removes the member and leaves its rooms. */
+	remove(member) {
+		for (const room of [...member.roomSet]) this.leave(member, room);
+		this.#members.delete(member.id);
+	}
+	get(id) {
+		return this.#members.get(id);
+	}
+	members() {
+		return this.#members.values();
+	}
+	join(member, room) {
+		if (!this.#members.has(member.id)) return;
+		let set = this.#rooms.get(room);
+		if (set === void 0) {
+			set = /* @__PURE__ */ new Set();
+			this.#rooms.set(room, set);
+		}
+		set.add(member);
+		member.roomSet.add(room);
+	}
+	leave(member, room) {
+		const set = this.#rooms.get(room);
+		member.roomSet.delete(room);
+		if (set === void 0) return;
+		set.delete(member);
+		if (set.size === 0) this.#rooms.delete(room);
+	}
+	/** The members of `room` (a read-only view). */
+	room(room) {
+		return this.#rooms.get(room) ?? /* @__PURE__ */ new Set();
+	}
+	/** Room → size. */
+	rooms() {
+		const sizes = /* @__PURE__ */ new Map();
+		for (const [name, set] of this.#rooms) sizes.set(name, set.size);
+		return sizes;
+	}
+	/** A broadcast over every member, or over the members of `rooms`. */
+	select(rooms, except = []) {
+		return new BroadcastImpl(this, {
+			rooms: rooms === void 0 ? void 0 : list(rooms),
+			except: new Set(except),
+			exceptRooms: []
+		});
+	}
+	/** @internal The members a selection designates, each once. */
+	resolve(selection) {
+		const excluded = new Set(selection.except);
+		for (const room of selection.exceptRooms) for (const member of this.room(room)) excluded.add(member.id);
+		const result = [];
+		const seen = /* @__PURE__ */ new Set();
+		const sources = selection.rooms === void 0 ? [this.#members.values()] : selection.rooms.map((r) => this.room(r));
+		for (const source of sources) for (const member of source) {
+			if (seen.has(member.id) || excluded.has(member.id)) continue;
+			seen.add(member.id);
+			result.push(member);
+		}
+		return result;
+	}
+};
+var BroadcastImpl = class BroadcastImpl {
+	#registry;
+	#selection;
+	constructor(registry, selection) {
+		this.#registry = registry;
+		this.#selection = selection;
+	}
+	to(room) {
+		const rooms = [...this.#selection.rooms ?? [], ...list(room)];
+		return new BroadcastImpl(this.#registry, {
+			...this.#selection,
+			rooms
+		});
+	}
+	except(target) {
+		const refs = Array.isArray(target) ? target : [target];
+		const except = new Set(this.#selection.except);
+		for (const ref of refs) except.add(typeof ref === "string" ? ref : ref.id);
+		return new BroadcastImpl(this.#registry, {
+			...this.#selection,
+			except
+		});
+	}
+	exceptRoom(room) {
+		return new BroadcastImpl(this.#registry, {
+			...this.#selection,
+			exceptRooms: [...this.#selection.exceptRooms, ...list(room)]
+		});
+	}
+	emit(event, data) {
+		this.send(this.#registry.codec.encode({
+			kind: "event",
+			event,
+			data
+		}));
+	}
+	send(frame) {
+		for (const member of this.#registry.resolve(this.#selection)) member.sendFrame(frame);
+	}
+	join(room) {
+		for (const member of this.#registry.resolve(this.#selection)) this.#registry.join(member, room);
+	}
+	leave(room) {
+		for (const member of this.#registry.resolve(this.#selection)) this.#registry.leave(member, room);
+	}
+	close(code, reason) {
+		for (const member of this.#registry.resolve(this.#selection)) member.close(code, reason);
+	}
+};
+// src/tokens.ts
+/**
+* Tokens of the values `@znight/websocket` supplies to the container. `WsConnection` is a
+* request-scoped external: the request scope of a WebSocket handshake lasts as long as its
+* connection. Inject it in request-scoped providers (`@Gateway({ scope: 'request' })`) or through
+* `Lazy<WsConnection>`.
+*/
+const WsTokens = Object.freeze({
+	Server: "@znight/websocket#WsServer",
+	Plugin: "@znight/websocket#WebSocketPlugin",
+	Connection: "@znight/websocket#WsConnection"
+});
+// src/transports/memory.ts
+/**
+* The client side of an in-memory connection: pass it as the `peer` of a memory upgrade
+* (`{ kind: 'memory', peer: client }`), then read `received` and send frames.
+*/
+var MemoryClient = class {
+	/** Frames received from the server, in order. */
+	received = [];
+	/** Called for each frame received from the server. */
+	onmessage;
+	/** Called once when the connection closes. */
+	onclose;
+	#protocol = "";
+	#closed;
+	#server;
+	/** The subprotocol the server selected, `''` when none. */
+	get protocol() {
+		return this.#protocol;
+	}
+	/** How the connection closed, `undefined` while open. */
+	get closed() {
+		return this.#closed;
+	}
+	/** Whether the server accepted the connection. */
+	get open() {
+		return this.#server !== void 0 && this.#closed === void 0;
+	}
+	/** Sends a frame to the server (a string is a text frame). */
+	send(frame) {
+		if (this.#server === void 0 || this.#closed !== void 0) throw new Error("The connection is not open");
+		this.#server.receive(frame);
+	}
+	/** Closes the connection from the client side. */
+	close(code = 1e3, reason = "") {
+		if (this.#server === void 0 || this.#closed !== void 0) return;
+		this.#server.closeFromPeer(code, reason);
+	}
+	/** @internal Bound by the memory transport. */
+	attach(server, protocol) {
+		if (this.#server !== void 0) throw new Error("This MemoryClient is already connected");
+		this.#server = server;
+		this.#protocol = protocol;
+	}
+	/** @internal */
+	deliver(frame) {
+		this.received.push(frame);
+		this.onmessage?.(frame);
+	}
+	/** @internal */
+	closedWith(info) {
+		if (this.#closed !== void 0) return;
+		this.#closed = info;
+		this.onclose?.(info);
+	}
+};
+/** The server side of an in-memory connection. */
+var MemorySocket = class {
+	bufferedAmount = 0;
+	extensions = "";
+	#client;
+	#events;
+	#queue = [];
+	#paused = false;
+	#closed = false;
+	constructor(client, events) {
+		this.#client = client;
+		this.#events = events;
+	}
+	send(frame, _binary) {
+		if (this.#closed) return "dropped";
+		this.#client.deliver(frame);
+		return "sent";
+	}
+	ping() {
+		if (!this.#closed) this.#events.pong();
+	}
+	pause() {
+		this.#paused = true;
+		return true;
+	}
+	resume() {
+		this.#paused = false;
+		while (!this.#paused && !this.#closed && this.#queue.length > 0) this.#dispatch(this.#queue.shift());
+	}
+	close(code, reason) {
+		this.#finish(code, reason);
+	}
+	terminate() {
+		this.#finish(1006, "");
+	}
+	receive(frame) {
+		if (this.#closed) return;
+		if (this.#paused) this.#queue.push(frame);
+		else this.#dispatch(frame);
+	}
+	closeFromPeer(code, reason) {
+		this.#finish(code, reason);
+	}
+	#dispatch(frame) {
+		this.#events.message(frame, typeof frame !== "string");
+	}
+	#finish(code, reason) {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#queue.length = 0;
+		this.#client.closedWith({
+			code,
+			reason
+		});
+		this.#events.close(code, reason);
+	}
+};
+/** The in-memory transport: completes `{ kind: 'memory', peer }` upgrades whose peer is a {@link MemoryClient}. */
+function memoryTransport() {
+	const sockets = /* @__PURE__ */ new Set();
+	return {
+		name: "memory",
+		accepts: "memory",
+		configure: () => void 0,
+		accept(native, init, events) {
+			if (native.kind !== "memory" || !(native.peer instanceof MemoryClient)) throw new Error("The memory transport only completes memory upgrades whose peer is a MemoryClient");
+			const socket = new MemorySocket(native.peer, {
+				message: (frame, binary) => events.message(frame, binary),
+				pong: () => events.pong(),
+				drain: () => events.drain(),
+				close: (code, reason) => {
+					sockets.delete(socket);
+					events.close(code, reason);
+				}
+			});
+			sockets.add(socket);
+			native.peer.attach(socket, init.protocol);
+			return socket;
+		},
+		close() {
+			for (const socket of [...sockets]) socket.terminate();
+			return Promise.resolve();
+		}
+	};
+}
+// src/plugin.ts
+/** The current async context (the handshake's request scope), to run the socket events in it. */
+function captureContext() {
+	const snapshot = AsyncLocalStorage.snapshot;
+	return typeof snapshot === "function" ? snapshot() : (run) => run();
+}
+const CONNECTION_HOOK = "websocket:connection";
+/**
+* The WebSocket plugin: `WebSocketPlugin.configure(options)` (name `websocket`). Requires
+* `HttpPlugin`: gateways are served on its server and port, whatever the plugin order.
+*
+* ```ts
+* await Application.create({
+*   metadata: __ZNIGHT_METADATA__,
+*   plugins: [HttpPlugin.configure({ port: 3000 }), WebSocketPlugin.configure({ maxPayload: '64kb' })],
+* })
+* ```
+*/
+var WebSocketPlugin = class WebSocketPlugin {
+	name = "websocket";
+	/** The `WsServer` of the application (also injectable). */
+	server = new WsServer();
+	#options;
+	#connections = /* @__PURE__ */ new Map();
+	/** Connections whose heartbeat the plugin drives (the `ws` transport). */
+	#beating = /* @__PURE__ */ new Set();
+	#stats = new StatsCounter();
+	#ctx;
+	#resolved;
+	#plans;
+	#transport;
+	#memory;
+	#heartbeat;
+	#draining = false;
+	/** Handshakes past their guards and not yet registered: they count against `maxConnections`. */
+	#accepting = 0;
+	#drain;
+	#active = false;
+	constructor(options) {
+		this.#options = options;
+	}
+	/**
+	* Creates the plugin. `options` may be a function of the container, evaluated once the container
+	* is initialised: `WebSocketPlugin.configure(c => ({ origins: c.get(ServerConfig).webOrigins }))`.
+	*/
+	static configure(options = {}) {
+		return new WebSocketPlugin(options);
+	}
+	/** Name of the transport (`ws`, `bun`), `undefined` before `HttpPlugin` collected the upgrade routes. */
+	get transport() {
+		return this.#transport?.name;
+	}
+	/** The served gateways (after bootstrap). */
+	get gateways() {
+		return (this.#plans ?? []).map((plan) => Object.freeze({
+			path: plan.path,
+			gateway: plan.name,
+			protocol: plan.definition.protocol,
+			events: Object.freeze(plan.definition.handlers.flatMap((handler) => handler.event ?? []))
+		}));
+	}
+	/** Open connections of every gateway. */
+	get connections() {
+		return this.#connections.size;
+	}
+	/** Totals since the application started. */
+	stats() {
+		return this.#stats.snapshot(this.#connections.size);
+	}
+	/**
+	* Providers `TestApp` creates at boot: the classes of the `messageGuards` and `exceptionMappers`
+	* options, and the gateways of the metadata with their guards.
+	*/
+	initRoots(context) {
+		const roots = /* @__PURE__ */ new Set();
+		try {
+			const options = this.#options;
+			if (options !== null && typeof options === "object") for (const key of ["messageGuards", "exceptionMappers"]) {
+				const refs = options[key];
+				if (Array.isArray(refs)) {
+					for (const ref of refs) if (typeof ref === "function") roots.add(ref);
+				}
+			}
+			const gateways = (context?.metadata.extensions?.websocket)?.gateways;
+			if (Array.isArray(gateways)) for (const gateway of gateways) {
+				if (typeof gateway?.token !== "string") continue;
+				roots.add(gateway.token);
+				const handlers = Array.isArray(gateway.handlers) ? gateway.handlers : [];
+				const tokens = [
+					...gateway.handshakeGuards ?? [],
+					...gateway.messageGuards ?? [],
+					...handlers.flatMap((handler) => handler?.guards ?? [])
+				];
+				for (const token of tokens) if (typeof token === "string") roots.add(token);
+			}
+		} catch {}
+		return [...roots];
+	}
+	register(ctx) {
+		if (this.#active) throw new ZnightError(ErrorCode.DuplicateProvider, "This WebSocketPlugin is already used by another application", { hints: ["Call WebSocketPlugin.configure() once per application"] });
+		if (ctx.getPlugin("http") === void 0) throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, "WebSocketPlugin needs HttpPlugin: gateways are served by the HTTP server", { hints: ["Add HttpPlugin.configure() to the plugins (without controllers for a WebSocket-only service)"] });
+		this.#active = true;
+		this.#ctx = ctx;
+		this.#resolved = void 0;
+		this.#plans = void 0;
+		this.#transport = void 0;
+		this.#memory = void 0;
+		this.#draining = false;
+		this.#drain = void 0;
+		this.#stats = new StatsCounter();
+		this.server.reset();
+		ctx.container.registerExternal({
+			token: WsTokens.Connection,
+			scope: "request",
+			providedBy: "WebSocketPlugin"
+		});
+		ctx.container.registerValue(WsTokens.Server, this.server);
+		ctx.container.registerValue(WsTokens.Plugin, this);
+	}
+	onBootstrap(ctx) {
+		this.#ctx = ctx;
+		this.#resolve();
+		gatewaysOf(ctx.metadata);
+	}
+	/**
+	* The `PluginHttpUpgrades` contract of `@znight/http`: one upgrade route per gateway, and the
+	* `Bun.serve()` settings of the Bun transport. Called once by `HttpPlugin.onBootstrap`. No route
+	* (and no transport) without gateways.
+	*/
+	httpUpgrades(context) {
+		const plans = this.#prepare(context);
+		if (plans.length === 0) return { routes: [] };
+		const extensions = this.#context().metadata.extensions;
+		const groups = {
+			...(extensions?.http)?.groups,
+			...(extensions?.websocket)?.groups
+		};
+		const options = this.#resolve();
+		const routes = plans.map((plan) => ({
+			path: plan.definition.path,
+			name: plan.name,
+			owner: plan.definition.token,
+			meta: metaEntries(plan.definition.meta, groups),
+			guards: plan.definition.handshakeGuards,
+			timeoutMs: options.handshakeTimeoutMs,
+			precheck: (ctx) => this.#precheck(plan, ctx),
+			accept: (ctx, upgrade) => this.#accept(plan, ctx, upgrade)
+		}));
+		const bunWebSocket = this.#transport?.bunWebSocket?.();
+		return bunWebSocket === void 0 ? { routes } : {
+			routes,
+			bunWebSocket
+		};
+	}
+	async onStart() {
+		const transport = this.#transport;
+		if (transport === void 0) return;
+		await transport.ready?.();
+		const intervalMs = this.#resolve().heartbeatMs;
+		if (intervalMs > 0 && transport.accepts === "node") {
+			this.#heartbeat = setInterval(() => {
+				for (const conn of this.#beating) conn.heartbeat();
+			}, intervalMs);
+			this.#heartbeat.unref?.();
+		}
+	}
+	/**
+	* The `PluginHttpRoutes` contract: `HttpPlugin` starts draining, whatever the plugin order.
+	* Refuses new handshakes and closes every connection gracefully (see {@link onStop}).
+	*/
+	onHttpDrain() {
+		return this.#shutdown();
+	}
+	/**
+	* Refuses handshakes (`503`), closes every connection with `shutdown.code`, waits for close
+	* frames, running handlers and `@OnDisconnect` up to `shutdown.timeoutMs`, then terminates the
+	* rest. Idempotent: the same drain as {@link onHttpDrain}.
+	*/
+	onStop() {
+		return this.#shutdown();
+	}
+	async onDispose() {
+		this.#stopHeartbeat();
+		try {
+			await this.#shutdown();
+			await Promise.all([this.#transport?.close(), this.#memory?.close()]);
+		} finally {
+			this.#active = false;
+			this.#beating.clear();
+			this.#connections.clear();
+			this.#plans = void 0;
+		}
+	}
+	/**
+	* Opens an in-memory connection (tests): the real handshake through the HTTP pipeline (guards,
+	* hooks, origin and subprotocol checks) with an in-memory request, then the in-memory transport.
+	* `path` is the URL path, HTTP prefix included. Rejects with {@link WsHandshakeError} when the
+	* handshake is refused.
+	*
+	* ```ts
+	* await using alice = await plugin.connect('/chat', { protocols: ['chat.v1'] })
+	* expect(await alice.request('room.join', { room: 'general' })).toEqual({ members: 1 })
+	* ```
+	*/
+	async connect(path, options = {}) {
+		const http = this.#ctx?.getPlugin("http");
+		if (http === void 0 || this.#plans === void 0) throw new ZnightError(ErrorCode.LifecycleFailed, "WebSocketPlugin is not bootstrapped yet", { hints: ["connect() is available once Application.create() resolved"] });
+		const headers = { ...options.headers };
+		if (options.protocols !== void 0 && options.protocols.length > 0) headers["sec-websocket-protocol"] = options.protocols.join(", ");
+		if (options.origin !== void 0) headers["origin"] = options.origin;
+		const peer = new MemoryClient();
+		const refused = await http.upgradeInMemory({
+			method: "GET",
+			url: path,
+			headers,
+			...options.query === void 0 ? {} : { query: options.query },
+			...options.cookies === void 0 ? {} : { cookies: options.cookies }
+		}, {
+			kind: "memory",
+			peer
+		});
+		if (refused !== void 0) throw new WsHandshakeError(refused);
+		return new WsClient(peer);
+	}
+	#context() {
+		const ctx = this.#ctx;
+		if (ctx === void 0) throw new ZnightError(ErrorCode.LifecycleFailed, "WebSocketPlugin is not registered in an application");
+		return ctx;
+	}
+	#resolve() {
+		if (this.#resolved !== void 0) return this.#resolved;
+		const container = this.#context().container;
+		this.#resolved = resolveWebSocketOptions(resolveOptions(this.#options, container));
+		return this.#resolved;
+	}
+	/** Builds the gateway plans and selects the transport, once. */
+	#prepare(context) {
+		if (this.#plans !== void 0) return this.#plans;
+		const ctx = this.#context();
+		const options = this.#resolve();
+		const definitions = gatewaysOf(ctx.metadata);
+		if (definitions.length === 0) {
+			this.#plans = [];
+			return this.#plans;
+		}
+		const transport = selectTransport(options, context);
+		let maxPayload = options.maxPayload;
+		let backpressureLimit = options.backpressure.limit;
+		for (const definition of definitions) {
+			maxPayload = Math.max(maxPayload, definition.maxPayload ?? 0);
+			backpressureLimit = Math.max(backpressureLimit, definition.backpressure?.limit ?? 0);
+		}
+		transport.configure({
+			maxPayload,
+			backpressureLimit,
+			heartbeatMs: options.heartbeatMs
+		});
+		this.#transport = transport;
+		const refs = new Refs(ctx.container, ctx.metadata);
+		const globalGuards = options.messageGuards.map((ref) => refs.guard(ref, "global message guard"));
+		const mappers = options.exceptionMappers.map((ref) => refs.mapper(ref));
+		const plans = definitions.map((definition) => {
+			const name = displayName(definition.token);
+			const path = joinPath(context.prefix, definition.path);
+			const classGuards = definition.messageGuards.map((token) => refs.guard(token, `message guard of ${name}`));
+			const handlers = definition.handlers.map((handler) => ({
+				definition: handler,
+				guards: [
+					...globalGuards,
+					...classGuards,
+					...handler.guards.map((token) => refs.guard(token, `message guard of ${name}.${handler.method}`))
+				],
+				meta: Object.freeze({
+					...definition.meta,
+					...handler.meta
+				})
+			}));
+			const requestScoped = ctx.metadata.providers[definition.token]?.scope === "request";
+			const instance = gatewayInstance(ctx.container, definition.token, requestScoped);
+			const rooms = new RoomRegistry(options.codec);
+			const backpressure = definition.backpressure;
+			const gatewayMaxPayload = definition.maxPayload ?? options.maxPayload;
+			const plan = {
+				definition,
+				name,
+				path,
+				rooms,
+				maxPayload: gatewayMaxPayload,
+				limits: {
+					maxPayload: gatewayMaxPayload,
+					maxPendingMessages: options.maxPendingMessages,
+					concurrency: definition.concurrency ?? 1,
+					backpressureLimit: backpressure?.limit ?? options.backpressure.limit,
+					onBackpressure: backpressure?.onLimit ?? options.backpressure.onLimit,
+					closeTimeoutMs: options.closeTimeoutMs
+				},
+				rateLimit: definition.rateLimit,
+				instance,
+				requestScoped,
+				dispatcher: new GatewayDispatcher({
+					definition,
+					path,
+					handlers,
+					instance,
+					handlerTimeoutMs: options.handlerTimeoutMs,
+					exposeErrors: options.exposeErrors,
+					hooks: ctx.hooks,
+					name,
+					mappers,
+					codec: options.codec,
+					...process.env["NODE_ENV"] === "production" ? {} : { ignoredResult: (handler, event) => ctx.logger.debug(`WebSocketPlugin: the result of ${name}.${handler} is ignored: "${event}" was sent without id (fire and forget)`, {
+						gateway: name,
+						handler,
+						event
+					}) },
+					logError: (message, error, conn) => {
+						ctx.logger.error(`WebSocketPlugin: ${message}`, {
+							err: error,
+							gateway: name,
+							path,
+							connectionId: conn.id,
+							requestId: conn.requestId
+						});
+					},
+					closed: (conn, info) => this.#closed(plan, conn, info)
+				})
+			};
+			this.server.register({
+				type: classOf(ctx.metadata, definition.token),
+				declaredPath: definition.path,
+				path,
+				rooms
+			});
+			return plan;
+		});
+		this.#plans = plans;
+		ctx.logger.debug("WebSocket gateways ready", {
+			gateways: plans.length,
+			transport: transport.name
+		});
+		return plans;
+	}
+	/** Origin, subprotocol and capacity checks, before the guards. */
+	async #precheck(plan, ctx) {
+		if (this.#draining) throw unavailable("The server is shutting down");
+		const options = this.#resolve();
+		const origin = ctx.header("origin");
+		if (origin !== void 0) {
+			let allowed = false;
+			try {
+				allowed = await options.origins.allows(origin, ctx) === true;
+			} catch {
+				allowed = false;
+			}
+			if (!allowed) throw new ForbiddenException("Origin not allowed");
+		}
+		selectProtocol(plan, ctx);
+		if (this.#full(options)) throw unavailable("Too many WebSocket connections");
+	}
+	#full(options) {
+		return this.#connections.size + this.#accepting >= options.maxConnections;
+	}
+	/** After the guards: completes the upgrade and starts the connection in the handshake's scope. */
+	async #accept(plan, ctx, upgrade) {
+		if (this.#draining) throw unavailable("The server is shutting down");
+		const options = this.#resolve();
+		if (this.#full(options)) throw unavailable("Too many WebSocket connections");
+		this.#accepting++;
+		let opened;
+		try {
+			opened = await this.#open(plan, ctx, upgrade);
+		} finally {
+			this.#accepting--;
+		}
+		const { conn, socket } = opened;
+		const ws = this.#context();
+		const openedAt = performance.now();
+		this.#connections.set(conn, openedAt);
+		if (upgrade.native.kind !== "memory" && this.#transport?.accepts === "node") this.#beating.add(conn);
+		this.#stats.opened++;
+		if (ws.hooks.hasListeners(CONNECTION_HOOK)) ws.hooks.emit(CONNECTION_HOOK, connectionEvent("open", plan, conn, openedAt, void 0));
+		conn.start(socket);
+		upgrade.hold(conn.finished);
+		if (this.#draining) conn.closeWith(options.shutdown.code, options.shutdown.reason, "shutdown");
+	}
+	/** Creates the connection (and a request-scoped gateway) and completes the handshake. */
+	async #open(plan, ctx, upgrade) {
+		const ws = this.#context();
+		const protocol = selectProtocol(plan, ctx);
+		const rate = plan.rateLimit;
+		const conn = new WsConnectionImpl({
+			id: crypto.randomUUID(),
+			gateway: plan.path,
+			handshake: ctx,
+			protocol,
+			limits: rate === void 0 ? plan.limits : {
+				...plan.limits,
+				rateLimit: {
+					bucket: new TokenBucket(rate.messages, rate.intervalMs),
+					onLimit: rate.onLimit
+				}
+			},
+			rooms: plan.rooms,
+			driver: plan.dispatcher,
+			stats: this.#stats
+		});
+		ws.container.currentScope()?.set(WsTokens.Connection, conn);
+		if (plan.requestScoped) await plan.instance(conn);
+		const memory = upgrade.native.kind === "memory";
+		let transport = this.#transport;
+		if (memory) {
+			this.#memory ??= memoryTransport();
+			transport = this.#memory;
+		}
+		const run = captureContext();
+		const events = conn.socketEvents();
+		const scoped = {
+			message: (frame, binary) => run(() => events.message(frame, binary)),
+			pong: () => events.pong(),
+			drain: () => events.drain(),
+			close: (code, reason) => run(() => events.close(code, reason))
+		};
+		if (upgrade.expired) throw new HttpException(408, "WebSocket handshake timed out");
+		if (this.#draining) throw unavailable("The server is shutting down");
+		return {
+			conn,
+			socket: await transport.accept(upgrade.native, {
+				protocol,
+				headers: upgrade.headers,
+				maxPayload: plan.maxPayload
+			}, scoped)
+		};
+	}
+	/** A connection fully closed (after `@OnDisconnect`, rooms left). */
+	#closed(plan, conn, info) {
+		const openedAt = this.#connections.get(conn) ?? performance.now();
+		this.#connections.delete(conn);
+		this.#beating.delete(conn);
+		this.#stats.closed++;
+		const hooks = this.#ctx?.hooks;
+		if (hooks?.hasListeners(CONNECTION_HOOK)) hooks.emit(CONNECTION_HOOK, connectionEvent("close", plan, conn, openedAt, info));
+	}
+	#shutdown() {
+		this.#drain ??= this.#closeAll();
+		return this.#drain;
+	}
+	async #closeAll() {
+		this.#draining = true;
+		this.#stopHeartbeat();
+		const options = this.#resolved;
+		const connections = [...this.#connections.keys()];
+		if (options === void 0 || connections.length === 0) return;
+		const { code, reason, timeoutMs } = options.shutdown;
+		for (const conn of connections) conn.closeWith(code, reason, "shutdown");
+		const all = Promise.all(connections.map((conn) => conn.finished));
+		if (await within(all, timeoutMs)) return;
+		for (const conn of connections) if (conn.readyState !== "closed") conn.terminateWith("shutdown");
+		await within(all, options.closeTimeoutMs);
+	}
+	#stopHeartbeat() {
+		if (this.#heartbeat !== void 0) clearInterval(this.#heartbeat);
+		this.#heartbeat = void 0;
+	}
+};
+/** Resolves when `task` settles (`true`) or after `ms` (`false`). */
+async function within(task, ms) {
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(false), ms);
+	});
+	try {
+		return await Promise.race([task.then(() => true), timeout]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function unavailable(message) {
+	return new HttpException(503, message, void 0, { headers: { "retry-after": "1" } });
+}
+function connectionEvent(type, plan, conn, openedAt, info) {
+	return {
+		type,
+		gateway: plan.name,
+		path: plan.path,
+		connectionId: conn.id,
+		requestId: conn.requestId,
+		connection: conn,
+		openedAt,
+		...info === void 0 ? {} : {
+			code: info.code,
+			reason: info.reason,
+			initiator: info.initiator
+		}
+	};
+}
+/** The subprotocol of a handshake: the first of the gateway's `protocols` the client offers (400 otherwise). */
+function selectProtocol(plan, ctx) {
+	const accepted = plan.definition.protocols;
+	if (accepted === void 0 || accepted.length === 0) return "";
+	const offered = (ctx.header("sec-websocket-protocol") ?? "").split(",").map((item) => item.trim()).filter((item) => item !== "");
+	const selected = accepted.find((protocol) => offered.includes(protocol));
+	if (selected === void 0) throw new BadRequestException("Unsupported WebSocket subprotocol");
+	return selected;
+}
+/** The transport of the `transport` option for the native upgrades of the adapter (ZNIGHT051). */
+function selectTransport(options, context) {
+	const kind = context.upgrades;
+	if (kind === void 0) throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, `WebSocketPlugin: the ${context.adapter} adapter cannot serve WebSocket upgrades`, { hints: ["Use a built-in adapter (node, fastify, express, hono) on a server Znight starts"] });
+	let transport = options.transport;
+	if (transport === "auto") transport = kind === "bun" ? bunTransport() : wsTransport();
+	if (transport.accepts !== kind) throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, `WebSocketPlugin: the ${transport.name} transport completes ${transport.accepts} upgrades, but the ${context.adapter} adapter produces ${kind} upgrades`, { hints: kind === "bun" ? ["Use bunTransport() (or transport: 'auto') with honoAdapter() on Bun"] : ["Use wsTransport() (or transport: 'auto') with the node:http adapters"] });
+	return transport;
+}
+/** `prefix` (`''`, `/api`) joined with a normalized gateway path (`/chat`, `/`). */
+function joinPath(prefix, path) {
+	if (prefix === "" || prefix === "/") return path;
+	const base = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+	return path === "/" ? base : `${base}${path}`;
+}
+/** Route decorator metadata as upgrade route entries, with the groups of `metadata.extensions.http`. */
+function metaEntries(meta, groups) {
+	return Object.keys(meta).sort().map((key) => {
+		for (const [group, definition] of Object.entries(groups)) if (definition.keys.includes(key)) return {
+			key,
+			value: meta[key],
+			group,
+			required: definition.required
+		};
+		return {
+			key,
+			value: meta[key]
+		};
+	});
+}
+function classOf(metadata, token) {
+	return metadata.providers[token]?.class;
+}
+/** The gateway instance of a connection: the singleton, or the request-scoped one of its handshake. */
+function gatewayInstance(container, token, requestScoped) {
+	if (requestScoped) return () => container.get(token);
+	let instance;
+	return () => {
+		instance ??= container.get(token);
+		return instance;
+	};
+}
+/** `metadata.extensions.websocket`, checked (ZNIGHT050): `[]` without gateways. */
+function gatewaysOf(metadata) {
+	const section = metadata.extensions?.websocket;
+	if (section === void 0) return [];
+	const gateways = section?.gateways;
+	if (!Array.isArray(gateways)) throw malformed("\"gateways\" must be an array");
+	for (const gateway of gateways) {
+		const where = typeof gateway?.token === "string" ? gateway.token : JSON.stringify(gateway);
+		if (gateway === null || typeof gateway !== "object" || typeof gateway.token !== "string") throw malformed(`invalid gateway ${where}`);
+		if (!Object.hasOwn(metadata.providers, gateway.token)) throw malformed(`the gateway ${where} is not a provider of the metadata`);
+		if (typeof gateway.path !== "string" || !gateway.path.startsWith("/")) throw malformed(`invalid path of ${where}`);
+		if (gateway.protocol !== "events" && gateway.protocol !== "raw") throw malformed(`invalid protocol of ${where}`);
+		if (!Array.isArray(gateway.handlers) || !Array.isArray(gateway.handshakeGuards) || !Array.isArray(gateway.messageGuards)) throw malformed(`handlers, handshakeGuards and messageGuards of ${where} must be arrays`);
+		for (const lifecycle of [gateway.onConnect, gateway.onDisconnect]) if (lifecycle !== void 0 && typeof lifecycle?.invoke !== "function") throw malformed(`invalid lifecycle handler of ${where}`);
+		for (const handler of gateway.handlers) if (handler === null || typeof handler !== "object" || typeof handler.invoke !== "function" || !Array.isArray(handler.guards)) throw malformed(`invalid handler of ${where}`);
+	}
+	return gateways;
+}
+function malformed(reason) {
+	return new ZnightError(ErrorCode.InvalidGateway, `WebSocketPlugin: malformed metadata.extensions.websocket: ${reason}`, { hints: ["Regenerate the container module (znight generate) with the same @znight/websocket version"] });
+}
+/**
+* Message guards and exception mappers resolved once at bootstrap: singletons to their instance,
+* request-scoped and transient providers per call, in the connection's scope.
+*/
+var Refs = class {
+	#container;
+	#metadata;
+	constructor(container, metadata) {
+		this.#container = container;
+		this.#metadata = metadata;
+	}
+	guard(ref, what) {
+		const resolve = this.#resolve(ref, what, "canHandle");
+		return typeof resolve === "function" ? { canHandle: (ctx) => resolve().canHandle(ctx) } : resolve;
+	}
+	mapper(ref) {
+		const resolve = this.#resolve(ref, "exception mapper", "map");
+		return typeof resolve === "function" ? { map: (error, ctx) => resolve().map(error, ctx) } : resolve;
+	}
+	/** The instance, or a function resolving it per call (request-scoped and transient providers). */
+	#resolve(ref, what, method) {
+		if (typeof ref !== "function" && typeof ref !== "string") return ref;
+		const token = typeof ref === "string" ? ref : this.#container.tokenOf(ref);
+		if (token === void 0 || !this.#container.has(token)) {
+			const name = typeof ref === "string" ? displayName(ref) : ref.name || "<anonymous>";
+			throw new ZnightError(ErrorCode.MissingProvider, `WebSocketPlugin: the ${what} ${name} is not a provider`, { hints: ["Add @Injectable() to the class, or pass an instance"] });
+		}
+		const definition = Object.hasOwn(this.#metadata.providers, token) ? this.#metadata.providers[token] : void 0;
+		const cls = definition?.class;
+		if (typeof cls === "function" && typeof cls.prototype?.[method] !== "function") throw new ZnightError(ErrorCode.InvalidGateway, `WebSocketPlugin: the ${what} ${displayName(token)} has no ${method}() method`);
+		const scope = definition?.scope;
+		if (scope === "request" || scope === "transient") return () => this.#container.get(token);
+		return this.#container.get(token);
+	}
+};
+// src/validate.ts
+/**
+* Validates a message payload with a Standard Schema and returns the schema output, synchronously
+* when the schema is synchronous.
+*
+* @throws WsValidationException (`BAD_REQUEST`, `details: [{ path, message }]`) when the payload is invalid.
+*/
+function validatePayload(schema, value) {
+	try {
+		const result = validate(schema, value, "payload");
+		return result instanceof Promise ? result.catch(rethrow) : result;
+	} catch (error) {
+		return rethrow(error);
+	}
+}
+function rethrow(error) {
+	if (error instanceof ValidationException) throw new WsValidationException(error.details);
+	throw error;
+}
+export { Conn, Ctx, EVENT_NAME, Gateway, MemoryClient, OnConnect, OnDisconnect, OnMessage, Payload, RoomRegistry, TokenBucket, UseHandshakeGuard, UseMessageGuard, WebSocketPlugin, WsClient, WsCloseCode, WsClosedError, WsErrorCode, WsException, WsHandshakeError, WsRequestError, WsServer, WsTokens, WsValidationException, codeOfStatus, decodeFrame, encodeErrorEvent, encodeErrorReply, encodeEvent, encodeReply, isFailure, isMessageId, jsonCodec, memoryTransport, validatePayload };
+
+//# sourceMappingURL=index.mjs.map