@fuzdev/fuz_app 0.147.0 → 0.149.0

package/dist/testing/cross_backend/setup.js

@@ -28,18 +28,22 @@ import { DEFAULT_TEST_PASSWORD } from '../test_credentials.js';
 import { create_fetch_transport } from '../transports/fetch_transport.js';
 import { MigrationTracker } from '../schema_introspect.js';
 import { ActionManifest } from './action_manifest.js';
+import { SPINE_ACCOUNT_LOGIN_PATH, SPINE_ACCOUNT_SIGNUP_PATH } from './spine_surface_constants.js';
 /**
- * Build an `ExtraAccountFixture` from a seeded `{account, actor,
- * api_token, session_cookie}` bundle and the session cookie name.
+ * Build a `TestAccount` from a seeded `{account, actor, api_token,
+ * session_cookie}` bundle and the session cookie name — the header builders
+ * close over its credentials.
  *
- * Same shape produced by either path that seeds bootstrap-time
- * secondaries: in-process via `create_test_account_with_credentials`
- * against the live backend's DB, or cross-process via the
- * `_testing_reset` RPC's `extra_accounts` output. Both call this
- * helper so the fixture-side header builders + field plumbing stays
- * in one place.
+ * Every fixture path that hands out a secondary account builds it here: the
+ * bootstrap-time `extra_accounts` (in-process via
+ * `create_test_account_with_credentials`, cross-process from the
+ * `_testing_reset` output) and the cross-process `fixture.create_account`.
+ *
+ * @param seeded - the account's identity and credentials
+ * @param cookie_name - the backend's session cookie name
+ * @returns the account with its header builders
  */
