@marianmeres/ws 0.2.0

package/README.md

@@ -0,0 +1,211 @@
+# @marianmeres/ws
+
+[![NPM](https://img.shields.io/npm/v/@marianmeres/ws)](https://www.npmjs.com/package/@marianmeres/ws)
+[![JSR](https://jsr.io/badges/@marianmeres/ws)](https://jsr.io/@marianmeres/ws)
+[![License](https://img.shields.io/npm/l/@marianmeres/ws)](LICENSE)
+
+A WebSocket client with namespaces, rooms, presence and reconnect that actually
+survives real networks — plus a mountable reference server implementing the same
+protocol.
+
+## Features
+
+- **Reconnects forever** — capped exponential backoff with jitter, plus instant
+  retry when the browser comes back online or the tab regains focus
+- **Detects half-open connections** — the failure where the peer vanishes, no
+  `onclose` ever fires, and a naive client sits "connected" receiving nothing
+- **Namespaces and rooms** — namespace isolates, rooms are channels within it
+- **Presence** — opt-in per room; membership snapshot plus join/leave deltas,
+  re-synced automatically after every reconnect
+- **Buffered sends** — publishes issued while offline are queued (capped, never
+  unbounded) and flushed after re-subscribe
+- **Acknowledged publishes** — `publish()` resolves with a recipient count
+- **Runs everywhere** — `WebSocket` is a global in browsers, Deno, Node 22+, Bun
+  and Workers, so there is no polyfill and no transport dependency
+- **Svelte-store compatible** reactive connection state
+
+## Installation
+
+```bash
+npm install @marianmeres/ws
+```
+
+```bash
+deno add jsr:@marianmeres/ws
+```
+
+> **npm ships the client only.** The reference server needs
+> `Deno.upgradeWebSocket`, so it exists solely as `jsr:@marianmeres/ws/server`.
+> The client is fully runtime-agnostic, so npm consumers lose nothing they could
+> have used.
+
+## ws or sse?
+
+`@marianmeres/sse` is the sibling package: same shape of API, different
+transport, different strengths. In short —
+
+- **Reach for `ws`** when traffic is genuinely bidirectional and chatty
+  (collaborative editing, games, chat with typing indicators), when you need
+  presence, or when you need binary frames.
+- **Reach for `sse`** when traffic is mostly server → client (notifications,
+  live dashboards, progress, activity feeds), or when losing messages across a
+  reconnect is not acceptable — SSE resumes from `Last-Event-ID`, WebSocket has
+  no equivalent.
+
+They are not drop-in replacements for one another and are not meant to be. See
+[COMPARISON.md](https://github.com/marianmeres/sse/blob/master/COMPARISON.md)
+in the `sse` package for the full table.
+
+## Usage
+
+### Client
+
+```typescript
+import { createWSClient } from "@marianmeres/ws";
+
+const ws = createWSClient({
+	url: "/ws",
+	namespace: "org-123",
+	auth: () => session.token, // called on every (re)connect, so refresh works
+});
+
+// Subscribe and handle in one call; the returned function detaches the handler
+// and unsubscribes the room when it was the last one.
+const unsub = await ws.subscribe("chat", (msg) => {
+	console.log(msg.from, msg.payload, msg.timestamp);
+});
+
+const { recipients } = await ws.publish("chat", { text: "hello" });
+
+unsub();
+ws.dispose();
+```
+
+`connect()` is optional — the first `subscribe()` or `publish()` starts the
+connection. Call it explicitly when you want a readiness gate:
+
+```typescript
+await ws.connect(); // resolves once connected; rejects only if retrying cannot help
+```
+
+### Presence
+
+Presence is enabled by _providing a presence handler_, and is opt-in per room —
+a room with thousands of subscribers does not want a join event per peer every
+time the fleet reconnects.
+
+```typescript
+await ws.subscribe("room", onMessage, {
+	presence: (e) => {
+		// e.event is "sync" | "join" | "leave"
+		// "sync" carries the full snapshot, and fires again after every reconnect
+		console.log(e.event, e.clientId, e.members);
+	},
+});
+
+ws.members("room"); // last known membership
+```
+
+### Reactive state (Svelte)
+
+```svelte
+<script>
+    import { createWSClient } from "@marianmeres/ws";
+    const ws = createWSClient({ url: "/ws" });
+    const state = ws.state;
+</script>
+
+{#if $state.connected}
+    <Online />
+{:else if $state.attempt > 0}
+    <p>Reconnecting… (attempt {$state.attempt})</p>
+{/if}
+```
+
+### Server
+
+```typescript
+import { createWSApp } from "@marianmeres/ws/server";
+
+const { app, service } = createWSApp("/ws", [], {
+	verify: async (payload, req) => {
+		const user = await authenticate(payload?.token);
+		// Returning null closes the socket with a terminal code.
+		return user ? { clientId: user.id, namespace: user.orgId } : null;
+	},
+});
+
+// Push to connected clients from anywhere in your app.
+await service.publish("notifications", { text: "deploy finished" }, "org-123");
+
+Deno.serve(app);
+```
+
+Mounted routes, relative to the mount path:
+
+| Method | Path                          | Notes                                     |
+| ------ | ----------------------------- | ----------------------------------------- |
+| GET    | `/`                           | WebSocket upgrade                         |
+| GET    | `/stats`                      | Guarded by `httpAuth` when supplied       |
+| POST   | `/publish/[namespace]/[room]` | Requires `httpAuth`, else **not mounted** |
+| POST   | `/broadcast/[room]`           | Requires `httpAuth`, else **not mounted** |
+
+## Example
+
+A complete room chat — demino server plus a plain HTML client — lives in
+[example/](https://github.com/marianmeres/ws/tree/master/example):
+
+```bash
+deno task example    # builds the client bundle, then serves on :8000
+```
+
+It exercises the handshake, namespaces, rooms, presence, acknowledged
+publishes, the broadcast gate, reconnect with buffered sends, HTTP injection
+and the pub/sub adapter seam. See
+[example/README.md](https://github.com/marianmeres/ws/blob/master/example/README.md).
+
+## Concepts
+
+**Namespace** — the isolation boundary. Clients in different namespaces can
+subscribe to identically named rooms without ever seeing each other's messages.
+A client may only publish into its own namespace.
+
+**Room** — a channel within a namespace. Subscribe to receive its messages.
+
+**Broadcast** — the one operation that crosses namespaces. It is a separate
+method rather than a flag on `publish()` precisely because crossing an isolation
+boundary deserves its own name and its own server-side check: `allowBroadcast`
+**denies by default**.
+
+## Behaviour worth knowing
+
+**Reconnect classification.** Everything reconnects except a local
+`disconnect()` and an explicit terminal close code (`4001 AUTH_FAILED`,
+`4003 FORBIDDEN` by default). A server-sent `1000 Normal Closure` _does_
+reconnect — a graceful shutdown or rolling deploy is exactly when clients must
+come back.
+
+**Terminal failures are loud.** Giving up is the only non-retrying exit, so it
+rejects any pending `connect()`, emits `terminated`, and logs at error level. A
+silent one would be indistinguishable from a network that never recovered.
+
+**Delivery is at-most-once.** A publish that was transmitted but unacknowledged
+when the socket died is _not_ resent — that would risk duplicates, and the
+server has no deduplication. It rejects on `sendTimeout`. At-least-once would
+need server-side replay, which this version does not do.
+
+**Sends are bounded.** Every publish carries one deadline covering queue, flight
+_and_ acknowledgement. Without it, a publish issued while offline would pend
+forever behind an infinite retry.
+
+**`disconnect()` is resumable; `dispose()` is terminal.** Handlers, rooms and
+buffered sends survive a `disconnect()`, so a later `connect()` picks up where
+it left off.
+
+## API
+
+See [API.md](API.md) for complete API documentation.
+
+## License
+
+[MIT](LICENSE)

package/dist/client/backoff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Reconnect backoff. Pure and injectable, so the curve can be unit tested
+ * without waiting on real timers.
+ *
+ * @module
+ */
+/**
+ * Exponential backoff with **equal jitter**.
+ *
+ * Returns a delay in `[d/2, d]` where `d = min(max, base * 2^(attempt-1))`.
+ *
+ * Equal jitter rather than full jitter (`random() * d`): full jitter can
+ * produce near-zero waits, which means a server coming back up gets hammered
+ * by the very clients it just dropped. Equal jitter keeps a floor while still
+ * breaking the lockstep that would otherwise make 10k clients retry in unison.
+ *
+ * The cap matters as much as the jitter — uncapped `base * 2^n` reaches ~17
+ * minutes by attempt 11, which is indistinguishable from "dead" to a user.
+ *
+ * @param attempt - 1-based attempt number
+ * @param base - initial delay in ms
+ * @param max - ceiling in ms
+ * @param rnd - randomness source, injectable for tests
+ */
+export declare function backoffDelay(attempt: number, base: number, max: number, rnd?: () => number): number;

package/dist/client/backoff.js

@@ -0,0 +1,31 @@
+/**
+ * Reconnect backoff. Pure and injectable, so the curve can be unit tested
+ * without waiting on real timers.
+ *
+ * @module
+ */
+/**
+ * Exponential backoff with **equal jitter**.
+ *
+ * Returns a delay in `[d/2, d]` where `d = min(max, base * 2^(attempt-1))`.
+ *
+ * Equal jitter rather than full jitter (`random() * d`): full jitter can
+ * produce near-zero waits, which means a server coming back up gets hammered
+ * by the very clients it just dropped. Equal jitter keeps a floor while still
+ * breaking the lockstep that would otherwise make 10k clients retry in unison.
+ *
+ * The cap matters as much as the jitter — uncapped `base * 2^n` reaches ~17
+ * minutes by attempt 11, which is indistinguishable from "dead" to a user.
+ *
+ * @param attempt - 1-based attempt number
+ * @param base - initial delay in ms
+ * @param max - ceiling in ms
+ * @param rnd - randomness source, injectable for tests
+ */
+export function backoffDelay(attempt, base, max, rnd = Math.random) {
+    const n = Math.max(1, Math.floor(attempt));
+    // 2^n overflows to Infinity well before it matters; Math.min handles it.
+    const full = Math.min(max, base * Math.pow(2, n - 1));
+    const half = full / 2;
+    return Math.round(half + rnd() * half);
+}

package/dist/client/heartbeat.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Application-level ping/pong liveness probe.
+ *
+ * Half-open TCP is *the* defining WebSocket failure: the peer vanishes, no FIN
+ * ever arrives, `onclose` never fires, and the client sits there looking
+ * connected while receiving nothing. Browsers expose no protocol-level ping,
+ * so detecting it requires an application-level probe.
+ *
+ * The interval doubles as proxy keep-alive — nginx and friends drop idle
+ * sockets at 60s by default, so the 25s default sits comfortably under that.
+ *
+ * @module
+ */
+/** Configuration for {@link Heartbeat}. */
+export interface HeartbeatOptions {
+    /** Ping cadence in ms. `0` disables the heartbeat entirely. */
+    interval: number;
+    /** How long to wait for a pong before declaring the socket dead. */
+    timeout: number;
+    /** Send a ping frame. */
+    onPing: () => void;
+    /** No pong arrived in time — the connection is dead but pretending. */
+    onTimeout: () => void;
+}
+/** Drives ping frames and enforces the pong deadline. */
+export declare class Heartbeat {
+    #private;
+    constructor(options: HeartbeatOptions);
+    /** Whether the heartbeat is currently running. */
+    get running(): boolean;
+    start(): void;
+    stop(): void;
+    /**
+     * Any inbound traffic proves the connection is alive, not just a literal
+     * `pong` — so the client feeds every received frame through here.
+     */
+    alive(): void;
+}

package/dist/client/heartbeat.js

@@ -0,0 +1,78 @@
+/**
+ * Application-level ping/pong liveness probe.
+ *
+ * Half-open TCP is *the* defining WebSocket failure: the peer vanishes, no FIN
+ * ever arrives, `onclose` never fires, and the client sits there looking
+ * connected while receiving nothing. Browsers expose no protocol-level ping,
+ * so detecting it requires an application-level probe.
+ *
+ * The interval doubles as proxy keep-alive — nginx and friends drop idle
+ * sockets at 60s by default, so the 25s default sits comfortably under that.
+ *
+ * @module
+ */
+import { createTicker } from "@marianmeres/ticker";
+/** Drives ping frames and enforces the pong deadline. */
+export class Heartbeat {
+    #options;
+    #ticker = null;
+    #unsubscribe = null;
+    #deadline;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Whether the heartbeat is currently running. */
+    get running() {
+        return !!this.#ticker;
+    }
+    start() {
+        if (this.#options.interval <= 0 || this.#ticker)
+            return;
+        this.#ticker = createTicker(this.#options.interval);
+        this.#unsubscribe = this.#ticker.subscribe((timestamp) => {
+            // The ticker emits 0 on stop; only real ticks should ping.
+            if (!timestamp)
+                return;
+            this.#options.onPing();
+            this.#armDeadline();
+        });
+        this.#ticker.start();
+    }
+    stop() {
+        this.#clearDeadline();
+        this.#unsubscribe?.();
+        this.#unsubscribe = null;
+        this.#ticker?.stop();
+        this.#ticker = null;
+    }
+    /**
+     * Any inbound traffic proves the connection is alive, not just a literal
+     * `pong` — so the client feeds every received frame through here.
+     */
+    alive() {
+        this.#clearDeadline();
+    }
+    /**
+     * Starts the pong deadline if one is not already running.
+     *
+     * Deliberately does **not** restart a pending deadline. The deadline
+     * measures time since the *oldest* unanswered ping, so a later ping must
+     * not postpone the verdict on an earlier one — otherwise any configuration
+     * with `pingInterval <= pongTimeout` would reset the timer forever and
+     * silently disable half-open detection altogether.
+     */
+    #armDeadline() {
+        if (this.#deadline !== undefined)
+            return;
+        this.#deadline = setTimeout(() => {
+            this.#deadline = undefined;
+            this.#options.onTimeout();
+        }, this.#options.timeout);
+    }
+    #clearDeadline() {
+        if (this.#deadline !== undefined) {
+            clearTimeout(this.#deadline);
+            this.#deadline = undefined;
+        }
+    }
+}

package/dist/client/outbox.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Outbox + pending-ack registry.
+ *
+ * This is where three decisions collide: awaited acks, buffering while
+ * disconnected, and retrying forever. Combined naively they produce promises
+ * that pend indefinitely, so every tracked frame carries **one timeout
+ * spanning queue + flight + ack** — not an ack-only timeout.
+ *
+ * Written by hand rather than on top of `@marianmeres/batch`: that flusher
+ * triggers on interval/count, whereas this one triggers on connection state.
+ * Bending it into shape costs more than the little code it saves.
+ *
+ * @module
+ */
+import type { ClientFrame, WSPublishResult } from "../protocol/frames.js";
+/** Configuration for {@link Outbox}. */
+export interface OutboxOptions {
+    /** Max frames buffered while disconnected. `0` disables buffering. */
+    maxSize: number;
+    /** Overall deadline per frame, covering queue + flight + ack. */
+    sendTimeout: number;
+    /** Called with frames evicted because the queue was full. */
+    onDrop?: (frames: ClientFrame[]) => void;
+}
+/**
+ * Tracks frames awaiting acknowledgement, and buffers those that could not be
+ * sent yet.
+ */
+export declare class Outbox {
+    #private;
+    constructor(options: OutboxOptions);
+    /** Frames buffered but not yet transmitted. */
+    get queuedCount(): number;
+    /** Frames awaiting an ack, transmitted or not. */
+    get pendingCount(): number;
+    /** Total frames evicted because the queue was full, for the lifetime. */
+    get droppedCount(): number;
+    /**
+     * Registers a frame and returns the promise the caller awaits.
+     *
+     * @param id - correlation id, matched against the server's ack/nack
+     * @param frame - the frame itself, retained so it can be flushed later
+     * @param queued - `true` to buffer it, `false` if it is going out now
+     */
+    track(id: string, frame: ClientFrame, queued: boolean): Promise<WSPublishResult>;
+    /**
+     * Marks every buffered frame as transmitted and returns them in FIFO order.
+     * They stay pending — they are awaiting acks now, not a connection.
+     */
+    drain(): ClientFrame[];
+    /** Resolves a pending frame — the server acked it. */
+    settle(id: string, recipients: number): boolean;
+    /** Rejects a single pending frame. */
+    fail(id: string, error: Error): boolean;
+    /**
+     * Rejects everything. Used on terminal close and on dispose — without it,
+     * callers would wait out `sendTimeout` for an answer that can never come.
+     */
+    failAll(error: Error): void;
+    /**
+     * Rejects only the frames still waiting to be transmitted, leaving
+     * in-flight ones to their acks or timeouts.
+     */
+    failQueued(error: Error): void;
+}

package/dist/client/outbox.js

@@ -0,0 +1,155 @@
+/**
+ * Outbox + pending-ack registry.
+ *
+ * This is where three decisions collide: awaited acks, buffering while
+ * disconnected, and retrying forever. Combined naively they produce promises
+ * that pend indefinitely, so every tracked frame carries **one timeout
+ * spanning queue + flight + ack** — not an ack-only timeout.
+ *
+ * Written by hand rather than on top of `@marianmeres/batch`: that flusher
+ * triggers on interval/count, whereas this one triggers on connection state.
+ * Bending it into shape costs more than the little code it saves.
+ *
+ * @module
+ */
+import { WSOutboxDropError, WSTimeoutError } from "../protocol/errors.js";
+/**
+ * Tracks frames awaiting acknowledgement, and buffers those that could not be
+ * sent yet.
+ */
+export class Outbox {
+    #pending = new Map();
+    /** Ids of not-yet-transmitted frames, in FIFO order. */
+    #queue = [];
+    #dropped = 0;
+    #options;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Frames buffered but not yet transmitted. */
+    get queuedCount() {
+        return this.#queue.length;
+    }
+    /** Frames awaiting an ack, transmitted or not. */
+    get pendingCount() {
+        return this.#pending.size;
+    }
+    /** Total frames evicted because the queue was full, for the lifetime. */
+    get droppedCount() {
+        return this.#dropped;
+    }
+    /**
+     * Registers a frame and returns the promise the caller awaits.
+     *
+     * @param id - correlation id, matched against the server's ack/nack
+     * @param frame - the frame itself, retained so it can be flushed later
+     * @param queued - `true` to buffer it, `false` if it is going out now
+     */
+    track(id, frame, queued) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#discard(id);
+                reject(new WSTimeoutError(this.#options.sendTimeout));
+            }, this.#options.sendTimeout);
+            this.#pending.set(id, { frame, resolve, reject, timer, queued });
+            if (queued) {
+                this.#queue.push(id);
+                this.#applyCap();
+            }
+        });
+    }
+    /**
+     * Marks every buffered frame as transmitted and returns them in FIFO order.
+     * They stay pending — they are awaiting acks now, not a connection.
+     */
+    drain() {
+        const frames = [];
+        for (const id of this.#queue) {
+            const entry = this.#pending.get(id);
+            if (!entry)
+                continue;
+            entry.queued = false;
+            frames.push(entry.frame);
+        }
+        this.#queue = [];
+        return frames;
+    }
+    /** Resolves a pending frame — the server acked it. */
+    settle(id, recipients) {
+        const entry = this.#discard(id);
+        if (!entry)
+            return false;
+        entry.resolve({ recipients });
+        return true;
+    }
+    /** Rejects a single pending frame. */
+    fail(id, error) {
+        const entry = this.#discard(id);
+        if (!entry)
+            return false;
+        entry.reject(error);
+        return true;
+    }
+    /**
+     * Rejects everything. Used on terminal close and on dispose — without it,
+     * callers would wait out `sendTimeout` for an answer that can never come.
+     */
+    failAll(error) {
+        const entries = [...this.#pending.values()];
+        this.#pending.clear();
+        this.#queue = [];
+        for (const entry of entries) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+    }
+    /**
+     * Rejects only the frames still waiting to be transmitted, leaving
+     * in-flight ones to their acks or timeouts.
+     */
+    failQueued(error) {
+        const ids = this.#queue;
+        this.#queue = [];
+        for (const id of ids)
+            this.fail(id, error);
+    }
+    #discard(id) {
+        const entry = this.#pending.get(id);
+        if (!entry)
+            return undefined;
+        clearTimeout(entry.timer);
+        this.#pending.delete(id);
+        if (entry.queued) {
+            const at = this.#queue.indexOf(id);
+            if (at !== -1)
+                this.#queue.splice(at, 1);
+        }
+        return entry;
+    }
+    /**
+     * Enforces `maxSize` by dropping the **oldest** frames.
+     *
+     * Dropping the oldest keeps the freshest state, which is what almost every
+     * real-time use wants. Each victim's promise rejects immediately, so a
+     * caller always gets an answer rather than silently losing a message.
+     */
+    #applyCap() {
+        const max = this.#options.maxSize;
+        const evicted = [];
+        while (this.#queue.length > max) {
+            const id = this.#queue.shift();
+            if (id === undefined)
+                break;
+            const entry = this.#pending.get(id);
+            if (!entry)
+                continue;
+            clearTimeout(entry.timer);
+            this.#pending.delete(id);
+            this.#dropped++;
+            evicted.push(entry.frame);
+            entry.reject(new WSOutboxDropError());
+        }
+        if (evicted.length)
+            this.#options.onDrop?.(evicted);
+    }
+}

package/dist/client/rooms.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Refcounted room registry.
+ *
+ * N handlers on one room produce exactly one wire subscription; the `unsub`
+ * frame goes out when the last handler detaches. This is what lets
+ * `subscribe()` hand back a plain unsubscriber that is safe to call from
+ * component teardown without any coordination between call sites.
+ *
+ * @module
+ */
+import type { SubRequest, WSMessage, WSPresenceEvent } from "../protocol/frames.js";
+/** Receives messages published to a room. */
+export type MessageHandler<T = unknown> = (msg: WSMessage<T>) => void;
+/** Receives membership changes for a room subscribed with presence enabled. */
+export type PresenceHandler = (event: WSPresenceEvent) => void;
+/** What changed as a result of an `add()`, and therefore what the wire needs. */
+export interface AddResult {
+    /** The room is new — a `sub` frame is required. */
+    created: boolean;
+    /** Presence was requested for a room that did not have it — re-`sub`. */
+    presenceUpgraded: boolean;
+}
+/** Tracks rooms, their handlers, and their known membership. */
+export declare class RoomRegistry {
+    #private;
+    /** Rooms currently held, in insertion order. */
+    get rooms(): string[];
+    has(room: string): boolean;
+    wantsPresence(room: string): boolean;
+    members(room: string): string[];
+    /**
+     * Attaches handlers, creating the room entry if needed.
+     *
+     * Presence is enabled by *providing a presence handler* rather than by a
+     * separate boolean — one way to express the intent instead of two that can
+     * disagree.
+     */
+    add(room: string, handler: MessageHandler, presenceHandler?: PresenceHandler): AddResult;
+    /**
+     * Detaches handlers.
+     *
+     * @returns `true` when the room became empty and should be unsubscribed.
+     */
+    remove(room: string, handler: MessageHandler, presenceHandler?: PresenceHandler): boolean;
+    /** Force-removes a room and every handler attached to it. */
+    removeRoom(room: string): boolean;
+    /**
+     * The full subscription set, for re-subscribing after a reconnect in a
+     * single batched frame rather than one round-trip per room.
+     */
+    subRequests(): SubRequest[];
+    /**
+     * Delivers to every handler for the room.
+     *
+     * Handlers are snapshotted first, so a handler that unsubscribes (or
+     * subscribes) during delivery cannot corrupt the in-flight iteration.
+     */
+    deliver(room: string, msg: WSMessage, onError: (e: unknown) => void): void;
+    /** Updates cached membership, then delivers to presence handlers. */
+    deliverPresence(room: string, event: WSPresenceEvent, onError: (e: unknown) => void): void;
+    clear(): void;
+}