@fuzdev/fuz_app 0.22.0 → 0.24.0

package/dist/testing/ws_round_trip.js

@@ -8,16 +8,25 @@
  * token id), and exposes a `connect()` factory returning a
  * `MockWsClient` per connection.
  *
- * Two layers are exported:
+ * Three layers are exported:
  *
  *   - **Primitives** (`create_fake_ws`, `create_fake_hono_context`,
- *     `create_stub_upgrade`, `MinimalActionEnvironment`) — used by
- *     fuz_app's own dispatcher tests and by consumers wiring tight
- *     one-off tests.
+ *     `create_stub_upgrade`, `MinimalActionEnvironment`,
+ *     `dispatch_ws_message`) — used by fuz_app's own dispatcher tests
+ *     and by consumers wiring tight one-off tests.
  *   - **Harness** (`create_ws_test_harness`, `MockWsClient`,
  *     `keeper_identity`) — the high-level driver. Give it specs +
- *     handlers, get back `{transport, connect()}`. Use this unless you
- *     need bare primitives.
+ *     handlers, get back `{transport, connect()}`. `connect()` is async
+ *     and resolves after `on_socket_open` completes, so broadcasts sent
+ *     immediately after `await harness.connect()` reach the client.
+ *   - **Round-trip helpers** — `is_notification` / `is_notification_with`
+ *     / `is_response_for` predicates, JSON-RPC wire-frame types
+ *     (`JsonrpcNotificationFrame`, `JsonrpcSuccessResponseFrame`,
+ *     `JsonrpcErrorResponseFrame` — distinct from the runtime Zod types
+ *     in `http/jsonrpc.ts` so tests can narrow `params` / `result`),
+ *     and `build_broadcast_api` for wiring a typed broadcast API against
+ *     the harness's transport. Used by consumer round-trip test suites
+ *     to replace ~100 lines of verbatim-identical glue.
  *
  * Hono's wire upgrade is skipped — the Node test runtime has no
  * `@hono/node-ws` adapter — but the full dispatch path is exercised
@@ -29,11 +38,15 @@
  */
 import { WSContext, createWSMessageEvent, } from 'hono/ws';
 import { Logger } from '@fuzdev/fuz_util/log.js';
