@fuzdev/fuz_app 0.21.0 → 0.22.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

@@ -120,8 +120,12 @@ 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;
+    /**
+     * 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>;
     /**
@@ -140,6 +144,10 @@ 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 {

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":"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"}
+{"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

@@ -215,7 +215,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,6 +228,8 @@ 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 = {}) => {
@@ -248,6 +250,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,16 +280,24 @@ 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 = 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((resolved) => {
+        const events_ready = Promise.resolve(events).then(async (resolved) => {
             events = resolved;
-            resolved.onOpen?.(new Event('open'), ws);
+            // 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 {
@@ -302,10 +315,11 @@ export const create_ws_test_harness = (options) => {
                 // handler, send).
                 await resolved.onMessage?.(message_event, ws);
             },
-            close(code, reason) {
+            async close(code, reason) {
                 if (is_closed)
-                    return;
+                    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) {

package/package.json

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