actions/transports_ws_backend.ts view source
import {BackendWebsocketTransport} from '@fuzdev/fuz_app/actions/transports_ws_backend.js'; inheritance
transport_name
type "backend_websocket_rpc"
add_connection
Add a new WebSocket connection with auth info.
Session connections pass a token hash for targeted revocation.
Bearer token connections (api_token) pass the api_token.id so the
socket can be closed when that specific token is revoked without
tearing down the account's other sockets. Daemon-token connections
pass null for both — they're only reachable via
close_sockets_for_account.
type (ws: WSContext<unknown>, token_hash: string | null, account_id: string & $brand<"Uuid">, api_token_id?: string | null): string & $brand<"Uuid">
ws
WSContext<unknown>token_hash
string | nullaccount_id
string & $brand<"Uuid">api_token_id
string | nullnullstring & $brand<"Uuid">the freshly assigned connection_id (branded Uuid)
remove_connection
Remove a WebSocket connection and its auth tracking data. Idempotent — safe to call after revocation has already cleaned up.
type (ws: WSContext<unknown>): void
ws
WSContext<unknown>voidclose_sockets_for_session
Close all sockets associated with a specific session token hash.
type (token_hash: string): number
token_hash
stringnumberthe number of sockets closed
close_sockets_for_account
Close all sockets associated with a specific account.
type (account_id: string & $brand<"Uuid">): number
account_id
string & $brand<"Uuid">numberthe number of sockets closed
close_sockets_for_token
Close all sockets associated with a specific API token.
Used on token_revoke audit events so revoking one token doesn't
tear down the account's session-authenticated sockets or other
tokens' sockets.
type (api_token_id: string): number
api_token_id
stringnumberthe number of sockets closed
send
type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }, options?: TransportSendOptions | undefined): Promise<...>
message
{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }options?
TransportSendOptions | undefinedPromise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }>broadcast_filtered
Broadcast to connections whose identity satisfies a predicate.
Used by the broadcast API when a consumer supplies a subscription ACL hook
(e.g. zap's zap_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.
type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; } | { ...; }, predicate: (identity: ConnectionIdentity) => boolean): number
message
{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; } | { ...; }predicate
(identity: ConnectionIdentity) => booleannumberthe number of sockets the message was sent to
send_to_account
Send a message to every socket bound to a specific account.
Targeted per-account fan-out for any flow where the delivery target
is a single known account. Prefer this over broadcast_filtered when
the filter is exactly "this account_id"; reach for broadcast_filtered
when the ACL is an arbitrary predicate over ConnectionIdentity.
Mirrors close_sockets_for_account on the send side: every connection
for the account (session, bearer, and daemon-token) receives the
message.
type (account_id: string & $brand<"Uuid">, message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { ...; }; } | { ...; }): number
account_id
string & $brand<"Uuid">message
{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; } | { ...; }numberthe number of sockets the message was sent to
request_connection
Initiate a JSON-RPC request to a single connected client and await its reply — the server→client request/response direction (ActionPeer).
Sends {jsonrpc, method, params, id} to exactly the connection_id
socket (never a broadcast) and registers a pending entry scoped to that
connection. Resolves when the client's matching reply arrives (routed in
via resolve_peer_response), the deadline elapses (timeout), the
per-connection cap is hit (too_many_in_flight), or the socket closes
(connection_gone). Never throws — every failure is a PeerRequestError.
Delegates correlation to #pending (id allocation, deadline, cap, drain);
this method owns only the socket lookup + the send. Server-issued ids are
s-prefixed so a malicious client echoing a non-s id (or an id it chose
for its own request) matches nothing.
type (connection_id: string & $brand<"Uuid">, method: string, params: { [x: string]: unknown; } | undefined, options?: PeerRequestOptions | undefined): Promise<...>
connection_id
string & $brand<"Uuid">method
stringparams
{ [x: string]: unknown; } | undefinedoptions?
PeerRequestOptions | undefinedPromise<PeerRequestOutcome>the client's success result, or a PeerRequestError
resolve_peer_response
Route an inbound client reply to the matching pending server→client
request on connection_id (delegates to #pending.resolve).
Returns false when no entry matches — an unsolicited, cross-connection,
or already-settled reply — so the caller drops it. Per-connection scoping
means a reply arriving on the wrong socket resolves nothing.
type (connection_id: string & $brand<"Uuid">, response: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { ...; }; }): boolean
connection_id
string & $brand<"Uuid">response
{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: JSONType; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }booleanwhether a pending request was resolved
is_ready
type (): boolean
booleanget_connection_count
Number of currently tracked WebSocket connections.
Read-only counter intended for telemetry, logging, and tests.
Counts every entry in the connection map — including connections
that have been closed by the peer but not yet removed by the WS
adapter's onClose callback.
type (): number
number