@marianmeres/ws 0.3.0 → 0.4.1

package/AGENTS.md

@@ -43,11 +43,13 @@ example/                   # standalone reference app — `deno task example`
 ├── server.ts              # demino apps: /ws (createWSApp), /api, / (static)
 ├── history.ts             # WSPubSubAdapter decorator -> in-memory backlog
 ├── shared.ts              # the APPLICATION protocol (what goes in `payload`)
+├── build-styles.ts        # generates public/theme.css, copies vui-base.css
 ├── client/                # @marianmeres/vanilla views + store, bundled by
 │                          # @marianmeres/deno-build to public/dist/bundle.js
-└── public/                # index.html + design-tokens CSS (theme.css is
-                           # generated by build-theme.ts and IS committed;
-                           # dist/ is not)
+└── public/                # index.html + CSS. theme.css (design tokens, prefix
+                           # "vui-") and vui-base.css (@marianmeres/vanilla-ui's
+                           # base style layer, copied verbatim) are generated by
+                           # build-styles.ts and ARE committed; dist/ is not
 ```
 
 `src/server.ts` and `src/protocol.ts` exist because the npm build maps subpath
@@ -73,9 +75,24 @@ not registered yet. There is a test that fails if you break it
 **`sub`/`unsub` bypass the outbox.** They are replayed wholesale by the
 re-subscribe step, so buffering them too would apply them twice.
 
+**A control-frame promise the client does not await must carry a `.catch()`.**
+`#sendControl` tracks the frame in the outbox, so its promise rejects on dispose,
+on a terminal close and on the send timeout. An unawaited one — the unsubscriber's
+`unsub`, the `#onHello` re-subscribe — is an uncaught rejection that exits a Deno
+or Node process.
+
+**The server validates every frame field before it uses it, and wraps the whole
+dispatch.** A malformed but parseable frame is a `nack`/`error` `bad_request`
+and the socket stays open; an unexpected throw is `error` `internal` and a 1011
+close. Both paths, including the async one, end in a `.catch()` — a handler that
+throws must never be able to take the process down.
+
 **Every send carries one deadline** spanning queue + flight + ack — not an
 ack-only timeout. Combining acks with infinite retry otherwise produces promises
