@fuzdev/fuz_app 0.118.0 → 0.119.0

package/dist/actions/transports_ws_backend.js

@@ -1,33 +1,166 @@
 /**
  * Backend WebSocket transport — manages server-side WebSocket connections
- * with session tracking and revocation support.
+ * with session tracking, revocation support, a per-account connection cap,
+ * and two-phase registration.
+ *
+ * ## Two-phase registration
+ *
+ * An upgrade resolves its credential before the socket exists, and every
+ * revocation closes the connections *registered* under the revoked
+ * credential. A one-step registration therefore has a window: a revocation
+ * landing between the credential check and the insert closes nothing, and the
+ * upgrade is admitted on a dead credential — for the socket's lifetime, since
+ * per-message dispatch never re-reads the session or token.
+ *
+ * Registration is split to close it:
+ *
+ * 1. `BackendWebsocketTransport.register_pending` inserts the entry
+ *    **un-admitted**. It is closeable from that instant — `close_sockets_for_*`
+ *    match pending entries deliberately — and is otherwise inert: it evicts
+ *    nothing, the cap does not count it, no broadcast / `send_to_account` /
+ *    `request_connection` reaches it, and the count accessors and
+ *    `is_registered` do not see it (`get_pending_connection_count` does).
+ * 2. The caller re-checks the credential against the database
+ *    (`revalidate_resolved_auth` in `auth/resolved_auth.ts`).
+ * 3. `BackendWebsocketTransport.admit` flips the entry to admitted — or
+ *    refuses when a revocation closed it in the meantime, evicting nothing.
+ *    The cap's eviction happens here, so a connection that is never admitted
+ *    never closes a live one, and any number of pending registrations on one
+ *    account leave its admitted connections alone.
+ *
+ * A revocation whose close ran **after** step 1 finds the entry, pending or
+ * admitted, and closes it; one that **committed before** step 2 is seen by the
+ * re-read, which refuses. Nothing is delivered to a pending entry rather than
+ * queued for it, so a refusal never has to promise that a queue a revoked
+ * credential would have read is dropped unread, and a broadcast's returned
+ * count names only connections that can receive it. The cost is a slightly
+ * wider blind spot at connect: a server-initiated message sent between the
+ * handshake and admission — one credential re-check later — is not delivered,
+ * just as one sent before the handshake is not.
+ *
+ * `add_connection` stays as the one-step form (register and admit together)
+ * for a connection with no revocable credential behind it — tests and
+ * harnesses that register a socket directly. An upgrade that authenticated a session or token
+ * uses the two-phase form. The twin of the Rust `fuz_realtime`
+ * `ConnectionRegistry`.
  *
  * @module
  */
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
+import { Logger } from '@fuzdev/fuz_util/log.ts';
 import { create_uuid } from '@fuzdev/fuz_util/id.ts';
 import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, create_jsonrpc_request, to_jsonrpc_message_id, is_jsonrpc_request } from '../http/jsonrpc_helpers.js';
-import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+import { WS_CLOSE_CONNECTION_LIMIT, WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON } from './transports.js';
 import { PendingPeerRequests } from './peer_request.js';
 /** Type guard for `FilterableBroadcastTransport`. */
 export const is_filterable_broadcast_transport = (transport) => 'broadcast_filtered' in transport &&
     typeof transport.broadcast_filtered === 'function';
