@marianmeres/ws 0.2.0

package/dist/client/ws-client.js

@@ -0,0 +1,892 @@
+/**
+ * The WebSocket client.
+ *
+ * @module
+ */
+import { createClog } from "@marianmeres/clog";
+import { createPubSub } from "@marianmeres/pubsub";
+import { base36 } from "@marianmeres/uid";
+import { CLOSE, DEFAULT_NAMESPACE, DEFAULT_TERMINAL_CLOSE_CODES, FRAME, PROTOCOL_VERSION, } from "../protocol/constants.js";
+import { WSConnectTimeoutError, WSDisposedError, WSError, WSNotConnectedError, WSRemoteError, WSTerminatedError, } from "../protocol/errors.js";
+import { backoffDelay } from "./backoff.js";
+import { Heartbeat } from "./heartbeat.js";
+import { Outbox } from "./outbox.js";
+import { RoomRegistry } from "./rooms.js";
+/**
+ * Legal transitions.
+ *
+ * This exists because the reconnect races are where ad-hoc boolean flags rot:
+ * a close arriving mid-`connecting`, a `disconnect()` during backoff, a
+ * terminal close while the outbox is flushing. An illegal transition is a bug
+ * in this file, so it logs loudly rather than failing quietly.
+ */
+const TRANSITIONS = {
+    idle: ["connecting", "disposed"],
+    connecting: ["authenticating", "reconnecting", "terminated", "idle", "disposed"],
+    authenticating: ["open", "reconnecting", "terminated", "idle", "disposed"],
+    open: ["reconnecting", "terminated", "idle", "disposed"],
+    reconnecting: ["connecting", "terminated", "idle", "disposed"],
+    // A terminal state is still re-entrant via an explicit connect() — the user
+    // may have refreshed the credentials that got them rejected.
+    terminated: ["connecting", "idle", "disposed"],
+    disposed: [],
+};
+const DEFAULTS = {
+    url: "/ws",
+    namespace: DEFAULT_NAMESPACE,
+    autoConnect: true,
+    reconnectDelay: 500,
+    reconnectDelayMax: 30_000,
+    pingInterval: 25_000,
+    pongTimeout: 10_000,
+    connectTimeout: 0,
+    sendTimeout: 30_000,
+    outboxMaxSize: 100,
+};
+const defaultEncode = (frame) => JSON.stringify(frame);
+const defaultDecode = (raw) => JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw));
+const noop = () => { };
+/** Idempotent, `using`-compatible unsubscriber. */
+function makeUnsubscriber(fn) {
+    let done = false;
+    const u = (() => {
+        if (done)
+            return;
+        done = true;
+        fn();
+    });
+    u[Symbol.dispose] = u;
+    return u;
+}
+/**
+ * A reconnecting WebSocket client with namespaces, rooms and presence.
+ *
+ * @example
+ * ```ts
+ * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
+ * const unsub = await ws.subscribe("chat", (msg) => console.log(msg.payload));
+ * await ws.publish("chat", { text: "hi" });
+ * ```
+ */
+export class WSClient {
+    #url;
+    #requestedNamespace;
+    #requestedClientId;
+    #authFn;
+    #autoConnect;
+    #terminalCodes;
+    #reconnectDelay;
+    #reconnectDelayMax;
+    #connectTimeout;
+    #pongTimeout;
+    #outboxMaxSize;
+    #encode;
+    #decode;
+    /** Logger. Assignable — set to `null` to silence. */
+    logger;
+    #socket = null;
+    /**
+     * Guards against events from superseded sockets. Every callback checks its
+     * captured generation, so a slow `onclose` from an old socket cannot
+     * cancel the reconnect that replaced it.
+     */
+    #generation = 0;
+    #state = "idle";
+    #clientId = null;
+    #namespace = null;
+    #attempt = 0;
+    #lastError = null;
+    #intentional = false;
+    #rooms = new RoomRegistry();
+    #outbox;
+    #heartbeat;
+    #bus = createPubSub();
+    #stateBus = createPubSub();
+    #reconnectTimer;
+    #handshakeTimer;
+    #connectTimer;
+    #connectDeferred = null;
+    #wakeListeners = [];
+    /**
+     * Nothing connects here — the socket opens on the first `connect()`,
+     * `subscribe()` or `publish()`.
+     *
+     * @param options - see {@link WSClientOptions}; every field has a default
+     */
+    constructor(options = {}) {
+        this.logger = options.logger === undefined ? createClog("ws") : options.logger;
+        this.#url = WSClient.resolveUrl(options.url ?? DEFAULTS.url);
+        this.#requestedNamespace = options.namespace ?? DEFAULTS.namespace;
+        this.#requestedClientId = options.clientId;
+        this.#authFn = options.auth;
+        this.#autoConnect = options.autoConnect ?? DEFAULTS.autoConnect;
+        this.#terminalCodes = options.terminalCloseCodes ??
+            DEFAULT_TERMINAL_CLOSE_CODES;
+        this.#reconnectDelay = options.reconnectDelay ?? DEFAULTS.reconnectDelay;
+        this.#reconnectDelayMax = options.reconnectDelayMax ??
+            DEFAULTS.reconnectDelayMax;
+        this.#connectTimeout = options.connectTimeout ?? DEFAULTS.connectTimeout;
+        this.#pongTimeout = options.pongTimeout ?? DEFAULTS.pongTimeout;
+        this.#outboxMaxSize = options.outboxMaxSize ?? DEFAULTS.outboxMaxSize;
+        this.#encode = options.encode ?? defaultEncode;
+        this.#decode = options.decode ?? defaultDecode;
+        this.#outbox = new Outbox({
+            maxSize: this.#outboxMaxSize,
+            sendTimeout: options.sendTimeout ?? DEFAULTS.sendTimeout,
+            onDrop: options.onOutboxDrop,
+        });
+        this.#heartbeat = new Heartbeat({
+            interval: options.pingInterval ?? DEFAULTS.pingInterval,
+            timeout: options.pongTimeout ?? DEFAULTS.pongTimeout,
+            onPing: () => this.#sendRaw({ type: FRAME.PING }),
+            onTimeout: () => {
+                this.logger?.warn?.("pong timeout — connection is half-open");
+                this.#forceClose(CLOSE.IDLE_TIMEOUT, "pong timeout");
+            },
+        });
+        // Rooms configured up front get a no-op handler; the `message` firehose
+        // still fires, so `rooms: [...]` + `on("message")` is a valid style.
+        for (const room of options.rooms ?? [])
+            this.#rooms.add(room, noop);
+        this.#installWakeListeners();
+    }
+    /**
+     * Normalizes an endpoint: relative paths resolve against `location`, and
+     * `http(s)` is upgraded to `ws(s)`.
+     *
+     * @param input - absolute url, or a path when running in a browser
+     * @returns the normalized `ws(s)://` url
+     * @throws {WSError} when the input cannot be resolved — outside a browser
+     * there is no `location` to resolve a relative path against
+     */
+    static resolveUrl(input) {
+        const base = typeof globalThis.location !== "undefined"
+            ? globalThis.location.href
+            : undefined;
+        let url;
+        try {
+            url = new URL(String(input), base);
+        }
+        catch {
+            throw new WSError(`Invalid url "${input}". Outside a browser an absolute ws:// or ` +
+                `wss:// url is required.`);
+        }
+        if (url.protocol === "http:")
+            url.protocol = "ws:";
+        else if (url.protocol === "https:")
+            url.protocol = "wss:";
+        return url;
+    }
+    // ---------------------------------------------------------------- getters
+    /** `true` only when authenticated and usable — not merely socket-open. */
+    get connected() {
+        return this.#state === "open";
+    }
+    /** Current lifecycle state. See {@link WSConnectionState}. */
+    get connectionState() {
+        return this.#state;
+    }
+    /** Server-assigned id, available once connected. */
+    get clientId() {
+        return this.#clientId;
+    }
+    /** Active namespace — the server's assignment wins over the request. */
+    get namespace() {
+        return this.#namespace ?? this.#requestedNamespace;
+    }
+    /** Resolved endpoint. A copy — mutating it does not affect the client. */
+    get url() {
+        return new URL(this.#url.href);
+    }
+    /**
+     * The underlying socket, or `null` while disconnected.
+     *
+     * Escape hatch for inspection. Sending on it directly bypasses the outbox
+     * and the ack correlation, so don't.
+     */
+    get socket() {
+        return this.#socket;
+    }
+    /** Rooms currently subscribed. */
+    get rooms() {
+        return this.#rooms.rooms;
+    }
+    /**
+     * Reactive state, Svelte-store compatible: the callback fires immediately
+     * with the current value and again on every change.
+     */
+    get state() {
+        return {
+            subscribe: (cb) => {
+                cb(this.#snapshot());
+                return this.#stateBus.subscribe("state", cb);
+            },
+        };
+    }
+    /**
+     * Debug snapshot: url, state, identity, rooms and outbox counters.
+     *
+     * For logging and troubleshooting — the shape is not part of the stable API.
+     */
+    dump() {
+        return {
+            url: this.#url.href,
+            state: this.#state,
+            clientId: this.#clientId,
+            namespace: this.namespace,
+            rooms: this.#rooms.rooms,
+            attempt: this.#attempt,
+            pending: this.#outbox.pendingCount,
+            queued: this.#outbox.queuedCount,
+            dropped: this.#outbox.droppedCount,
+        };
+    }
+    // ----------------------------------------------------------------- events
+    /**
+     * Subscribes to a lifecycle event. See {@link WSEvents}.
+     *
+     * @param event - event name
+     * @param cb - handler; a throw here is caught and reported as `error`
+     * @returns detaches the handler; also `Symbol.dispose`-compatible
+     */
+    on(event, cb) {
+        return this.#bus.subscribe(event, cb);
+    }
+    /**
+     * Like {@link on}, but detaches after the first emission.
+     *
+     * @param event - event name
+     * @param cb - handler
+     * @returns detaches the handler early, if it has not fired yet
+     */
+    once(event, cb) {
+        return this.#bus.subscribeOnce(event, cb);
+    }
+    // -------------------------------------------------------------- lifecycle
+    /**
+     * Starts the connection and resolves once it is established.
+     *
+     * Idempotent: concurrent calls share one promise, and it resolves
+     * immediately when already connected.
+     *
+     * Rejects **only** where retrying cannot help:
+     * - {@link WSTerminatedError} — terminal close code (bad credentials, etc.)
+     * - {@link WSConnectTimeoutError} — `connectTimeout` elapsed; note the
+     *   client keeps retrying in the background, so this bounds *your await*,
+     *   not the connection attempt
+     *
+     * Ordinary network failure never rejects; that is what the infinite retry
+     * is for.
+     *
+     * Calling this is optional when `autoConnect` is on — it is a readiness
+     * gate, not a prerequisite.
+     *
+     * @returns resolves once authenticated
+     */
+    connect() {
+        if (this.#state === "disposed") {
+            return Promise.reject(new WSDisposedError());
+        }
+        if (this.#state === "open")
+            return Promise.resolve();
+        if (this.#connectDeferred)
+            return this.#connectDeferred.promise;
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        this.#connectDeferred = { promise, resolve, reject };
+        if (this.#connectTimeout > 0) {
+            this.#connectTimer = setTimeout(() => {
+                this.#settleConnect(new WSConnectTimeoutError(this.#connectTimeout));
+            }, this.#connectTimeout);
+        }
+        this.#intentional = false;
+        if (this.#state === "idle" || this.#state === "terminated")
+            this.#open();
+        return promise;
+    }
+    /**
+     * Stops retrying and closes the socket.
+     *
+     * Resumable: handlers, room subscriptions and buffered sends all survive,
+     * so a later `connect()` picks up exactly where this left off. Use
+     * {@link dispose} for terminal teardown.
+     */
+    disconnect() {
+        if (this.#state === "disposed")
+            return;
+        this.logger?.debug?.("disconnect()");
+        this.#intentional = true;
+        this.#clearTimers();
+        this.#heartbeat.stop();
+        this.#settleConnect(new WSTerminatedError(CLOSE.CLIENT_GONE, "disconnect() called"));
+        this.#closeSocket(CLOSE.CLIENT_GONE, "client disconnect");
+        this.#setState("idle");
+    }
+    /**
+     * Terminal teardown: disconnects, then drops every handler, room, timer and
+     * pending promise. The instance is unusable afterwards.
+     */
+    dispose() {
+        if (this.#state === "disposed")
+            return;
+        this.logger?.debug?.("dispose()");
+        this.disconnect();
+        this.#outbox.failAll(new WSDisposedError());
+        this.#rooms.clear();
+        this.#bus.unsubscribeAll();
+        this.#stateBus.unsubscribeAll();
+        this.#removeWakeListeners();
+        this.#setState("disposed");
+    }
+    // ---------------------------------------------------------- subscriptions
+    /**
+     * Subscribes to a room and attaches a handler.
+     *
+     * The handler is attached **synchronously**, before any frame goes out, so
+     * nothing arriving between the request and its acknowledgement is lost.
+     *
+     * Rooms are refcounted: N handlers produce one wire subscription, and the
+     * returned unsubscriber detaches this handler — sending `unsub` only when
+     * it was the last one.
+     *
+     * Resolution: when connected, this awaits the server's acknowledgement, so
+     * a rejected subscription surfaces as a rejection here. When not connected
+     * it resolves as soon as the room is registered — the subscription is then
+     * guaranteed to be established by the re-subscribe step on the next
+     * connect, and a failure there surfaces as an `error` event.
+     *
+     * @param room - room name, scoped to this client's namespace
+     * @param handler - receives every message published to the room
+     * @param options - pass `presence` to enable membership tracking
+     * @returns detaches this handler; also `Symbol.dispose`-compatible, and
+     * idempotent, so calling it twice is harmless
+     * @throws {WSRemoteError} when connected and the server refuses
+     * @throws {WSDisposedError} when the client was disposed
+     *
+     * @example
+     * ```ts
+     * const unsub = await ws.subscribe("chat", (msg) => render(msg.payload), {
+     *     presence: (e) => setMembers(e.members),
+     * });
+     * ```
+     */
+    async subscribe(room, handler, options) {
+        this.#assertUsable();
+        const messageHandler = handler;
+        const presenceHandler = options?.presence;
+        const { created, presenceUpgraded } = this.#rooms.add(room, messageHandler, presenceHandler);
+        const unsubscriber = makeUnsubscriber(() => {
+            const emptied = this.#rooms.remove(room, messageHandler, presenceHandler);
+            if (emptied && this.connected) {
+                this.#sendControl({
+                    type: FRAME.UNSUB,
+                    id: this.#nextId(),
+                    rooms: [room],
+                });
+            }
+        });
+        if (this.#autoConnect)
+            this.#ensureStarted();
+        if ((created || presenceUpgraded) && this.connected) {
+            try {
+                await this.#sendControl({
+                    type: FRAME.SUB,
+                    id: this.#nextId(),
+                    rooms: [{ room, presence: this.#rooms.wantsPresence(room) }],
+                });
+            }
+            catch (e) {
+                // Keep local state honest: if the server refused, we are not
+                // subscribed, and pretending otherwise would silently swallow
+                // every message the caller expects.
+                this.#rooms.remove(room, messageHandler, presenceHandler);
+                throw e;
+            }
+        }
+        return unsubscriber;
+    }
+    /**
+     * Removes every handler for a room and unsubscribes it.
+     *
+     * The blunt counterpart to the refcounted unsubscriber returned by
+     * {@link subscribe} — this drops other call sites' handlers too.
+     *
+     * @param room - room name; unknown rooms are a no-op
+     */
+    async unsubscribe(room) {
+        this.#assertUsable();
+        if (!this.#rooms.removeRoom(room))
+            return;
+        if (this.connected) {
+            await this.#sendControl({
+                type: FRAME.UNSUB,
+                id: this.#nextId(),
+                rooms: [room],
+            });
+        }
+    }
+    /**
+     * Whether the room is held locally.
+     *
+     * Reflects local intent, not server state: a room registered while offline
+     * reads `true` before the wire subscription exists.
+     *
+     * @param room - room name
+     */
+    isSubscribed(room) {
+        return this.#rooms.has(room);
+    }
+    /**
+     * Last known membership of a presence-enabled room.
+     *
+     * @param room - room name
+     * @returns a copy of the members; empty when the room has no presence
+     */
+    members(room) {
+        return this.#rooms.members(room);
+    }
+    // --------------------------------------------------------------- sending
+    /**
+     * Publishes to a room within this client's namespace.
+     *
+     * Resolves with the recipient count once the server acknowledges. While
+     * disconnected the frame is buffered and the promise stays pending until it
+     * flushes — bounded by `sendTimeout`, never indefinitely.
+     *
+     * @param room - target room
+     * @param payload - opaque application data; never inspected or mutated
+     * @param namespace - must equal this client's namespace; the server rejects
+     * anything else, so this is only useful for asserting the expected one
+     * @returns the recipient count reported by the receiving server instance —
+     * best-effort telemetry, not a delivery guarantee
+     * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
+     * @throws {WSOutboxDropError} evicted from a full outbox
+     * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSRemoteError} the server rejected it with a `nack`
+     */
+    publish(room, payload, namespace) {
+        this.#assertUsable();
+        const id = this.#nextId();
+        return this.#send({
+            type: FRAME.PUB,
+            id,
+            room,
+            payload,
+            ...(namespace ? { namespace } : {}),
+        }, id);
+    }
+    /**
+     * Publishes to a room across **all** namespaces.
+     *
+     * This crosses the isolation boundary, which is why it is its own method
+     * rather than a flag on {@link publish} — the server gates it separately
+     * via `allowBroadcast`, and it denies by default.
+     *
+     * @param room - target room, in every namespace at once
+     * @param payload - opaque application data
+     * @returns the recipient count across all namespaces on the receiving
+     * server instance
+     * @throws {WSRemoteError} with code `forbidden` when `allowBroadcast` denies
+     */
+    broadcast(room, payload) {
+        this.#assertUsable();
+        const id = this.#nextId();
+        return this.#send({ type: FRAME.BROADCAST, id, room, payload }, id);
+    }
+    // -------------------------------------------------------------- internals
+    #nextId() {
+        return base36(12);
+    }
+    #assertUsable() {
+        if (this.#state === "disposed")
+            throw new WSDisposedError();
+    }
+    #ensureStarted() {
+        if (this.#state === "idle")
+            this.#open();
+    }
+    #send(frame, id) {
+        if (this.#autoConnect)
+            this.#ensureStarted();
+        const canSendNow = this.connected &&
+            this.#socket?.readyState === WebSocket.OPEN;
+        if (!canSendNow && this.#outboxMaxSize === 0) {
+            return Promise.reject(new WSNotConnectedError());
+        }
+        const promise = this.#outbox.track(id, frame, !canSendNow);
+        if (canSendNow)
+            this.#sendRaw(frame);
+        return promise;
+    }
+    /**
+     * Sends a control frame that must never be buffered.
+     *
+     * `sub`/`unsub` bypass the outbox deliberately: they are replayed wholesale
+     * by the re-subscribe step on reconnect, so queueing them too would apply
+     * them twice.
+     */
+    #sendControl(frame) {
+        const id = "id" in frame ? frame.id : this.#nextId();
+        const promise = this.#outbox.track(id, frame, false);
+        this.#sendRaw(frame);
+        return promise;
+    }
+    #sendRaw(frame) {
+        const socket = this.#socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            socket.send(this.#encode(frame));
+        }
+        catch (e) {
+            this.#fail(e, "send failed");
+        }
+    }
+    #open() {
+        // Defensive: every caller already guards this, but a second socket
+        // opened from a race here would leak the first one silently.
+        if (this.#state === "connecting" ||
+            this.#state === "authenticating" ||
+            this.#state === "open") {
+            return;
+        }
+        if (!this.#setState("connecting"))
+            return;
+        this.#intentional = false;
+        const generation = ++this.#generation;
+        let socket;
+        try {
+            socket = new WebSocket(this.#url);
+        }
+        catch (e) {
+            this.#fail(e, "socket construction failed");
+            this.#scheduleReconnect();
+            return;
+        }
+        this.#socket = socket;
+        this.logger?.debug?.(`connecting to ${this.#url.href}`);
+        socket.onopen = () => {
+            if (generation !== this.#generation)
+                return;
+            void this.#onOpen(generation);
+        };
+        socket.onmessage = (event) => {
+            if (generation !== this.#generation)
+                return;
+            this.#onMessage(event.data);
+        };
+        socket.onerror = () => {
+            if (generation !== this.#generation)
+                return;
+            // The browser deliberately withholds detail here; onclose carries
+            // the actionable information, so this is informational only.
+            this.logger?.debug?.("socket error");
+        };
+        socket.onclose = (event) => {
+            if (generation !== this.#generation)
+                return;
+            this.#onClose(event.code, event.reason);
+        };
+    }
+    async #onOpen(generation) {
+        this.#emit("open", undefined);
+        if (!this.#setState("authenticating"))
+            return;
+        let payload = null;
+        try {
+            payload = (await this.#authFn?.()) ?? null;
+        }
+        catch (e) {
+            this.#fail(e, "auth payload failed");
+            this.#forceClose(CLOSE.PROTOCOL_ERROR, "auth payload failed");
+            return;
+        }
+        // The await above yields; a close may have superseded this socket.
+        if (generation !== this.#generation)
+            return;
+        this.#sendRaw({
+            type: FRAME.AUTH,
+            id: this.#nextId(),
+            protocol: PROTOCOL_VERSION,
+            payload,
+            ...(this.#requestedClientId ? { clientId: this.#requestedClientId } : {}),
+            namespace: this.#requestedNamespace,
+        });
+        // Without this, a server that accepts the socket then never replies
+        // leaves us in `authenticating` forever — the heartbeat has not started
+        // yet, so nothing else would notice.
+        this.#handshakeTimer = setTimeout(() => {
+            this.logger?.warn?.("handshake timeout");
+            this.#forceClose(CLOSE.AUTH_TIMEOUT, "handshake timeout");
+        }, this.#pongTimeout);
+    }
+    #onMessage(raw) {
+        // Any inbound traffic proves the socket is alive, not just a pong.
+        this.#heartbeat.alive();
+        let frame;
+        try {
+            frame = this.#decode(raw);
+        }
+        catch (e) {
+            this.#fail(e, "decode failed");
+            return;
+        }
+        if (!frame || typeof frame.type !== "string") {
+            this.logger?.warn?.("ignoring frame without a type", frame);
+            return;
+        }
+        switch (frame.type) {
+            case FRAME.HELLO:
+                this.#onHello(frame.clientId, frame.namespace, frame.protocol);
+                break;
+            case FRAME.ACK:
+                this.#outbox.settle(frame.id, frame.recipients ?? 0);
+                break;
+            case FRAME.NACK:
+                this.#outbox.fail(frame.id, new WSRemoteError(frame.error));
+                break;
+            case FRAME.MSG: {
+                const { type: _t, ...message } = frame;
+                this.#emit("message", message);
+                this.#rooms.deliver(message.room, message, (e) => this.#fail(e, "message handler threw"));
+                break;
+            }
+            case FRAME.PRESENCE: {
+                const { type: _t, ...event } = frame;
+                this.#emit("presence", event);
+                this.#rooms.deliverPresence(event.room, event, (e) => this.#fail(e, "presence handler threw"));
+                break;
+            }
+            case FRAME.PONG:
+                break;
+            case FRAME.ERROR:
+                this.#fail(new WSRemoteError(frame.error), "server error");
+                break;
+            default:
+                this.logger?.warn?.("ignoring unknown frame type", frame);
+        }
+    }
+    #onHello(clientId, namespace, protocol) {
+        clearTimeout(this.#handshakeTimer);
+        this.#handshakeTimer = undefined;
+        if (protocol !== PROTOCOL_VERSION) {
+            this.logger?.warn?.(`protocol version mismatch (client ${PROTOCOL_VERSION}, server ${protocol})`);
+        }
+        this.#clientId = clientId;
+        this.#namespace = namespace;
+        this.#attempt = 0;
+        this.#lastError = null;
+        if (!this.#setState("open"))
+            return;
+        this.logger?.debug?.(`connected as ${clientId} in "${namespace}"`);
+        this.#emit("connected", { clientId, namespace });
+        this.#heartbeat.start();
+        this.#settleConnect(null);
+        // Order matters and is not cosmetic: re-subscribe first, then flush.
+        // The socket preserves ordering, so the server registers the rooms
+        // before it sees any buffered publish destined for them.
+        const requests = this.#rooms.subRequests();
+        if (requests.length) {
+            this.#sendControl({
+                type: FRAME.SUB,
+                id: this.#nextId(),
+                rooms: requests,
+            }).catch((e) => this.#fail(e, "re-subscribe failed"));
+        }
+        const buffered = this.#outbox.drain();
+        if (buffered.length) {
+            this.logger?.debug?.(`flushing ${buffered.length} buffered frame(s)`);
+            for (const frame of buffered)
+                this.#sendRaw(frame);
+        }
+    }
+    #onClose(code, reason) {
+        clearTimeout(this.#handshakeTimer);
+        this.#handshakeTimer = undefined;
+        this.#heartbeat.stop();
+        this.#socket = null;
+        const terminal = this.#terminalCodes.includes(code);
+        const willReconnect = !this.#intentional && !terminal &&
+            this.#state !== "disposed";
+        this.logger?.debug?.(`closed (${code}${reason ? ` ${reason}` : ""}), reconnect=${willReconnect}`);
+        this.#emit("close", { code, reason, willReconnect });
+        if (terminal) {
+            this.#setState("terminated");
+            const error = new WSTerminatedError(code, reason);
+            this.#lastError = error;
+            // Loud on purpose: this is the only path where a client that
+            // otherwise retries forever gives up, and a silent one looks
+            // exactly like a network that never came back.
+            this.logger?.error?.(error.message);
+            this.#outbox.failAll(error);
+            this.#settleConnect(error);
+            this.#emit("terminated", { code, reason });
+            return;
+        }
+        if (!willReconnect) {
+            this.#setState("idle");
+            return;
+        }
+        this.#scheduleReconnect();
+    }
+    #scheduleReconnect() {
+        if (!this.#setState("reconnecting"))
+            return;
+        this.#attempt++;
+        const delay = backoffDelay(this.#attempt, this.#reconnectDelay, this.#reconnectDelayMax);
+        this.logger?.debug?.(`reconnecting in ${delay}ms (attempt ${this.#attempt})`);
+        this.#emit("reconnecting", { attempt: this.#attempt, delay });
+        this.#publishState();
+        clearTimeout(this.#reconnectTimer);
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = undefined;
+            this.#open();
+        }, delay);
+    }
+    /**
+     * Reconnect right now instead of waiting out the backoff.
+     *
+     * Matters more than backoff tuning: a laptop waking from sleep should be
+     * back in milliseconds, not sit out a 30s timer it started before sleeping.
+     */
+    #wake(source) {
+        if (this.#state !== "reconnecting")
+            return;
+        this.logger?.debug?.(`${source} — retrying immediately`);
+        clearTimeout(this.#reconnectTimer);
+        this.#reconnectTimer = undefined;
+        this.#attempt = 0;
+        this.#open();
+    }
+    #installWakeListeners() {
+        const target = globalThis;
+        if (typeof target.addEventListener !== "function")
+            return;
+        const onOnline = () => this.#wake("online");
+        const onVisible = () => {
+            if (target.document?.visibilityState === "visible") {
+                this.#wake("tab visible");
+            }
+        };
+        target.addEventListener("online", onOnline);
+        this.#wakeListeners.push(() => target.removeEventListener?.("online", onOnline));
+        if (target.document) {
+            target.addEventListener("visibilitychange", onVisible);
+            this.#wakeListeners.push(() => target.removeEventListener?.("visibilitychange", onVisible));
+        }
+    }
+    #removeWakeListeners() {
+        for (const remove of this.#wakeListeners)
+            remove();
+        this.#wakeListeners = [];
+    }
+    /**
+     * Closes a socket we have decided is dead, and drives the close transition
+     * ourselves.
+     *
+     * `#closeSocket` supersedes the generation, so the real `onclose` — if it
+     * arrives at all, which for a half-open socket it may not — is ignored.
+     * That is the point: waiting for it is exactly the hang we are escaping.
+     */
+    #forceClose(code, reason) {
+        this.#closeSocket(code, reason);
+        this.#onClose(code, reason);
+    }
+    #closeSocket(code, reason) {
+        const socket = this.#socket;
+        this.#socket = null;
+        // Supersede: any late callback from this socket is now ignored.
+        this.#generation++;
+        if (!socket)
+            return;
+        try {
+            if (socket.readyState === WebSocket.OPEN ||
+                socket.readyState === WebSocket.CONNECTING) {
+                socket.close(code, reason);
+            }
+        }
+        catch {
+            // Closing an already-dead socket is not worth reporting.
+        }
+    }
+    #clearTimers() {
+        clearTimeout(this.#reconnectTimer);
+        clearTimeout(this.#handshakeTimer);
+        this.#reconnectTimer = undefined;
+        this.#handshakeTimer = undefined;
+    }
+    #settleConnect(error) {
+        clearTimeout(this.#connectTimer);
+        this.#connectTimer = undefined;
+        const deferred = this.#connectDeferred;
+        if (!deferred)
+            return;
+        this.#connectDeferred = null;
+        if (error)
+            deferred.reject(error);
+        else
+            deferred.resolve();
+    }
+    #setState(next) {
+        if (this.#state === next)
+            return true;
+        if (!TRANSITIONS[this.#state].includes(next)) {
+            this.logger?.warn?.(`ignoring illegal state transition ${this.#state} -> ${next}`);
+            return false;
+        }
+        this.#state = next;
+        this.#publishState();
+        return true;
+    }
+    #snapshot() {
+        return {
+            state: this.#state,
+            connected: this.#state === "open",
+            connecting: this.#state === "connecting" ||
+                this.#state === "authenticating" ||
+                this.#state === "reconnecting",
+            attempt: this.#attempt,
+            lastError: this.#lastError,
+        };
+    }
+    #publishState() {
+        this.#stateBus.publish("state", this.#snapshot());
+    }
+    #emit(event, data) {
+        this.#bus.publish(event, data);
+    }
+    #fail(error, context) {
+        const err = error instanceof Error ? error : new WSError(String(error));
+        this.#lastError = err;
+        this.logger?.error?.(`${context}: ${err.message}`);
+        this.#emit("error", err);
+    }
+}
+/**
+ * Creates a {@link WSClient}.
+ *
+ * Both this and the class are exported, following the `PubSub` /
+ * `createPubSub` precedent in `@marianmeres/pubsub`.
+ *
+ * @param options - see {@link WSClientOptions}
+ * @returns a client that has not connected yet
+ *
+ * @example
+ * ```ts
+ * const ws = createWSClient({
+ *     url: "wss://example.com/ws",
+ *     namespace: "org-123",
+ *     auth: () => session.token, // re-read on every reconnect
+ * });
+ *
+ * await ws.subscribe("chat", (msg) => console.log(msg.from, msg.payload));
+ * await ws.publish("chat", { text: "hello" });
+ * ```
+ */
+export function createWSClient(options = {}) {
+    return new WSClient(options);
+}