@fuzdev/fuz_app 0.118.0 → 0.119.0

package/dist/testing/cross_backend/sse_round_trip.js

@@ -11,7 +11,7 @@ import '../assert_dev_env.js';
  * (`describe_standard_cross_process_tests`) omits SSE by design, so consumers
  * call this alongside it (paralleling `describe_cross_process_ws_tests`).
  *
- * Four cases, mirroring the in-process SSE self-test against fuz_app's
+ * Its cases follow the in-process SSE self-test against fuz_app's
  * standard audit-log stream:
  *
  * 1. **connects** — the stream opens and emits the `: connected` comment.
@@ -23,20 +23,28 @@ import '../assert_dev_env.js';
  *    stream opens so `create_account`'s own audit events (invite / signup /
  *    login / token) don't land on it.
  * 3. **close-on-revoke, account-wide** (gated on `rpc_path`) — the subscriber's
- *    *own* sessions are revoked (`account_session_revoke_all`), so the
- *    `session_revoke_all` event targets the keeper and the audit guard drops
- *    the live stream via the account-wide `close_for_account` path. Asserted
- *    via `SseTransport.wait_for_close`.
+ *    *own* sessions are revoked (`account_session_revoke_all`), which closes
+ *    every stream of the account once the revoke commits (the handler's
+ *    close, repeated by the audit guard on the `session_revoke_all` row).
+ *    Asserted via `SseTransport.wait_for_close`.
  * 4. **close-on-revoke, session-scoped** (gated on `rpc_path`) — the
  *    subscriber's *own* single session is revoked (`account_session_revoke`),