+/**
+ * Default per-account WebSocket connection cap, applied by
+ * `BackendWebsocketTransport` unless overridden via
+ * `BackendWebsocketTransportOptions.max_connections_per_account`.
+ *
+ * Matches the account-wide ceiling the audit SSE cap implies (the default
+ * session cap, `DEFAULT_MAX_SESSIONS`, times `AUDIT_LOG_SSE_MAX_PER_SCOPE`
+ * streams per session) — generous enough that a user's tabs and tools never
+ * meet it; only an abusive or leaking client does. The twin of the Rust
+ * spine's `DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT`.
+ */
+export const DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT = 50;
 export class BackendWebsocketTransport {
     transport_name = 'backend_websocket_rpc';
-    // Map connection IDs to WebSocket contexts
+    // Per-account connection cap; `null` = uncapped.
+    #max_connections_per_account;
+    #log;
+    // One entry per registered connection, pending or admitted, in
+    // registration order (Map iteration is insertion order — the cap's
+    // "oldest"). Adding a new identity scope (e.g. `device_id`) means adding a
+    // field to `ConnectionIdentity`, not a parallel map.
     #connections = new Map();
-    // Reverse map to find connection ID by socket
-    #connection_ids = new WeakMap();
-    // Auth identity per connection. Adding a new identity scope (e.g.
-    // `device_id`) means adding a field here, not a new parallel map.
-    #connection_identities = new Map();
     // Server→client request correlation (ActionPeer). The transport owns the
     // sockets + the send; the registry owns the pending map, id allocation,
     // deadlines, and the per-connection in-flight cap (see `peer_request.ts`).
     #pending = new PendingPeerRequests();
     /**
-     * Add a new WebSocket connection with auth info.
+     * @throws Error when `max_connections_per_account` is neither `null` nor a
+     *   positive integer
+     */
+    constructor(options) {
+        const max = options?.max_connections_per_account === undefined
+            ? DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT
+            : options.max_connections_per_account;
+        if (max !== null && (!Number.isInteger(max) || max < 1)) {
+            throw new Error(`BackendWebsocketTransport: max_connections_per_account must be a positive integer or null, got ${max}`);
+        }
+        this.#max_connections_per_account = max;
+        this.#log = options?.log === undefined ? new Logger('[ws]') : options.log;
+    }
+    /**
+     * Register a connection **un-admitted** — phase one of the two-phase
+     * registration an upgrade runs (module doc).
+     *
+     * The entry is closeable at once: a `close_sockets_for_*` matching
+     * `token_hash` / `account_id` / `api_token_id` removes it, aborts
+     * `abort_controller`, and closes `ws` with `WS_CLOSE_SESSION_REVOKED`; the
+     * later `admit` then refuses. Until admitted it evicts nothing, is not
+     * counted toward the per-account cap, and receives no message.
+     *
+     * The caller owns the entry until it is admitted: every refusal path calls
+     * `remove_connection` with the returned id.
+     *
+     * @param ws - the socket to close on revocation
+     * @param token_hash - blake3 session token hash, or `null` for non-session credentials
+     * @param account_id - the authenticated account
+     * @param api_token_id - `api_token.id` for bearer connections, else `null`
+     * @param abort_controller - the socket-scoped controller to abort when the
+     *   transport closes this connection (revocation or cap eviction)
+     * @returns the freshly assigned `connection_id` (branded `Uuid`)
+     * @mutates this - inserts an un-admitted entry into `#connections`
+     */
+    register_pending(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+        return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, false);
+    }
+    /**
+     * Admit a pending connection — phase two (module doc).
+     *
+     * If the entry is gone — a revocation closed it while it was pending, or it
+     * was removed — nothing is evicted and the connection is refused. Otherwise
+     * the per-account cap is enforced exactly as in `add_connection`, counting
+     * only **admitted** connections, and the entry becomes admitted: it now
+     * receives messages, is counted, and can itself be superseded. Admitting an
+     * already-admitted connection is a no-op that answers `true`.
+     *
+     * @param connection_id - the id `register_pending` returned
+     * @returns `false` when the connection is no longer registered — the caller
+     *   closes the socket as revoked
+     * @mutates this - marks the entry admitted; past the cap, first removes the
+     *   account's oldest admitted connections and closes their `WSContext`
+     */
+    admit(connection_id) {
+        const entry = this.#connections.get(connection_id);
+        if (!entry)
+            return false;
+        if (entry.admitted)
+            return true;
+        // the entry itself is un-admitted, so the eviction neither counts nor
+        // removes it
+        if (this.#max_connections_per_account !== null) {
+            this.#evict_oldest_for_account(entry.identity.account_id, this.#max_connections_per_account);
+        }
+        entry.admitted = true;
+        return true;
+    }
+    /**
+     * Register a connection, admitted at once — the one-step form of
+     * `register_pending` + `admit`.
+     *
+     * **Not for an upgrade that authenticated a revocable credential**: a
+     * revocation landing between that upgrade's credential check and this call
+     * closes nothing, and the connection would be admitted on a dead credential
+     * (module doc, "Two-phase registration"). This is for a connection with
+     * nothing to revoke behind it.
+     *
      * Session connections pass a token hash for targeted revocation.
      * Bearer token connections (`api_token`) pass the `api_token.id` so the
      * socket can be closed when that specific token is revoked without
@@ -35,93 +168,179 @@ export class BackendWebsocketTransport {
      * pass `null` for both — they're only reachable via
      * `close_sockets_for_account`.
      *
+     * Enforces the per-account cap (`max_connections_per_account`): when
+     * `account_id` already holds the maximum, its oldest admitted connections are
+     * removed and sent a `WS_CLOSE_CONNECTION_LIMIT` close before the new one is
+     * inserted. A removed connection gets no further broadcast or peer request,
+     * stops counting toward the cap at once, and has its `abort_controller`
+     * aborted; its socket is closed when the close handshake completes. The new
+     * connection is always admitted.
+     *
      * @returns the freshly assigned `connection_id` (branded `Uuid`)
-     * @mutates this - inserts into `#connections`, `#connection_ids`, and
-     *   `#connection_identities`
+     * @mutates this - inserts an admitted entry into `#connections`; past the
+     *   cap, first removes the account's oldest admitted connections and closes
+     *   their `WSContext`
      */
