@fuzdev/fuz_app 0.12.0 → 0.13.0

package/dist/testing/round_trip.js

@@ -12,10 +12,11 @@ import { describe, test, beforeAll, afterAll } from 'vitest';
 import { ROLE_ADMIN } from '../auth/role_schema.js';
 import { create_test_app } from './app_server.js';
 import { create_pglite_factory } from './db.js';
-import { assert_response_matches_spec } from './integration_helpers.js';
+import { assert_response_matches_spec, pick_auth_headers } from './integration_helpers.js';
 import { resolve_valid_path, generate_valid_body } from './schema_generators.js';
 import { run_migrations } from '../db/migrate.js';
 import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+import { create_stub_app_server_context } from './stubs.js';
 /**
  * Run schema-driven round-trip validation tests.
  *
@@ -37,6 +38,12 @@ export const describe_round_trip_validation = (options) => {
         await run_migrations(db, [AUTH_MIGRATION_NS]);
     };
     const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    // Pre-compute route specs at describe time so test.each can register one
+    // test per route. Mirrors create_test_app's route set (consumer routes
+    // only — bootstrap routes are not added unless `bootstrap` is configured
+    // on AppServerOptions, which create_test_app doesn't do).
+    const stub_ctx = create_stub_app_server_context(options.session_options);
+    const describe_time_specs = options.create_route_specs(stub_ctx);
     for (const factory of factories) {
         const describe_fn = factory.skip ? describe.skip : describe;
         describe_fn(`round-trip validation (${factory.name})`, () => {
@@ -66,62 +73,41 @@ export const describe_round_trip_validation = (options) => {
                 await test_app.cleanup();
                 await factory.close(db);
             });
-            test('all routes produce schema-valid responses', async () => {
-                for (const spec of test_app.route_specs) {
-                    const route_key = `${spec.method} ${spec.path}`;
-                    if (skip_set.has(route_key))
-                        continue;
-                    // Resolve URL with valid param values
-                    const url = resolve_valid_path(spec.path, spec.params);
-                    // Generate or override request body
-                    const override = options.input_overrides?.get(route_key);
-                    const body = override ?? generate_valid_body(spec.input);
-                    // Pick auth headers based on route auth requirement
-                    const headers = pick_auth_headers(spec, test_app, authed_account, admin_account);
-                    // Fire request
-                    const request_init = {
-                        method: spec.method,
-                        headers: {
-                            ...headers,
-                            ...(body ? { 'content-type': 'application/json' } : {}),
-                        },
-                        ...(body ? { body: JSON.stringify(body) } : {}),
-                    };
-                    const res = await test_app.app.request(url, request_init); // eslint-disable-line no-await-in-loop
-                    // Skip SSE responses — streaming bodies can't be parsed as JSON
-                    if (res.headers.get('Content-Type')?.includes('text/event-stream')) {
-                        await res.body?.cancel(); // eslint-disable-line no-await-in-loop
-                        continue;
-                    }
-                    // Validate response against declared schemas
-                    try {
-                        await assert_response_matches_spec(test_app.route_specs, spec.method, url, res); // eslint-disable-line no-await-in-loop
-                    }
-                    catch (e) {
-                        // Re-throw with route context for easier debugging
-                        throw new Error(`Round-trip validation failed for ${route_key} (status ${res.status}): ${e.message}`);
-                    }
+            test.each(describe_time_specs)('$method $path produces schema-valid response', async (spec) => {
+                const route_key = `${spec.method} ${spec.path}`;
+                if (skip_set.has(route_key))
+                    return;
+                // Resolve URL with valid param values
+                const url = resolve_valid_path(spec.path, spec.params);
+                // Generate or override request body
+                const override = options.input_overrides?.get(route_key);
+                const body = override ?? generate_valid_body(spec.input);
+                // Pick auth headers based on route auth requirement
+                const headers = pick_auth_headers(spec, test_app, authed_account, admin_account);
+                // Fire request
+                const request_init = {
+                    method: spec.method,
+                    headers: {
+                        ...headers,
+                        ...(body ? { 'content-type': 'application/json' } : {}),
+                    },
+                    ...(body ? { body: JSON.stringify(body) } : {}),
+                };
+                const res = await test_app.app.request(url, request_init);
+                // Skip SSE responses — streaming bodies can't be parsed as JSON
+                if (res.headers.get('Content-Type')?.includes('text/event-stream')) {
+                    await res.body?.cancel();
+                    return;
+                }
+                // Validate response against declared schemas
+                try {
+                    await assert_response_matches_spec(test_app.route_specs, spec.method, url, res);
+                }
+                catch (e) {
+                    // Re-throw with route context for easier debugging
+                    throw new Error(`Round-trip validation failed for ${route_key} (status ${res.status}): ${e.message}`);
                 }
             });
         });
     }
 };
-/**
- * Pick auth headers matching a route spec's auth requirement.
- */
-const pick_auth_headers = (spec, test_app, authed_account, admin_account) => {
-    switch (spec.auth.type) {
-        case 'none':
-            return { host: 'localhost', origin: 'http://localhost:5173' };
-        case 'authenticated':
-            return authed_account.create_session_headers();
-        case 'role':
-            if (spec.auth.role === ROLE_ADMIN) {
-                return admin_account.create_session_headers();
-            }
-            // Keeper role uses the bootstrapped account (which has keeper role)
-            return test_app.create_session_headers();
-        case 'keeper':
-            return test_app.create_daemon_token_headers();
-    }
-};

