@fuzdev/fuz_app 0.147.0 → 0.148.0

package/dist/testing/cross_backend/transport_composition.js

@@ -31,9 +31,10 @@ import '../assert_dev_env.js';
  *   Rust spine) or one value joined from them (the TS runtimes), so a check that
  *   reads only the first lets it through.
  * - **over cap + foreign `Origin`** declares a `Content-Length` one byte over
- *   the shared 1 MiB cap and carries no credential: the cap answers on the
- *   header, ahead of both the origin check and auth. Only the surfaces that
- *   take a body have the column.
+ *   the route's cap — the shared 1 MiB default, or `rpc_max_body_bytes` on the
+ *   RPC row — and carries no credential: the cap answers on the header, ahead
+ *   of both the origin check and auth. Only the surfaces that take a body have
+ *   the column.
  * - **no credential** sends an allowed `Origin` and nothing else.
  * - **narrowed token** sends a bearer minted with a method-scoped scope, and no
  *   `Origin` (a bearer in a browser context is discarded, not refused). The RPC
@@ -56,21 +57,31 @@ import '../assert_dev_env.js';
  * in-process transport, whole bodies included, and the WebSocket rows skip
  * (there is no socket to upgrade).
  *
+ * **Multi-actor upgrade.** One more WS row needs a keeper seeded with a
+ * second actor (`extra_actors`), so it runs only given `multi_actor`: a
+ * multi-actor keeper's session upgrading with no `?acting=` → 400
+ * `actor_required`, the flat body the TS spine's upgrade-time authorization
+ * phase answers. The upgrade resolves an actor there, and a multi-actor
+ * account must name one. A backend whose upgrade resolves no actor admits
+ * the socket instead; `multi_actor.xfail` runs the row as `xfail_until` for
+ * it.
+ *
  * Wire it for any backend that serves the spine's account routes, RPC
  * endpoint, WebSocket endpoint and audit stream; the WS and SSE rows gate on
  * `capabilities.ws` and `capabilities.sse`.
  *
  * @module
  */
-import { assert, describe } from 'vitest';
+import { assert, describe, test } from 'vitest';
 import { randomBytes } from 'node:crypto';
 import { account_verify_action_spec } from '../../auth/account_action_specs.js';
-import { ERROR_AUTHENTICATION_REQUIRED, ERROR_CREDENTIAL_TYPE_REQUIRED, ERROR_FORBIDDEN_ORIGIN, ERROR_PAYLOAD_TOO_LARGE, ERROR_TOKEN_SCOPE_REQUIRED } from '../../http/error_schemas.js';
+import { ERROR_ACTOR_REQUIRED, ERROR_AUTHENTICATION_REQUIRED, ERROR_CREDENTIAL_TYPE_REQUIRED, ERROR_FORBIDDEN_ORIGIN, ERROR_PAYLOAD_TOO_LARGE, ERROR_TOKEN_SCOPE_REQUIRED } from '../../http/error_schemas.js';
 import { create_rpc_get_url } from '../rpc_helpers.js';
-import { raw_http_exchange, raw_http_parse_response } from '../transports/raw_http.js';
+import { raw_http_exchange, raw_http_header_lines, raw_http_parse_json, raw_http_parse_response, RAW_HTTP_READ_TIMEOUT_MS } from '../transports/raw_http.js';
 import { test_if } from './capabilities.js';
 import { mint_narrowed_api_token } from './narrowed_api_token.js';
-import { SPINE_RPC_PATH, SPINE_SSE_PATH } from './spine_surface_constants.js';
+import { SPINE_ACCOUNT_LOGOUT_PATH, SPINE_ACCOUNT_PASSWORD_PATH, SPINE_BODY_LIMIT_DEFAULT_BYTES, SPINE_RPC_PATH, SPINE_SSE_PATH, SPINE_WS_PATH } from './spine_surface_constants.js';
+import { xfail_until } from './xfail.js';
 /** The RPC method the narrowed token admits. */
 const NARROWED_ADMITTED_METHOD = account_verify_action_spec.method;
 /**
@@ -146,29 +157,26 @@ export const transport_composition_cases = [
     { surface: 'sse', probe: 'no_credential', expect: UNAUTHENTICATED, gate: 'sse' },
     { surface: 'sse', probe: 'narrowed_token', expect: SESSION_ONLY, gate: 'sse' }
 ];
-/** The shared 1 MiB default cap both spines ship, as in `body_size.ts`. */
-const BODY_LIMIT_DEFAULT_BYTES = 1024 * 1024;
+/**
+ * The rows that need a multi-actor keeper — run only given
+ * `TransportCompositionCrossTestOptions.multi_actor`, on its fixture.
+ */
+export const transport_composition_multi_actor_cases = [
+    {
+        surface: 'ws_upgrade',
+        probe: 'multi_actor_no_acting',
+        expect: { status: 400, error: ERROR_ACTOR_REQUIRED },
+        gate: 'ws'
+    }
+];
 /** An `Origin` no backend's allowlist admits. */
 const DISALLOWED_ORIGIN = 'http://evil.com';
