@fuzdev/fuz_app 0.16.0 → 0.17.0

package/dist/actions/broadcast_api.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Backend-initiated broadcast notification plumbing — generic across consumers.
+ *
+ * Builds a typed `{method_name: (input) => Promise<void>}` object from a list
+ * of action specs. Each call validates input against the spec, wraps it in a
+ * JSON-RPC notification, and either broadcasts to every connection or
+ * fans out with a per-connection ACL predicate.
+ *
+ * Counterpart to `register_action_ws`: that handles request-scoped dispatch
+ * (frontend-initiated), this handles broadcast (backend-initiated). Together
+ * they cover the two primitives fuz_app consumers share. Request-scoped
+ * 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.
+ *
+ * @module
+ */
+import { type Logger as LoggerType } from '@fuzdev/fuz_util/log.js';
+import type { ActionPeer } from './action_peer.js';
+import type { ActionSpecUnion } from './action_spec.js';
+import { type ConnectionIdentity } from './transports_ws_backend.js';
+/**
+ * Per-connection delivery predicate for subscription ACLs.
+ *
+ * Called once per connection for every broadcast send. Returning `false`
+ * skips that connection. Keep it fast — this runs in the broadcast hot path.
+ *
+ * `input` is the already-validated payload (matches the spec's input schema);
+ * `method` is the action method name.
+ */
+export type ShouldDeliverFn = (connection: ConnectionIdentity, method: string, input: unknown) => boolean;
+/** Options for `create_broadcast_api`. */
+export interface CreateBroadcastApiOptions {
+    /** The peer holding the transport registry used for sends. */
+    peer: ActionPeer;
+    /**
+     * Notification specs to expose as broadcast methods. Typically the
+     * `remote_notification` specs whose initiator is `backend` (or `both`).
+     * Other kinds are accepted — the helper only uses `spec.method` and
+     * `spec.input` — but the typical use is notifications.
+     */
+    specs: ReadonlyArray<ActionSpecUnion>;
+    /** Logger for validation/send errors. Defaults to a `[broadcast]` namespace. */
+    log?: LoggerType | null;
+    /**
+     * Optional per-connection ACL predicate. When set, the broadcast fans out
+     * via the transport's `broadcast_filtered` (feature-detected) — each
+     * connection's identity is checked before the message is sent. When
+     * unset, the transport broadcasts unfiltered via `transport.send`.
+     *
+     * Requires a transport that implements `FilterableBroadcastTransport`
+     * (today: only `BackendWebsocketTransport`). If set and the active
+     * transport is not filterable, the send is skipped and an error logged.
+     */
+    should_deliver?: ShouldDeliverFn;
+}
+/**
+ * Loose base shape for a broadcast API. Consumers typically declare a
+ * stricter per-method interface (e.g. `BackendActionsApi`) and pin it via
+ * the type parameter on `create_broadcast_api`.
+ */
+export type BroadcastApi = Record<string, (input: never) => Promise<void>>;
+/**
+ * Builds a typed broadcast API from a set of action specs.
+ *
+ * For each spec, adds a method keyed by `spec.method` that:
+ * - Validates `input` against the spec's Zod schema (logs and returns on failure)
+ * - Creates a JSON-RPC notification from the validated input
+ * - Broadcasts via the peer (filtered by `should_deliver` when supplied)
+ *
+ * Silently returns when no transport is ready (e.g. before any clients
+ * connect). Errors during send are logged but never thrown — broadcasts are
+ * fire-and-forget from the handler's perspective.
+ *
+ * ## Typed consumer surface
+ *
+ * Consumers declare an explicit interface and pin it via the type parameter:
+ *
+ * ```ts
+ * export interface BackendActionsApi {
+ *   filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
+ *   workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
+ * }
+ *
+ * const api = create_broadcast_api<BackendActionsApi>({
+ *   peer: backend.peer,
+ *   specs: [filer_change_action_spec, workspace_changed_action_spec],
+ * });
+ * ```
+ *
+ * The cast is unchecked — callers must keep the interface and the `specs`
+ * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
+ * if the consumer already generates per-method type maps.
+ */
+export declare const create_broadcast_api: <TApi = BroadcastApi>(options: CreateBroadcastApiOptions) => TApi;
+//# sourceMappingURL=broadcast_api.d.ts.map

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

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

package/dist/actions/broadcast_api.js

