@fuzdev/fuz_app 0.21.0 → 0.23.0

package/dist/actions/register_action_ws.d.ts

@@ -22,11 +22,12 @@
  * @module
  */
 import type { Context, Hono } from 'hono';
-import type { UpgradeWebSocket } from 'hono/ws';
+import type { UpgradeWebSocket, WSContext } from 'hono/ws';
 import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
 import { type JsonrpcRequestId } from '../http/jsonrpc.js';
+import type { Uuid } from '../uuid.js';
 import type { ActionSpecUnion } from './action_spec.js';
-import { BackendWebsocketTransport } from './transports_ws_backend.js';
+import { BackendWebsocketTransport, type ConnectionIdentity } from './transports_ws_backend.js';
 /**
  * Minimum per-request context every handler receives.
  *
@@ -51,6 +52,45 @@ export interface BaseHandlerContext {
 }
 /** Handler signature — receives validated input and per-request context. */
 export type WsActionHandler<TCtx extends BaseHandlerContext> = (input: unknown, ctx: TCtx) => unknown;
+/**
+ * Context passed to the `on_socket_open` hook.
+ *
+ * Fires after the transport has registered the new connection (so
+ * `connection_id` is valid) but before any client message can dispatch.
+ * Consumers use this to bootstrap per-socket domain state — e.g. undying
+ * spawns the per-account spirit unit and pushes an initial state snapshot.
+ */
+export interface SocketOpenContext {
+    /** The raw WebSocket context — exposed for edge cases; prefer `notify` for sends. */
+    ws: WSContext;
+    /** Connection id assigned by `BackendWebsocketTransport.add_connection`. */
+    connection_id: Uuid;
+    /** Auth identity registered for this connection. */
+    identity: ConnectionIdentity;
+    /**
+     * Send a JSON-RPC notification to just this socket. Mirrors `ctx.notify`
+     * on per-message handler contexts — same socket-scoped semantics.
+     */
+    notify: (method: string, params: unknown) => void;
+    /** Fires when this socket closes — threaded through to every handler's `ctx.signal`. */
+    signal: AbortSignal;
+}
+/**
+ * Context passed to the `on_socket_close` hook.
+ *
+ * Fires before `transport.remove_connection` runs, so consumer cleanup can
+ * still read identity before it's torn down. Fires for both client-initiated
+ * closes (Hono onClose) and server-initiated closes via audit revocation
+ * (the audit guard calls `ws.close()`, which triggers Hono's onClose).
+ */
+export interface SocketCloseContext {
+    /** The raw WebSocket context at close time. */
+    ws: WSContext;
+    /** Connection id captured at open time. */
+    connection_id: Uuid;
+    /** Auth identity captured at open time — still valid even if the transport already cleaned up. */
+    identity: ConnectionIdentity;
+}
 /** Options for `register_action_ws`. */
 export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
     /** Mount path (e.g., `/api/ws`). */
@@ -80,6 +120,20 @@ export interface RegisterActionWsOptions<TCtx extends BaseHandlerContext> {
     artificial_delay?: number;
     /** Optional logger; defaults to `[ws]` namespace. */
     log?: LoggerType;
+    /**
+     * Called once per socket, after the transport registers the connection.
+     * Awaited before any message is dispatched. Throwing logs an error and
+     * closes the socket with an `internal_error` frame — a failing bootstrap
+     * should not leave a partially-initialized socket alive.
+     */
+    on_socket_open?: (ctx: SocketOpenContext) => void | Promise<void>;
+    /**
+     * Called once per socket on close, *before* the transport removes the
+     * connection. Receives `connection_id` and `identity` captured at open
+     * time, so it is safe to read even when the audit guard has already torn
+     * down the transport's internal state. Errors are logged and swallowed.
+     */
+    on_socket_close?: (ctx: SocketCloseContext) => void | Promise<void>;
 }
 /** Result of `register_action_ws`. */
 export interface RegisterActionWsResult {

package/dist/actions/register_action_ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,SAAS,CAAC;AAE9C,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAK1E,OAAO,EAAkB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAY1E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAC,yBAAyB,EAAC,MAAM,4BAA4B,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC,kEAAkE;IAClE,UAAU,EAAE,gBAAgB,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CAAC;CACpB;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,kBAAkB,IAAI,CAC9D,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,IAAI,KACL,OAAO,CAAC;AAEb,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,yFAAyF;IACzF,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA0NF,CAAC"}
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"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"}