- *    so the `session_revoke` event drops the stream via the session-hash-scoped
- *    `close_for_session` path (the distinct primitive cases 2–3 don't reach).
+ *    which closes only the stream registered under that session's hash (the
+ *    distinct close cases 2–3 don't reach).
+ * 5. **close on account delete** (gated on `rpc_path` and
+ *    `capabilities.account_lifecycle`) — the keeper soft-deletes a second
+ *    admin whose stream is open; the delete revokes its credentials and
+ *    closes its stream.
+ * 6. **per-session cap** — one stream past `max_per_scope` on one session
+ *    closes the oldest (evict-oldest, no final frame) and leaves every other
+ *    stream open. Needs no RPC: the cap runs inside the subscribe itself.
  *
- * The close-on-revoke matrix is layered: cases 3–4 exercise the account-wide
- * and session-scoped paths cross-process; the remaining union events
- * (`token_revoke_all` / `logout` / `password_change`, all account-wide; and
- * `role_grant_revoke`, role-matched) are covered by the spine's `fuz_realtime`
- * SSE-registry unit tests and the in-process guard self-test, so a cross-process
+ * The close-on-revoke matrix is layered: cases 3–5 exercise the account-wide
+ * and session-scoped paths cross-process; the remaining revocation events
+ * (`token_revoke_all` / `logout` / `password_change` / `account_purge`, all
+ * account-wide; `token_revoke`, token-scoped; and `role_grant_revoke`,
+ * role-matched) are covered by the spine's `fuz_realtime` SSE-registry unit
+ * tests and the in-process guard self-test, so a cross-process
  * `token_revoke_all`-with-zero-tokens case (which may emit no audit row) stays
  * out to keep the spawned-backend suite non-flaky.
  *
@@ -49,8 +57,9 @@ import '../assert_dev_env.js';
  */
 import { assert, describe } from 'vitest';
 import { account_session_list_action_spec, account_session_revoke_action_spec, account_session_revoke_all_action_spec } from '../../auth/account_action_specs.js';
-import { admin_session_revoke_all_action_spec } from '../../auth/admin_action_specs.js';
-import { audit_log_event_specs } from '../../realtime/sse_auth_guard.js';
+import { account_delete_action_spec, admin_session_revoke_all_action_spec } from '../../auth/admin_action_specs.js';
+import { ROLE_ADMIN } from '../../auth/role_schema.js';
+import { AUDIT_LOG_SSE_MAX_PER_SCOPE, audit_log_event_specs } from '../../realtime/sse_auth_guard.js';
 import { SSE_CONNECTED_COMMENT } from '../../realtime/sse_constants.js';
 import { create_sse_transport } from '../transports/sse_transport.js';
 import { create_rpc_post_init } from '../rpc_helpers.js';
@@ -73,13 +82,15 @@ const assert_audit_data_frame = (frame) => {
     assert.ok(result.success, `audit data frame params mismatch for '${String(payload.method)}': ${result.success ? '' : JSON.stringify(result.error.issues)}`);
 };
 /**
- * Register the cross-process SSE round-trip suite. Up to four cases over a
+ * Register the cross-process SSE round-trip suite. Its cases run over a
  * real streaming `fetch`: connected-comment, audit data frame, account-wide
- * close-on-revoke, and session-scoped close-on-revoke.
+ * close-on-revoke, session-scoped close-on-revoke, close on account delete,
+ * and the per-session cap.
  */
 export const describe_cross_process_sse_tests = (options) => {
     const { setup_test, capabilities, base_url, rpc_path, origin } = options;
     const sse_path = options.sse_path ?? DEFAULT_SSE_PATH;
+    const max_per_scope = options.max_per_scope === undefined ? AUDIT_LOG_SSE_MAX_PER_SCOPE : options.max_per_scope;
     describe('cross-process sse', () => {
         test_if(capabilities.sse, 'connects and emits the connected comment', async () => {
             const fixture = await setup_test();
@@ -127,8 +138,9 @@ export const describe_cross_process_sse_tests = (options) => {
                 await sse.close();
             }
         });
-        // Revoke the subscriber's OWN sessions → `session_revoke_all` targets the
-        // keeper, so the audit guard closes the live stream.
+        // Revoke the subscriber's OWN sessions → the handler closes the keeper's
+        // streams once the revoke commits (the audit guard repeats the close on
+        // the `session_revoke_all` row).
         test_if(capabilities.sse && rpc_path !== undefined, 'stream closes when the subscriber sessions are revoked', async () => {
             const fixture = await setup_test();
             const sse = await create_sse_transport({
@@ -150,14 +162,15 @@ export const describe_cross_process_sse_tests = (options) => {
             }
         });
         // Single `session_revoke` of the subscriber's OWN session → the
-        // session-hash-scoped close path (`close_for_session` / the TS guard's
-        // `close_by_identity(session_id)`). The keeper holds exactly one session,
-        // so revoking it by its blake3 hash drops the stream opened under it.
-        // This is the close-on-revoke path the account-wide cases above don't
-        // exercise; the remaining union events (`token_revoke_all` / `logout` /
-        // `password_change`) share the account-wide `close_for_account` path the
-        // `session_revoke_all` case already covers, and `role_grant_revoke`'s
-        // role-matched path is covered by `fuz_realtime`'s SSE registry unit tests.
+        // session-hash-scoped close (the Rust registry's `close_for_session`, the
+        // TS registry's `close_by_identity(session_hash)`). The keeper holds
+        // exactly one session, so revoking it by its blake3 hash drops the stream
+        // opened under it. This is the close-on-revoke path the account-wide case
+        // above doesn't exercise; the remaining account-wide events
+        // (`token_revoke_all` / `logout` / `password_change` / `account_purge`)
+        // share the close the `session_revoke_all` and account-delete cases cover,
+        // and `token_revoke`'s token-scoped and `role_grant_revoke`'s role-matched
+        // closes are covered by `fuz_realtime`'s SSE registry unit tests.
         test_if(capabilities.sse && rpc_path !== undefined, 'stream closes on a single session_revoke of the subscriber session', async () => {
             const fixture = await setup_test();
             const sse = await create_sse_transport({
@@ -183,5 +196,59 @@ export const describe_cross_process_sse_tests = (options) => {
                 await sse.close();
             }
         });
+        // A soft-deleted account's credentials stop authenticating, and a stream
+        // never rechecks its own — so the delete must close it. The keeper
+        // deletes a second admin whose stream is open; the keeper's own admin
+        // grant keeps the delete clear of the last-admin guard.
+        test_if(capabilities.sse && capabilities.account_lifecycle && rpc_path !== undefined, 'stream closes when the subscriber account is deleted', async () => {
+            const fixture = await setup_test();
+            const target = await fixture.create_account({
+                username: 'sse_delete_target',
+                roles: [ROLE_ADMIN]
+            });
+            const cookie = target.create_session_headers().cookie;
+            assert.ok(cookie, 'expected a session cookie for the target account');
+            const sse = await create_sse_transport({ base_url, sse_path, cookies: [cookie], origin });
+            try {
+                const first = await sse.read_frame();
+                assert.strictEqual(first + '\n\n', SSE_CONNECTED_COMMENT, 'first frame must be the connected comment');
+                const res = await fixture.transport(rpc_path, create_rpc_post_init(account_delete_action_spec.method, {
+                    account_id: target.account.id
+                }));
+                assert.strictEqual(res.status, 200, `account_delete RPC failed (status=${res.status})`);
+                const closed = await sse.wait_for_close(2000);
+                assert.ok(closed, 'stream did not close within 2s after account_delete');
+            }
+            finally {
+                await sse.close();
+            }
+        });
+        // One stream past the cap on one session → the oldest closes, the newest
+        // stays open. Opened in sequence, each awaited to its connect comment, so
+        // the server registered them in order and "oldest" is stream 0 on both
+        // spines. The evicted stream ends with no final frame, so a browser
+        // `EventSource` would reconnect — this asserts the server side only.
+        test_if(capabilities.sse && max_per_scope !== null, 'one stream past the per-session cap closes the oldest', async () => {
+            const fixture = await setup_test();
+            const cookies = fixture.transport.cookies();
+            const streams = [];
+            try {
+                for (let i = 0; i <= max_per_scope; i++) {
+                    const sse = await create_sse_transport({ base_url, sse_path, cookies, origin });
+                    streams.push(sse);
+                    const first = await sse.read_frame();
+                    assert.strictEqual(first + '\n\n', SSE_CONNECTED_COMMENT, `stream ${i}: first frame must be the connected comment`);
+                }
+                const [oldest, ...survivors] = streams;
+                const closed = await oldest.wait_for_close(2000);
+                assert.ok(closed, 'the oldest stream did not close within 2s of the cap overflow');
+                // only the oldest — every later stream on the session stays open
+                const survivors_closed = await Promise.all(survivors.map((sse) => sse.wait_for_close(200)));
+                assert.deepStrictEqual(survivors_closed, survivors.map(() => false), 'only the oldest stream may close; the rest of the session stays open');
+            }
+            finally {
+                await Promise.all(streams.map((sse) => sse.close()));
+            }
+        });
     });
 };

package/dist/testing/cross_backend/testing_server_bun.js

@@ -53,10 +53,10 @@ export const create_bun_testing_adapter = () => ({
             // hang), and the client runtime — a single server-closed WS is
             // necessary and sufficient. Client-initiated close or leaving the
             // socket open both stop cleanly in ~0ms. In this suite the trigger is
-            // `create_ws_auth_guard` closing the socket on `session_revoke_all`
-            // (the `ws.cross.test.ts` close-on-revoke case) — the only
-            // server-initiated WS close, which is why teardown hangs there and
-            // not under HTTP-only or client-closed WS traffic.
+            // any server-initiated WS close — a revocation's (the `ws.cross.test.ts`
+            // close-on-revoke cases), a cap eviction's, an oversized message's —
+            // which is why teardown hangs after those and not under HTTP-only or
+            // client-closed WS traffic.
             //
             // So initiate a force-close (`true` drops active connections, no
             // drain) but DON'T await it: awaiting hangs `start_testing_server`'s

package/dist/testing/cross_backend/ts_spine_backend_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts_spine_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ts_spine_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAkC3D,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,uDAAuD,CAAC;AAEvF,MAAM,WAAW,2BAA2B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAWD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAmBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAmBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAgCF,CAAC"}
+{"version":3,"file":"ts_spine_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ts_spine_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AASzD,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AA0C3D,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,uDAAuD,CAAC;AAEvF,MAAM,WAAW,2BAA2B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAWD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAmBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAmBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAgCF,CAAC"}

package/dist/testing/cross_backend/ts_spine_backend_config.js

@@ -9,6 +9,7 @@ export const TS_SPINE_DIR_ENV = 'FUZ_TESTING_TS_SPINE_DIR';
  * (the binary wires `audit_log_sse`), `ready` (the binary live-mounts the
  * `/ready` deploy gate in `build_spine_app`), `peer_request` (the backend
  * WS transport's `request_connection` path drives server→client `peer/ping`),
+ * `ws_account_actions` (the binary mounts the account actions on `/api/ws`),
  * and `cell_gated_create` (the binary's `full_spine_mount` mounts the
  * `test_cell_gated_create_authorize` policy).
  */
@@ -17,11 +18,13 @@ const ts_spine_capabilities = Object.freeze({
     sse: true,
     ready: true,
     peer_request: true,
+    ws_account_actions: true,
     cell_gated_create: true
 });
 /**
  * Capabilities for the **Bun** spine binary — `ts_spine_capabilities` with
- * `oversized_reject_closes_connection: false`. `Bun.serve` drains the declared
+ * `oversized_reject_closes_connection: false` and
+ * `ws_handshake_pipelining: false`. `Bun.serve` drains the declared
  * `Content-Length` of an oversized-body `413` reject and keeps the socket
  * alive (processing the correctly-framed pipelined request) even when the
  * response carries `Connection: close`, unlike `@hono/node-server` / Deno /
@@ -29,10 +32,15 @@ const ts_spine_capabilities = Object.freeze({
  * there is no desync — but the smuggling suite's strong "connection closes"
  * assertion doesn't hold; this flag routes Bun onto the suite's no-desync arm.
  * See `docs/security.md` §"Body Size Limiting".
+ *
+ * `Bun.serve` also answers `400` to an upgrade request that carries WebSocket
+ * frames in the same TCP write, before any handler runs, so the WS suite's
+ * frames-with-the-handshake case has nothing to drive there.
  */
 const ts_spine_bun_capabilities = Object.freeze({
     ...ts_spine_capabilities,
-    oversized_reject_closes_connection: false
+    oversized_reject_closes_connection: false,
+    ws_handshake_pipelining: false
 });
 /** Default port for the Node TS spine binary — slots beside the Rust `spine_stub` (1177). */
 export const TS_SPINE_NODE_DEFAULT_PORT = 1178;

package/dist/testing/cross_backend/ws_connection_cap.d.ts

@@ -0,0 +1,35 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Options for the WebSocket connection-cap parity suite. */
+export interface WsConnectionCapCrossTestOptions {
+    /**
+     * Per-test fixture producer (`default_cross_process_setup(handle)`). Every
+     * socket in a case upgrades with the fresh-per-test keeper's session
+     * cookies, so they all land on one account.
+     */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `capabilities.ws`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at (e.g. `http://localhost:1178`). */
+    readonly base_url: string;
+    /** WebSocket endpoint path on the backend (e.g. `/api/ws`). */
+    readonly ws_path: string;
+    /** Origin for the upgrades. Defaults to `base_url`. */
+    readonly origin?: string;
+    /**
+     * The backend's per-account connection cap, which each case opens past.
+     * Defaults to `DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT`, the cap both spines
+     * apply unless overridden; pass the consumer's value when it sets one, or
+     * `null` (a backend with the cap disabled) to skip the cases.
+     */
+    readonly max_connections_per_account?: number | null;
+}
+/**
+ * Register the WebSocket connection-cap parity suite over a real upgrade:
+ * one connection past the cap closes the account's oldest with
+ * `WS_CLOSE_CONNECTION_LIMIT` and nothing else, and a closed connection
+ * frees its slot.
+ */
+export declare const describe_ws_connection_cap_cross_tests: (options: WsConnectionCapCrossTestOptions) => void;
+//# sourceMappingURL=ws_connection_cap.d.ts.map

package/dist/testing/cross_backend/ws_connection_cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws_connection_cap.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_connection_cap.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAsD9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,6DAA6D;AAC7D,MAAM,WAAW,+BAA+B;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC,GAClD,SAAS,+BAA+B,KACtC,IA4GF,CAAC"}

package/dist/testing/cross_backend/ws_connection_cap.js

@@ -0,0 +1,131 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-backend parity suite for the **per-account WebSocket connection cap**
+ * over a real upgrade.
+ *
+ * Both spines bound an account's concurrent WebSocket connections
+ * (`BackendWebsocketTransport`'s `max_connections_per_account` on the TS side,
+ * the Rust `fuz_realtime` `ConnectionRegistry` on the other; both default to
+ * `DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT`) with the same policy: **evict-oldest**
+ * — a connection past the cap is always admitted, and the account's oldest is
+ * closed with `WS_CLOSE_CONNECTION_LIMIT` and the reason `connection limit`.
+ * A client reads that close as "superseded": closed until the user acts, not
+ * revoked and not reconnecting (`FrontendWebsocketClient.superseded`). The
+ * code, the reason, and which socket closes are therefore wire contract, and
+ * this suite is the pin that runs on both. Two cases:
+ *
+ * - **the oldest is superseded, and it is not a revocation** — on one session,
+ *   opening one socket past the cap closes exactly the first with the
+ *   connection-limit code and reason; every other socket, the newest included,
+ *   stays open and still dispatches. The session then upgrades again, which a
+ *   revoked session could not — and that upgrade supersedes the next-oldest
+ *   in turn.
+ * - **a closed connection frees its slot** — one socket held open while a
+ *   cap's worth of others open and close in sequence is never evicted. A
+ *   backend that leaks closed connections in its registry counts them toward
+ *   the cap and closes the held socket, which is what this catches.
+ *
+ * Sockets open in sequence, each answering a `heartbeat` before the next
+ * opens (`create_admitted_ws_transport`), so the backend registered them in
+ * that order and "oldest" names the same socket on both spines (an upgrade
+ * answers its handshake before the connection is registered and admitted, so
+ * the handshake alone doesn't order them).
+ *
+ * **Consumer-agnostic**, like `describe_cross_process_ws_tests`: it drives
+ * only the `heartbeat` protocol action, present on every WS endpoint. Gated on
+ * `capabilities.ws`; cross-process only (`create_ws_transport` needs a real
+ * bound socket). Each case opens more than a cap's worth of real sockets,
+ * which is why it's a separate call rather than more cases on the WS
+ * round-trip suite.
+ *
+ * `$lib`-free by contract (relative specifiers only), like the sibling
+ * cross-backend suites.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { heartbeat_action_spec } from '../../actions/heartbeat.js';
+import { WS_CLOSE_CONNECTION_LIMIT } from '../../actions/transports.js';
+import { DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT } from '../../actions/transports_ws_backend.js';
+import { create_admitted_ws_transport } from '../transports/ws_transport.js';
+import { test_if } from './capabilities.js';
+/** The close reason both spines send with `WS_CLOSE_CONNECTION_LIMIT`. */
+const CONNECTION_LIMIT_REASON = 'connection limit';
+/**
+ * Register the WebSocket connection-cap parity suite over a real upgrade:
+ * one connection past the cap closes the account's oldest with
+ * `WS_CLOSE_CONNECTION_LIMIT` and nothing else, and a closed connection
+ * frees its slot.
+ */
+export const describe_ws_connection_cap_cross_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path, origin } = options;
+    const max = options.max_connections_per_account === undefined
+        ? DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT
+        : options.max_connections_per_account;
+    const enabled = capabilities.ws && max !== null;
+    /**
+     * Open a socket the backend has admitted (a `heartbeat` round trip), so
+     * the connections are registered in the order they were opened.
+     */
+    const open_registered = (cookies) => create_admitted_ws_transport({ base_url, ws_path, cookies, origin });
+    const assert_superseded = async (client, label) => {
+        const closed = await client.wait_for_close(2000);
+        assert.ok(closed, `${label} did not close within 2s of the cap overflow`);
+        assert.strictEqual(client.close_code, WS_CLOSE_CONNECTION_LIMIT, `${label} close code`);
+        assert.strictEqual(client.close_reason, CONNECTION_LIMIT_REASON, `${label} close reason`);
+    };
+    /** Every client still open and answering — a fresh request id per call via `id`. */
+    const assert_all_answer = async (clients, id, message) => {
+        const results = await Promise.all(clients.map((client) => client.request(id, heartbeat_action_spec.method, {})));
+        assert.deepStrictEqual(results, clients.map(() => ({})), message);
+        assert.deepStrictEqual(clients.map((client) => client.close_code), clients.map(() => null), message);
+    };
+    // each case opens more than a cap's worth of real sockets in sequence, so its
+    // time scales with the cap and the backend's upgrade cost
+    describe('per-account websocket connection cap parity', { timeout: 30_000 }, () => {
+        test_if(enabled, 'one connection past the cap closes the oldest with WS_CLOSE_CONNECTION_LIMIT, and only it', async () => {
+            const fixture = await setup_test();
+            const cookies = fixture.transport.cookies();
+            const sockets = [];
+            try {
+                for (let i = 0; i < max; i++) {
+                    sockets.push(await open_registered(cookies));
+                }
+                // at the cap, nothing has closed
+                await assert_all_answer(sockets, 'at_cap', 'every socket at the cap stays open');
+                // one past it: always admitted, never refused
+                sockets.push(await open_registered(cookies));
+                const [oldest, ...survivors] = sockets;
+                await assert_superseded(oldest, 'the oldest socket');
+                await assert_all_answer(survivors, 'past_cap', 'only the oldest may close; every other socket, the newest included, keeps answering');
+                // Not a revocation — the session still authenticates an upgrade
+                // (a revoked one is refused there). That upgrade is one more past
+                // the cap, so it supersedes the next-oldest.
+                sockets.push(await open_registered(cookies));
+                await assert_superseded(survivors[0], 'the next-oldest socket');
+                await assert_all_answer(sockets.slice(2), 'past_cap_again', 'the session keeps its newest sockets after a second overflow');
+            }
+            finally {
+                await Promise.all(sockets.map((client) => client.close().catch(() => { })));
+            }
+        });
+        test_if(enabled, 'a closed connection frees its slot', async () => {
+            const fixture = await setup_test();
+            const cookies = fixture.transport.cookies();
+            const held = await open_registered(cookies);
+            try {
+                // A cap's worth of connections, one at a time, each closed before
+                // the next opens — the account never holds more than a few at once,
+                // however late the backend notices each close.
+                for (let i = 0; i < max; i++) {
+                    const client = await open_registered(cookies);
+                    await client.close();
+                }
+                await assert_all_answer([held], 'held', 'closed connections must not count toward the cap — the held socket was evicted');
+            }
+            finally {
+                await held.close().catch(() => { });
+            }
+        });
+    });
+};

package/dist/testing/cross_backend/ws_round_trip.d.ts

@@ -37,7 +37,8 @@ export interface CrossProcessWsTestOptions {
  * `heartbeat` round-trip, `heartbeat`'s parameterless-shape contract, an
  * oversized message closing with `WS_CLOSE_MESSAGE_TOO_BIG`, anonymous-upgrade
  * refusal, disallowed-origin refusal, and — when `rpc_path` is supplied —
- * session-revocation closing the live socket.
+ * session revocation and account deletion closing the live socket, plus a
+ * self-revoking socket reading its reply before its close.
  */
 export declare const describe_cross_process_ws_tests: (options: CrossProcessWsTestOptions) => void;
 //# sourceMappingURL=ws_round_trip.d.ts.map

package/dist/testing/cross_backend/ws_round_trip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAoE9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,yBAAyB,KAAG,IAwIpF,CAAC"}
+{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6F9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,yBAAyB,KAAG,IA+RpF,CAAC"}