@@ -0,0 +1,99 @@
+/**
+ * Backend-initiated broadcast notification plumbing — generic across consumers.
+ *
+ * Builds a typed `{method_name: (input) => Promise<void>}` object from a list
+ * of action specs. Each call validates input against the spec, wraps it in a
+ * JSON-RPC notification, and either broadcasts to every connection or
+ * fans out with a per-connection ACL predicate.
+ *
+ * Counterpart to `register_action_ws`: that handles request-scoped dispatch
+ * (frontend-initiated), this handles broadcast (backend-initiated). Together
+ * they cover the two primitives fuz_app consumers share. Request-scoped
+ * 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.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { create_jsonrpc_notification, to_jsonrpc_params } from '../http/jsonrpc_helpers.js';
+import { is_filterable_broadcast_transport, } from './transports_ws_backend.js';
+/**
+ * Builds a typed broadcast API from a set of action specs.
+ *
+ * For each spec, adds a method keyed by `spec.method` that:
+ * - Validates `input` against the spec's Zod schema (logs and returns on failure)
+ * - Creates a JSON-RPC notification from the validated input
+ * - Broadcasts via the peer (filtered by `should_deliver` when supplied)
+ *
+ * Silently returns when no transport is ready (e.g. before any clients
+ * connect). Errors during send are logged but never thrown — broadcasts are
+ * fire-and-forget from the handler's perspective.
+ *
+ * ## Typed consumer surface
+ *
+ * Consumers declare an explicit interface and pin it via the type parameter:
+ *
+ * ```ts
+ * export interface BackendActionsApi {
+ *   filer_change: (input: ActionInputs['filer_change']) => Promise<void>;
+ *   workspace_changed: (input: ActionInputs['workspace_changed']) => Promise<void>;
+ * }
+ *
+ * const api = create_broadcast_api<BackendActionsApi>({
+ *   peer: backend.peer,
+ *   specs: [filer_change_action_spec, workspace_changed_action_spec],
+ * });
+ * ```
+ *
+ * The cast is unchecked — callers must keep the interface and the `specs`
+ * array in sync. Codegen (`action_collections.gen.ts`) is a natural fit
+ * if the consumer already generates per-method type maps.
+ */
+export const create_broadcast_api = (options) => {
+    const { peer, specs, should_deliver } = options;
+    const log = options.log === undefined ? new Logger('[broadcast]') : options.log;
+    const api = {};
+    for (const spec of specs) {
+        const { method } = spec;
+        api[method] = async (input) => {
+            const parsed = spec.input.safeParse(input);
+            if (!parsed.success) {
+                log?.error(`[${method}] input validation failed:`, parsed.error.issues);
+                return;
+            }
+            // Resolve the broadcast target deterministically — no fallback.
+            // Broadcast is 1→N over a specific primary transport; falling through
+            // to "any ready transport" would send to an unexpected audience.
+            // Silent skip when no ready transport (e.g. before any clients connect).
+            const transport_name = peer.default_send_options.transport_name;
+            const transport = transport_name
+                ? peer.transports.get_transport_by_name(transport_name)
+                : peer.transports.get_current_transport();
+            if (!transport?.is_ready())
+                return;
+            const notification = create_jsonrpc_notification(method, to_jsonrpc_params(parsed.data));
+            try {
+                if (should_deliver) {
+                    if (!is_filterable_broadcast_transport(transport)) {
+                        log?.error(`[${method}] should_deliver set but transport ${transport.transport_name} does not support per-connection filtering`);
+                        return;
+                    }
+                    transport.broadcast_filtered(notification, (identity) => should_deliver(identity, method, parsed.data));
+                    return;
+                }
+                const result = await transport.send(notification);
+                if (result !== null) {
+                    log?.error(`[${method}] failed to send notification:`, result.error);
+                }
+            }
+            catch (error) {
+                log?.error(`[${method}] unexpected error:`, error);
+            }
+        };
+    }
+    return api;
+};

package/dist/actions/transports_ws_backend.d.ts

@@ -5,7 +5,7 @@
  * @module
  */
 import type { WSContext } from 'hono/ws';
-import type { JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
+import type { JsonrpcMessageFromServerToClient, JsonrpcNotification, JsonrpcRequest, JsonrpcResponseOrError, JsonrpcErrorResponse } from '../http/jsonrpc.js';
 import { type Uuid } from '../uuid.js';
 import { type Transport } from './transports.js';
 /**
@@ -24,7 +24,21 @@ export interface ConnectionIdentity {
     /** `api_token.id` for bearer-authenticated connections, else null. */
     api_token_id: string | null;
 }