-/** How long a raw exchange waits for the refusal. */
-const RAW_READ_TIMEOUT_MS = 2000;
 const rpc_envelope = (method, id) => JSON.stringify({ jsonrpc: '2.0', method, id });
 /** A JSON object body of exactly `bytes` ASCII bytes. */
 const sized_json = (bytes) => {
     const base = JSON.stringify({ pad: '' });
     return JSON.stringify({ pad: 'x'.repeat(Math.max(0, bytes - base.length)) });
 };
-const to_header_lines = (headers) => Object.entries(headers)
-    .map(([name, value]) => `${name}: ${value}\r\n`)
-    .join('');
-const parse_json = (text) => {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-};
 const case_name = (c) => `${c.surface} × ${c.probe} → ${c.expect.status} ${c.expect.error}`;
 /**
  * Read the refusal reason and fields out of a body, by the shape the case
@@ -207,9 +215,10 @@ const assert_refusal_body = (c, body, text) => {
 export const describe_transport_composition_cross_tests = (options) => {
     const { setup_test, capabilities, base_url } = options;
     const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
-    const rest_path = options.rest_path ?? '/api/account/logout';
-    const password_path = options.password_path ?? '/api/account/password';
-    const ws_path = options.ws_path ?? '/api/ws';
+    const rest_path = options.rest_path ?? SPINE_ACCOUNT_LOGOUT_PATH;
+    const rpc_max_body_bytes = options.rpc_max_body_bytes ?? SPINE_BODY_LIMIT_DEFAULT_BYTES;
+    const password_path = options.password_path ?? SPINE_ACCOUNT_PASSWORD_PATH;
+    const ws_path = options.ws_path ?? SPINE_WS_PATH;
     const sse_path = options.sse_path ?? SPINE_SSE_PATH;
     const allowed_origin = options.origin ?? (base_url === null ? 'http://localhost:5173' : new URL(base_url).origin);
     /** The request line, headers and body a case's probe sends. */