package/dist/testing/sse_round_trip.d.ts

@@ -0,0 +1,64 @@
+import './assert_dev_env.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import { type EventSpec } from '../realtime/sse.js';
+import type { AuditLogEvent } from '../auth/audit_log_schema.js';
+import { type TestApp, type TestAccount } from './app_server.js';
+import { type DbFactory } from './db.js';
+/** Config for a single SSE route under test. */
+export interface SseRouteTestSpec {
+    /** Full HTTP path of the SSE endpoint (e.g., `'/api/tx/subscribe'`). */
+    path: string;
+    /**
+     * Fire an event matching one of the declared `event_specs` that should
+     * reach the open stream. Called after the `: connected` comment is observed.
+     * The triggered frame must be a JSON-serializable `{method, params}` payload.
+     */
+    trigger: (ctx: {
+        test_app: TestApp;
+        account: TestAccount;
+    }) => Promise<void>;
+    /**
+     * Event specs to validate the triggered payload against. When omitted,
+     * the payload is only asserted to be well-formed `{method, params}`.
+     */
+    event_specs?: Array<EventSpec>;
+    /**
+     * Whether to assert the stream closes after `session_revoke_all`.
+     * Default `true`. Set `false` for endpoints that don't wire a close-on-revoke
+     * guard (leaves a TODO to fix, rather than silently passing).
+     */
+    assert_closes_on_revoke?: boolean;
+}
+/** Options for `describe_sse_route_tests`. */
+export interface SseRouteTestOptions {
+    /** Session config for cookie-based auth. */
+    session_options: SessionOptions<string>;
+    /** Route spec factory — same shape as production. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** Optional overrides for `AppServerOptions`. */
+    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
+    /** Database factories to run tests against. Default: pglite only. */
+    db_factories?: Array<DbFactory>;
+    /**
+     * Backend audit event callback — threaded to `create_test_app_server`.
+     * Use to wire a close-on-revoke guard for consumer SSE registries
+     * (e.g., via `create_sse_auth_guard`) so `session_revoke_all` actually
+     * closes the tested streams.
+     */
+    on_audit_event?: (event: AuditLogEvent) => void;
+    /** SSE routes to exercise. */
+    routes: Array<SseRouteTestSpec>;
+}
+/**
+ * Run SSE route validation tests.
+ *
+ * For each route: opens an authenticated SSE connection, asserts the
+ * connected comment, fires the trigger, validates the resulting payload,
+ * then asserts close-on-revoke (unless opted out).
+ *
+ * @param options - SSE test configuration
+ */
+export declare const describe_sse_route_tests: (options: SseRouteTestOptions) => void;
+//# sourceMappingURL=sse_round_trip.d.ts.map

package/dist/testing/sse_round_trip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/sse_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAmB7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAwB,KAAK,SAAS,EAAuB,MAAM,oBAAoB,CAAC;AAE/F,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAkB,KAAK,OAAO,EAAE,KAAK,WAAW,EAAC,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,SAAS,CAAC;AAM9D,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAChC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/B;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,qDAAqD;IACrD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAChD,8BAA8B;IAC9B,MAAM,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;CAChC;AA0HD;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,mBAAmB,KAAG,IA4GvE,CAAC"}

package/dist/testing/sse_round_trip.js