-that pend forever.
+that pend forever. And a socket close settles in-flight frames at once, rather
+than waiting out a deadline for an answer that can no longer arrive: `sub` and
+`unsub` resolve, everything else rejects with `WSConnectionLostError`. Queued
+frames are untouched — they are still waiting for a connection, not an ack.
 
 **The pong deadline is not restarted by later pings.** It measures time since
 the _oldest_ unanswered ping. Restarting it means any `pingInterval <=
@@ -87,7 +104,13 @@ checks its captured generation. Without it a slow `onclose` from a dead socket
 cancels the reconnect that replaced it.
 
 **Safe defaults are deny.** `allowBroadcast` denies; HTTP injection routes are
-not mounted without `httpAuth`. Do not "helpfully" relax either.
+not mounted without `httpAuth`. Do not "helpfully" relax either. The documented
+exception: `clientId` and `namespace` fall back to what the client asked for
+(assigned → requested → generated), so a multi-tenant `verify` must return both.
+Its third argument carries the client's proposals so they can be validated there
+instead of being duplicated into the auth payload. `allowedOrigins` is the other
+exception — opt-in, because a default allow-list would break every non-browser
+deployment; unset means no check at all.
 
 **Delivery is at-most-once.** Transmitted-but-unacked sends are never resent.
 If that changes, the server needs deduplication first.
@@ -122,7 +145,9 @@ run `deno publish` then the npm build.
 
 ## Before Making Changes
 
-1. `deno task test` — 39 tests, all real sockets against a real server
+1. `deno task test` — 66 tests, mostly real sockets against a real server:
+   `unit`, `integration`, `resilience`, `protocol` (server input hardening,
+   raw sockets) and `codec` (custom encode/decode, binary frames)
 2. `deno lint && deno fmt --check && deno check src/mod.ts src/server.ts src/protocol.ts`
 3. Touched a public signature? `deno doc --lint src/mod.ts src/server.ts
    src/protocol.ts` **and** `deno publish --dry-run --allow-dirty`
@@ -146,14 +171,16 @@ run `deno publish` then the npm build.
 - Presence is scoped to `(room, namespace)`; broadcast crosses namespaces but
   presence does not
 - Node/Bun cannot run the server (`Deno.upgradeWebSocket`)
+- Origin checking is opt-in via `allowedOrigins`; unset means no check
 
 ## Documentation Index
 
-| Document            | Purpose                                          |
-| ------------------- | ------------------------------------------------ |
-| `README.md`         | Human-facing overview and usage                  |
-| `API.md`            | Complete API reference — every public export     |
-| `example/README.md` | The reference app: what it demonstrates, and how |
+| Document            | Purpose                                                       |
+| ------------------- | ------------------------------------------------------------- |
+| `README.md`         | Human-facing overview and usage                               |
+| `API.md`            | Complete API reference — every public export                  |
+| `PROTOCOL.md`       | Wire protocol spec + Python server, for other implementations |
+| `example/README.md` | The reference app: what it demonstrates, and how              |
 
 `tmp/spec.md` (design spec and decision log) is referenced in some commits but
 is **untracked** — `tmp/*` is gitignored, so it does not exist in a fresh clone.

package/API.md

@@ -42,6 +42,11 @@ following the `PubSub` / `createPubSub` precedent.
 | `onOutboxDrop`       | `(frames: ClientFrame[]) => void`   | —                  | Called with evicted frames                                                    |
 | `encode` / `decode`  | `WSEncoder` / `WSDecoder`           | JSON               | Must match the server's                                                       |
 
+`pingInterval: 0` disables the client's heartbeat, not the server's reaper: the
+reference server still closes a connection that sent nothing for `idleTimeout`
+(60 s) with `4008`, so a heartbeat-free client reconnects roughly every minute.
+Disable both or neither.
+
 **Returns** `WSClient`
 
 **Example**
@@ -84,10 +89,14 @@ gate, not a prerequisite.
 
 Rejects **only** where retrying cannot help:
 
-- `WSTerminatedError` — a terminal close code
+- `WSTerminatedError` — a terminal close code, or code `4900` when
+  `disconnect()` (or `dispose()`, which disconnects first) is called while this
+  is still pending
 - `WSConnectTimeoutError` — `connectTimeout` elapsed. Retrying continues in the
   background, so this bounds _your await_, not the connection attempt
-- `WSDisposedError` — the client was disposed
+- `WSDisposedError` — called on an already disposed client. A `dispose()`
+  _during_ a pending connect settles it with the `4900` `WSTerminatedError`
+  above, not with this
 
 Ordinary network failure never rejects; that is what the infinite retry is for.
 
@@ -97,6 +106,10 @@ Stops retrying and closes the socket. **Resumable** — handlers, room
 subscriptions and buffered sends all survive, so a later `connect()` picks up
 where it left off.
 
+Emits `close` with code `4900` (`CLOSE.CLIENT_GONE`) and `willReconnect: false`
+when there was a socket to close; nothing when already idle, reconnecting or
+terminated.
+
 ##### `dispose(): void`
 
 Terminal teardown: disconnects, then drops every handler, room, timer and
@@ -162,13 +175,20 @@ 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.
+flushes — bounded by `sendTimeout`, never indefinitely. A frame already in
+flight when the socket closes rejects there and then with
+`WSConnectionLostError`; it is not resent. After a terminal close nothing is
+buffered at all: the promise rejects immediately with `WSTerminatedError`,
+because only an explicit `connect()` leaves that state.
 
 `namespace` must equal the client's own; the server rejects anything else, so it
 is only useful for asserting the expected one.
 
-**Throws** `WSTimeoutError`, `WSOutboxDropError`, `WSNotConnectedError`,
-`WSRemoteError`, `WSDisposedError`
+A payload `encode` refuses — a `BigInt` is enough for the JSON default — rejects
+with the encoder's own error, unwrapped, and also surfaces as an `error` event.
+
+**Throws** `WSTimeoutError`, `WSConnectionLostError`, `WSOutboxDropError`,
+`WSNotConnectedError`, `WSTerminatedError`, `WSRemoteError`, `WSDisposedError`
 
 ##### `broadcast<T>(room, payload): Promise<WSPublishResult>`
 
@@ -277,6 +297,9 @@ stop delivery to the others.
 `error` means something failed but the client carried on (a decode failure, a
 throwing handler). `terminated` is the only non-retrying exit.
 
+A local `disconnect()` is a `close` too: code `4900`, `willReconnect: false` —
+that pair is how a deliberate teardown is told apart from a lost connection.
+
 ### `WSState`
 
 ```typescript
@@ -319,34 +342,36 @@ Creates a mountable demino app plus the service it is wired to.
 
 **Parameters**
 
-| Name                         | Type                                   | Default                   | Description                                                                    |
-| ---------------------------- | -------------------------------------- | ------------------------- | ------------------------------------------------------------------------------ |
-| `mountPath`                  | `string`                               | `"/ws"`                   | Demino mount path                                                              |
-| `middlewares`                | `DeminoHandler[]`                      | `[]`                      | Applied to all routes                                                          |
-| `options.verify`             | `(payload, req) => AuthResult \| null` | —                         | Return `null` (or throw) to reject with `4001`. Absent means no authentication |
-| `options.allowBroadcast`     | `(ctx, room) => boolean`               | **deny**                  | Gate for cross-namespace broadcast                                             |
-| `options.httpAuth`           | `DeminoHandler`                        | —                         | Guards the HTTP routes. **Without it they are not mounted**                    |
-| `options.deminoOptions`      | `DeminoOptions`                        | —                         | Passed through to `demino()`                                                   |
-| `options.authTimeout`        | `number`                               | `5_000`                   | Deadline for the `auth` frame → `4002`                                         |
-| `options.idleTimeout`        | `number`                               | `60_000`                  | Reap silent connections → `4008`                                               |
-| `options.maxFrameSize`       | `number`                               | `262144`                  | Oversized frames → `4013`                                                      |
-| `options.maxFramesPerSecond` | `number`                               | `100`                     | Rate cap → `4009`                                                              |
-| `options.adapter`            | `WSPubSubAdapter`                      | `WSPubSubLocal`           | Cross-instance fan-out                                                         |
-| `options.logger`             | `Logger \| null`                       | `createClog("ws:server")` | `null` silences                                                                |
-| `options.encode` / `.decode` | `WSEncoder` / `WSDecoder`              | JSON                      | Must match the client's                                                        |
+| Name                         | Type                                              | Default                   | Description                                                                                                                                                                   |
+| ---------------------------- | ------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mountPath`                  | `string`                                          | `"/ws"`                   | Demino mount path                                                                                                                                                             |
+| `middlewares`                | `DeminoHandler[]`                                 | `[]`                      | Applied to all routes                                                                                                                                                         |
+| `options.verify`             | `(payload, req, requested) => AuthResult \| null` | —                         | Return `null` (or throw) to reject with `4001`. Absent means no authentication. `requested` is the identity the client asked for — see [below](#security-namespace-isolation) |
+| `options.allowedOrigins`     | `string[] \| (origin, req) => boolean`            | — (no check)              | Origins allowed to upgrade → `403` — see [below](#security-cross-site-websocket-hijacking)                                                                                    |
+| `options.allowBroadcast`     | `(ctx, room) => boolean`                          | **deny**                  | Gate for cross-namespace broadcast                                                                                                                                            |
+| `options.httpAuth`           | `DeminoHandler`                                   | —                         | Guards the HTTP routes. **Without it they are not mounted**                                                                                                                   |
+| `options.deminoOptions`      | `DeminoOptions`                                   | —                         | Passed through to `demino()`                                                                                                                                                  |
+| `options.authTimeout`        | `number`                                          | `5_000`                   | Deadline for the `auth` frame → `4002`                                                                                                                                        |
+| `options.idleTimeout`        | `number`                                          | `60_000`                  | Reap silent connections → `4008`                                                                                                                                              |
+| `options.maxFrameSize`       | `number`                                          | `262144`                  | Oversized frames → `4013`                                                                                                                                                     |
+| `options.maxFramesPerSecond` | `number`                                          | `100`                     | Rate cap → `4009`                                                                                                                                                             |
+| `options.adapter`            | `WSPubSubAdapter`                                 | `WSPubSubLocal`           | Cross-instance fan-out                                                                                                                                                        |
+| `options.logger`             | `Logger \| null`                                  | `createClog("ws:server")` | `null` silences                                                                                                                                                               |
+| `options.encode` / `.decode` | `WSEncoder` / `WSDecoder`                         | JSON                      | Must match the client's                                                                                                                                                       |
 
 **Returns** `WSApp` — `{ app: Demino, service: WSService }`
 
 **Routes**, relative to `mountPath`:
 
-| Method | Path                          | Returns                     | Notes                                     |
-| ------ | ----------------------------- | --------------------------- | ----------------------------------------- |
-| GET    | `/`                           | 101, or 426 without upgrade | WebSocket upgrade                         |
-| GET    | `/stats`                      | `WSStats`                   | Guarded by `httpAuth` when supplied       |
-| POST   | `/publish/[namespace]/[room]` | `{ ok: true, recipients }`  | Requires `httpAuth`, else **not mounted** |
-| POST   | `/broadcast/[room]`           | `{ ok: true, recipients }`  | Requires `httpAuth`, else **not mounted** |
+| Method | Path                          | Returns                    | Notes                                     |
+| ------ | ----------------------------- | -------------------------- | ----------------------------------------- |
+| GET    | `/`                           | 101, 426 without upgrade   | WebSocket upgrade, `403` on a bad origin  |
+| GET    | `/stats`                      | `WSStats`                  | Requires `httpAuth`, else **not mounted** |
+| POST   | `/publish/[namespace]/[room]` | `{ ok: true, recipients }` | Requires `httpAuth`, else **not mounted** |
+| POST   | `/broadcast/[room]`           | `{ ok: true, recipients }` | Requires `httpAuth`, else **not mounted** |
 
-The POST routes take the JSON request body as the message payload.
+The POST routes take the JSON request body as the message payload; a body that
+is not valid JSON answers `400`.
 
 **Example**
 
@@ -367,6 +392,63 @@ await service.publish("notifications", { text: "deploy finished" }, "org-123");
 Deno.serve(app);
 ```
 
+#### Security: namespace isolation
+
+Namespace is the isolation boundary and `clientId` is the identity peers see in
+`from` — and a claimed id evicts whoever holds it. Both fall back to what the
+client asked for:
+
+```
+assigned by verify  →  requested by the client  →  generated
+```
+
+**In any multi-tenant deployment `verify` must return `namespace` and
+`clientId`.** Return neither and the client's proposals are honoured verbatim,
+so any authenticated user can enter any tenant. The third argument,
+[`WSRequestedIdentity`](#wsrequestedidentity), carries those proposals, so they
+can be validated there rather than duplicated into the auth payload:
+
+```typescript
+createWSApp("/ws", [], {
+	verify: async (payload, req, requested) => {
+		const user = await authenticate((payload as any)?.token);
+		if (!user) return null;
+		// The namespace is checked, not trusted — and assigned either way.
+		if (!user.orgs.includes(requested.namespace)) return null;
+		return { clientId: user.id, namespace: requested.namespace };
+	},
+});
+```
+
+#### Security: cross-site WebSocket hijacking
+
+The upgrade request is an ordinary browser request, so the browser attaches its
+cookies for your origin no matter which site opened the socket. A `verify` that
+authenticates from cookies therefore authenticates the attacker's page too —
+same-origin policy does not apply to WebSockets, and there is no preflight.
+
+`allowedOrigins` closes that, and is **opt-in**: unset, nothing is checked.
+
+```typescript
+createWSApp("/ws", [], {
+	allowedOrigins: ["https://app.example"],
+	verify: (_payload, req) => sessionFromCookie(req),
+});
+```
+
+An unlisted `Origin` is answered `403 Origin not allowed` and never reaches
+`verify`. The array form **permits a missing `Origin`**, because only browsers
+send the header and non-browser clients (the stock Deno client included) send
+none — the check exists to stop browsers. Pass a function instead when that is
+too lax, or when the allowed set is dynamic:
+
+```typescript
+allowedOrigins: (origin, req) => origin !== null && isTenantOrigin(origin),
+```
+
+Token authentication in the `auth` payload is not exposed this way: another
+site's page cannot read your token, only ride your cookies.
+
 ---
 
 ### `WSService`
@@ -378,7 +460,8 @@ Owns every connection, the room index, presence and delivery. Usable standalone
 ##### `handleUpgrade(request): Response`
 
 Upgrades an HTTP request and takes ownership of the socket. Return the 101
-response from your route handler unmodified.
+response from your route handler unmodified. With `allowedOrigins` set, a
+disallowed request is answered `403` instead and nothing is upgraded.
 
 ##### `publish(room, payload, namespace?, from?): Promise<number>`
 
@@ -402,8 +485,10 @@ Instance-local.
 
 ##### `stats(): WSStats`
 
-Counts only, never client ids, so it stays safe to expose unguarded in
-development.
+Counts only, never client ids — but `namespaces` is keyed by namespace name, so
+in a multi-tenant deployment it enumerates the tenants that are online. Hence
+the `/stats` route only exists behind `httpAuth`; this method is for in-process
+use.
 
 ##### `close(): Promise<void>`
 
@@ -557,6 +642,19 @@ What the server's `verify()` hook returns. `null` rejects the connection.
 }
 ```
 
+### `WSRequestedIdentity`
+
+The third argument to `verify()`: what the client proposed in its `auth` frame.
+Hints, not facts — see
+[Security: namespace isolation](#security-namespace-isolation).
+
+```typescript
+{
+	clientId?: string;   // absent unless the frame carried a usable one
+	namespace: string;   // DEFAULT_NAMESPACE when the frame carried none
+}
+```
+
 ### `WSErrorInfo`
 
 ```typescript
@@ -615,6 +713,7 @@ string-matching messages.
 | `WSTerminatedError`     | Terminal close code                             | `code`, `reason` |
 | `WSConnectTimeoutError` | `connectTimeout` elapsed (retrying continues)   |                  |
 | `WSTimeoutError`        | `sendTimeout` elapsed with no acknowledgement   |                  |
+| `WSConnectionLostError` | Socket closed while the frame was in flight     |                  |
 | `WSOutboxDropError`     | Evicted from a full outbox                      |                  |
 | `WSRemoteError`         | Server sent a `nack`                            | `code`           |
 | `WSNotConnectedError`   | Sent while disconnected with `outboxMaxSize: 0` |                  |

package/README.md

@@ -6,12 +6,12 @@
 
 A WebSocket client with namespaces, rooms, presence and reconnect that actually
 survives real networks — plus a mountable reference server implementing the same
-protocol.
+[protocol](./PROTOCOL.md).
 
 ## Features
 
 - **Reconnects forever** — capped exponential backoff with jitter, plus instant
-  retry when the browser comes back online or the tab regains focus
+  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
@@ -128,10 +128,12 @@ ws.members("room"); // last known membership
 import { createWSApp } from "@marianmeres/ws/server";
 
 const { app, service } = createWSApp("/ws", [], {
-	verify: async (payload, req) => {
+	// `requested` is what the client asked for — hints, never facts.
+	verify: async (payload, req, requested) => {
 		const user = await authenticate(payload?.token);
 		// Returning null closes the socket with a terminal code.
-		return user ? { clientId: user.id, namespace: user.orgId } : null;
+		if (!user || !user.orgs.includes(requested.namespace)) return null;
+		return { clientId: user.id, namespace: requested.namespace };
 	},
 });
 
@@ -141,12 +143,21 @@ await service.publish("notifications", { text: "deploy finished" }, "org-123");
 Deno.serve(app);
 ```
 
+Namespace is the isolation boundary, and it falls back to what the client asked
+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.
+
 Mounted routes, relative to the mount path:
 
 | Method | Path                          | Notes                                     |
 | ------ | ----------------------------- | ----------------------------------------- |
 | GET    | `/`                           | WebSocket upgrade                         |
-| GET    | `/stats`                      | Guarded by `httpAuth` when supplied       |
+| GET    | `/stats`                      | Requires `httpAuth`, else **not mounted** |
 | POST   | `/publish/[namespace]/[room]` | Requires `httpAuth`, else **not mounted** |
 | POST   | `/broadcast/[room]`           | Requires `httpAuth`, else **not mounted** |
 
@@ -177,6 +188,12 @@ 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.
+
 ## Behaviour worth knowing
 
 **Reconnect classification.** Everything reconnects except a local
@@ -191,8 +208,9 @@ 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.
+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.
 
 **Sends are bounded.** Every publish carries one deadline covering queue, flight
 _and_ acknowledgement. Without it, a publish issued while offline would pend
@@ -206,6 +224,13 @@ it left off.
 
 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.
+
 ## License
 
 [MIT](LICENSE)

package/dist/client/outbox.d.ts

@@ -58,8 +58,16 @@ export declare class Outbox {
      */
     failAll(error: Error): void;
     /**
-     * Rejects only the frames still waiting to be transmitted, leaving
-     * in-flight ones to their acks or timeouts.
+     * Settles every already-transmitted frame, leaving the queued ones to wait
+     * for the next connection.
+     *
+     * Used when the socket closes: the ack can no longer arrive, because the
+     * socket that would have carried it is gone and the next one is a new
+     * session. Waiting out `sendTimeout` would only delay an answer that is
+     * already known.
+     *
+     * @param decide - per frame: the error to reject with, or `null` to resolve
+     * it with no recipients
      */