@@ -236,6 +245,10 @@ export const describe_transport_composition_cross_tests = (options) => {
             case 'no_credential':
                 credential = { origin: allowed_origin };
                 break;
+            case 'multi_actor_no_acting':
+                // the multi-actor keeper's session, no `?acting=` on the path
+                credential = { ...fixture.create_session_headers(), origin: allowed_origin };
+                break;
             case 'narrowed_token': {
                 const token = await mint_narrowed_api_token({
                     app: fixture.transport,
@@ -257,8 +270,8 @@ export const describe_transport_composition_cross_tests = (options) => {
                     method: 'POST',
                     path: c.surface === 'rest_post' ? rest_path : password_path,
                     headers: { ...credential, 'content-type': 'application/json' },
-                    body: over_cap ? sized_json(BODY_LIMIT_DEFAULT_BYTES + 1) : '{}',
-                    over_cap,
+                    body: over_cap ? sized_json(SPINE_BODY_LIMIT_DEFAULT_BYTES + 1) : '{}',
+                    over_cap_length: over_cap ? SPINE_BODY_LIMIT_DEFAULT_BYTES + 1 : null,
                     repeated_headers
                 };
             case 'rpc_post': {
@@ -266,8 +279,8 @@ export const describe_transport_composition_cross_tests = (options) => {
                     method: 'POST',
                     path: rpc_path,
                     headers: { ...credential, 'content-type': 'application/json' },
-                    body: over_cap ? sized_json(BODY_LIMIT_DEFAULT_BYTES + 1) : rpc_envelope(rpc_method, id),
-                    over_cap,
+                    body: over_cap ? sized_json(rpc_max_body_bytes + 1) : rpc_envelope(rpc_method, id),
+                    over_cap_length: over_cap ? rpc_max_body_bytes + 1 : null,
                     repeated_headers
                 };
             }
@@ -277,7 +290,7 @@ export const describe_transport_composition_cross_tests = (options) => {
                     path: create_rpc_get_url(rpc_path, rpc_method, undefined, id),
                     headers: credential,
                     body: null,
-                    over_cap,
+                    over_cap_length: null,
                     repeated_headers
                 };
             case 'ws_upgrade':
@@ -292,7 +305,7 @@ export const describe_transport_composition_cross_tests = (options) => {
                         'sec-websocket-version': '13'
                     },
                     body: null,
-                    over_cap,
+                    over_cap_length: null,
                     repeated_headers
                 };
             case 'sse':
@@ -301,7 +314,7 @@ export const describe_transport_composition_cross_tests = (options) => {
                     path: sse_path,
                     headers: { ...credential, accept: 'text/event-stream' },
                     body: null,
-                    over_cap,
+                    over_cap_length: null,
                     repeated_headers
                 };
         }
@@ -321,44 +334,61 @@ export const describe_transport_composition_cross_tests = (options) => {
             return { status: res.status, text: await res.text() };
         }
         const url = new URL(base_url);
-        const body = probe.over_cap ? '' : (probe.body ?? '');
-        const length_header = probe.over_cap
-            ? { 'content-length': String(BODY_LIMIT_DEFAULT_BYTES + 1) }
+        const body = probe.over_cap_length === null ? (probe.body ?? '') : '';
+        const length_header = probe.over_cap_length !== null
+            ? { 'content-length': String(probe.over_cap_length) }
             : probe.body === null
                 ? {}
                 : { 'content-length': String(body.length) };
         const request = `${probe.method} ${probe.path} HTTP/1.1\r\n` +
-            to_header_lines({ host: url.host, ...probe.headers, ...length_header }) +
+            raw_http_header_lines({ host: url.host, ...probe.headers, ...length_header }) +
             (probe.repeated_headers ?? []).map(([name, value]) => `${name}: ${value}\r\n`).join('') +
             `\r\n` +
             body;
         const { received, closed_by_server } = await raw_http_exchange(base_url, request, {
-            read_timeout_ms: RAW_READ_TIMEOUT_MS,
+            read_timeout_ms: RAW_HTTP_READ_TIMEOUT_MS,
             until: 'response'
         });
         const response = raw_http_parse_response(received);
         assert.ok(response, `${probe.method} ${probe.path}: expected a whole response; ` +
             (closed_by_server
                 ? 'the server closed the connection first'
-                : `none arrived within ${RAW_READ_TIMEOUT_MS}ms`) +
+                : `none arrived within ${RAW_HTTP_READ_TIMEOUT_MS}ms`) +
             `. Received: ${received ? received.slice(0, 200) : 'nothing'}`);
         return { status: response.status, text: response.body };
     };
+    const run_case = async (c, fixture_setup) => {
+        const fixture = await fixture_setup();
+        const res = await send_probe(fixture, await build_probe(c, fixture));
+        assert.strictEqual(res.status, c.expect.status, `${case_name(c)}: status (body: ${res.text.slice(0, 200)})`);
+        // a backend that declares no WS refusal body (Node's `@hono/node-ws`)
+        // may answer with an empty one; a body it does send is still asserted
+        if (c.surface === 'ws_upgrade' && !capabilities.ws_refusal_body && res.text === '')
+            return;
+        assert_refusal_body(c, raw_http_parse_json(res.text), res.text);
+    };
+    const is_runnable = (c) => (c.gate === undefined || capabilities[c.gate]) &&
+        // an upgrade needs a socket; in-process there is none
+        (c.surface !== 'ws_upgrade' || base_url !== null);
     describe('transport composition (front door)', () => {
         for (const c of transport_composition_cases) {
-            const gated = c.gate === undefined || capabilities[c.gate];
-            // an upgrade needs a socket; in-process there is none
-            const reachable = c.surface !== 'ws_upgrade' || base_url !== null;
-            test_if(gated && reachable, case_name(c), async () => {
-                const fixture = await setup_test();
-                const res = await send_probe(fixture, await build_probe(c, fixture));
-                assert.strictEqual(res.status, c.expect.status, `${case_name(c)}: status (body: ${res.text.slice(0, 200)})`);
-                // a backend that declares no WS refusal body (Node's `@hono/node-ws`)
-                // may answer with an empty one; a body it does send is still asserted
-                if (c.surface === 'ws_upgrade' && !capabilities.ws_refusal_body && res.text === '')
-                    return;
-                assert_refusal_body(c, parse_json(res.text), res.text);
-            });
+            test_if(is_runnable(c), case_name(c), () => run_case(c, setup_test));
+        }
+        const { multi_actor } = options;
+        if (!multi_actor)
+            return;
+        for (const c of transport_composition_multi_actor_cases) {
+            const name = case_name(c);
+            const body = () => run_case(c, multi_actor.setup_test);
+            if (!is_runnable(c)) {
+                test_if(false, name, body);
+            }
+            else if (multi_actor.xfail) {
+                xfail_until(multi_actor.xfail.tracking_id, multi_actor.xfail.reason, name, body);
+            }
+            else {
+                test(name, body);
+            }
         }
     });
 };

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