-    add_connection(ws, token_hash, account_id, api_token_id = null) {
+    add_connection(ws, token_hash, account_id, api_token_id = null, abort_controller = null) {
+        if (this.#max_connections_per_account !== null) {
+            this.#evict_oldest_for_account(account_id, this.#max_connections_per_account);
+        }
+        return this.#insert(ws, token_hash, account_id, api_token_id, abort_controller, true);
+    }
+    #insert(ws, token_hash, account_id, api_token_id, abort_controller, admitted) {
         const connection_id = create_uuid();
-        this.#connections.set(connection_id, ws);
-        this.#connection_ids.set(ws, connection_id);
-        this.#connection_identities.set(connection_id, { token_hash, account_id, api_token_id });
+        this.#connections.set(connection_id, {
+            ws,
+            identity: { token_hash, account_id, api_token_id },
+            admitted,
+            abort_controller
+        });
         return connection_id;
     }
     /**
-     * Remove a WebSocket connection and its auth tracking data.
-     * Idempotent — safe to call after revocation has already cleaned up.
+     * Remove a connection and its auth tracking data, pending or admitted, by
+     * the id `register_pending` / `add_connection` returned. Idempotent — safe
+     * to call after revocation or a cap eviction has already cleaned up, and a
+     * no-op for an unknown id.
+     *
+     * Keyed by id rather than by `WSContext` because a runtime adapter may hand
+     * each socket event its own context object (`hono/bun` does), so the one a
+     * close event carries can't identify the connection.
+     *
+     * Removal only: the socket is not closed and the registered
+     * `abort_controller` is not aborted — the caller that ends a socket does
+     * both.
      *
-     * @mutates this - deletes the connection's entries from `#connections`,
-     *   `#connection_ids`, and `#connection_identities`
+     * @mutates this - deletes the connection's entry from `#connections` and
+     *   settles its pending peer requests as `connection_gone`
      */
