@fuzdev/fuz_app 0.20.0 → 0.22.0

package/dist/actions/action_registry.js

@@ -7,7 +7,7 @@
 // `request_response_specs`, `remote_notification_specs`, `local_call_specs`,
 // `frontend_methods`, `backend_methods`, and `methods` are used by consumers (codegen).
 // The rest are pre-built for future use. Revisit which getters to keep when the action
-// system matures (saes-rpc quest). Also consider lazy memoization (`??=` or derived).
+// system matures. Also consider lazy memoization (`??=` or derived).
 /**
  * Utility class to manage and query action specifications.
  * Provides helper methods to get actions by various criteria.

package/dist/actions/action_spec.d.ts

@@ -6,7 +6,7 @@
  * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
- * action_codegen, action_bridge) will evolve significantly with the saes-rpc quest.
+ * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
  * Current state: bridge is stable, registry and codegen are partially stub API.
  * Search for `@action-system-review` across the actions/ and routes/ modules.
  *

package/dist/actions/action_spec.js

@@ -6,7 +6,7 @@
  * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
- * action_codegen, action_bridge) will evolve significantly with the saes-rpc quest.
+ * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
  * Current state: bridge is stable, registry and codegen are partially stub API.
  * Search for `@action-system-review` across the actions/ and routes/ modules.
  *

package/dist/actions/broadcast_api.d.ts

@@ -12,9 +12,8 @@
  * streaming (`completion_progress`, `tx_apply` events) stays on
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
- * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
- * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
- * undying.
+ * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
+ * drifting across zzz, tx, and undying.
  *
  * @module
  */

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

@@ -1 +1 @@
-{"version":3,"file":"broadcast_api.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/broadcast_api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,KACV,OAAO,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,gFAAgF;IAChF,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,GAAG,YAAY,EACvD,SAAS,yBAAyB,KAChC,IAoDF,CAAC"}
+{"version":3,"file":"broadcast_api.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/broadcast_api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,KACV,OAAO,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,gFAAgF;IAChF,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,GAAG,YAAY,EACvD,SAAS,yBAAyB,KAChC,IAoDF,CAAC"}

package/dist/actions/broadcast_api.js

@@ -12,9 +12,8 @@
  * streaming (`completion_progress`, `tx_apply` events) stays on
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
- * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
- * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
- * undying.
+ * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
+ * drifting across zzz, tx, and undying.
  *
  * @module
  */

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAK1E,OAAO,EAAkB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAW1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AACrC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F;;;;;;;;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;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,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;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;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,sBAwRF,CAAC"}

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;
@@ -143,9 +184,9 @@ export const register_action_ws = (options) => {
                     await wait(artificial_delay);
                 }
                 // Socket-scoped notification — routes to originator only, not