@@ -34,6 +34,14 @@ export interface TsSpineBackendConfigOptions {
     readonly port?: number;
     /** Database URL. Default `'memory://'` (in-memory pglet). */
     readonly database_url?: string;
+    /**
+     * Backend name — labels the spawn in errors and logs, and names its
+     * directory under `os.tmpdir()` (`build_test_backend_paths`). Defaults per
+     * runtime (`ts_spine_node`, `ts_spine_deno`, `ts_spine_bun`). Give each
+     * backend spawned alongside another of its runtime its own name, so their
+     * bootstrap and daemon-token files don't collide.
+     */
+    readonly name?: string;
     /**
      * Enable the per-IP + per-account login rate limiters on the spawned binary
      * (`FUZ_LOGIN_RATE_LIMIT_ENABLED=true`). Off by default — the standard cross

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;AAiEzD,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,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,MAAM,CAAC;CACjD;AAWD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAoBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAoBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAiCF,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;AA4EzD,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,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,8BAA8B,CAAC,EAAE,MAAM,CAAC;CACjD;AAWD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAwBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAwBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAqCF,CAAC"}

package/dist/testing/cross_backend/ts_spine_backend_config.js

@@ -3,7 +3,12 @@ import { build_test_backend_paths } from './build_test_backend_paths.js';
 import { action_rate_limit_env, make_default_ts_backend_config, ts_default_capabilities } from './default_backend_configs.js';
 import { LOGIN_RATE_LIMIT_ENABLED_ENV, SPINE_SSE_PATH, TS_SPINE_DIR_ENV } from './spine_surface_constants.js';
 /**
- * Capabilities for the TS spine binary — `ts_default_capabilities` plus `sse`
+ * Capabilities for the TS spine binary — `ts_default_capabilities` with every `MountFlag` stated, all `true`: `ws`
+ * (the binary mounts `/api/ws` through `create_app_server`'s `ws_endpoints`),
+ * `cell_crud` + `cell_relations` (`full_spine_mount` live-mounts the full cell
+ * surface over the `fuz_cell` namespace), `fact_serving` (the cell-gated serve
+ * route, the `fuz_facts` namespace and `_testing_put_fact`),
+ * `fact_serving_admin_hash` (the admin bare-hash route), `sse`
  * (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`),
@@ -17,7 +22,12 @@ import { LOGIN_RATE_LIMIT_ENABLED_ENV, SPINE_SSE_PATH, TS_SPINE_DIR_ENV } from '
  */
 const ts_spine_capabilities = Object.freeze({
     ...ts_default_capabilities,
+    ws: true,
     sse: true,
+    cell_crud: true,
+    cell_relations: true,
+    fact_serving: true,
+    fact_serving_admin_hash: true,
     ready: true,
     peer_request: true,
     ws_account_actions: true,
@@ -75,8 +85,7 @@ const login_rate_limit_env = (enable) => enable ? { [LOGIN_RATE_LIMIT_ENABLED_EN
  * (Gro's TS loader resolves the entry's relative imports).
  */
 export const ts_spine_node_backend_config = (options = {}) => {
-    const { port = TS_SPINE_NODE_DEFAULT_PORT, database_url, enable_login_rate_limit } = options;
-    const name = 'ts_spine_node';
+    const { port = TS_SPINE_NODE_DEFAULT_PORT, database_url, enable_login_rate_limit, name = 'ts_spine_node' } = options;
     const paths = build_test_backend_paths(name);
     return {
         ...make_default_ts_backend_config({
@@ -85,8 +94,8 @@ export const ts_spine_node_backend_config = (options = {}) => {
             start_command: ['gro', 'run', TS_SPINE_NODE_ENTRY],
             database_url,
             paths,
+            daemon_token_dir_env: TS_SPINE_DIR_ENV,
             extra_env: {
-                [TS_SPINE_DIR_ENV]: paths.root,
                 ...login_rate_limit_env(enable_login_rate_limit),
                 ...action_rate_limit_env(options)
             },
@@ -103,8 +112,7 @@ export const ts_spine_node_backend_config = (options = {}) => {
  * optional `@hono/bun` peer dep.
  */
 export const ts_spine_bun_backend_config = (options = {}) => {
-    const { port = TS_SPINE_BUN_DEFAULT_PORT, database_url, enable_login_rate_limit } = options;
-    const name = 'ts_spine_bun';
+    const { port = TS_SPINE_BUN_DEFAULT_PORT, database_url, enable_login_rate_limit, name = 'ts_spine_bun' } = options;
     const paths = build_test_backend_paths(name);
     return {
         ...make_default_ts_backend_config({
@@ -113,8 +121,8 @@ export const ts_spine_bun_backend_config = (options = {}) => {
             start_command: ['bun', 'run', TS_SPINE_BUN_ENTRY],
             database_url,
             paths,
+            daemon_token_dir_env: TS_SPINE_DIR_ENV,
             extra_env: {
-                [TS_SPINE_DIR_ENV]: paths.root,
                 ...login_rate_limit_env(enable_login_rate_limit),
                 ...action_rate_limit_env(options)
             },
@@ -135,8 +143,7 @@ export const ts_spine_bun_backend_config = (options = {}) => {
  * built package; this binary tests live source instead.)
  */
 export const ts_spine_deno_backend_config = (options = {}) => {
-    const { port = TS_SPINE_DENO_DEFAULT_PORT, database_url, enable_login_rate_limit } = options;
-    const name = 'ts_spine_deno';
+    const { port = TS_SPINE_DENO_DEFAULT_PORT, database_url, enable_login_rate_limit, name = 'ts_spine_deno' } = options;
     const paths = build_test_backend_paths(name);
     return {
         ...make_default_ts_backend_config({
@@ -158,8 +165,8 @@ export const ts_spine_deno_backend_config = (options = {}) => {
             ],
             database_url,
             paths,
+            daemon_token_dir_env: TS_SPINE_DIR_ENV,
             extra_env: {
-                [TS_SPINE_DIR_ENV]: paths.root,
                 ...login_rate_limit_env(enable_login_rate_limit),
                 ...action_rate_limit_env(options)
             },

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

@@ -1,13 +1,10 @@
 import '../assert_dev_env.js';
 import type { SetupTest } from './setup.js';
+import { type WsEndpointTarget } from './ws_endpoint.js';
 /** Options for `describe_ws_action_rate_limit_cross_tests`. */
-export interface WsActionRateLimitCrossTestOptions {
+export interface WsActionRateLimitCrossTestOptions extends WsEndpointTarget {
     /** Per-test fixture producer (cross-process only — see the module doc). */
     readonly setup_test: SetupTest;
-    /** Base URL the backend is reachable at (e.g. `http://localhost:1177`). */
-    readonly base_url: string;
-    /** WebSocket endpoint path (e.g. `/api/ws`). */
-    readonly ws_path: string;
     /** JSON-RPC endpoint path. Default `/api/rpc` (the spine convention). */
     readonly rpc_path?: string;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"ws_action_rate_limit.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_action_rate_limit.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAkE9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgD5C,+DAA+D;AAC/D,MAAM,WAAW,iCAAiC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAkBD;;;;GAIG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,iCAAiC,KACxC,IAwSF,CAAC"}
+{"version":3,"file":"ws_action_rate_limit.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_action_rate_limit.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAiE9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAgD1E,+DAA+D;AAC/D,MAAM,WAAW,iCAAkC,SAAQ,gBAAgB;IAC1E,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC9B;AAkBD;;;;GAIG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,iCAAiC,KACxC,IAkSF,CAAC"}

package/dist/testing/cross_backend/ws_action_rate_limit.js

@@ -54,8 +54,9 @@ import '../assert_dev_env.js';
  */
 import { assert, describe, test } from 'vitest';
 import { create_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
-import { create_ws_transport } from '../transports/ws_transport.js';
 import { is_response_for } from '../transports/ws_client.js';
+import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { open_session_ws } from './ws_endpoint.js';
 // Wire literals are deliberate independent copies of the producers'
 // constants (`JSONRPC_ERROR_CODES` on TS, the `JsonrpcError` taxonomy on
 // Rust) — parity by test, so a renamed or renumbered code fails here.
@@ -106,8 +107,8 @@ const outcome_from_frame = (status, frame) => ({
  * across both transports, and the account axis at the RPC and WS dispatchers.
  */
 export const describe_ws_action_rate_limit_cross_tests = (options) => {
-    const { setup_test, base_url, ws_path, max_attempts } = options;
-    const rpc_path = options.rpc_path ?? '/api/rpc';
+    const { setup_test, max_attempts } = options;
+    const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
     assert(Number.isInteger(max_attempts) && max_attempts >= 2, 'ws_action_rate_limit needs max_attempts >= 2 to split a budget across transports');
     let next_id = 1;
     /** POST one JSON-RPC call on a fresh (cookie-jar-free) transport. */
@@ -128,17 +129,10 @@ export const describe_ws_action_rate_limit_cross_tests = (options) => {
         return outcome_from_frame(null, frame);
     };
     /** Open a socket on the keeper's session, optionally behind a forwarded IP. */
-    const open_ws = (fixture, forwarded_for) => {
-        const cookie = fixture.create_session_headers().cookie;
-        assert.ok(cookie, 'expected a session cookie for the WS upgrade');
-        return create_ws_transport({
-            base_url,
-            ws_path,
-            cookies: [cookie],
-            origin: base_url,
-            headers: forwarded_for ? { 'x-forwarded-for': forwarded_for } : undefined
-        });
-    };
+    const open_ws = (fixture, forwarded_for) => open_session_ws(options, fixture, {
+        admitted: false,
+        headers: forwarded_for ? { 'x-forwarded-for': forwarded_for } : undefined
+    });
     const assert_charged_not_limited = (outcome, label) => {
         assert.strictEqual(outcome.code, CODE_INVALID_PARAMS, `${label}: expected invalid_params (charged, under the cap), got ${JSON.stringify(outcome)}`);
         if (outcome.status !== null)

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

@@ -1,22 +1,17 @@
 import '../assert_dev_env.js';
 import { type BackendCapabilities } from './capabilities.js';
 import type { SetupTest } from './setup.js';
+import { type WsEndpointTarget } from './ws_endpoint.js';
 /** Options for the WebSocket connection-cap parity suite. */
-export interface WsConnectionCapCrossTestOptions {
+export interface WsConnectionCapCrossTestOptions extends WsEndpointTarget {
     /**
      * 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.
+     * socket in a case upgrades on the fresh-per-test keeper's session
+     * cookie, 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

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

@@ -1 +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;AAmD9B,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"}
+{"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;AAkD9B,OAAO,EAAE,KAAK,mBAAmB,EAAW,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AACzD,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAK1E,6DAA6D;AAC7D,MAAM,WAAW,+BAAgC,SAAQ,gBAAgB;IACxE;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC,GAClD,SAAS,+BAA+B,KACtC,IA2GF,CAAC"}

package/dist/testing/cross_backend/ws_connection_cap.js

@@ -44,8 +44,8 @@ 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';
+import { open_session_ws } from './ws_endpoint.js';
 /** The close reason both spines send with `WS_CLOSE_CONNECTION_LIMIT`. */
 const CONNECTION_LIMIT_REASON = 'connection limit';
 /**
@@ -55,7 +55,7 @@ const CONNECTION_LIMIT_REASON = 'connection limit';
  * frees its slot.
  */
 export const describe_ws_connection_cap_cross_tests = (options) => {
-    const { setup_test, capabilities, base_url, ws_path, origin } = options;
+    const { setup_test, capabilities } = options;
     const max = options.max_connections_per_account === undefined
         ? DEFAULT_MAX_CONNECTIONS_PER_ACCOUNT
         : options.max_connections_per_account;
@@ -64,7 +64,7 @@ export const describe_ws_connection_cap_cross_tests = (options) => {
      * 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 open_registered = (fixture) => open_session_ws(options, fixture, { admitted: true });
     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`);
@@ -78,27 +78,27 @@ export const describe_ws_connection_cap_cross_tests = (options) => {
         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 }, () => {
+    // time scales with the cap and the backend's upgrade cost — inside the 30 s
+    // budget `make_cross_backend_project` gives every case
+    describe('per-account websocket connection cap parity', () => {
         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));
+                    sockets.push(await open_registered(fixture));
                 }
                 // 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));
+                sockets.push(await open_registered(fixture));
                 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));
+                sockets.push(await open_registered(fixture));
                 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');
             }
@@ -108,14 +108,13 @@ export const describe_ws_connection_cap_cross_tests = (options) => {
         });
         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);
+            const held = await open_registered(fixture);
             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);
+                    const client = await open_registered(fixture);
                     await client.close();
                 }
                 await assert_all_answer([held], 'held', 'closed connections must not count toward the cap — the held socket was evicted');

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

@@ -0,0 +1,52 @@
+import '../assert_dev_env.js';
+import { type WsTransportOptions } from '../transports/ws_transport.js';
+import type { WsClient } from '../transports/ws_client.js';
+/** Where a backend's WebSocket endpoint is. */
+export interface WsEndpointTarget {
+    /** 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 a browser-context upgrade. Defaults to `base_url`. */
+    readonly origin?: string;
+}
+/** An account a session socket opens as — a fixture or a minted account. */
+export interface WsSessionAccount {
+    /** Build request headers carrying the account's session cookie. */
+    readonly create_session_headers: (extra?: Record<string, string>) => Record<string, string>;
+}
+/** Options for `open_session_ws`. */
+export interface OpenSessionWsOptions extends Pick<WsTransportOptions, 'default_timeout_ms' | 'on_request' | 'headers'> {
+    /**
+     * Round-trip `heartbeat` before resolving, so the backend has admitted the
+     * connection (`create_admitted_ws_transport`) — needed by a case that waits
+     * for a push or relies on registration order. `false` resolves once the
+     * socket is open (`create_ws_transport`), for a case that only round-trips
+     * or counts its own requests.
+     */
+    readonly admitted: boolean;
+}
+/**
+ * The account's session cookie (`<name>=<value>`), asserted present.
+ *
+ * @param account - the account whose session headers carry the cookie
+ * @returns the `Cookie` header value
+ */
+export declare const to_session_cookie: (account: WsSessionAccount) => string;
+/**
+ * Open a real-upgrade socket on `target` as `account`'s session: its session
+ * cookie on the upgrade, `target.origin` (or `base_url`) as the `Origin`.
+ *
+ * The cookie is the static one `account.create_session_headers` carries, not
+ * whatever `fixture.transport`'s jar holds now, so a case that rotates the
+ * session through `fixture.transport` first upgrades on the stale cookie.
+ *
+ * @param target - the backend's WebSocket endpoint
+ * @param account - the account whose session the socket upgrades on
+ * @param options - whether to wait for admission, plus transport extras
+ * @returns the open socket
+ * @throws Error if the account carries no session cookie, or the upgrade (or
+ *   the admission heartbeat) fails
+ */
+export declare const open_session_ws: (target: WsEndpointTarget, account: WsSessionAccount, options: OpenSessionWsOptions) => Promise<WsClient>;
+//# sourceMappingURL=ws_endpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmB9B,OAAO,EAGN,KAAK,kBAAkB,EACvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,sBAAsB,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5F;AAED,qCAAqC;AACrC,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CACjD,kBAAkB,EAClB,oBAAoB,GAAG,YAAY,GAAG,SAAS,CAC/C;IACA;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,gBAAgB,KAAG,MAI7D,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAC3B,QAAQ,gBAAgB,EACxB,SAAS,gBAAgB,EACzB,SAAS,oBAAoB,KAC3B,OAAO,CAAC,QAAQ,CAUlB,CAAC"}