@marianmeres/ws 0.4.1 → 0.5.0

package/README.md

@@ -4,9 +4,11 @@
 [![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](./PROTOCOL.md).
+A WebSocket client that survives real networks — reconnect, half-open
+detection, buffered sends, token refresh — used either as a plain **message
+channel to your server** or with **rooms and presence** on top. Plus a mountable
+reference server, and a [protocol](./PROTOCOL.md) small enough to implement in
+any language.
 
 ## Features
 
@@ -14,12 +16,12 @@ survives real networks — plus a mountable reference server implementing the sa
   retry when the browser comes back online or the tab becomes visible again
 - **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
+- **Buffered sends** — anything sent while offline is queued (capped, never
+  unbounded) and flushed on reconnect, with one deadline per send
+- **Token refresh for free** — the `auth()` callback runs before every
+  (re)connect
+- **Two ways to talk** — plain messages to and from the server, fire-and-forget
+  or request/response; or namespaces, rooms, presence and broadcast
 - **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
@@ -39,26 +41,92 @@ deno add jsr:@marianmeres/ws
 > The client is fully runtime-agnostic, so npm consumers lose nothing they could
 > have used.
 
-## ws or sse?
+## Two ways to use it
 
-`@marianmeres/sse` is the sibling package: same shape of API, different
-transport, different strengths. In short —
+The protocol has a small required **core** — a handshake, messages both ways, a
+heartbeat — and an optional **rooms extension**. Which one you use decides what
+your server has to implement:
 
-- **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.
+|                        | Messages                                                      | Rooms                                                                         |
+| ---------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Who talks to whom      | the client and **the server**                                 | clients to **each other**, relayed by the server                              |
+| Client API             | `send()`, `on("message")`                                     | `subscribe()`, `publish()`, `broadcast()`                                     |
+| The server implements  | the core only — 8 small frame types                           | the core plus the rooms extension                                             |
+| Server in any language | [PROTOCOL.md §8](PROTOCOL.md#8-python-a-core-server) (Python) | [PROTOCOL.md §9](PROTOCOL.md#9-python-the-full-reference-with-rooms) (Python) |
+| Reference server       | `onMessage` + `service.send()`                                | works as is                                                                   |
 
-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.
+Both get everything in the feature list above. They also mix freely on one
+connection: a room-based app can still `send()` to the server, and a server can
+still push directly to one client.
+
+### 1. Messages — a data channel to your server
+
+No rooms, no namespaces, no ceremony: the client sends messages to the server,
+the server sends messages to the client.
+
+```typescript
+import { createWSClient, WSRemoteError } from "@marianmeres/ws";
+
+const ws = createWSClient({
+	url: "wss://api.example.com/ws",
+	auth: () => session.token, // called on every (re)connect, so refresh works
+});
+
+// Everything the server pushes.
+ws.on("message", (msg) => console.log(msg.payload));
+
+// Fire-and-forget: resolves once written to the socket. Safe not to await.
+ws.send({ op: "cursor", x: 10, y: 20 });
+
+// Request/response: waits for the server's acknowledgement, resolves with its reply.
+const doc = await ws.send<Doc>({ op: "load", id: 42 }, { ack: true });
+
+// A refusal arrives as a typed error carrying the server's own code.
+try {
+	await ws.send({ op: "delete", id: 42 }, { ack: true });
+} catch (e) {
+	if (e instanceof WSRemoteError && e.code === "forbidden") showNotAllowed();
+}
+```
 
-## Usage
+**Fire-and-forget or acknowledged — your call, per message.** Without
+`{ ack: true }` there is no delivery confirmation: a message written into a
+connection that turns out to be dead is lost, exactly as with a plain
+`WebSocket`. With it, the server confirms every message, can answer it, and a
+message lost with its connection rejects with `WSConnectionLostError` instead of
+silently vanishing.
 
-### Client
+**The server side** is small enough to write in any language:
+[PROTOCOL.md](PROTOCOL.md) specifies it, section 8 is a complete Python
+server, and Appendix A is a conformance script that drives this client against
+yours. The reference server does it with one hook and one method:
+
+```typescript
+import { createWSApp, WSRemoteError } from "@marianmeres/ws/server";
+
+const { app, service } = createWSApp("/ws", [], {
+	verify: async (payload) => {
+		const user = await authenticate(payload); // null closes with 4001
+		return user ? { clientId: user.id } : null;
+	},
+	// Every ws.send() lands here. The return value is the reply for { ack: true }.
+	onMessage: async (ctx, payload) => {
+		const { op, id } = payload as { op: string; id: number };
+		if (op === "load") return await loadDoc(id);
+		throw new WSRemoteError({ code: "unknown_op", message: `unknown op ${op}` });
+	},
+});
+
+// Push to one client, any time.
+service.send(userId, { op: "progress", done: 42 });
+
+Deno.serve(app);
+```
+
+### 2. Rooms — the server as a relay
+
+Namespaces, rooms, presence and broadcast, for clients that talk to each other:
+chat, collaboration, live cursors.
 
 ```typescript
 import { createWSClient } from "@marianmeres/ws";
@@ -66,7 +134,7 @@ import { createWSClient } from "@marianmeres/ws";
 const ws = createWSClient({
 	url: "/ws",
 	namespace: "org-123",
-	auth: () => session.token, // called on every (re)connect, so refresh works
+	auth: () => session.token,
 });
 
 // Subscribe and handle in one call; the returned function detaches the handler
@@ -81,18 +149,9 @@ 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.
+**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, {
@@ -106,23 +165,7 @@ await ws.subscribe("room", onMessage, {
 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
+**The server:**
 
 ```typescript
 import { createWSApp } from "@marianmeres/ws/server";
@@ -137,7 +180,7 @@ const { app, service } = createWSApp("/ws", [], {
 	},
 });
 
-// Push to connected clients from anywhere in your app.
+// Push into a room from anywhere in your app.
 await service.publish("notifications", { text: "deploy finished" }, "org-123");
 
 Deno.serve(app);
@@ -148,11 +191,36 @@ for when `verify` returns none — so in a multi-tenant deployment `verify` must
 return `namespace` and `clientId`, validating `requested` rather than trusting
 it.
 
-If `verify` authenticates from cookies, set `allowedOrigins` as well: browsers
-attach cookies to a WebSocket opened from any site, and without an `Origin`
-check that is cross-site WebSocket hijacking.
+### Either way
+
+`connect()` is optional — the first `send()`, `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
+```
+
+Connection state is reactive, through the Svelte store contract:
+
+```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}
+```
+
+If `verify` authenticates from cookies, set `allowedOrigins` on the server as
+well: browsers attach cookies to a WebSocket opened from any site, and without
+an `Origin` check that is cross-site WebSocket hijacking.
 
-Mounted routes, relative to the mount path:
+The reference server mounts these routes, relative to the mount path:
 
 | Method | Path                          | Notes                                     |
 | ------ | ----------------------------- | ----------------------------------------- |
@@ -161,6 +229,23 @@ Mounted routes, relative to the mount path:
 | POST   | `/publish/[namespace]/[room]` | Requires `httpAuth`, else **not mounted** |
 | POST   | `/broadcast/[room]`           | Requires `httpAuth`, else **not mounted** |
 
+## 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.
+
 ## Example
 
 A complete room chat — demino server plus a plain HTML client — lives in
@@ -170,16 +255,21 @@ A complete room chat — demino server plus a plain HTML client — lives in
 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
+It exercises the rooms side end to end: 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.
+**Message** — what the application sends and receives. Its `payload` is opaque:
+never inspected, never mutated, free to carry its own `type` field. A message
+the server sends directly has nothing else; one delivered through a room also
+carries `room`, `namespace`, `from` and `timestamp` (a `WSRoomMessage`).
+
+**Namespace** — the isolation boundary for rooms. 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.
 
@@ -188,11 +278,10 @@ 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**.
 
-**Frame vs message** — a _frame_ is one JSON protocol envelope (`auth`, `sub`,
-`pub`, `msg`, `ack`, …), carried in exactly one WebSocket text message — not an
-RFC 6455 fragment. A _message_ is the application-level object a `msg` frame
-delivers (`room`, `namespace`, `from`, `payload`, `timestamp`) — a `msg` frame
-minus its `type` field _is_ a `WSMessage`, which is what your handlers receive.
+**Frame vs message** — a _frame_ is one JSON protocol envelope (`auth`, `msg`,
+`ack`, `sub`, …), carried in exactly one WebSocket text message — not an RFC
+6455 fragment. A `msg` frame minus its `type` field _is_ the message your
+handlers receive.
 
 ## Behaviour worth knowing
 
@@ -206,16 +295,22 @@ come back.
 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 immediately with `WSConnectionLostError`
-rather than waiting out `sendTimeout`: the answer is already known at the close.
-At-least-once would need server-side replay, which this version does not do.
+**Delivery is at-most-once.** An acknowledged send or 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 immediately
+with `WSConnectionLostError` rather than waiting out `sendTimeout`: the answer
+is already known at the close. A fire-and-forget `send()` has no such answer to
+give — it resolved when it was written. 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
+**Sends are bounded.** Every send carries one deadline covering queue, flight
+_and_ acknowledgement. Without it, a send issued while offline would pend
 forever behind an infinite retry.
 
+**A server that does not do rooms says so.** Against a core-only server,
+`subscribe()` and `publish()` reject at once with `WSRemoteError` code
+`unsupported` — they do not time out.
+
 **`disconnect()` is resumable; `dispose()` is terminal.** Handlers, rooms and
 buffered sends survive a `disconnect()`, so a later `connect()` picks up where
 it left off.
@@ -227,9 +322,10 @@ See [API.md](API.md) for complete API documentation.
 ## Protocol
 
 The reference server is Deno-only; the protocol is not.
-[PROTOCOL.md](PROTOCOL.md) specifies the wire format frame by frame — with a
-complete Python implementation and a conformance script that drives the real
-client — so a compatible server can be written in any language.
+[PROTOCOL.md](PROTOCOL.md) specifies the wire format frame by frame, core first
+and the rooms extension after it — with complete Python servers for both (a
+core-only one, and the full reference) and a conformance script that drives the
+real client against yours.
 
 ## License
 

package/dist/client/outbox.d.ts

@@ -6,13 +6,31 @@
  * that pend indefinitely, so every tracked frame carries **one timeout
  * spanning queue + flight + ack** — not an ack-only timeout.
  *
+ * Not every frame awaits an ack. A `msg` sent without `{ ack: true }` is
+ * complete the moment it is written to the socket; it passes through here
+ * only so that, while offline, it is buffered and bounded like everything else.
+ *
  * 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";
+import type { ClientFrame } from "../protocol/frames.js";
+/** What a settled send resolves with — the parts of the `ack` the caller needs. */
+export interface OutboxResult {
+    /** Delivery count from a `pub`/`broadcast` ack; `0` otherwise. */
+    recipients: number;
+    /** The server's reply from a `msg` ack; `undefined` otherwise. */
+    payload?: unknown;
+}
+/** A tracked frame together with the key it is tracked under. */
+export interface OutboxEntry {
+    /** The key — the frame's wire `id` when it has one, a local one otherwise. */
+    id: string;
+    /** The frame itself. */
+    frame: ClientFrame;
+}
 /** Configuration for {@link Outbox}. */
 export interface OutboxOptions {
     /** Max frames buffered while disconnected. `0` disables buffering. */
@@ -38,18 +56,32 @@ export declare class Outbox {
     /**
      * Registers a frame and returns the promise the caller awaits.
      *
-     * @param id - correlation id, matched against the server's ack/nack
+     * @param id - correlation id, matched against the server's ack/nack; for a
+     * frame that awaits no ack, any locally unique key
      * @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
+     * @param awaitAck - `false` when the frame is complete once transmitted —
+     * see {@link transmitted}
+     */
+    track(id: string, frame: ClientFrame, queued: boolean, awaitAck?: boolean): Promise<OutboxResult>;
+    /**
+     * Takes every buffered frame out of the queue and returns them in FIFO
+     * order, for the caller to write and then report via {@link transmitted}
+     * or {@link fail}. They stay pending — awaiting acks now, not a connection.
+     */
+    drain(): OutboxEntry[];
+    /**
+     * Reports a frame as written to the socket. One that awaits no ack is
+     * complete and resolves here; one that does keeps waiting for its ack.
      */
-    track(id: string, frame: ClientFrame, queued: boolean): Promise<WSPublishResult>;
+    transmitted(id: string): void;
     /**
-     * Marks every buffered frame as transmitted and returns them in FIFO order.
-     * They stay pending — they are awaiting acks now, not a connection.
+     * Resolves a pending frame — the server acked it.
+     *
+     * @param recipients - the ack's delivery count, `0` when it carried none
+     * @param payload - the ack's reply, when it carried one
      */
-    drain(): ClientFrame[];
-    /** Resolves a pending frame — the server acked it. */
-    settle(id: string, recipients: number): boolean;
+    settle(id: string, recipients: number, payload?: unknown): boolean;
     /** Rejects a single pending frame. */
     fail(id: string, error: Error): boolean;
     /**

package/dist/client/outbox.js

@@ -6,6 +6,10 @@
  * that pend indefinitely, so every tracked frame carries **one timeout
  * spanning queue + flight + ack** — not an ack-only timeout.
  *
+ * Not every frame awaits an ack. A `msg` sent without `{ ack: true }` is
+ * complete the moment it is written to the socket; it passes through here
+ * only so that, while offline, it is buffered and bounded like everything else.
+ *
  * 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.
@@ -41,17 +45,20 @@ export class Outbox {
     /**
      * Registers a frame and returns the promise the caller awaits.
      *
-     * @param id - correlation id, matched against the server's ack/nack
+     * @param id - correlation id, matched against the server's ack/nack; for a
+     * frame that awaits no ack, any locally unique key
      * @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
+     * @param awaitAck - `false` when the frame is complete once transmitted —
+     * see {@link transmitted}
      */
-    track(id, frame, queued) {
+    track(id, frame, queued, awaitAck = true) {
         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 });
+            this.#pending.set(id, { frame, resolve, reject, timer, queued, awaitAck });
             if (queued) {
                 this.#queue.push(id);
                 this.#applyCap();
@@ -59,27 +66,44 @@ export class Outbox {
         });
     }
     /**
-     * Marks every buffered frame as transmitted and returns them in FIFO order.
-     * They stay pending — they are awaiting acks now, not a connection.
+     * Takes every buffered frame out of the queue and returns them in FIFO
+     * order, for the caller to write and then report via {@link transmitted}
+     * or {@link fail}. They stay pending — awaiting acks now, not a connection.
      */
     drain() {
-        const frames = [];
+        const entries = [];
         for (const id of this.#queue) {
             const entry = this.#pending.get(id);
             if (!entry)
                 continue;
             entry.queued = false;
-            frames.push(entry.frame);
+            entries.push({ id, frame: entry.frame });
         }
         this.#queue = [];
-        return frames;
+        return entries;
+    }
+    /**
+     * Reports a frame as written to the socket. One that awaits no ack is
+     * complete and resolves here; one that does keeps waiting for its ack.
+     */
+    transmitted(id) {
+        const entry = this.#pending.get(id);
+        if (!entry || entry.awaitAck)
+            return;
+        this.#discard(id);
+        entry.resolve({ recipients: 0 });
     }
-    /** Resolves a pending frame — the server acked it. */
-    settle(id, recipients) {
+    /**
+     * Resolves a pending frame — the server acked it.
+     *
+     * @param recipients - the ack's delivery count, `0` when it carried none
+     * @param payload - the ack's reply, when it carried one
+     */
+    settle(id, recipients, payload) {
         const entry = this.#discard(id);
         if (!entry)
             return false;
-        entry.resolve({ recipients });
+        entry.resolve(payload === undefined ? { recipients } : { recipients, payload });
         return true;
     }
     /** Rejects a single pending frame. */

package/dist/client/rooms.d.ts

@@ -1,5 +1,5 @@
 /**
- * Refcounted room registry.
+ * Refcounted room registry (rooms extension).
  *
  * N handlers on one room produce exactly one wire subscription; the `unsub`
  * frame goes out when the last handler detaches. This is what lets
@@ -8,9 +8,9 @@
  *
  * @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;
+import type { SubRequest, WSPresenceEvent, WSRoomMessage } from "../protocol/frames.js";
+/** Receives messages published to a room — every routing field is present. */
+export type MessageHandler<T = unknown> = (msg: WSRoomMessage<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. */
@@ -55,7 +55,7 @@ export declare class RoomRegistry {
      * 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;
+    deliver(room: string, msg: WSRoomMessage, 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;

package/dist/client/rooms.js

@@ -1,5 +1,5 @@
 /**
- * Refcounted room registry.
+ * Refcounted room registry (rooms extension).
  *
  * N handlers on one room produce exactly one wire subscription; the `unsub`
  * frame goes out when the last handler detaches. This is what lets