actions/notification_sender.ts

Pushing a server-initiated JSON-RPC notification to an account's live WebSocket connections.

Why the handler context carries it. A notification carries a domain payload (an offer, a revoked grant) that only the handler holds, so the handler builds the message and queues the send after its commit (queue_offer_notification in auth/role_grant_offer_notifications.ts). perform_action puts the sender on every ActionContext, so no action factory takes one and none can be wired with the wrong one: an offer created over HTTP RPC must reach the recipient's sockets on the WebSocket registry, which a sender bound to any other registry would miss silently.

Why a fan-out. create_app_backend puts one RealtimeNotificationSender on AppDeps.notification_sender, and create_app_server adds every WebSocket connection registry it mounts. The registries are created at mount, after the RPC and WebSocket action factories run, so a sender read at send time is the only one that reaches them. A server mounting no WebSocket endpoint holds an empty fan-out, and its sends reach no one.

Twin of the Rust spine's NotificationSender and NoopNotificationSender; the Rust backend serves one connection registry on every endpoint, which the fan-out stands in for.

view source

Declarations
#

4 declarations

create_realtime_notification_sender
#

noop_notification_sender
#

NotificationSender
#

actions/notification_sender.ts view source

NotificationSender import type {NotificationSender} from '@fuzdev/fuz_app/actions/notification_sender.js';

Send a JSON-RPC notification to every admitted socket bound to an account.

ConnectionRegistry satisfies this structurally — its send_to_account accepts the broader JsonrpcMessageFromServerToClient. The interface stays narrow so handlers don't couple to the concrete registry and tests can capture sends with no WebSocket machinery.

Returns how many sockets accepted the notification — bookkeeping, not a delivery receipt; 0 means the account has no live socket.

send_to_account

type (account_id: Branded<string, "Uuid">, message: { jsonrpc: "2.0"; method: string; params?: ({} & Record<string, unknown>) | undefined; } & Record<string, unknown>): number

account_id

type Branded

message

returns number

RealtimeNotificationSender
#

actions/notification_sender.ts view source

RealtimeNotificationSender import type {RealtimeNotificationSender} from '@fuzdev/fuz_app/actions/notification_sender.js';

One NotificationSender over every WebSocket connection registry of a backend.

Each send reaches every member and returns the sum, so an account with sockets on two registries hears the notification on each. A member that throws does not stop the others: every member is called, then the first error is thrown for the caller (the post-commit flush) to log.

inheritance

add

Add a registry's sender, returning a remover for this addition.

Membership is by reference: a sender added twice — two endpoints sharing one registry — is one member, and every send reaches it once, so no socket hears a notification twice. Each add is counted, and its remover releases only that count: the sender stays a member until every addition is removed. Calling a remover again is a no-op.

type (sender: NotificationSender): () => void

sender

the registry's sender

returns () => void

a remover for this addition, idempotent

member_count

Count of distinct members — introspection for tests and diagnostics.

type (): number

returns number

Depends on
#

Imported by
#