-    remove_connection(ws) {
-        const connection_id = this.#connection_ids.get(ws);
-        if (connection_id) {
-            this.#cleanup_connection(connection_id, ws);
-        }
+    remove_connection(connection_id) {
+        this.#cleanup_connection(connection_id);
     }
     /**
-     * Close every connection whose identity matches the predicate.
+     * Close every connection whose identity matches the predicate — pending or
+     * admitted. Never filter on admission here: reaching a registration in
+     * flight is the point of the pending phase, and `admit` then refuses it.
+     *
+     * A socket whose `close` throws does not stop the loop: every match is
+     * removed and closed, and the first error is thrown afterward. The failing
+     * socket's connection is already removed and its handlers aborted, so
+     * nothing more is dispatched or delivered on it.
      *
      * @returns the number of sockets closed
+     * @throws the first error a socket's `close` threw, after every match was attempted
      */
     #close_where(predicate) {
         let count = 0;
-        for (const [connection_id, identity] of this.#connection_identities) {
-            if (predicate(identity)) {
-                const ws = this.#connections.get(connection_id);
-                if (ws) {
-                    this.#revoke_connection(connection_id, ws);
+        let failed = false;
+        let first_error;
+        // deleting the current entry during Map iteration is safe
+        for (const [connection_id, entry] of this.#connections) {
+            if (predicate(entry.identity)) {
+                try {
+                    this.#revoke_connection(connection_id, entry);
                     count++;
                 }
+                catch (error) {
+                    if (!failed) {
+                        failed = true;
+                        first_error = error;
+                    }
+                }
             }
         }
+        if (failed)
+            throw first_error;
         return count;
     }
     /**
-     * Close all sockets associated with a specific session token hash.
+     * Close all sockets associated with a specific session token hash,
+     * including a registration still pending admission.
      *
      * @returns the number of sockets closed
-     * @mutates this - removes matching connections from internal maps and
-     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_session(token_hash) {
         return this.#close_where((id) => id.token_hash === token_hash);
     }
     /**
-     * Close all sockets associated with a specific account.
+     * Close all sockets associated with a specific account, including a
+     * registration still pending admission.
      *
      * @returns the number of sockets closed
-     * @mutates this - removes matching connections from internal maps and
-     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_account(account_id) {
         return this.#close_where((id) => id.account_id === account_id);
     }
     /**
-     * Close all sockets associated with a specific API token.
+     * Close all sockets associated with a specific API token, including a
+     * registration still pending admission.
      *
-     * Used on `token_revoke` audit events so revoking one token doesn't
-     * tear down the account's session-authenticated sockets or other
-     * tokens' sockets.
+     * Closes just this token's sockets, so revoking one token — or evicting
+     * one past the token cap — doesn't tear down the account's
+     * session-authenticated sockets or other tokens' sockets.
      *
      * @returns the number of sockets closed
-     * @mutates this - removes matching connections from internal maps and
-     *   closes their underlying `WSContext` with `WS_CLOSE_SESSION_REVOKED`
+     * @mutates this - removes matching connections, aborts their registered
+     *   controllers, and closes their underlying `WSContext` with
+     *   `WS_CLOSE_SESSION_REVOKED`
      */
     close_sockets_for_token(api_token_id) {
         return this.#close_where((id) => id.api_token_id === api_token_id);
     }
-    #cleanup_connection(connection_id, ws) {
+    #cleanup_connection(connection_id) {
         this.#connections.delete(connection_id);
-        this.#connection_ids.delete(ws);
-        this.#connection_identities.delete(connection_id);
         // Wake any handler still awaiting a reply on this socket — the peer is
         // gone, so the request can never complete.
         this.#pending.drain(connection_id);
     }
-    #revoke_connection(connection_id, ws) {
-        this.#cleanup_connection(connection_id, ws);
-        ws.close(WS_CLOSE_SESSION_REVOKED, 'Session revoked');
+    #revoke_connection(connection_id, entry) {
+        this.#cleanup_connection(connection_id);
+        // abort before the close so a handler observing `ctx.signal` bails out
+        // without waiting for the close handshake
+        entry.abort_controller?.abort();
+        entry.ws.close(WS_CLOSE_SESSION_REVOKED, WS_CLOSE_SESSION_REVOKED_REASON);
+    }
+    /**
+     * Make room for one more admitted connection on `account_id`: when the
+     * account already holds `max`, close its oldest so that `max - 1` remain.
+     * Pending registrations are neither counted nor closed — a connection that
+     * may yet be refused must not cost a live one its slot.
+     */
+    #evict_oldest_for_account(account_id, max) {
+        // Map iteration is insertion order, so `owned` is oldest-first
+        const owned = [];
+        for (const [connection_id, entry] of this.#connections) {
+            if (entry.admitted && entry.identity.account_id === account_id) {
+                owned.push([connection_id, entry]);
+            }
+        }
+        const excess = owned.length + 1 - max;
+        if (excess <= 0)
+            return;
+        for (let i = 0; i < excess; i++) {
+            const [connection_id, entry] = owned[i];
+            this.#supersede_connection(connection_id, entry);
+        }
+        // same line as the Rust spine's registry, so one grep finds either
+        this.#log?.info('ws: connection cap closed oldest', { account_id, closed: excess, max });
+    }
+    #supersede_connection(connection_id, entry) {
+        this.#cleanup_connection(connection_id);
+        try {
+            entry.abort_controller?.abort();
+            entry.ws.close(WS_CLOSE_CONNECTION_LIMIT, 'connection limit');
+        }
+        catch (error) {
+            // the evicted socket is another connection's — a failure closing it
+            // must not fail the connection being admitted
+            this.#log?.error('error closing superseded client:', error);
+        }
     }
     async send(message, _options) {
         if (is_jsonrpc_request(message)) {
@@ -138,19 +357,23 @@ export class BackendWebsocketTransport {
     }
     #broadcast(message) {
         const serialized = JSON.stringify(message);
-        for (const ws of this.#connections.values()) {
+        for (const entry of this.#connections.values()) {
+            // a registration pending admission is not a connection yet
+            if (!entry.admitted)
+                continue;
             try {
-                ws.send(serialized);
+                entry.ws.send(serialized);
             }
             catch (error) {
-                console.error('[backend websocket transport] Error broadcasting to client:', error);
+                this.#log?.error('error broadcasting to client:', error);
             }
         }
         // TODO hack - remove if not ever needed, I assume this will need to be async so let's hold that assumption
         return Promise.resolve();
     }
     /**
-     * Broadcast to connections whose identity satisfies a predicate.
+     * Broadcast to admitted connections whose identity satisfies a predicate. A
+     * registration pending admission is skipped before the predicate runs.
      *
      * Used by the broadcast API when a consumer supplies a subscription ACL hook
      * (e.g. zap's `zap_run_created` only reaches the account that owns the run).
@@ -162,24 +385,21 @@ export class BackendWebsocketTransport {
     broadcast_filtered(message, predicate) {
         const serialized = JSON.stringify(message);
         let count = 0;
-        for (const [connection_id, identity] of this.#connection_identities) {
-            if (!predicate(identity))
-                continue;
-            const ws = this.#connections.get(connection_id);
-            if (!ws)
+        for (const entry of this.#connections.values()) {
+            if (!entry.admitted || !predicate(entry.identity))
                 continue;
             try {
-                ws.send(serialized);
+                entry.ws.send(serialized);
                 count++;
             }
             catch (error) {
-                console.error('[backend websocket transport] Error broadcasting filtered to client:', error);
+                this.#log?.error('error broadcasting filtered to client:', error);
             }
         }
         return count;
     }
     /**
-     * Send a message to every socket bound to a specific account.
+     * Send a message to every admitted socket bound to a specific account.
      *
      * Targeted per-account fan-out for any flow where the delivery target
      * is a single known account. Prefer this over `broadcast_filtered` when
@@ -204,7 +424,9 @@ export class BackendWebsocketTransport {
      * connection. Resolves when the client's matching reply arrives (routed in
      * via `resolve_peer_response`), the deadline elapses (`timeout`), the
      * per-connection cap is hit (`too_many_in_flight`), or the socket closes
-     * (`connection_gone`). Never throws — every failure is a `PeerRequestError`.
+     * (`connection_gone`). A connection still pending admission answers
+     * `connection_gone` like an unknown one. Never throws — every failure is a
+     * `PeerRequestError`.
      *
      * Delegates correlation to `#pending` (id allocation, deadline, cap, drain);
      * this method owns only the socket lookup + the send. Server-issued ids are
@@ -215,9 +437,11 @@ export class BackendWebsocketTransport {
      * @mutates this - registers then clears an entry in `#pending`
      */
     request_connection(connection_id, method, params, options) {
-        const ws = this.#connections.get(connection_id);
-        if (!ws)
+        const entry = this.#connections.get(connection_id);
+        if (!entry?.admitted) {
             return Promise.resolve({ ok: false, error: { kind: 'connection_gone' } });
+        }
+        const { ws } = entry;
         const registered = this.#pending.register(connection_id, options?.timeout_ms);
         if (!registered)
             return Promise.resolve({ ok: false, error: { kind: 'too_many_in_flight' } });
@@ -246,18 +470,51 @@ export class BackendWebsocketTransport {
     resolve_peer_response(connection_id, response) {
         return this.#pending.resolve(connection_id, response);
     }
+    /**
+     * Whether a connection is still registered — and admitted: a registration
+     * pending admission answers `false`, like every other reader of the
+     * transport.
+     *
+     * `register_action_ws` checks it before dispatching each inbound message, so
+     * a socket the server has closed — revoked, superseded by the cap, or
+     * refused at admission — dispatches nothing more while its close handshake
+     * is still in flight. The twin of the Rust `ConnectionRegistry::is_registered`.
+     */
+    is_registered(connection_id) {
+        return this.#connections.get(connection_id)?.admitted === true;
+    }
     is_ready() {
-        return this.#connections.size > 0;
+        return this.get_connection_count() > 0;
     }
     /**
-     * Number of currently tracked WebSocket connections.
+     * Number of currently **admitted** WebSocket connections.
      *
-     * Read-only counter intended for telemetry, logging, and tests.
-     * Counts every entry in the connection map — including connections
-     * that have been closed by the peer but not yet removed by the WS
-     * adapter's `onClose` callback.
+     * Read-only counter intended for telemetry, logging, and tests. A
+     * registration still pending admission is not a connection yet and is
+     * counted by `get_pending_connection_count` instead. Includes connections
+     * that have been closed by the peer but not yet removed by the WS adapter's
+     * `onClose` callback.
      */
     get_connection_count() {
-        return this.#connections.size;
+        let count = 0;
+        for (const entry of this.#connections.values()) {
+            if (entry.admitted)
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Number of registrations awaiting admission — between `register_pending`
+     * and `admit` (or their refusal). Each lives for one credential re-check, so
+     * a count that stays high means upgrades are stalling there. For telemetry
+     * and tests.
+     */
+    get_pending_connection_count() {
+        let count = 0;
+        for (const entry of this.#connections.values()) {
+            if (!entry.admitted)
+                count++;
+        }
+        return count;
     }
 }

package/dist/actions/ws_endpoint_spec.d.ts

@@ -52,6 +52,14 @@ export interface WsEndpointSpec {
      * `AppServer.ws_endpoints[path]` for broadcast / fan-out.
      */
     transport?: BackendWebsocketTransport;
+    /**
+     * Per-account connection cap for the auto-created transport. See
+     * `RegisterActionWsOptions.max_connections_per_account` — rejected
+     * alongside `transport`, which carries its own cap.
+     *
+     * @default DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT
+     */
+    max_connections_per_account?: number | null;
     /**
      * Server-side heartbeat policy. Default-on (60s receive-silence
      * timeout). Set `false` only when an upstream stack (TCP keepalive,
@@ -68,23 +76,29 @@ export interface WsEndpointSpec {
      */
     max_message_bytes?: number;
     /**
-     * Called once per socket after `transport.add_connection` but before
-     * the first message dispatches. See
-     * `RegisterActionWsOptions.on_socket_open`.
+     * Called once per socket after the connection is admitted — registered
+     * and its credential re-checked — and before the first message
+     * dispatches. See `RegisterActionWsOptions.on_socket_open`.
      */
     on_socket_open?: (ctx: SocketOpenContext) => void | Promise<void>;
     /**
-     * Called once per socket on close, before `transport.remove_connection`.
-     * See `RegisterActionWsOptions.on_socket_close`.
+     * Called once per admitted socket on close, after
+     * `transport.remove_connection`. See
+     * `RegisterActionWsOptions.on_socket_close`.
      */
     on_socket_close?: (ctx: SocketCloseContext) => void | Promise<void>;
     /**
-     * Default `true` — auto-composes `create_ws_auth_guard` +
-     * `create_ws_logout_closer` against this endpoint's transport and
-     * registers them via `deps.audit.add_listener`. Wiring is deduped by
+     * Default `true` — registers `create_ws_auth_guard` against this
+     * endpoint's transport via `deps.audit.add_listener`, so a revocation's
+     * audit row closes its sockets. Wiring is deduped by
      * transport **reference identity** (`WeakSet<BackendWebsocketTransport>`),
      * so two `WsEndpointSpec`s sharing the exact same instance get a
-     * single pair of listeners.
+     * single listener.
+     *
+     * The guard repeats what the revocation handlers already do: the
+     * transport is always in `deps.connection_closer`, whatever this flag
+     * says, and the handlers close through it after their commit. Turning the
+     * guard off leaves those closes in place.
      *
      * **Shared-transport OR-semantics.** When multiple `WsEndpointSpec`s
      * share one transport, the guard is wired iff **any** of those specs
@@ -96,11 +110,10 @@ export interface WsEndpointSpec {
      * Reference-identity dedupe means **wrapped or proxied transports
      * dedupe as separate entries** — a consumer threading every
      * transport through a tracing / DI / metrics shim will get a fresh
-     * pair of listeners per shimmed reference, even when the underlying
+     * listener per shimmed reference, even when the underlying
      * transport is the same. If you wrap or proxy, set `auth_guard:
      * false` on the duplicate `WsEndpointSpec`s and compose
-     * `create_ws_auth_guard` / `create_ws_logout_closer` against the
-     * underlying transport once.
+     * `create_ws_auth_guard` against the underlying transport once.
      *
      * Set `false` when a consumer needs to compose their own callback
      * from scratch — or to opt out of the auto-wiring entirely.
@@ -115,7 +128,7 @@ export interface WsEndpointSpec {
     /**
      * Extra audit-event handlers registered via `deps.audit.add_listener`
      * AFTER the standard `auth_guard` wiring (when enabled). By the time
-     * these run, the standard guards may have already closed sockets. Use
+     * these run, the standard guard may have already closed sockets. Use
      * for role-revoke disconnection, custom analytics, etc.
      *
      * Never deduped — consumer-owned; pass the same handler twice and it

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

@@ -1 +1 @@
-{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD"}
+{"version":3,"file":"ws_endpoint_spec.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/ws_endpoint_spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EACX,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACxD"}