-    failQueued(error: Error): void;
+    settleInFlight(decide: (frame: ClientFrame) => Error | null): void;
 }

package/dist/client/outbox.js

@@ -104,14 +104,28 @@ export class Outbox {
         }
     }
     /**
-     * Rejects only the frames still waiting to be transmitted, leaving
-     * in-flight ones to their acks or timeouts.
+     * Settles every already-transmitted frame, leaving the queued ones to wait
+     * for the next connection.
+     *
+     * Used when the socket closes: the ack can no longer arrive, because the
+     * socket that would have carried it is gone and the next one is a new
+     * session. Waiting out `sendTimeout` would only delay an answer that is
+     * already known.
+     *
+     * @param decide - per frame: the error to reject with, or `null` to resolve
+     * it with no recipients
      */
-    failQueued(error) {
-        const ids = this.#queue;
-        this.#queue = [];
-        for (const id of ids)
-            this.fail(id, error);
+    settleInFlight(decide) {
+        for (const [id, entry] of [...this.#pending]) {
+            if (entry.queued)
+                continue;
+            const error = decide(entry.frame);
+            this.#discard(id);
+            if (error)
+                entry.reject(error);
+            else
+                entry.resolve({ recipients: 0 });
+        }
     }
     #discard(id) {
         const entry = this.#pending.get(id);

package/dist/client/ws-client.d.ts

@@ -27,7 +27,10 @@ export interface WSEvents {
     message: WSMessage;
     /** Membership change in a room subscribed with presence enabled. */
     presence: WSPresenceEvent;
-    /** Socket closed. `willReconnect` reflects the retry classification. */
+    /**
+     * Socket closed. `willReconnect` reflects the retry classification, and is
+     * `false` for the `4900` a local `disconnect()` emits.
+     */
     close: {
         code: number;
         reason: string;
@@ -229,6 +232,10 @@ export declare class WSClient<TAuth = unknown> {
      * 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.
+     *
+     * Emits `close` with {@link CLOSE.CLIENT_GONE} and `willReconnect: false`
+     * when there was a socket to close; nothing when already idle, reconnecting
+     * or terminated.
      */
     disconnect(): void;
     /**
@@ -309,6 +316,8 @@ export declare class WSClient<TAuth = unknown> {
      * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
      * @throws {WSOutboxDropError} evicted from a full outbox
      * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close, which only an
+     * explicit `connect()` recovers from — rejected at once, not buffered
      * @throws {WSRemoteError} the server rejected it with a `nack`
      */
     publish<T = unknown>(room: string, payload: T, namespace?: string): Promise<WSPublishResult>;

package/dist/client/ws-client.js

@@ -7,7 +7,7 @@ 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 { WSConnectionLostError, 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";
@@ -96,7 +96,12 @@ export class WSClient {
     #namespace = null;
     #attempt = 0;
     #lastError = null;
-    #intentional = false;
+    /**
+     * Kept apart from `#lastError` on purpose: a handler that throws after the
+     * terminal close would overwrite `#lastError` and a send rejected from the
+     * `terminated` state would then blame the wrong thing.
+     */
+    #terminalError = null;
     #rooms = new RoomRegistry();
     #outbox;
     #heartbeat;
@@ -303,7 +308,6 @@ export class WSClient {
                 this.#settleConnect(new WSConnectTimeoutError(this.#connectTimeout));
             }, this.#connectTimeout);
         }
-        this.#intentional = false;
         if (this.#state === "idle" || this.#state === "terminated")
             this.#open();
         return promise;
@@ -314,16 +318,29 @@ export class WSClient {
      * 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.
+     *
+     * Emits `close` with {@link CLOSE.CLIENT_GONE} and `willReconnect: false`
+     * when there was a socket to close; nothing when already idle, reconnecting
+     * or terminated.
      */
     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");
+        const reason = "client disconnect";
+        const closed = this.#socket !== null;
+        this.#closeSocket(CLOSE.CLIENT_GONE, reason);
+        if (closed) {
+            this.#emit("close", {
+                code: CLOSE.CLIENT_GONE,
+                reason,
+                willReconnect: false,
+            });
+        }
+        this.#settleInFlight();
         this.#setState("idle");
     }
     /**
@@ -386,6 +403,10 @@ export class WSClient {
                     type: FRAME.UNSUB,
                     id: this.#nextId(),
                     rooms: [room],
+                }).catch((e) => {
+                    // Not actionable: the handler is already detached locally and
+                    // the server drops the room on close anyway.
+                    this.logger?.debug?.(`unsub "${room}" unconfirmed: ${e.message}`);
                 });
             }
         });
@@ -466,6 +487,8 @@ export class WSClient {
      * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
      * @throws {WSOutboxDropError} evicted from a full outbox
      * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close, which only an
+     * explicit `connect()` recovers from — rejected at once, not buffered
      * @throws {WSRemoteError} the server rejected it with a `nack`
      */
     publish(room, payload, namespace) {
@@ -512,14 +535,22 @@ export class WSClient {
     #send(frame, id) {
         if (this.#autoConnect)
             this.#ensureStarted();
+        // Nothing restarts from `terminated` except an explicit connect(), so
+        // buffering here would only defer the same answer by `sendTimeout`.
+        if (this.#terminalError && this.#state === "terminated") {
+            return Promise.reject(this.#terminalError);
+        }
         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);
+        if (canSendNow) {
+            const error = this.#sendRaw(frame);
+            if (error)
+                this.#outbox.fail(id, error);
+        }
         return promise;
     }
     /**
@@ -532,19 +563,27 @@ export class WSClient {
     #sendControl(frame) {
         const id = "id" in frame ? frame.id : this.#nextId();
         const promise = this.#outbox.track(id, frame, false);
-        this.#sendRaw(frame);
+        const error = this.#sendRaw(frame);
+        if (error)
+            this.#outbox.fail(id, error);
         return promise;
     }
+    /**
+     * @returns the error the send failed with — a frame that never left cannot
+     * be acknowledged, so the caller settles its promise instead of letting it
+     * wait out `sendTimeout`.
+     */
     #sendRaw(frame) {
         const socket = this.#socket;
         if (!socket || socket.readyState !== WebSocket.OPEN)
-            return;
+            return null;
         try {
             socket.send(this.#encode(frame));
         }
         catch (e) {
-            this.#fail(e, "send failed");
+            return this.#fail(e, "send failed");
         }
+        return null;
     }
     #open() {
         // Defensive: every caller already guards this, but a second socket
@@ -556,7 +595,7 @@ export class WSClient {
         }
         if (!this.#setState("connecting"))
             return;
-        this.#intentional = false;
+        this.#terminalError = null;
         const generation = ++this.#generation;
         let socket;
         try {
@@ -568,6 +607,9 @@ export class WSClient {
             return;
         }
         this.#socket = socket;
+        // Without this a binary frame arrives as a Blob, which no synchronous
+        // decoder can read — the `WSDecoder` contract promises an `ArrayBuffer`.
+        socket.binaryType = "arraybuffer";
         this.logger?.debug?.(`connecting to ${this.#url.href}`);
         socket.onopen = () => {
             if (generation !== this.#generation)
@@ -601,6 +643,13 @@ export class WSClient {
             payload = (await this.#authFn?.()) ?? null;
         }
         catch (e) {
+            // The await yields, so this rejection may belong to a socket that a
+            // later connect() already replaced — closing on it would kill the
+            // healthy socket that took its place.
+            if (generation !== this.#generation) {
+                this.logger?.debug?.("superseded auth attempt failed");
+                return;
+            }
             this.#fail(e, "auth payload failed");
             this.#forceClose(CLOSE.PROTOCOL_ERROR, "auth payload failed");
             return;
@@ -700,8 +749,11 @@ export class WSClient {
         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);
+            for (const frame of buffered) {
+                const error = this.#sendRaw(frame);
+                if (error && "id" in frame)
+                    this.#outbox.fail(frame.id, error);
+            }
         }
     }
     #onClose(code, reason) {
@@ -710,14 +762,14 @@ export class WSClient {
         this.#heartbeat.stop();
         this.#socket = null;
         const terminal = this.#terminalCodes.includes(code);
-        const willReconnect = !this.#intentional && !terminal &&
-            this.#state !== "disposed";
+        const willReconnect = !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;
+            this.#terminalError = 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.
@@ -727,12 +779,27 @@ export class WSClient {
             this.#emit("terminated", { code, reason });
             return;
         }
+        this.#settleInFlight();
         if (!willReconnect) {
             this.#setState("idle");
             return;
         }
         this.#scheduleReconnect();
     }
+    /**
+     * Answers the frames that were on the wire when the socket went away.
+     *
+     * `sub`/`unsub` resolve: the room registry is authoritative locally and the
+     * re-subscribe step will establish it on the next connection, which is
+     * exactly the contract of a `subscribe()` issued while offline — and the
+     * server forgets its rooms on close anyway. Publishes reject: they were not
+     * delivered, and at-most-once means they will not be resent.
+     */
+    #settleInFlight() {
+        this.#outbox.settleInFlight((frame) => frame.type === FRAME.SUB || frame.type === FRAME.UNSUB
+            ? null
+            : new WSConnectionLostError());
+    }
     #scheduleReconnect() {
         if (!this.#setState("reconnecting"))
             return;
@@ -864,6 +931,7 @@ export class WSClient {
         this.#lastError = err;
         this.logger?.error?.(`${context}: ${err.message}`);
         this.#emit("error", err);
+        return err;
     }
 }
 /**

package/dist/protocol/errors.d.ts

@@ -71,6 +71,15 @@ export declare class WSTimeoutError extends WSError {
 export declare class WSOutboxDropError extends WSError {
     constructor();
 }
+/**
+ * The socket closed while the frame was in flight.
+ *
+ * Distinct from {@link WSTimeoutError} on purpose: this one means "retry when
+ * connected", that one means "the server is not answering".
+ */
+export declare class WSConnectionLostError extends WSError {
+    constructor();
+}
 /** The server rejected the operation with a `nack`. */
 export declare class WSRemoteError extends WSError {
     /** Machine-readable code from the server — see `ERROR_CODE`. */

package/dist/protocol/errors.js

@@ -81,6 +81,17 @@ export class WSOutboxDropError extends WSError {
         super("Dropped from outbox (capacity reached while disconnected)");
     }
 }
+/**
+ * The socket closed while the frame was in flight.
+ *
+ * Distinct from {@link WSTimeoutError} on purpose: this one means "retry when
+ * connected", that one means "the server is not answering".
+ */
+export class WSConnectionLostError extends WSError {
+    constructor() {
+        super("The connection closed before the server acknowledged the frame; it was not resent");
+    }
+}
 /** The server rejected the operation with a `nack`. */
 export class WSRemoteError extends WSError {
     /** Machine-readable code from the server — see `ERROR_CODE`. */

package/dist/protocol/frames.d.ts

@@ -136,6 +136,16 @@ export interface WSPublishResult {
      */
     recipients: number;
 }
+/**
+ * What the client proposed in its `auth` frame. Hints, not facts — they are
+ * whatever the socket sent, so validate them before honouring them.
+ */
+export interface WSRequestedIdentity {
+    /** The claimed client id, when the frame carried a usable one. */
+    clientId?: string;
+    /** The requested namespace, or the default when the frame carried none. */
+    namespace: string;
+}
 /** Outcome of the server's `verify()` hook. */
 export interface AuthResult {
     /** Assign a specific client id. Defaults to a generated one. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ws",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
@@ -27,7 +27,7 @@
 		"@marianmeres/clog": "^3.21.0",
 		"@marianmeres/pubsub": "^3.0.0",
 		"@marianmeres/ticker": "^1.17.1",
-		"@marianmeres/uid": "^1.1.0"
+		"@marianmeres/uid": "^1.2.0"
 	},
 	"repository": {
 		"type": "git",