+import { ActionPeer } from '../actions/action_peer.js';
+import { create_broadcast_api } from '../actions/broadcast_api.js';
 import { register_action_ws, } from '../actions/register_action_ws.js';
 import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { REQUEST_CONTEXT_KEY } from '../auth/request_context.js';
 import { ROLE_KEEPER } from '../auth/role_schema.js';
 import { AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { JSONRPC_VERSION } from '../http/jsonrpc.js';
+import { create_jsonrpc_request, is_jsonrpc_error_response, is_jsonrpc_notification, is_jsonrpc_response, } from '../http/jsonrpc_helpers.js';
 import { create_uuid } from '../uuid.js';
 /**
  * Build a real `WSContext` backed by in-memory `send`/`close` capture.
@@ -121,6 +134,27 @@ export const dispatch_ws_message = async (on_message, event, ws) => {
     if (result instanceof Promise)
         await result;
 };
+/** Predicate matching a JSON-RPC notification with the given method name. */
+export const is_notification = (method) => (msg) => is_jsonrpc_notification(msg) && msg.method === method;
+/**
+ * Type-guard combinator: match a notification whose typed `params` satisfies
+ * `match`. Collapses the common test pattern of casting `msg` to
+ * `JsonrpcNotificationFrame<P>` in every predicate body.
+ *
+ * ```ts
+ * const match_roster_for = (id: Uuid) =>
+ *   is_notification_with<RosterChangedParams>(
+ *     WORLD_METHODS.roster_changed,
+ *     (params) => params.character_id === id && !params.removed,
+ *   );
+ * const roster = await client.wait_for(match_roster_for(char_id));
+ * ```
+ */
+export const is_notification_with = (method, match) => (msg) => is_jsonrpc_notification(msg) &&
+    msg.method === method &&
+    match(msg.params);
+/** Predicate matching a JSON-RPC response frame (success or error) for the given request id. */
+export const is_response_for = (id) => (msg) => (is_jsonrpc_response(msg) || is_jsonrpc_error_response(msg)) && msg.id === id;
 const DEFAULT_TIMEOUT_MS = 1000;
 /**
  * Build a `RequestContext` with a fresh UUID account/actor and permits
@@ -215,7 +249,7 @@ const build_simple_request_context = (role) => {
  * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
  */
 export const create_ws_test_harness = (options) => {
-    const { specs, handlers, extend_context = (base) => base, transport = new BackendWebsocketTransport(), log = new Logger('[ws-test]', { level: 'off' }), on_socket_open, on_socket_close, } = options;
+    const { actions, extend_context = (base) => base, transport = new BackendWebsocketTransport(), heartbeat = false, log = new Logger('[ws-test]', { level: 'off' }), on_socket_open, on_socket_close, } = options;
     const stub = create_stub_upgrade();
     // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
     const stub_app = { get: () => stub_app };
@@ -223,16 +257,16 @@ export const create_ws_test_harness = (options) => {
         path: '/test/ws',
         app: stub_app,
         upgradeWebSocket: stub.upgradeWebSocket,
-        specs,
-        handlers,
+        actions,
         extend_context,
         transport,
+        heartbeat,
         log,
         on_socket_open,
         on_socket_close,
     });
     const events_factory = stub.get_create_events();
-    const connect = (identity = {}) => {
+    const connect = async (identity = {}) => {
         const account_id = identity.account_id ?? create_uuid();
         const credential_type = identity.credential_type ?? 'session';
         const session_id = identity.session_id ?? create_uuid();
@@ -280,63 +314,80 @@ export const create_ws_test_harness = (options) => {
                     reason: { value: reason ?? '', writable: false },
                     wasClean: { value: true, writable: false },
                 });
-                close_pending = Promise.resolve(events).then(async (e) => {
+                close_pending = (async () => {
                     // onClose is typed as `void` by Hono but `register_action_ws`
                     // returns a promise when `on_socket_close` does async cleanup.
-                    await e.onClose?.(close_event, ws);
-                });
+                    await events.onClose?.(close_event, ws);
+                })();
             },
         });