-export const build_extra_account_fixture = (seeded, cookie_name) => ({
+export const to_test_account = (seeded, cookie_name) => ({
     account: seeded.account,
     actor: seeded.actor,
     api_token: seeded.api_token,
@@ -326,8 +330,10 @@ const mint_account = async (handle, options) => {
     // it. The keeper holds `ROLE_ADMIN` from bootstrap (see
     // `bootstrap_account.ts` — both `ROLE_KEEPER` and `ROLE_ADMIN` grants
     // are created in the bootstrap transaction), so `invite_create` (admin-
-    // only) authorizes without any extra grants.
-    const invite_result = (await rpc_via_transport(handle.keeper_transport, handle.config.rpc_path, 'invite_create', { username }, handle.config.name));
+    // only) authorizes without any extra grants. It acts as the keeper's
+    // bootstrap actor, the one holding those grants, so a keeper seeded with
+    // `extra_actors` resolves it too rather than answering `actor_required`.
+    const invite_result = (await rpc_via_transport(handle.keeper_transport, handle.config.rpc_path, 'invite_create', { username, acting: handle.keeper_actor.id }, handle.config.name));
     if (!invite_result?.invite?.id) {
         throw new Error(`invite_create(${handle.config.name}, username=${username}) returned unexpected result: ` +
             JSON.stringify(invite_result));
@@ -340,7 +346,7 @@ const mint_account = async (handle, options) => {
     // `app_server.ts`): "requested" is `undefined` vs present, so a
     // caller-supplied value is forwarded verbatim and signup validates it,
     // rather than the truthy form silently dropping an empty string.
-    const signup_response = await transport('/api/account/signup', {
+    const signup_response = await transport(options.signup_path, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -358,7 +364,7 @@ const mint_account = async (handle, options) => {
     if (!parsed.success) {
         throw new Error(`signup(${handle.config.name}) returned unexpected body: ${JSON.stringify(signup_raw)} (${parsed.error.message})`);
     }
-    const login_response = await transport('/api/account/login', {
+    const login_response = await transport(options.login_path, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ username, password })
@@ -401,7 +407,9 @@ const mint_account = async (handle, options) => {
  */
 const grant_roles_via_offer_accept = async (handle, minted, roles) => {
     for (const role of roles) {
-        const offer_result = (await rpc_via_transport(handle.keeper_transport, handle.config.rpc_path, 'role_grant_offer_create', { to_account_id: minted.account.id, role }, `${handle.config.name}, role=${role}`));
+        const offer_result = (await rpc_via_transport(handle.keeper_transport, handle.config.rpc_path, 'role_grant_offer_create', 
+        // as the keeper's bootstrap actor, like `mint_account`'s invite
+        { to_account_id: minted.account.id, role, acting: handle.keeper_actor.id }, `${handle.config.name}, role=${role}`));
         if (!offer_result?.offer?.id) {
             throw new Error(`role_grant_offer_create(${handle.config.name}, role=${role}) returned unexpected result: ` + JSON.stringify(offer_result));
         }
@@ -461,6 +469,8 @@ export const default_cross_process_setup = (handle, options) => {
     const extra_keeper_roles = options?.extra_keeper_roles ?? [];
     const extra_account_specs = options?.extra_accounts ?? [];
     const extra_actor_names = options?.extra_actors ?? [];
+    const signup_path = options?.signup_path ?? SPINE_ACCOUNT_SIGNUP_PATH;
+    const login_path = options?.login_path ?? SPINE_ACCOUNT_LOGIN_PATH;
     const { cookie_name } = handle.config;
     return async () => {
         const { keeper, extra_accounts: seeded_extras, extra_actors } = await fire_testing_reset(handle, {
@@ -501,6 +511,8 @@ export const default_cross_process_setup = (handle, options) => {
         });
         const create_account = async (account_options) => {
             const other = await mint_account(refreshed_handle, {
+                signup_path,
+                login_path,
                 ...(account_options?.username !== undefined && { username: account_options.username }),
                 ...(account_options?.password_value !== undefined && {
                     password_value: account_options.password_value
@@ -510,20 +522,7 @@ export const default_cross_process_setup = (handle, options) => {
             if (account_options?.roles && account_options.roles.length > 0) {
                 await grant_roles_via_offer_accept(refreshed_handle, other, account_options.roles);
             }
-            return {
-                account: other.account,
-                actor: other.actor,
-                session_cookie: other.session_cookie,
-                api_token: other.api_token,
-                create_session_headers: (extra) => ({
-                    cookie: `${cookie_name}=${other.session_cookie}`,
-                    ...extra
-                }),
-                create_bearer_headers: (extra) => ({
-                    authorization: `Bearer ${other.api_token}`,
-                    ...extra
-                })
-            };
+            return to_test_account(other, cookie_name);
         };
         const extra_accounts = {};
         for (let i = 0; i < extra_account_specs.length; i++) {
@@ -531,7 +530,7 @@ export const default_cross_process_setup = (handle, options) => {
             const seeded = seeded_extras[i];
             if (!spec || !seeded)
                 continue;
-            extra_accounts[spec.username] = build_extra_account_fixture(seeded, cookie_name);
+            extra_accounts[spec.username] = to_test_account(seeded, cookie_name);
         }
         // Per-test transport — fresh jar carrying the new keeper's cookie
         // so requests authenticate as the keeper without callers having to
@@ -556,6 +555,7 @@ export const default_cross_process_setup = (handle, options) => {
             create_account,
             extra_accounts,
             extra_actors,
+            reject_unknown_audit_metadata_keys: options?.reject_unknown_audit_metadata_keys ?? false,
             // Forge over the wire — the cross-process driver has no keyring,
             // so `_testing_mint_session` mints the backdated row + signs the
             // cookie server-side over the keeper's daemon-token channel.

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

@@ -1 +1 @@
-{"version":3,"file":"simple_request.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/simple_request.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6B9B,OAAO,KAAK,EAAE,wBAAwB,EAAe,MAAM,YAAY,CAAC;AAGxE,mDAAmD;AACnD,MAAM,WAAW,6BAA8B,SAAQ,wBAAwB;IAC9E,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAaD,eAAO,MAAM,mCAAmC,GAC/C,SAAS,6BAA6B,KACpC,IAuHF,CAAC"}
+{"version":3,"file":"simple_request.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/simple_request.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA6B9B,OAAO,KAAK,EAAE,wBAAwB,EAAe,MAAM,YAAY,CAAC;AAOxE,mDAAmD;AACnD,MAAM,WAAW,6BAA8B,SAAQ,wBAAwB;IAC9E,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAaD,eAAO,MAAM,mCAAmC,GAC/C,SAAS,6BAA6B,KACpC,IAuHF,CAAC"}

package/dist/testing/cross_backend/simple_request.js

@@ -16,7 +16,7 @@ import '../assert_dev_env.js';
  *
  * Runs both legs via the shared `setup_test` protocol: in-process
  * (`auth/simple_request_parity.db.test.ts`) and cross-process
- * (`cross_backend/simple_request.cross.test.ts`). Every spine has the gate,
+ * (`cross_backend/spine_suites.cross.test.ts`). Every spine has the gate,
  * so the suite is ungated.
  *
  * @module
@@ -24,7 +24,7 @@ import '../assert_dev_env.js';
 import { describe, test, assert } from 'vitest';
 import { account_verify_action_spec } from '../../auth/account_action_specs.js';
 import { ERROR_UNSUPPORTED_CONTENT_TYPE } from '../../http/error_schemas.js';
-import { SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { SPINE_ACCOUNT_LOGIN_PATH, SPINE_ACCOUNT_LOGOUT_PATH, SPINE_RPC_PATH } from './spine_surface_constants.js';
 /** Build the JSON-RPC envelope body for a nullary `account_verify` call. */
 const verify_envelope = (id) => JSON.stringify({ jsonrpc: '2.0', method: account_verify_action_spec.method, id });
 /** Assert a flat `415` content-type refusal. */
@@ -36,8 +36,8 @@ const assert_refused = async (res, label) => {
 export const describe_simple_request_cross_tests = (options) => {
     const { setup_test } = options;
     const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
-    const login_path = options.login_path ?? '/api/account/login';
-    const logout_path = options.logout_path ?? '/api/account/logout';
+    const login_path = options.login_path ?? SPINE_ACCOUNT_LOGIN_PATH;
+    const logout_path = options.logout_path ?? SPINE_ACCOUNT_LOGOUT_PATH;
     /** POST a JSON `account_verify` with the fixture's session — 200 while it's valid. */
     const verify_session = async (fixture, id) => {
         const res = await fixture.transport(rpc_path, {

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

@@ -5,18 +5,30 @@ import '../assert_dev_env.js';
  *
  * Lifecycle:
  *
- * 1. Write the bootstrap token (`config.bootstrap.token`) to
- *    `config.bootstrap.token_path` so the binary picks it up at startup.
- * 2. `child_process.spawn(...)` the binary with `detached: true` —
+ * 1. Refuse when `config.base_url`'s port already accepts a TCP connection —
+ *    another cross run or a stale backend holds it, and the health probe
+ *    would otherwise drive that process instead of the one spawned here.
+ * 2. Write the bootstrap token (`config.bootstrap.token`) to
+ *    `config.bootstrap.token_path` so the binary picks it up at startup, and
+ *    delete any `config.bootstrap.daemon_token_path` a previous run left, so
+ *    step 5 can only read the token this binary writes.
+ * 3. `child_process.spawn(...)` the binary with `detached: true` —
  *    creates a new process group so a `SIGTERM` to the negative PID
  *    tears down any descendants the binary spawned (PTYs, child
- *    workers). vitest worker death + Ctrl+C handlers also fire the
- *    group teardown so ports never strand.
- * 3. Poll `{base_url}{health_path}` until it returns 2xx or
- *    `startup_timeout_ms` elapses.
- * 4. Read `config.bootstrap.daemon_token_path` to load the binary's
+ *    workers). vitest worker death + `SIGINT` / `SIGTERM` / `SIGHUP`
+ *    handlers also fire the group teardown so ports never strand.
+ * 4. Poll `{base_url}{health_path}` until it returns 2xx or
+ *    `startup_timeout_ms` elapses — each probe bounded by its own timeout, so
+ *    a listener that accepts but never answers can't outlast the deadline.
+ * 5. Read `config.bootstrap.daemon_token_path` to load the binary's
  *    deterministic daemon token; thread it onto `BackendHandle` so
  *    `_testing_reset` and other keeper-credential calls can authenticate.
+ * 6. Log one line with the time from spawn to step 5 done, so a run shows
+ *    what each backend costs to bring up.
+ *
+ * The child's stderr is kept as a bounded tail (`STDERR_TAIL_MAX_BYTES`):
+ * a startup failure reports it with the exit code or signal, and an exit
+ * after startup that teardown didn't cause is logged with it.
  *
  * Bootstrapping (`POST /api/account/bootstrap`) is a separate concern —
  * the caller composes `bootstrap()` from `testing/transports/bootstrap.ts`
@@ -42,17 +54,54 @@ export interface BackendHandle {
      */
     readonly daemon_token: string;
     /**
-     * SIGTERM the child's process group, drain stderr, await exit. Idempotent —
-     * calls after the first are no-ops.
+     * SIGTERM the child's process group — even when the child itself has
+     * exited, so no descendant outlives it — and await the group's exit,
+     * escalating to SIGKILL after a grace window. Idempotent — later calls
+     * await the same exit. A descendant that left the group — spawned detached,
+     * or one that called `setsid` — is out of reach and survives teardown.
      */
     readonly teardown: () => Promise<void>;
 }
+/**
+ * How much of the child's stderr is kept (bytes) — the tail a startup failure
+ * or an unexpected exit reports. Bounded so a backend that logs to stderr for
+ * a whole suite doesn't grow the runner's memory with it.
+ */
+export declare const STDERR_TAIL_MAX_BYTES: number;
+/**
+ * Whether something accepts TCP connections at `base_url`'s host and port.
+ * A refused connection, an unresolvable host or no answer within
+ * `PORT_PROBE_TIMEOUT_MS` all read as free.
+ *
+ * @param base_url - an `http://` or `https://` URL; a missing port is the scheme's default
+ */
+export declare const is_port_accepting: (base_url: string) => Promise<boolean>;
+/**
+ * A byte-bounded tail of a stream's output: keeps the last `max_bytes`
+ * written, dropping the oldest.
+ */
+export interface OutputTail {
+    readonly push: (chunk: Buffer) => void;
+    /** The kept bytes as UTF-8, prefixed with a marker when older output was dropped. */
+    readonly text: () => string;
+}
+/**
+ * Create an `OutputTail` keeping at most `max_bytes`.
+ *
+ * @param max_bytes - how many trailing bytes to keep
+ */
+export declare const create_output_tail: (max_bytes: number) => OutputTail;
 /**
  * Spawn `config.start_command` and return a handle once the binary is
  * health-probe-ready and the daemon-token file is readable.
  *
  * Errors at any stage SIGTERM the child group before rethrowing — the
  * caller never sees a half-started backend.
+ *
+ * @throws Error when `config.base_url`'s port already accepts connections,
+ *   before anything is spawned; when the child exits before it is healthy
+ *   (with its exit code or signal and stderr tail); or when the health probe
+ *   or the daemon-token read times out
  */
 export declare const spawn_backend: (config: BackendConfig) => Promise<BackendHandle>;
 //# sourceMappingURL=spawn_backend.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"spawn_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spawn_backend.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AA4ID;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAU,QAAQ,aAAa,KAAG,OAAO,CAAC,aAAa,CAiHhF,CAAC"}
+{"version":3,"file":"spawn_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spawn_backend.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,6EAA6E;AAC7E,MAAM,WAAW,aAAa;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAgBD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAY,CAAC;AAmE/C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAenE,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,KAAG,UAmBtD,CAAC;AAuFF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAU,QAAQ,aAAa,KAAG,OAAO,CAAC,aAAa,CAoMhF,CAAC"}