-                // broadcast. Future work (websockets quest Phase 3/4): other
-                // audiences — account-scoped, ACL-filtered, broadcast —
-                // likely via a transport-level policy hook.
+                // broadcast. Future work: other audiences — account-scoped,
+                // ACL-filtered, broadcast — likely via a transport-level
+                // policy hook.
                 const notify = (notify_method, notify_params) => {
                     try {
                         const notification = create_jsonrpc_notification(notify_method, to_jsonrpc_params(notify_params));
@@ -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

@@ -0,0 +1,169 @@
+/**
+ * In-process test helpers for WebSocket JSON-RPC round-trips.
+ *
+ * Drives `register_action_ws` without an HTTP server. Consumers supply
+ * specs + handlers; the harness constructs real `WSContext` instances
+ * backed by test-owned `send`/`close` pairs, fakes the authenticated
+ * Hono context (`request_context`, credential type, session id, api
+ * token id), and exposes a `connect()` factory returning a
+ * `MockWsClient` per connection.
+ *
+ * Two 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.
+ *   - **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.
+ *
+ * Hono's wire upgrade is skipped — the Node test runtime has no
+ * `@hono/node-ws` adapter — but the full dispatch path is exercised
+ * (per-action auth, input validation, `ctx.notify` back to the
+ * originating socket, broadcast via `BackendWebsocketTransport`, and
+ * close-on-revoke).
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+import { WSContext, type UpgradeWebSocket, type WSEvents } from 'hono/ws';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import type { ActionSpecUnion } from '../actions/action_spec.js';
+import type { ActionEventEnvironment } from '../actions/action_event_types.js';
+import { type BaseHandlerContext, type RegisterActionWsOptions, type WsActionHandler } from '../actions/register_action_ws.js';
+import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
+import { type RequestContext } from '../auth/request_context.js';
+import { type CredentialType } from '../hono_context.js';
+import { type Uuid } from '../uuid.js';
+/**
+ * A `WSContext` paired with capture arrays. Use `sends` to assert on
+ * outgoing frames; use `closes` to assert on revocation / close.
+ */
+export interface FakeWs {
+    ws: WSContext;
+    sends: Array<string>;
+    closes: Array<{
+        code?: number;
+        reason?: string;
+    }>;
+}
+/**
+ * Build a real `WSContext` backed by in-memory `send`/`close` capture.
+ * Parsing of outgoing frames is left to the caller — `sends` holds the
+ * raw strings as the dispatcher wrote them.
+ */
+export declare const create_fake_ws: () => FakeWs;
+/** Options for `create_fake_hono_context`. */
+export interface FakeHonoContextOptions {
+    credential_type: CredentialType;
+    /** A single role to grant via `create_test_request_context`. */
+    role?: string;
+    auth_session_id?: string | null;
+    api_token_id?: string | null;
+    /**
+     * Override the `RequestContext` outright (for multi-role or custom
+     * account/actor fixtures). Takes precedence over `role`.
+     */
+    request_context?: RequestContext;
+}
+/**
+ * Build a fake Hono `Context` exposing the auth keys the dispatcher
+ * reads via `c.get(...)`. Only `.get()` is populated — no other Hono
+ * context surface is simulated.
+ */
+export declare const create_fake_hono_context: (opts: FakeHonoContextOptions) => Context;
+/** The return of `create_stub_upgrade` — fake `upgradeWebSocket` + factory capture. */
+export interface StubUpgrade {
+    upgradeWebSocket: UpgradeWebSocket;
+    get_create_events: () => (c: Context) => WSEvents | Promise<WSEvents>;
+}
+/**
+ * Build a fake `upgradeWebSocket` that captures the `createEvents`
+ * callback. The returned middleware is inert — tests drive
+ * `createEvents` directly.
+ */
+export declare const create_stub_upgrade: () => StubUpgrade;
+/**
+ * Minimal `ActionEventEnvironment` for tests that instantiate an
+ * `ActionPeer` without pulling in the full runtime. Pre-loads a
+ * spec map from the supplied list.
+ */
+export declare class MinimalActionEnvironment implements ActionEventEnvironment {
+    #private;
+    executor: 'frontend' | 'backend';
+    constructor(specs: ReadonlyArray<ActionSpecUnion>);
+    lookup_action_handler(): undefined;
+    lookup_action_spec(method: string): ActionSpecUnion | undefined;
+}
+/**
+ * Hono types `WSEvents.onMessage` as `() => void | Promise<void>`.
+ * Awaits only the Promise branch so tests observe full dispatch
+ * (auth, validation, handler, send).
+ */
+export declare const dispatch_ws_message: (on_message: NonNullable<WSEvents["onMessage"]>, event: MessageEvent, ws: WSContext) => Promise<void>;
+/** Auth identity for a mock connection. */
+export interface WsConnectIdentity {
+    /** Account id for the connection. Defaults to a fresh uuid per call. */
+    account_id?: Uuid;
+    /** Credential type. Defaults to `'session'`. Keeper actions require `'daemon_token'`. */
+    credential_type?: CredentialType;
+    /** Session id (any string). Defaults to a fresh uuid. Hashed by the dispatcher. */
+    session_id?: string;
+    /** Api token id; set for bearer connections, null otherwise. */
+    api_token_id?: string | null;
+    /** Roles to grant via active permits. Pass `[ROLE_KEEPER]` for keeper actions. */
+    roles?: Array<string>;
+}
+/** A mock WS client: send requests, inspect/await incoming messages. */
+export interface MockWsClient {
+    /** Send a JSON-RPC message (request or notification) to the server. */
+    send: (message: unknown) => Promise<void>;
+    /**
+     * 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).
+     */
+    wait_for: <T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number) => Promise<T>;
+}
+/** Options for `create_ws_test_harness`. */
+export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
+    specs: ReadonlyArray<ActionSpecUnion>;
+    handlers: Record<string, WsActionHandler<TCtx>>;
+    extend_context?: RegisterActionWsOptions<TCtx>['extend_context'];
+    /** Pass a pre-created transport to share with a broadcast API. */
+    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;
+}
+/**
+ * Create a WebSocket test harness for the given specs + handlers.
+ *
+ * Registers against a throwaway Hono app with a fake
+ * `upgradeWebSocket`; the captured events factory is invoked per
+ * `connect()` with a synthesized Hono context carrying the requested
+ * auth identity. Returned clients drive the real
+ * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
+ */
+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;
+//# sourceMappingURL=ws_round_trip.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,348 @@
+/**
+ * In-process test helpers for WebSocket JSON-RPC round-trips.
+ *
+ * Drives `register_action_ws` without an HTTP server. Consumers supply
+ * specs + handlers; the harness constructs real `WSContext` instances
+ * backed by test-owned `send`/`close` pairs, fakes the authenticated
+ * Hono context (`request_context`, credential type, session id, api
+ * token id), and exposes a `connect()` factory returning a
+ * `MockWsClient` per connection.
+ *
+ * Two 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.
+ *   - **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.
+ *
+ * Hono's wire upgrade is skipped — the Node test runtime has no
+ * `@hono/node-ws` adapter — but the full dispatch path is exercised
+ * (per-action auth, input validation, `ctx.notify` back to the
+ * originating socket, broadcast via `BackendWebsocketTransport`, and
+ * close-on-revoke).
+ *
+ * @module
+ */
+import { WSContext, createWSMessageEvent, } from 'hono/ws';
+import { Logger } from '@fuzdev/fuz_util/log.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 { create_uuid } from '../uuid.js';
+/**
+ * Build a real `WSContext` backed by in-memory `send`/`close` capture.
+ * Parsing of outgoing frames is left to the caller — `sends` holds the
+ * raw strings as the dispatcher wrote them.
+ */
+export const create_fake_ws = () => {
+    const sends = [];
+    const closes = [];
+    const init = {
+        send: (data) => {
+            sends.push(typeof data === 'string' ? data : '<binary>');
+        },
+        close: (code, reason) => {
+            closes.push({ code, reason });
+        },
+        readyState: 1,
+    };
+    return { ws: new WSContext(init), sends, closes };
+};
+/**
+ * Build a fake Hono `Context` exposing the auth keys the dispatcher
+ * reads via `c.get(...)`. Only `.get()` is populated — no other Hono
+ * context surface is simulated.
+ */
+export const create_fake_hono_context = (opts) => {
+    const request_context = opts.request_context ?? build_simple_request_context(opts.role);
+    const vars = {
+        [REQUEST_CONTEXT_KEY]: request_context,
+        [CREDENTIAL_TYPE_KEY]: opts.credential_type,
+        auth_session_id: opts.auth_session_id ?? (opts.credential_type === 'session' ? 's1' : null),
+        [AUTH_API_TOKEN_ID_KEY]: opts.api_token_id ?? null,
+    };
+    return {
+        get: (key) => vars[key],
+    };
+};
+/**
+ * Build a fake `upgradeWebSocket` that captures the `createEvents`
+ * callback. The returned middleware is inert — tests drive
+ * `createEvents` directly.
+ */
+export const create_stub_upgrade = () => {
+    let captured = null;
+    const upgradeWebSocket = ((createEvents) => {
+        captured = createEvents;
+        return async (_c, next) => next();
+    });
+    return {
+        upgradeWebSocket,
+        get_create_events: () => {
+            if (!captured)
+                throw new Error('upgradeWebSocket was not called');
+            return captured;
+        },
+    };
+};
+/**
+ * Minimal `ActionEventEnvironment` for tests that instantiate an
+ * `ActionPeer` without pulling in the full runtime. Pre-loads a
+ * spec map from the supplied list.
+ */
+export class MinimalActionEnvironment {
+    executor = 'backend';
+    #specs = new Map();
+    constructor(specs) {
+        for (const spec of specs)
+            this.#specs.set(spec.method, spec);
+    }
+    lookup_action_handler() {
+        return undefined;
+    }
+    lookup_action_spec(method) {
+        return this.#specs.get(method);
+    }
+}
+/**
+ * Hono types `WSEvents.onMessage` as `() => void | Promise<void>`.
+ * Awaits only the Promise branch so tests observe full dispatch
+ * (auth, validation, handler, send).
+ */
+export const dispatch_ws_message = async (on_message, event, ws) => {
+    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+    const result = on_message(event, ws);
+    if (result instanceof Promise)
+        await result;
+};
+const DEFAULT_TIMEOUT_MS = 1000;
+/**
+ * Build a `RequestContext` with a fresh UUID account/actor and permits
+ * for the supplied roles. Used by the high-level harness so callers can
+ * pass `roles: [ROLE_KEEPER, 'admin']`.
+ */
+const build_multi_role_request_context = (account_id, roles) => {
+    const actor_id = create_uuid();
+    const now = new Date().toISOString();
+    return {
+        account: {
+            id: account_id,
+            username: 'ws-test',
+            email: null,
+            email_verified: false,
+            password_hash: '',
+            created_at: now,
+            created_by: null,
+            updated_at: now,
+            updated_by: null,
+        },
+        actor: {
+            id: actor_id,
+            account_id,
+            name: 'ws-test',
+            created_at: now,
+            updated_at: null,
+            updated_by: null,
+        },
+        permits: roles.map((role) => ({
+            id: create_uuid(),
+            actor_id,
+            role,
+            created_at: now,
+            expires_at: null,
+            revoked_at: null,
+            revoked_by: null,
+            granted_by: null,
+        })),
+    };
+};
+/**
+ * Stub `RequestContext` for single-role or public fakes. Hardcoded
+ * ids (`acc_1` / `act_1`) mirror `create_test_request_context` in
+ * `auth_apps.ts`.
+ */
+const build_simple_request_context = (role) => {
+    const now = new Date().toISOString();
+    return {
+        account: {
+            id: 'acc_1',
+            username: 'testuser',
+            password_hash: 'hash',
+            created_at: now,
+            updated_at: now,
+            created_by: null,
+            updated_by: null,
+            email: null,
+            email_verified: false,
+        },
+        actor: {
+            id: 'act_1',
+            account_id: 'acc_1',
+            name: 'testuser',
+            created_at: now,
+            updated_at: null,
+            updated_by: null,
+        },
+        permits: role
+            ? [
+                {
+                    id: 'perm_1',
+                    actor_id: 'act_1',
+                    role,
+                    created_at: now,
+                    expires_at: null,
+                    revoked_at: null,
+                    revoked_by: null,
+                    granted_by: null,
+                },
+            ]
+            : [],
+    };
+};
+/**
+ * Create a WebSocket test harness for the given specs + handlers.
+ *
+ * Registers against a throwaway Hono app with a fake
+ * `upgradeWebSocket`; the captured events factory is invoked per
+ * `connect()` with a synthesized Hono context carrying the requested
+ * auth identity. Returned clients drive the real
+ * `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 stub = create_stub_upgrade();
+    // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
+    const stub_app = { get: () => stub_app };
+    register_action_ws({
+        path: '/test/ws',
+        app: stub_app,
+        upgradeWebSocket: stub.upgradeWebSocket,
+        specs,
+        handlers,
+        extend_context,
+        transport,
+        log,
+        on_socket_open,
+        on_socket_close,
+    });
+    const events_factory = stub.get_create_events();
+    const connect = (identity = {}) => {
+        const account_id = identity.account_id ?? create_uuid();
+        const credential_type = identity.credential_type ?? 'session';
+        const session_id = identity.session_id ?? create_uuid();
+        const api_token_id = identity.api_token_id ?? null;
+        const roles = identity.roles ?? [];
+        const ctx_store = new Map([
+            [REQUEST_CONTEXT_KEY, build_multi_role_request_context(account_id, roles)],
+            [CREDENTIAL_TYPE_KEY, credential_type],
+            ['auth_session_id', session_id],
+            [AUTH_API_TOKEN_ID_KEY, api_token_id],
+        ]);
+        const fake_c = {
+            get: (key) => ctx_store.get(key),
+        };
+        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({
+            readyState: 1,
+            send: (data) => {
+                if (is_closed)
+                    return;
+                const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+                received.push(parsed);
+                for (let i = waiters.length - 1; i >= 0; i--) {
+                    const waiter = waiters[i];
+                    if (waiter.predicate(parsed)) {
+                        waiter.resolve(parsed);
+                        waiters.splice(i, 1);
+                    }
+                }
+            },
+            close: (code, reason) => {
+                if (is_closed)
+                    return;
+                is_closed = true;
+                const close_event = new Event('close');
+                Object.defineProperties(close_event, {
+                    code: { value: code ?? 1000, writable: false },
+                    reason: { value: reason ?? '', writable: false },
+                    wasClean: { value: true, writable: false },
+                });
+                close_pending = Promise.resolve(events).then(async (e) => {
+                    // 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);
+                });
+            },
+        });
+        // 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;
+        });
+        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);
+            },
+            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);
+                        },
+                    });
+                });
+            },
+        };
+    };
+    return { transport, connect };
+};
+/** Convenience: default identity for keeper-authenticated connections. */
+export const keeper_identity = () => ({
+    credential_type: 'daemon_token',
+    roles: [ROLE_KEEPER],
+});

package/package.json

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