-        // Resolve the (possibly async) events factory synchronously via
-        // a microtask chain. Tests always await `connect().send(...)`
-        // which sequences after.
-        let events = events_factory(fake_c);
-        const events_ready = Promise.resolve(events).then(async (resolved) => {
-            events = resolved;
-            // onOpen is typed as `void` by Hono but `register_action_ws`
-            // returns a promise when `on_socket_open` does async bootstrap.
-            // Tests have to see the fully-bootstrapped socket before
-            // `send()`, so wait on the hook chain here.
-            await resolved.onOpen?.(new Event('open'), ws);
-            return resolved;
-        });
+        // Resolve the (possibly async) events factory and fire onOpen
+        // before returning the client. Awaiting the hook chain here
+        // means the transport has registered the connection and any
+        // `on_socket_open` bootstrap (sending an initial snapshot,
+        // populating per-connection state) has completed by the time
+        // the caller's `await harness.connect(...)` resolves.
+        const factory_result = events_factory(fake_c);
+        const events = await Promise.resolve(factory_result);
+        // onOpen is typed as `void` by Hono but `register_action_ws`
+        // returns a promise when `on_socket_open` does async bootstrap.
+        await events.onOpen?.(new Event('open'), ws);
+        const wait_for_impl = (predicate, timeout_ms = DEFAULT_TIMEOUT_MS) => {
+            for (const msg of received) {
+                if (predicate(msg))
+                    return Promise.resolve(msg);
+            }
+            return new Promise((resolve, reject) => {
+                const waiter = {
+                    predicate,
+                    resolve: (msg) => {
+                        clearTimeout(timer);
+                        resolve(msg);
+                    },
+                };
+                const timer = setTimeout(() => {
+                    // Drop the waiter on timeout — without this, a later `send`
+                    // would still iterate it and the `waiters` array would grow
+                    // across timed-out waits.
+                    const i = waiters.indexOf(waiter);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    reject(new Error(`wait_for timed out after ${timeout_ms}ms`));
+                }, timeout_ms);
+                waiters.push(waiter);
+            });
+        };
+        const send_impl = async (message) => {
+            if (is_closed)
+                throw new Error('send after close');
+            const message_event = createWSMessageEvent(JSON.stringify(message));
+            // `onMessage` is typed as returning void by Hono, but
+            // `register_action_ws` implements it as async — cast so
+            // tests await the full dispatch (auth, validation,
+            // handler, send).
+            await events.onMessage?.(message_event, ws);
+        };
         return {
             get messages() {
                 return received;
             },
-            async send(message) {
-                const resolved = await events_ready;
-                if (is_closed)
-                    throw new Error('send after close');
-                const message_event = createWSMessageEvent(JSON.stringify(message));
-                // `onMessage` is typed as returning void by Hono, but
-                // `register_action_ws` implements it as async — cast so
-                // tests await the full dispatch (auth, validation,
-                // handler, send).
-                await resolved.onMessage?.(message_event, ws);
+            send: send_impl,
+            async request(id, method, params, timeout_ms) {
+                await send_impl(create_jsonrpc_request(method, params, id));
+                const msg = await wait_for_impl(is_response_for(id), timeout_ms);
+                if ('error' in msg) {
+                    const detail = msg.error.data === undefined ? '' : ` data=${JSON.stringify(msg.error.data)}`;
+                    throw new Error(`rpc #${id} failed: [${msg.error.code}] ${msg.error.message}${detail}`);
+                }
+                return msg.result;
             },
             async close(code, reason) {
-                if (is_closed)
-                    return close_pending ?? undefined;
-                ws.close(code, reason);
-                return close_pending ?? undefined;
-            },
-            wait_for(predicate, timeout_ms = DEFAULT_TIMEOUT_MS) {
-                for (const msg of received) {
-                    if (predicate(msg))
-                        return Promise.resolve(msg);
-                }
-                return new Promise((resolve, reject) => {
-                    const timer = setTimeout(() => reject(new Error(`wait_for timed out after ${timeout_ms}ms`)), timeout_ms);
-                    waiters.push({
-                        predicate,
-                        resolve: (msg) => {
-                            clearTimeout(timer);
-                            resolve(msg);
-                        },
-                    });
-                });
+                if (!is_closed)
+                    ws.close(code, reason);
+                if (close_pending)
+                    await close_pending;
             },
+            wait_for: wait_for_impl,
         };
     };
     return { transport, connect };
@@ -346,3 +397,33 @@ export const keeper_identity = () => ({
     credential_type: 'daemon_token',
     roles: [ROLE_KEEPER],
 });
+// ---------------------------------------------------------------------
+// Broadcast wiring — for tests that assert on server-initiated
+// notification fan-out. `build_broadcast_api` mirrors how consumer
+// `backend_actions_api.ts` composes the real stack (peer + transport
+// registered + `create_broadcast_api`); the helper exists so each test
+// doesn't re-spell that boilerplate.
+// ---------------------------------------------------------------------
+const make_peer = () => new ActionPeer({ environment: new MinimalActionEnvironment([]) });
+/**
+ * Wire a typed broadcast API against the harness's transport, matching
+ * how a consumer's real backend composes the stack. Returns the typed
+ * API so tests can call `.tx_run_created(...)` / `.workspace_changed(...)`
+ * etc. directly.
+ *
+ * ```ts
+ * const harness = create_ws_test_harness<BaseHandlerContext>({specs, handlers});
+ * const broadcast = build_broadcast_api<MyBackendActionsApi>({
+ *   harness,
+ *   specs: my_broadcast_action_specs,
+ * });
+ * const client = await harness.connect(keeper_identity());
+ * await broadcast.tx_run_created({run_id: '...', ...});
+ * await client.wait_for(is_notification('tx_run_created'));
+ * ```
+ */
+export const build_broadcast_api = (options) => {
+    const peer = make_peer();
+    peer.transports.register_transport(options.harness.transport);
+    return create_broadcast_api({ peer, specs: options.specs });
+};

package/package.json

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