@fuzdev/fuz_app 0.118.0 → 0.120.0

package/dist/actions/register_ws_endpoint.d.ts

@@ -59,6 +59,7 @@ export interface RegisterWsEndpointOptions extends RegisterActionWsOptions {
  * @mutates options.app - applies origin/auth/scope/authorization/role middleware
  *   via `app.use`, then registers the `GET path` route via the inner
  *   `register_action_ws`
+ * @mutates options.connection_closer - adds the endpoint's transport
  */
 export declare const register_ws_endpoint: (options: RegisterWsEndpointOptions) => RegisterActionWsResult;
 //# sourceMappingURL=register_ws_endpoint.d.ts.map

package/dist/actions/register_ws_endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAgDD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAoBF,CAAC"}
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,0CAA0C;AAC1C,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACzE;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CACzC;AAgDD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAChC,SAAS,yBAAyB,KAChC,sBAoBF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -83,6 +83,7 @@ const create_ws_authorization_middleware = (db) => {
  * @mutates options.app - applies origin/auth/scope/authorization/role middleware
  *   via `app.use`, then registers the `GET path` route via the inner
  *   `register_action_ws`
+ * @mutates options.connection_closer - adds the endpoint's transport
  */
 export const register_ws_endpoint = (options) => {
     const { app, path, allowed_origins, db, required_roles, log = new Logger('[ws]'), ...rest } = options;

package/dist/actions/socket.svelte.d.ts

@@ -5,8 +5,10 @@
  * Drop into any SvelteKit frontend as the underlying connection for
  * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
  * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
- * server revokes auth), exposes reactive status for UI indicators, and ships
- * three correctness primitives default-on:
+ * server revokes auth) and `WS_CLOSE_CONNECTION_LIMIT` (no reconnect after the
+ * server closes this socket to admit a newer one — closed until the user
+ * acts), exposes reactive status for UI indicators, and ships three
+ * correctness primitives default-on:
  *
  * - `FrontendWebsocketClient.request` — promise-based JSON-RPC with
  *   auto-assigned ids and a pending-id map. Intercepts responses on the
@@ -72,8 +74,9 @@ export declare const DEFAULT_QUEUE_MAX_SIZE = 100;
  * - `connecting` — WebSocket `readyState === CONNECTING`.
  * - `connected` — WebSocket `readyState === OPEN`.
  * - `reconnecting` — close fired; waiting out backoff before next attempt.
- * - `closed` — socket is not open. Terminal only when `revoked` is `true`
- *   or auto-reconnect is disabled; otherwise `connect()` reopens.
+ * - `closed` — socket is not open, and nothing is scheduled to reopen it.
+ *   Terminal only when `revoked` is `true`; otherwise `connect()` reopens,
+ *   including after a `superseded` close.
  */
 export type SocketStatus = 'initial' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
 export type SocketMessageHandler = (event: MessageEvent) => void;
@@ -145,6 +148,11 @@ export interface FrontendWebsocketClientOptions {
  *
  * Session-revocation close codes (`WS_CLOSE_SESSION_REVOKED`) put the client
  * in a permanently-closed state; reconnecting would just loop on 401.
+ *
+ * A connection-limit close (`WS_CLOSE_CONNECTION_LIMIT`) leaves the client
+ * closed with `superseded` set and no reconnect scheduled — the server closed
+ * this socket to admit a newer one on the same account, and reconnecting
+ * would close that one in turn. An explicit `connect()` reopens.
  */
 export declare class FrontendWebsocketClient implements WebsocketConnection, Disposable {
     #private;
@@ -247,14 +255,35 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * reflects any closed state (incl. user-initiated `disconnect()`).
      */
     get revoked(): boolean;
+    /**
+     * Whether the server closed this client's socket to admit a newer
+     * connection on the same account (`WS_CLOSE_CONNECTION_LIMIT`) and it
+     * hasn't been reopened since. While `true` the client is `closed` and
+     * schedules no reconnect — reconnecting on its own would supersede a newer
+     * socket in turn, and clients past the cap would close each other in a loop.
+     *
+     * Unlike `revoked` this is not terminal: the credential is still good, and
+     * the next `connect()` clears it and reopens — only `connect()` does;
+     * `disconnect()` leaves it set. Requests in flight or queued at the close
+     * reject with `service_unavailable`; ones made afterwards buffer in the
+     * durable queue like any other call on a closed client. Reactive, so UI can
+     * say why the connection is closed and offer the reconnect.
+     *
+     * `socket_status_to_async_status` reads a superseded client as `initial`,
+     * the same as one that was never connected. An app that connects on its
+     * own when its status reads `initial` must also check `superseded`, or it
+     * rebuilds the loop.
+     */
+    get superseded(): boolean;
     /**
      * Open the WebSocket. No-op on SSR, or if the session has been revoked.
      * Cancels any pending reconnect and tears down any existing connection first;
-     * an open prior socket is closed with a normal-closure code.
+     * an open prior socket is closed with a normal-closure code. Reopens after
+     * a `superseded` close, clearing the flag.
      *
-     * @mutates this - replaces `ws`, sets `status` to `connecting` (or
-     *   `closed` on construction failure), and on construction failure may
-     *   schedule a reconnect (mutating `reconnect_count` /
+     * @mutates this - replaces `ws`, clears `superseded`, sets `status` to
+     *   `connecting` (or `closed` on construction failure), and on construction
+     *   failure may schedule a reconnect (mutating `reconnect_count` /
      *   `current_reconnect_delay`)
      */
     connect(): void;
@@ -309,7 +338,7 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      *   - `request_cancelled` — caller's `AbortSignal` fired
      *   - `queue_overflow` — durable queue full
      *   - `service_unavailable` — socket not connected / closed / torn down
-     *     mid-flight
+     *     mid-flight, including a `superseded` close
      *   - `internal_error` — `ws.send` threw (serialization, buffer full)
      *   - server's wire code verbatim — JSON-RPC error frame from peer
      */
@@ -328,6 +357,11 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
  * `failure` (UI shows "lost, retrying") and splits `closed` by `revoked` so
  * a terminal session-revocation read as `failure` while a clean client-
  * initiated close reads as `initial` (the "not connected, not trying" state).
+ * A `superseded` close reads as `initial` too — the client is not trying and
+ * an explicit `connect()` reopens it; read `FrontendWebsocketClient.superseded`
+ * to tell the user why, and before connecting on an `initial` status without
+ * the user asking (connecting a superseded client on its own closes a newer
+ * socket in turn, which is the loop the close code exists to stop).
  *
  * @param revoked - whether the session has been permanently revoked
  *   (typically `FrontendWebsocketClient.revoked`)

package/dist/actions/socket.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}

package/dist/actions/socket.svelte.js

@@ -5,8 +5,10 @@
  * Drop into any SvelteKit frontend as the underlying connection for
  * `FrontendWebsocketTransport`. Handles auto-reconnect with exponential
  * backoff, respects `WS_CLOSE_SESSION_REVOKED` (no reconnect loop after the
- * server revokes auth), exposes reactive status for UI indicators, and ships
- * three correctness primitives default-on:
+ * server revokes auth) and `WS_CLOSE_CONNECTION_LIMIT` (no reconnect after the
+ * server closes this socket to admit a newer one — closed until the user
+ * acts), exposes reactive status for UI indicators, and ships three
+ * correctness primitives default-on:
  *
  * - `FrontendWebsocketClient.request` — promise-based JSON-RPC with
  *   auto-assigned ids and a pending-id map. Intercepts responses on the
@@ -27,7 +29,7 @@
 import { BROWSER } from 'esm-env';
 import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { JSONRPC_ERROR_CODES, ThrownJsonrpcError, jsonrpc_errors } from '../http/jsonrpc_errors.js';
-import { WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT, WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_SESSION_REVOKED } from './transports.js';
 import { cancel_action_spec } from './cancel.js';
 import { heartbeat_action_spec } from './heartbeat.js';
 /** Default WebSocket close code (normal closure). */
@@ -77,6 +79,11 @@ export const DEFAULT_QUEUE_MAX_SIZE = 100;
  *
  * Session-revocation close codes (`WS_CLOSE_SESSION_REVOKED`) put the client
  * in a permanently-closed state; reconnecting would just loop on 401.
+ *
+ * A connection-limit close (`WS_CLOSE_CONNECTION_LIMIT`) leaves the client
+ * closed with `superseded` set and no reconnect scheduled — the server closed
+ * this socket to admit a newer one on the same account, and reconnecting
+ * would close that one in turn. An explicit `connect()` reopens.
  */
 export class FrontendWebsocketClient {
     #url;
@@ -136,6 +143,7 @@ export class FrontendWebsocketClient {
     #reconnect_timeout = null;
     #reconnect_scheduled_at = null;
     #revoked = $state.raw(false);
+    #superseded = $state.raw(false);
     #message_handlers = new Set();
     #error_handlers = new Set();
     connected = $derived(this.status === 'connected');
@@ -277,14 +285,37 @@ export class FrontendWebsocketClient {
     get revoked() {
         return this.#revoked;
     }
+    /**
+     * Whether the server closed this client's socket to admit a newer
+     * connection on the same account (`WS_CLOSE_CONNECTION_LIMIT`) and it
+     * hasn't been reopened since. While `true` the client is `closed` and
+     * schedules no reconnect — reconnecting on its own would supersede a newer
+     * socket in turn, and clients past the cap would close each other in a loop.
+     *
+     * Unlike `revoked` this is not terminal: the credential is still good, and
+     * the next `connect()` clears it and reopens — only `connect()` does;
+     * `disconnect()` leaves it set. Requests in flight or queued at the close
+     * reject with `service_unavailable`; ones made afterwards buffer in the
+     * durable queue like any other call on a closed client. Reactive, so UI can
+     * say why the connection is closed and offer the reconnect.
+     *
+     * `socket_status_to_async_status` reads a superseded client as `initial`,
+     * the same as one that was never connected. An app that connects on its
+     * own when its status reads `initial` must also check `superseded`, or it
+     * rebuilds the loop.
+     */
+    get superseded() {
+        return this.#superseded;
+    }
     /**
      * Open the WebSocket. No-op on SSR, or if the session has been revoked.
      * Cancels any pending reconnect and tears down any existing connection first;
-     * an open prior socket is closed with a normal-closure code.
+     * an open prior socket is closed with a normal-closure code. Reopens after
+     * a `superseded` close, clearing the flag.
      *
-     * @mutates this - replaces `ws`, sets `status` to `connecting` (or
-     *   `closed` on construction failure), and on construction failure may
-     *   schedule a reconnect (mutating `reconnect_count` /
+     * @mutates this - replaces `ws`, clears `superseded`, sets `status` to
+     *   `connecting` (or `closed` on construction failure), and on construction
+     *   failure may schedule a reconnect (mutating `reconnect_count` /
      *   `current_reconnect_delay`)
      */
     connect() {
@@ -292,6 +323,7 @@ export class FrontendWebsocketClient {
             return;
         if (this.#revoked)
             return;
+        this.#superseded = false;
         this.#cancel_reconnect();
         this.#teardown(DEFAULT_CLOSE_CODE);
         try {
@@ -390,7 +422,7 @@ export class FrontendWebsocketClient {
      *   - `request_cancelled` — caller's `AbortSignal` fired
      *   - `queue_overflow` — durable queue full
      *   - `service_unavailable` — socket not connected / closed / torn down
-     *     mid-flight
+     *     mid-flight, including a `superseded` close
      *   - `internal_error` — `ws.send` threw (serialization, buffer full)
      *   - server's wire code verbatim — JSON-RPC error frame from peer
      */
@@ -697,6 +729,20 @@ export class FrontendWebsocketClient {
             this.#reject_all('session revoked', jsonrpc_errors.unauthenticated);
             return;
         }
+        // The server closed this socket to admit a newer one on the same account.
+        // Reconnecting would supersede that one in turn — two clients past the cap
+        // would close each other in a loop — so stay closed until `connect()` is
+        // called. Not a revocation: the credential is still good. Nothing will
+        // reopen the socket on its own, so the queue is rejected with the pending
+        // requests, as when auto-reconnect is off.
+        if (event.code === WS_CLOSE_CONNECTION_LIMIT) {
+            this.#superseded = true;
+            this.status = 'closed';
+            this.#cancel_reconnect();
+            this.#reset_reconnect_counters();
+            this.#reject_all('connection superseded', jsonrpc_errors.service_unavailable);
+            return;
+        }
         // Pending in-flight requests can't be correlated post-reconnect; reject
         // them. Queue stays so the flush on reopen replays unsent work.
         this.#reject_pending_only(`connection closed (code ${event.code})`, jsonrpc_errors.service_unavailable);
@@ -785,6 +831,11 @@ export class FrontendWebsocketClient {
  * `failure` (UI shows "lost, retrying") and splits `closed` by `revoked` so
  * a terminal session-revocation read as `failure` while a clean client-
  * initiated close reads as `initial` (the "not connected, not trying" state).
+ * A `superseded` close reads as `initial` too — the client is not trying and
+ * an explicit `connect()` reopens it; read `FrontendWebsocketClient.superseded`
+ * to tell the user why, and before connecting on an `initial` status without
+ * the user asking (connecting a superseded client on its own closes a newer
+ * socket in turn, which is the loop the close code exists to stop).
  *
  * @param revoked - whether the session has been permanently revoked
  *   (typically `FrontendWebsocketClient.revoked`)

package/dist/actions/transports.d.ts

@@ -8,17 +8,64 @@
  */
 import { z } from 'zod';
 import type { JsonrpcMessageFromClientToServer, JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
-/** WebSocket close code for session revocation. */
+/**
+ * WebSocket close code for session revocation.
+ *
+ * Also the close for an upgrade refused at admission because its credential
+ * was revoked while the upgrade was in flight (`register_action_ws`) — the
+ * same outcome, reached a moment earlier.
+ */
 export declare const WS_CLOSE_SESSION_REVOKED = 4001;
+/**
+ * The close reason sent with `WS_CLOSE_SESSION_REVOKED` — one definition, so a
+ * socket revoked mid-life and an upgrade refused at admission are
+ * indistinguishable on the wire. The Rust spine sends the same text.
+ */
+export declare const WS_CLOSE_SESSION_REVOKED_REASON = "Session revoked";
 /** WebSocket close code — client timed out waiting for a response. */
 export declare const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
 /** WebSocket close code — server timed out with no incoming activity. */
 export declare const WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003;
+/**
+ * WebSocket close code — the server closed this socket to admit a newer
+ * connection on the same account, past the per-account connection cap
+ * (`BackendWebsocketTransport`'s `max_connections_per_account`, evict-oldest).
+ *
+ * Distinct from `WS_CLOSE_SESSION_REVOKED`: the credential is still good, so
+ * a client must not enter its `revoked` state — but it must not auto-reconnect
+ * either, since a reconnect would supersede a newer socket in turn and two
+ * tabs past the cap would close each other in a loop. `FrontendWebsocketClient`
+ * treats it as closed until the user acts (`superseded`). The twin of the Rust
+ * spine's `WS_CLOSE_CONNECTION_LIMIT`.
+ */
+export declare const WS_CLOSE_CONNECTION_LIMIT = 4004;
 /**
  * WebSocket close code — an inbound message exceeded the receiver's size cap
  * (RFC 6455 §7.4.1 "Message Too Big").
  */
 export declare const WS_CLOSE_MESSAGE_TOO_BIG = 1009;
+/**
+ * WebSocket close code — the server closed a socket that sent too much while
+ * it was still opening: past `MAX_PRE_ADMISSION_FRAMES` frames or the
+ * `PRE_ADMISSION_QUEUE_BYTES_FACTOR` byte budget, before its admission and
+ * `on_socket_open` had completed (RFC 6455 §7.4.1 "Policy Violation"). Not a
+ * revocation: the client reconnects under its ordinary backoff.
+ */
+export declare const WS_CLOSE_POLICY_VIOLATION = 1008;
+/**
+ * WebSocket close code — the server hit an unexpected condition (RFC 6455
+ * §7.4.1 "Internal Error").
+ *
+ * Sent when an upgraded socket can't be admitted because its credential
+ * re-check itself failed (a database error), when an `on_socket_open` hook
+ * throws, and when a frame arrives on a socket whose connection was removed
+ * from the transport without a close (a bare `remove_connection`). The
+ * handshake has already answered `101`, so an HTTP `500` is no longer
+ * available. Not a revocation: the client's credential may be fine, so it
+ * reconnects under its ordinary backoff rather than entering its `revoked`
+ * state. The twin of the Rust spine's `WS_CLOSE_INTERNAL_ERROR`.
+ */
+export declare const WS_CLOSE_INTERNAL_ERROR = 1011;
 /**
  * Default cap on one WebSocket message, in UTF-8 bytes — equal to the default
  * HTTP body cap (`DEFAULT_MAX_BODY_SIZE`), so one JSON-RPC request is bounded
@@ -38,6 +85,13 @@ export declare const DEFAULT_WS_MAX_MESSAGE_BYTES: number;
  * @returns the UTF-8 byte length when it exceeds `max_bytes`, else `null`
  */
 export declare const utf8_length_over: (text: string, max_bytes: number) => number | null;
+/**
+ * The UTF-8 byte length of `text`.
+ *
+ * @param text - the string to measure
+ * @returns its length in UTF-8 bytes
+ */
+export declare const utf8_length: (text: string) => number;
 export declare const TransportName: z.ZodString;
 export type TransportName = z.infer<typeof TransportName>;
 /**

package/dist/actions/transports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B,mDAAmD;AACnD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,QAAc,CAAC;AAIxD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM,GAAG,IAI3E,CAAC;AAKF,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/F,IAAI,CACH,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACxC,IAAI,CACH,OAAO,EAAE,gCAAgC,EACzC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACpD,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAQ9C;;;;;OAKG;IACH,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;;OAMG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAwCtE"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EACX,gCAAgC,EAChC,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,oBAAoB,CAAC;AACjE,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD,yEAAyE;AACzE,eAAO,MAAM,iCAAiC,OAAO,CAAC;AACtD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C;;;GAGG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,QAAc,CAAC;AAIxD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM,GAAG,IAI3E,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAA8C,CAAC;AAK1F,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACzB,cAAc,EAAE,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/F,IAAI,CACH,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IACxC,IAAI,CACH,OAAO,EAAE,gCAAgC,EACzC,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IACpD,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,UAAU;;IAItB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAQ;IAE/B;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAQ9C;;;;;OAKG;IACH,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,IAAI;IAM1D;;;;;;OAMG;IACH,aAAa,CAAC,cAAc,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;IAO/D,QAAQ,IAAI,OAAO,GAAG,IAAI;IAM1B,qBAAqB,IAAI,SAAS,GAAG,IAAI;IAIzC,0BAA0B,IAAI,aAAa,GAAG,IAAI;IAIlD,qBAAqB,CAAC,cAAc,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI;CAwCtE"}

package/dist/actions/transports.js

@@ -7,17 +7,64 @@
  * @module
  */
 import { z } from 'zod';
-/** WebSocket close code for session revocation. */
+/**
+ * WebSocket close code for session revocation.
+ *
+ * Also the close for an upgrade refused at admission because its credential
+ * was revoked while the upgrade was in flight (`register_action_ws`) — the
+ * same outcome, reached a moment earlier.
+ */
 export const WS_CLOSE_SESSION_REVOKED = 4001;
+/**
+ * The close reason sent with `WS_CLOSE_SESSION_REVOKED` — one definition, so a
+ * socket revoked mid-life and an upgrade refused at admission are
+ * indistinguishable on the wire. The Rust spine sends the same text.
+ */
+export const WS_CLOSE_SESSION_REVOKED_REASON = 'Session revoked';
 /** WebSocket close code — client timed out waiting for a response. */
 export const WS_CLOSE_CLIENT_HEARTBEAT_TIMEOUT = 4002;
 /** WebSocket close code — server timed out with no incoming activity. */
 export const WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT = 4003;
+/**
+ * WebSocket close code — the server closed this socket to admit a newer
+ * connection on the same account, past the per-account connection cap
+ * (`BackendWebsocketTransport`'s `max_connections_per_account`, evict-oldest).
+ *
+ * Distinct from `WS_CLOSE_SESSION_REVOKED`: the credential is still good, so
+ * a client must not enter its `revoked` state — but it must not auto-reconnect
+ * either, since a reconnect would supersede a newer socket in turn and two
+ * tabs past the cap would close each other in a loop. `FrontendWebsocketClient`
+ * treats it as closed until the user acts (`superseded`). The twin of the Rust
+ * spine's `WS_CLOSE_CONNECTION_LIMIT`.
+ */
+export const WS_CLOSE_CONNECTION_LIMIT = 4004;
 /**
  * WebSocket close code — an inbound message exceeded the receiver's size cap
  * (RFC 6455 §7.4.1 "Message Too Big").
  */
 export const WS_CLOSE_MESSAGE_TOO_BIG = 1009;
+/**
+ * WebSocket close code — the server closed a socket that sent too much while
+ * it was still opening: past `MAX_PRE_ADMISSION_FRAMES` frames or the
+ * `PRE_ADMISSION_QUEUE_BYTES_FACTOR` byte budget, before its admission and
+ * `on_socket_open` had completed (RFC 6455 §7.4.1 "Policy Violation"). Not a
+ * revocation: the client reconnects under its ordinary backoff.
+ */
+export const WS_CLOSE_POLICY_VIOLATION = 1008;
+/**
+ * WebSocket close code — the server hit an unexpected condition (RFC 6455
+ * §7.4.1 "Internal Error").
+ *
+ * Sent when an upgraded socket can't be admitted because its credential
+ * re-check itself failed (a database error), when an `on_socket_open` hook
+ * throws, and when a frame arrives on a socket whose connection was removed
+ * from the transport without a close (a bare `remove_connection`). The
+ * handshake has already answered `101`, so an HTTP `500` is no longer
+ * available. Not a revocation: the client's credential may be fine, so it
+ * reconnects under its ordinary backoff rather than entering its `revoked`
+ * state. The twin of the Rust spine's `WS_CLOSE_INTERNAL_ERROR`.
+ */
+export const WS_CLOSE_INTERNAL_ERROR = 1011;
 /**
  * Default cap on one WebSocket message, in UTF-8 bytes — equal to the default
  * HTTP body cap (`DEFAULT_MAX_BODY_SIZE`), so one JSON-RPC request is bounded
@@ -43,6 +90,13 @@ export const utf8_length_over = (text, max_bytes) => {
     const size = text_encoder.encode(text).byteLength;
     return size > max_bytes ? size : null;
 };
+/**
+ * The UTF-8 byte length of `text`.
+ *
+ * @param text - the string to measure
+ * @returns its length in UTF-8 bytes
+ */
+export const utf8_length = (text) => text_encoder.encode(text).byteLength;
 // TODO figure out the symmetry of frontend and backend transports (none/partial/full?) --
 // we may also need orthogonal abstractions to clarify the transport role
 export const TransportName = z.string(); // not branded for convenience, will just error at runtime, the schema is just for docs atm

package/dist/actions/transports_ws_auth_guard.d.ts

@@ -1,101 +1,87 @@
 /**
- * WebSocket auth guard — bridges audit events to `BackendWebsocketTransport`.
+ * WebSocket auth guard — the audit-event listener that closes live
+ * connections when a row reports a revocation.
  *
  * **Why this exists.** `register_action_ws` captures `account_id` and
  * `credential_type` at upgrade time and reuses them for every message.
  * `perform_action`'s per-message authorization phase reloads role_grants
- * from the DB, but session and token VALIDITY are not re-queried — that
- * trade-off keeps chatty WS connections fast. The cost: nothing in the
- * dispatch path notices when a session is revoked or a token is rotated.
- * This guard is the enforcement mechanism — it listens on the audit
- * chain and closes affected sockets when revocation events fire, so
- * revocation actually takes effect on existing connections. Without it,
- * `session_revoke` / `token_revoke` are no-ops for open WS connections.
+ * from the DB, but session and token VALIDITY are not re-queried per message
+ * — they are re-read once, at admission (`revalidate_resolved_auth`) — a
+ * trade-off that keeps chatty WS connections fast. The cost: nothing in the
+ * dispatch path notices when a session is revoked or a token is rotated, so a
+ * revocation reaches an open connection only when something closes it.
  *
- * Mirror of `realtime/sse_auth_guard.ts` for the backend WebSocket
- * transport. Dispatches audit events to the right `close_sockets_for_*`
- * method so consumers do not re-implement the switch themselves.
+ * Two things do. The revocation handlers close directly, after their
+ * transaction commits (`queue_connection_close` in
+ * `actions/connection_closer.ts`) — that close does not depend on the audit
+ * write. This guard repeats it when the audit row is announced, which covers
+ * a revocation emitted by code that holds no closer. Closing is idempotent, so
+ * the overlap is a repeat, not a conflict. A success row is announced only
+ * after its request's transaction commits (`auth/audit_emitter.ts`), so the
+ * guard's close is post-commit too.
+ *
+ * ## Which rows close
+ *
+ * The guard dispatches on the `RevocationScope` each audit event declares in
+ * `audit_event_revocation_scopes` (`auth/audit_log_schema.ts`), the table the
+ * SSE guard (`realtime/sse_auth_guard.ts`) reads too — one declaration, so the
+ * two cannot drift into closing a revoked token's socket while leaving its
+ * stream open.
+ *
+ * `role` is the one scope this guard deliberately does not act on:
+ * `perform_action` re-authorizes every message, so a socket whose account just
+ * lost the gating role is refused at its next message, and closing it would
+ * only change when the caller learns. A stream has no later check, so the SSE
+ * guard closes there.
  *
  * For standard WS endpoints mounted via `AppServerOptions.ws_endpoints`,
- * `create_app_server` composes the guard automatically per
+ * `create_app_server` registers the guard automatically per
  * `WsEndpointSpec.auth_guard`. For custom wiring, register the handler
  * inside the consumer's `audit_factory` body (or via
  * `audit.add_listener(...)` post-assembly).
  *
+ * Twin of the Rust spine's `register_socket_revocation_listeners`.
+ *
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
-import type { AuditLogEvent } from '../auth/audit_log_schema.js';
-import type { BackendWebsocketTransport } from './transports_ws_backend.js';
+import { type AuditLogEvent } from '../auth/audit_log_schema.js';
+import type { ConnectionCloser } from './connection_closer.js';
 /**
  * Audit-event callback shape — the function `CreateAuditEmitterOptions.on_audit_event`
- * accepts and that the helpers in this module return.
+ * accepts and that `create_ws_auth_guard` returns.
  *
  * Exported so consumers composing multiple handlers (typically
- * `create_ws_auth_guard` + `create_ws_logout_closer` + their own
- * pre-existing `on_audit_event`) can annotate their composed callback
- * without reaching for `Parameters<typeof create_ws_auth_guard>[0]`.
+ * `create_ws_auth_guard` + their own pre-existing `on_audit_event`) can
+ * annotate their composed callback without reaching for
+ * `Parameters<typeof create_ws_auth_guard>[0]`.
  */
 export type AuditEventHandler = (event: AuditLogEvent) => void;
 /**
- * Audit event types that trigger WebSocket socket closure.
+ * Create an audit event handler that closes connections on a successful
+ * revocation row, dispatching on the event's `RevocationScope`:
  *
- * - `session_revoke` — close only the socket tied to the revoked session hash.
- * - `token_revoke` — close only the socket(s) authenticated with the revoked `api_token.id`.
- * - `session_revoke_all` / `token_revoke_all` / `password_change` — close every socket
- *   for the affected account (all credentials invalidated).
- *
- * `role_grant_revoke` is intentionally omitted: the WS transport does not track
- * per-connection role requirements, so role-scoped disconnection would
- * require either closing all sockets (too aggressive) or new tracking
- * (out of scope). Consumers that need it compose their own callback.
- */
-export declare const ws_disconnect_event_types: ReadonlySet<string>;
-/**
- * Create an audit event handler that closes WebSocket connections on auth changes.
+ * - `session` → `close_sockets_for_session(metadata.session_id)`
+ * - `token` → `close_sockets_for_token(metadata.token_id)`
+ * - `account` → `close_sockets_for_account(target_account_id ?? account_id)`
+ *   — `logout`, `password_change`, `session_revoke_all`, `token_revoke_all`,
+ *   `account_delete`, `account_purge`
+ * - `role` → nothing, deliberately (module doc)
+ * - `none` → nothing — every other event, and any event type fuz_app does not
+ *   define
  *
  * Ignores `outcome === 'failure'` events — they carry attacker-controlled
  * identifiers (e.g. a `session_revoke` that the DB rejected still records
  * the submitted session_id), so reacting to them would let any authenticated
  * user close another user's socket by guessing a session hash or token id.
  *
+ * @param closer - what to close on — a `BackendWebsocketTransport`, or a
+ *   `RealtimeCloser` to reach every transport from one listener
  * @param log - logger for disconnect events (info level on non-zero closures)
  * @returns an `on_audit_event` callback suitable for `create_audit_emitter`'s
  *   `on_audit_event` slot, or for registering via
- *   `audit.add_listener` post-assembly. The returned callback mutates
- *   `transport` (closing matching sockets via
- *   `close_sockets_for_session` / `_token` / `_account`) on every relevant event.
- */
-export declare const create_ws_auth_guard: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
-/**
- * Create an audit event handler that closes WebSocket connections on
- * user-initiated logout.
- *
- * Sibling helper to `create_ws_auth_guard` — kept separate because
- * `ws_disconnect_event_types` deliberately omits `logout` (admin-initiated
- * revocations use `session_revoke`, while `logout` is the user-initiated
- * case). Multiple consumers hand-rolled this same branch before extraction.
- *
- * Compose with `create_ws_auth_guard` to handle both kinds of disconnect:
- *
- * ```ts
- * const ws_guard = create_ws_auth_guard(transport, log);
- * const ws_logout_closer = create_ws_logout_closer(transport, log);
- * const on_audit_event = (event: AuditLogEvent): void => {
- *   ws_guard(event);
- *   ws_logout_closer(event);
- * };
- * ```
- *
- * Ignores `outcome === 'failure'` events — failed logouts carry
- * unauthenticated identifiers (no session to close anyway), and reacting
- * to them would let an unauthenticated probe close the targeted account's
- * sockets by submitting a logout for an arbitrary `account_id`.
- *
- * @param log - logger for disconnect events (info level on non-zero closures)
- * @returns an `on_audit_event` callback wireable alongside `create_ws_auth_guard`.
- *   The returned callback mutates `transport` via `close_sockets_for_account`
- *   on every successful `logout` event with a non-empty `account_id`.
+ *   `audit.add_listener` post-assembly. The returned callback closes matching
+ *   connections on `closer` on every relevant event.
  */
-export declare const create_ws_logout_closer: (transport: BackendWebsocketTransport, log: Logger) => AuditEventHandler;
+export declare const create_ws_auth_guard: (closer: ConnectionCloser, log: Logger) => AuditEventHandler;
 //# sourceMappingURL=transports_ws_auth_guard.d.ts.map

package/dist/actions/transports_ws_auth_guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAChC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBA6CF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB,GACnC,WAAW,yBAAyB,EACpC,KAAK,MAAM,KACT,iBAaF,CAAC"}
+{"version":3,"file":"transports_ws_auth_guard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_auth_guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,gBAAgB,EAAE,KAAK,MAAM,KAAG,iBAoD5E,CAAC"}