package/dist/actions/register_action_ws.js

@@ -51,7 +51,7 @@ import { BackendWebsocketTransport } from './transports_ws_backend.js';
  *   `create_ws_auth_guard` or broadcast on audit events.
  */
 export const register_action_ws = (options) => {
-    const { path, app, upgradeWebSocket, specs, handlers, extend_context, transport = new BackendWebsocketTransport(), artificial_delay = 0, log = new Logger('[ws]'), } = options;
+    const { path, app, upgradeWebSocket, specs, handlers, extend_context, transport = new BackendWebsocketTransport(), artificial_delay = 0, log = new Logger('[ws]'), on_socket_open, on_socket_close, } = options;
     // Build spec lookup for per-action auth and input validation.
     const spec_by_method = new Map(specs.map((spec) => [spec.method, spec]));
     app.get(path, upgradeWebSocket((c) => {
@@ -75,10 +75,51 @@ export const register_action_ws = (options) => {
         // a single socket-scoped signal is sufficient today since cancel
         // granularity tracks connection lifetime, not individual requests.
         const socket_abort_controller = new AbortController();
+        // Identity is assembled at upgrade time so `on_socket_close` can
+        // still read it after the audit guard tears the transport record
+        // down; `BackendWebsocketTransport.#revoke_connection` clears the
+        // identity map before Hono fires onClose.
+        const identity = { token_hash, account_id, api_token_id };
+        // Captured on open, consumed on close. Null before onOpen fires or
+        // when a consumer never opens (e.g. immediate disconnect).
+        let captured_connection_id = null;
+        // Socket-scoped notification helper — routes to this socket only,
+        // matches the `ctx.notify` semantics exposed to per-message handlers.
+        const notify_socket = (ws) => (notify_method, notify_params) => {
+            try {
+                const notification = create_jsonrpc_notification(notify_method, to_jsonrpc_params(notify_params));
+                ws.send(JSON.stringify(notification));
+            }
+            catch (error) {
+                log.error('notify send failed:', notify_method, error);
+            }
+        };
         return {
-            onOpen: (event, ws) => {
+            onOpen: async (event, ws) => {
                 const connection_id = transport.add_connection(ws, token_hash, account_id, api_token_id);
+                captured_connection_id = connection_id;
                 log.debug('ws opened', connection_id, event);
+                if (on_socket_open) {
+                    try {
+                        await on_socket_open({
+                            ws,
+                            connection_id,
+                            identity,
+                            notify: notify_socket(ws),
+                            signal: socket_abort_controller.signal,
+                        });
+                    }
+                    catch (error) {
+                        log.error('on_socket_open failed — closing socket:', error);
+                        try {
+                            ws.send(JSON.stringify(create_jsonrpc_error_response(null, jsonrpc_error_messages.internal_error())));
+                        }
+                        catch {
+                            // ignore — socket may already be dead
+                        }
+                        ws.close(1011, 'socket bootstrap failed');
+                    }
+                }
             },
             onMessage: async (event, ws) => {
                 let json;
@@ -178,8 +219,20 @@ export const register_action_ws = (options) => {
                     ws.send(JSON.stringify(create_jsonrpc_error_response_from_thrown(id, error)));
                 }
             },
-            onClose: (event, ws) => {
+            onClose: async (event, ws) => {
                 socket_abort_controller.abort();
+                if (on_socket_close && captured_connection_id) {
+                    try {
+                        await on_socket_close({
+                            ws,
+                            connection_id: captured_connection_id,
+                            identity,
+                        });
+                    }
+                    catch (error) {
+                        log.error('on_socket_close failed:', error);
+                    }
+                }
                 transport.remove_connection(ws);
                 log.debug('ws closed', event);
             },

package/dist/testing/ws_round_trip.d.ts

@@ -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
@@ -36,6 +45,7 @@ import { type BaseHandlerContext, type RegisterActionWsOptions, type WsActionHan
 import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { type RequestContext } from '../auth/request_context.js';
 import { type CredentialType } from '../hono_context.js';
+import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { type Uuid } from '../uuid.js';
 /**
  * A `WSContext` paired with capture arrays. Use `sends` to assert on
@@ -120,17 +130,76 @@ export interface WsConnectIdentity {
 export interface MockWsClient {
     /** Send a JSON-RPC message (request or notification) to the server. */
     send: (message: unknown) => Promise<void>;
-    /** Close the connection, firing `onClose`. */
-    close: (code?: number, reason?: string) => void;
+    /**
+     * Send a JSON-RPC request and await its response. Resolves with the
+     * `result`; throws with a useful message (code, text, and any `data`
+     * payload) on an error frame — without this, asserting on
+     * `result.foo` for a failed request throws
+     * `Cannot read property 'foo' of undefined`, which hides the real
+     * cause. Use `send` + `wait_for(is_response_for(id))` directly when
+     * you need to assert on the error frame itself.
+     */
+    request: <R = unknown>(id: number | string, method: string, params: unknown, timeout_ms?: number) => Promise<R>;
+    /**
+     * Close the connection, firing `onClose`. Returns a promise that
+     * resolves once `on_socket_close` (and the transport's own cleanup)
+     * have completed — tests that assert on post-close state should await.
+     */
+    close: (code?: number, reason?: string) => Promise<void>;
     /** Every message the server has sent, in arrival order. */
     readonly messages: ReadonlyArray<unknown>;
     /**
      * Wait until a message satisfies `predicate`. Matches are checked
      * against already-received messages first, then new arrivals until
      * the timeout (defaults to 1000ms).
+     *
+     * When `predicate` is a type guard (e.g. `is_notification_with<P>`),
+     * the result is narrowed automatically and callers don't need to
+     * spell `<JsonrpcNotificationFrame<P>>` on the call site.
      */
-    wait_for: <T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number) => Promise<T>;
+    wait_for: {
+        <T>(predicate: (msg: unknown) => msg is T, timeout_ms?: number): Promise<T>;
+        <T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number): Promise<T>;
+    };
 }
+export interface JsonrpcNotificationFrame<P = unknown> {
+    jsonrpc: typeof JSONRPC_VERSION;
+    method: string;
+    params: P;
+}
+export interface JsonrpcSuccessResponseFrame<R = unknown> {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: number | string;
+    result: R;
+}
+export interface JsonrpcErrorResponseFrame<D = unknown> {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: number | string;
+    error: {
+        code: number;
+        message: string;
+        data?: D;
+    };
+}
+/** Predicate matching a JSON-RPC notification with the given method name. */
+export declare const is_notification: (method: string) => (msg: unknown) => boolean;
+/**
+ * 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 declare const is_notification_with: <P>(method: string, match: (params: P) => boolean) => (msg: unknown) => msg is JsonrpcNotificationFrame<P>;
+/** Predicate matching a JSON-RPC response frame (success or error) for the given request id. */
+export declare const is_response_for: (id: number | string) => (msg: unknown) => boolean;
 /** Options for `create_ws_test_harness`. */
 export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
     specs: ReadonlyArray<ActionSpecUnion>;
@@ -140,11 +209,22 @@ export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
     transport?: BackendWebsocketTransport;
     /** Optional logger. Defaults to a silent `[ws-test]` logger. */
     log?: Logger;
+    /** Threaded straight through to `register_action_ws`. */
+    on_socket_open?: RegisterActionWsOptions<TCtx>['on_socket_open'];
+    /** Threaded straight through to `register_action_ws`. */
+    on_socket_close?: RegisterActionWsOptions<TCtx>['on_socket_close'];
 }
 /** A harness instance — transport handle + connection factory. */
 export interface WsTestHarness {
     transport: BackendWebsocketTransport;
-    connect: (identity?: WsConnectIdentity) => MockWsClient;
+    /**
+     * Open a mock connection. Resolves after `on_socket_open` (and the
+     * transport's `register_ws`) completes, so broadcasts issued
+     * immediately after the `await` reach the connection. Earlier
+     * revisions returned synchronously and required a `settle_open()`
+     * microtask drain — no longer necessary.
+     */
+    connect: (identity?: WsConnectIdentity) => Promise<MockWsClient>;
 }
 /**
  * Create a WebSocket test harness for the given specs + handlers.
@@ -158,4 +238,25 @@ export interface WsTestHarness {
 export declare const create_ws_test_harness: <TCtx extends BaseHandlerContext>(options: CreateWsTestHarnessOptions<TCtx>) => WsTestHarness;
 /** Convenience: default identity for keeper-authenticated connections. */
 export declare const keeper_identity: () => WsConnectIdentity;
+/**
+ * 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 declare const build_broadcast_api: <TApi>(options: {
+    harness: WsTestHarness;
+    specs: ReadonlyArray<ActionSpecUnion>;
+}) => TApi;
 //# sourceMappingURL=ws_round_trip.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/ws_round_trip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAO,MAAM,MAAM,CAAC;AACxC,OAAO,EACN,SAAS,EAET,KAAK,gBAAgB,EAErB,KAAK,QAAQ,EACb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAE/C,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAC,yBAAyB,EAAC,MAAM,qCAAqC,CAAC;AAC9E,OAAO,EAAsB,KAAK,cAAc,EAAC,MAAM,4BAA4B,CAAC;AAEpF,OAAO,EAA6C,KAAK,cAAc,EAAC,MAAM,oBAAoB,CAAC;AACnG,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAMlD;;;GAGG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB,MAAM,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAO,MAajC,CAAC;AAEF,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACtC,eAAe,EAAE,cAAc,CAAC;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,sBAAsB,KAAG,OAWvE,CAAC;AAEF,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC3B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,iBAAiB,EAAE,MAAM,CAAC,CAAC,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACtE;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAO,WAatC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,sBAAsB;;IACtE,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAa;gBAEjC,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC;IAGjD,qBAAqB,IAAI,SAAS;IAGlC,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;CAG/D;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,YAAY,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAC9C,OAAO,YAAY,EACnB,IAAI,SAAS,KACX,OAAO,CAAC,IAAI,CAId,CAAC;AAMF,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,yFAAyF;IACzF,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kFAAkF;IAClF,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC5B,uEAAuE;IACvE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,8CAA8C;IAC9C,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACjG;AAED,4CAA4C;AAC5C,MAAM,WAAW,0BAA0B,CAAC,IAAI,SAAS,kBAAkB;IAC1E,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD,cAAc,CAAC,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACjE,kEAAkE;IAClE,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,yBAAyB,CAAC;IACrC,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,iBAAiB,KAAK,YAAY,CAAC;CACxD;AA4FD;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAAI,IAAI,SAAS,kBAAkB,EACrE,SAAS,0BAA0B,CAAC,IAAI,CAAC,KACvC,aAmIF,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,eAAe,QAAO,iBAGjC,CAAC"}
+{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/ws_round_trip.ts"],"names":[],"mappings":"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"}

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' }), } = 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 stub = create_stub_upgrade();
     // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
     const stub_app = { get: () => stub_app };
@@ -228,9 +262,11 @@ export const create_ws_test_harness = (options) => {
         extend_context,
         transport,
         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();
@@ -248,6 +284,9 @@ export const create_ws_test_harness = (options) => {
         const received = [];
         const waiters = [];
         let is_closed = false;
+        // Captured in `ws.close` below; `client.close(...)` returns it so
+        // tests can await async `on_socket_close` cleanup.
+        let close_pending = null;
         // Real WSContext backed by test-owned send/close. Parsing is done
         // on receive so tests can assert against structured messages.
         const ws = new WSContext({
@@ -275,54 +314,80 @@ export const create_ws_test_harness = (options) => {
                     reason: { value: reason ?? '', writable: false },
                     wasClean: { value: true, writable: false },
                 });
-                void Promise.resolve(events).then((e) => e.onClose?.(close_event, ws));
+                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 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((resolved) => {
-            events = resolved;
-            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);
-            },
-            close(code, reason) {
-                if (is_closed)
-                    return;
-                ws.close(code, reason);
-            },
-            wait_for(predicate, timeout_ms = DEFAULT_TIMEOUT_MS) {
-                for (const msg of received) {
-                    if (predicate(msg))
-                        return Promise.resolve(msg);
+            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 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);
-                        },
-                    });
-                });
+                return msg.result;
+            },
+            async close(code, reason) {
+                if (!is_closed)
+                    ws.close(code, reason);
+                if (close_pending)
+                    await close_pending;
             },
+            wait_for: wait_for_impl,
         };
     };
     return { transport, connect };
@@ -332,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.21.0",
+  "version": "0.23.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",