actions/transports_ws_backend.ts

Backend WebSocket transport — manages server-side WebSocket connections with session tracking and revocation support.

Declarations
#

4 declarations

view source

BackendWebsocketTransport
#

actions/transports_ws_backend.ts view source

inheritance

transport_name

readonly

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
type WSContext<unknown>
token_hash
type string | null
account_id
type string & $brand<"Uuid">
api_token_id
type string | null
default null
returns string & $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
type WSContext<unknown>
returns void

close_sockets_for_session

Close all sockets associated with a specific session token hash.

type (token_hash: string): number

token_hash
type string
returns number

the 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
type string & $brand<"Uuid">
returns number

the 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
type string
returns number

the 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
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }
options?
type TransportSendOptions | undefined
optional
returns Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [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; };...

send

type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }, options?: TransportSendOptions | undefined): Promise<...>

message
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }
options?
type TransportSendOptions | undefined
optional
returns Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [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; };...

send

type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }, options?: TransportSendOptions | undefined): Promise<...>

message
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }
options?
type TransportSendOptions | undefined
optional
returns Promise<{ [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [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. 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.

type (message: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [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
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [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
type (identity: ConnectionIdentity) => boolean
returns number

the 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: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { ...; }; } | { ...; }): number

account_id
type string & $brand<"Uuid">
message
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [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; }; } | { ....
returns number

the number of sockets the message was sent to

is_ready

type (): boolean

returns boolean

get_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

returns number

ConnectionIdentity
#

actions/transports_ws_backend.ts view source

ConnectionIdentity

Auth identity attached to a single WebSocket connection.

One record per connection. token_hash is set for cookie-session connections, api_token_id for bearer (api_token) connections, and both are null for daemon-token connections (reachable only via BackendWebsocketTransport.close_sockets_for_account).

token_hash

Blake3 session token hash, or null for non-session credentials.

type string | null

account_id

Authenticated account id. Always set.

type Uuid

api_token_id

api_token.id for bearer-authenticated connections, else null.

type string | null

FilterableBroadcastTransport
#

actions/transports_ws_backend.ts view source

FilterableBroadcastTransport

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.

inheritance

extends:

broadcast_filtered

type ( message: JsonrpcMessageFromServerToClient, predicate: (identity: ConnectionIdentity) => boolean, ) => number

is_filterable_broadcast_transport
#

Depends on
#

Imported by
#