-export declare class BackendWebsocketTransport implements Transport {
+/**
+ * Structural capability for transports that can broadcast with a
+ * per-connection ACL predicate. Named separately from `Transport` so the
+ * broadcast API can feature-detect without importing a concrete class.
+ *
+ * `ConnectionIdentity` is the auth-gated identity shape used today. When a
+ * second implementation (e.g. SSE backend transport) lands with a
+ * different identity, consider parameterizing on `TIdentity`.
+ */
+export interface FilterableBroadcastTransport extends Transport {
+    broadcast_filtered: (message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean) => number;
+}
+/** Type guard for `FilterableBroadcastTransport`. */
+export declare const is_filterable_broadcast_transport: (transport: Transport) => transport is FilterableBroadcastTransport;
+export declare class BackendWebsocketTransport implements FilterableBroadcastTransport {
     #private;
     readonly transport_name: "backend_websocket_rpc";
     /**
@@ -66,6 +80,17 @@ export declare class BackendWebsocketTransport implements Transport {
     close_sockets_for_token(api_token_id: string): number;
     send(message: JsonrpcRequest): Promise<JsonrpcResponseOrError>;
     send(message: JsonrpcNotification): Promise<JsonrpcErrorResponse | null>;
+    /**
+     * Broadcast to connections whose identity satisfies a predicate.
+     *
+     * Used by the broadcast API when a consumer supplies a subscription ACL hook
+     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
+     * to skip the per-connection predicate overhead.
+     *
+     * @returns the number of sockets the message was sent to
+     */
+    broadcast_filtered(message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean): number;
     is_ready(): boolean;
 }
 //# sourceMappingURL=transports_ws_backend.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAGX,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAClD,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,yBAA0B,YAAW,SAAS;;IAC1D,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4C9E,QAAQ,IAAI,OAAO;CAGnB"}
+{"version":3,"file":"transports_ws_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/transports_ws_backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAEX,gCAAgC,EAChC,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAc,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAClD,OAAO,EAA2B,KAAK,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAIzE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,UAAU,EAAE,IAAI,CAAC;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,4BAA6B,SAAQ,SAAS;IAC9D,kBAAkB,EAAE,CACnB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,KAChD,MAAM,CAAC;CACZ;AAED,qDAAqD;AACrD,eAAO,MAAM,iCAAiC,GAC7C,WAAW,SAAS,KAClB,SAAS,IAAI,4BAEqE,CAAC;AAEtF,qBAAa,yBAA0B,YAAW,4BAA4B;;IAC7E,QAAQ,CAAC,cAAc,EAAG,uBAAuB,CAAU;IAY3D;;;;;;;;OAQG;IACH,cAAc,CACb,EAAE,EAAE,SAAS,EACb,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,IAAI,EAChB,YAAY,GAAE,MAAM,GAAG,IAAW,GAChC,IAAI;IAQP;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IA0BtC;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIrD;;;;OAIG;IACH,yBAAyB,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM;IAInD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAsB/C,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA4C9E;;;;;;;;;OASG;IACH,kBAAkB,CACjB,OAAO,EAAE,gCAAgC,EACzC,SAAS,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,GAClD,MAAM;IAoBT,QAAQ,IAAI,OAAO;CAGnB"}

package/dist/actions/transports_ws_backend.js

@@ -8,6 +8,9 @@ import { jsonrpc_error_messages } from '../http/jsonrpc_errors.js';
 import { create_jsonrpc_error_response, to_jsonrpc_message_id, is_jsonrpc_request, } from '../http/jsonrpc_helpers.js';
 import { create_uuid } from '../uuid.js';
 import { WS_CLOSE_SESSION_REVOKED } from './transports.js';
+/** Type guard for `FilterableBroadcastTransport`. */
+export const is_filterable_broadcast_transport = (transport) => 'broadcast_filtered' in transport &&
+    typeof transport.broadcast_filtered === 'function';
 export class BackendWebsocketTransport {
     transport_name = 'backend_websocket_rpc';
     // Map connection IDs to WebSocket contexts
@@ -135,6 +138,35 @@ export class BackendWebsocketTransport {
         // TODO hack - remove if not ever needed, I assume this will need to be async so let's hold that assumption
         return Promise.resolve();
     }
+    /**
+     * Broadcast to connections whose identity satisfies a predicate.
+     *
+     * Used by the broadcast API when a consumer supplies a subscription ACL hook
+     * (e.g. tx's `tx_run_created` only reaches the account that owns the run).
+     * When no ACL is needed, callers should prefer `send(message)` / `#broadcast`
+     * to skip the per-connection predicate overhead.
+     *
+     * @returns the number of sockets the message was sent to
+     */
+    broadcast_filtered(message, predicate) {
+        const serialized = JSON.stringify(message);
+        let count = 0;
+        for (const [connection_id, identity] of this.#connection_identities) {
+            if (!predicate(identity))
+                continue;
+            const ws = this.#connections.get(connection_id);
+            if (!ws)
+                continue;
+            try {
+                ws.send(serialized);
+                count++;
+            }
+            catch (error) {
+                console.error('[backend websocket transport] Error broadcasting filtered to client:', error);
+            }
+        }
+        return count;
+    }
     is_ready() {
         return this.#connections.size > 0;
     }

package/package.json

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