@@ -0,0 +1,241 @@
+import './assert_dev_env.js';
+/**
+ * Schema-driven SSE route validation test suite.
+ *
+ * Complements `describe_round_trip_validation` (which skips SSE routes).
+ * For each configured SSE route:
+ * 1. Open the stream with matching auth.
+ * 2. Assert the `: connected` comment is emitted.
+ * 3. Fire `trigger()` — expect one `data: {...}` frame.
+ * 4. Validate the payload as `{method, params}` against declared `EventSpec`s.
+ * 5. Fire `session_revoke_all` for the account and assert the stream closes
+ *    (when `assert_closes_on_revoke !== false`).
+ *
+ * @module
+ */
+import { describe, test, beforeAll, afterAll, assert } from 'vitest';
+import { SSE_CONNECTED_COMMENT } from '../realtime/sse.js';
+import { ROLE_ADMIN } from '../auth/role_schema.js';
+import { create_test_app } from './app_server.js';
+import { create_pglite_factory } from './db.js';
+import { find_route_spec, pick_auth_headers } from './integration_helpers.js';
+import { run_migrations } from '../db/migrate.js';
+import { AUTH_MIGRATION_NS } from '../auth/migrations.js';
+/**
+ * Read one complete SSE frame (up to `\n\n`) from a stream reader.
+ *
+ * Returns the frame without the trailing `\n\n`. Throws on premature close.
+ * Preserves any bytes past the terminator in the shared buffer for the next call.
+ */
+const create_sse_frame_reader = (reader) => {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let closed = false;
+    const pump_once = async (timeout_ms) => {
+        // Race the read against a timeout — vitest will otherwise hang on a misbehaving stream.
+        const timeout = new Promise((resolve) => {
+            setTimeout(() => resolve({ done: true, value: undefined, timed_out: true }), timeout_ms);
+        });
+        const result = (await Promise.race([reader.read(), timeout]));
+        if ('timed_out' in result) {
+            throw new Error(`SSE read timed out after ${timeout_ms}ms`);
+        }
+        if (result.done) {
+            closed = true;
+            return false;
+        }
+        buffer += decoder.decode(result.value, { stream: true });
+        return true;
+    };
+    return {
+        read_frame: async (timeout_ms = 2000) => {
+            // SSE frames end with a blank line — the canonical terminator is `\n\n`.
+            while (true) {
+                const idx = buffer.indexOf('\n\n');
+                if (idx >= 0) {
+                    const frame = buffer.slice(0, idx);
+                    buffer = buffer.slice(idx + 2);
+                    return frame;
+                }
+                const cont = await pump_once(timeout_ms); // eslint-disable-line no-await-in-loop
+                if (!cont)
+                    throw new Error('SSE stream ended before a frame was received');
+            }
+        },
+        wait_for_close: async (timeout_ms) => {
+            // Drain until the server closes the stream (pump_once returns false) or timeout expires.
+            const deadline = Date.now() + timeout_ms;
+            for (;;) {
+                if (closed)
+                    return true;
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    return false;
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    await pump_once(Math.min(remaining, timeout_ms));
+                }
+                catch {
+                    return false;
+                }
+            }
+        },
+        cancel: async () => {
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // already closed
+            }
+        },
+    };
+};
+/**
+ * Validate a decoded SSE `data:` frame as a JSON-RPC-style `{method, params}` payload.
+ */
+const parse_and_validate_sse_payload = (frame, event_specs, route_path) => {
+    const data_line = frame.split('\n').find((line) => line.startsWith('data: '));
+    assert.ok(data_line, `${route_path}: no 'data:' line in frame: ${JSON.stringify(frame)}`);
+    const json_str = data_line.slice('data: '.length);
+    let payload;
+    try {
+        payload = JSON.parse(json_str);
+    }
+    catch (e) {
+        throw new Error(`${route_path}: data frame not JSON: ${e.message} — ${json_str}`);
+    }
+    assert.ok(payload && typeof payload === 'object', `${route_path}: payload must be an object, got ${typeof payload}`);
+    const notification = payload;
+    assert.strictEqual(typeof notification.method, 'string', `${route_path}: payload.method must be a string`);
+    assert.ok('params' in notification, `${route_path}: payload missing 'params'`);
+    if (event_specs) {
+        const spec = event_specs.find((s) => s.method === notification.method);
+        assert.ok(spec, `${route_path}: no EventSpec declared for method '${notification.method}' (declared: ${event_specs.map((s) => s.method).join(', ')})`);
+        const result = spec.params.safeParse(notification.params);
+        if (!result.success) {
+            throw new Error(`${route_path}: params mismatch for method '${notification.method}': ${JSON.stringify(result.error.issues)}`);
+        }
+    }
+    return notification;
+};
+/**
+ * Run SSE route validation tests.
+ *
+ * For each route: opens an authenticated SSE connection, asserts the
+ * connected comment, fires the trigger, validates the resulting payload,
+ * then asserts close-on-revoke (unless opted out).
+ *
+ * @param options - SSE test configuration
+ */
+export const describe_sse_route_tests = (options) => {
+    const init_schema = async (db) => {
+        await run_migrations(db, [AUTH_MIGRATION_NS]);
+    };
+    const factories = options.db_factories ?? [create_pglite_factory(init_schema)];
+    for (const factory of factories) {
+        const describe_fn = factory.skip ? describe.skip : describe;
+        describe_fn(`SSE validation (${factory.name})`, () => {
+            for (const route_config of options.routes) {
+                describe(`GET ${route_config.path}`, () => {
+                    let test_app;
+                    let authed_account;
+                    let admin_account;
+                    let account;
+                    let db;
+                    beforeAll(async () => {
+                        db = await factory.create();
+                        test_app = await create_test_app({
+                            session_options: options.session_options,
+                            create_route_specs: options.create_route_specs,
+                            db,
+                            app_options: options.app_options,
+                            on_audit_event: options.on_audit_event,
+                        });
+                        authed_account = await test_app.create_account({
+                            username: 'sse_authed',
+                            roles: [],
+                        });
+                        admin_account = await test_app.create_account({
+                            username: 'sse_admin',
+                            roles: [ROLE_ADMIN],
+                        });
+                    });
+                    afterAll(async () => {
+                        await test_app.cleanup();
+                        await factory.close(db);
+                    });
+                    test('opens, emits payload, closes on revoke', async () => {
+                        const spec = find_route_spec(test_app.route_specs, 'GET', route_config.path);
+                        assert.ok(spec, `no route spec for GET ${route_config.path}`);
+                        account = pick_account_for_auth(spec, test_app, authed_account, admin_account);
+                        const headers = pick_auth_headers(spec, test_app, authed_account, admin_account);
+                        const res = await test_app.app.request(route_config.path, {
+                            method: 'GET',
+                            headers,
+                        });
+                        assert.strictEqual(res.status, 200, `expected 200 for ${route_config.path}, got ${res.status}`);
+                        assert.ok(res.headers.get('Content-Type')?.includes('text/event-stream'), `${route_config.path}: Content-Type must be text/event-stream`);
+                        assert.ok(res.body, `${route_config.path}: response has no body`);
+                        const reader = res.body.getReader();
+                        const sse = create_sse_frame_reader(reader);
+                        try {
+                            // 1. Connected comment — matches SSE_CONNECTED_COMMENT minus the trailing \n\n.
+                            const first = await sse.read_frame();
+                            assert.strictEqual(first + '\n\n', SSE_CONNECTED_COMMENT, `${route_config.path}: first frame must be the connected comment`);
+                            // 2. Trigger → first data frame.
+                            await route_config.trigger({ test_app, account });
+                            const data_frame = await sse.read_frame();
+                            parse_and_validate_sse_payload(data_frame, route_config.event_specs, route_config.path);
+                            // 3. Close-on-revoke.
+                            if (route_config.assert_closes_on_revoke !== false) {
+                                const revoke_res = await test_app.app.request('/api/account/sessions/revoke-all', {
+                                    method: 'POST',
+                                    headers: account.create_session_headers(),
+                                });
+                                assert.ok(revoke_res.ok, `session_revoke_all returned ${revoke_res.status} — cannot assert stream closure`);
+                                const closed = await sse.wait_for_close(2000);
+                                assert.ok(closed, `${route_config.path}: stream did not close within 2s after session_revoke_all`);
+                            }
+                        }
+                        finally {
+                            await sse.cancel();
+                        }
+                    });
+                });
+            }
+        });
+    }
+};
+/**
+ * Pick the TestAccount that matches the route's auth type.
+ *
+ * Needed so the test can revoke the right account's sessions. Mirrors the
+ * fallthrough order of `pick_auth_headers` — routes with `role: admin` get
+ * the admin account; `authenticated` gets the authed account; stricter auth
+ * (keeper, other roles) uses the bootstrapped keeper account.
+ */
+const pick_account_for_auth = (spec, test_app, authed_account, admin_account) => {
+    switch (spec.auth.type) {
+        case 'authenticated':
+            return authed_account;
+        case 'role':
+            if (spec.auth.role === ROLE_ADMIN)
+                return admin_account;
+            // keeper role — bootstrapped account is the keeper; model it as a TestAccount
+            return bootstrap_as_account(test_app);
+        case 'keeper':
+        case 'none':
+            return bootstrap_as_account(test_app);
+    }
+};
+/**
+ * Treat the bootstrapped `TestApp` account as a `TestAccount` for revocation.
+ */
+const bootstrap_as_account = (test_app) => ({
+    account: test_app.backend.account,
+    actor: test_app.backend.actor,
+    session_cookie: test_app.backend.session_cookie,
+    api_token: test_app.backend.api_token,
+    create_session_headers: test_app.create_session_headers,
+    create_bearer_headers: test_app.create_bearer_headers,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",