actions/connection_registry.ts

the connection's identity

the connections to close

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

Authenticated account id. Always set.

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

The roles the endpoint required at upgrade (any-of), or empty for an ungated endpoint — what a role close target matches on.

Register a connection un-admitted — phase one of the two-phase registration an upgrade runs (module doc).

The entry is closeable at once: a close_connections whose target matches session_hash / account_id / api_token_id removes it, aborts abort_controller, and closes ws with WS_CLOSE_SESSION_REVOKED (a role target, matching required_roles, with WS_CLOSE_PERMISSION_REVOKED); the later admit then refuses. Until admitted it evicts nothing, is not counted toward the per-account cap, and receives no message.

The caller owns the entry until it is admitted: a refusal closes it with close_connection, and remove_connection drops it once its socket has closed.

Once the registry is closing (close_all_connections) the registration is born closed: nothing is inserted, abort_controller is aborted, and ws is closed with WS_CLOSE_GOING_AWAY before this returns. The id names nothing, so admit refuses it (module doc, "Shutdown").

Twin of the Rust ConnectionRegistry::register_pending, which takes the same ConnectionIdentity.

the freshly assigned connection_id (branded Uuid)

The close code the registry closed a still-pending registration with — WS_CLOSE_SESSION_REVOKED for a credential revocation, WS_CLOSE_PERMISSION_REVOKED for a role close, WS_CLOSE_GOING_AWAY for the shutdown — read once: the record is dropped by this call (and by remove_connection). null when the registry did not close it while pending. For a caller whose admit was refused, to say why; the twin of the reason the Rust ConnectionRegistry::admit refuses with.

the close code, or null

Admit a pending connection — phase two (module doc).

If the entry is gone — a revocation closed it while it was pending, or it was removed — nothing is evicted and the connection is refused. Otherwise the per-account cap is enforced exactly as in add_connection, counting only admitted connections, and the entry becomes admitted: it now receives messages, is counted, and can itself be superseded. Admitting an already-admitted connection is a no-op that answers true.

false when the connection is no longer registered — the caller closes the socket as revoked

Register a connection, admitted at once — the one-step form of register_pending + admit.

Not for an upgrade that authenticated a revocable credential: a revocation landing between that upgrade's credential check and this call closes nothing, and the connection would be admitted on a dead credential (module doc, "Two-phase registration"). This is for a connection with nothing to revoke behind it.

A session connection's identity carries its session hash for targeted revocation. A bearer token connection (api_token) carries the api_token.id so the socket can be closed when that specific token is revoked without tearing down the account's other sockets. A daemon-token connection carries null for both — it's only reachable via an account close target.

Enforces the per-account cap (max_connections_per_account): when account_id already holds the maximum, its oldest admitted connections are removed and sent a WS_CLOSE_CONNECTION_LIMIT close before the new one is inserted. A removed connection gets no further broadcast or peer request, stops counting toward the cap at once, and has its abort_controller aborted; its socket is closed when the close handshake completes. The new connection is always admitted — unless the registry is closing: then it is born closed, as in register_pending, and evicts nothing.

the freshly assigned connection_id (branded Uuid)

Remove a connection and its auth tracking data, pending or admitted, by the id register_pending / add_connection returned. Idempotent — safe to call after revocation or a cap eviction has already cleaned up, and a no-op for an unknown id.

Keyed by id rather than by WSContext because a runtime adapter may hand each socket event its own context object (@hono/bun does), so the one a close event carries can't identify the connection.

Removal only: the socket is not closed and the registered abort_controller is not aborted — the caller that ends a socket does both. What was waiting to be written to it is dropped.

For a socket that has closed (an adapter's close event): on a connection the registry closed it also drops the close deadline, so calling it while that socket is still closing leaves a client that is not reading uncut.

Close one connection, pending or admitted, with code and reason — the close register_action_ws makes for a heartbeat timeout, an oversized message, a failed on_socket_open, and a refused admission. Not to be confused with close_connections, which closes every connection a ConnectionCloseTarget names.

The connection is removed and its controller aborted at once; frames still waiting for the socket are handed to it ahead of the close frame while its buffer has room and discarded otherwise, and the close frame is held to WS_CLOSE_WRITE_TIMEOUT (module doc, "Outbound bound"). A socket whose close throws is logged, not thrown.

false when the connection is not registered — nothing was closed

Close every connection target names, including a registration still pending admission (connection_identity_matches). Not to be confused with close_connection, which closes one connection by id.

A credential target — session, token, account — closes with WS_CLOSE_SESSION_REVOKED. A token close takes just that token's sockets, so revoking one token — or evicting one past the token cap — leaves the account's session sockets and other tokens' sockets open.

A role target — a revoked global grant of a role the upgrade gate admitted on — closes with WS_CLOSE_PERMISSION_REVOKED, not a revocation's code: the credential is still good. It over-closes an any-of gate: an endpoint gated on several roles admits an account holding any one of them, but this closes on the loss of any listed role, without checking whether the account still holds another. The client can reconnect when it still qualifies. The account's sockets on endpoints that did not list role, and on ungated ones, stay open.

the number of sockets closed

Close every connection, pending or admitted, with WS_CLOSE_GOING_AWAY — the shutdown close AppServer.close runs. Not a revocation: the client reconnects under its ordinary backoff.

Each closed connection is removed and its controller aborted, as a revocation does, so its heartbeat timer stops and nothing more dispatches on it. A socket whose close throws does not stop the loop.

Leaves the registry closing, for good: every later registration is born closed (module doc, "Shutdown"). A second call closes nothing.

the number of sockets closed

Whether close_all_connections has run — the registry is shutting down and every registration from now on is born closed (module doc, "Shutdown"). For telemetry and logs: register_action_ws reads it to say why an upgrade was refused.

Broadcast a notification to every admitted connection — a registration pending admission is not a connection yet. A server→client *request* has no single target here; that is request_connection.

A connection the message overflows is closed and not counted (module doc, "Outbound bound").

the number of connections that accepted the message

Broadcast to admitted connections whose identity satisfies a predicate. A registration pending admission is skipped before the predicate runs.

Used by the broadcast API when a consumer supplies a subscription ACL hook (e.g. an event that only reaches the account that owns the resource it reports). When no ACL is needed, callers should prefer broadcast to skip the per-connection predicate overhead.

A connection the message overflows is closed and not counted (module doc, "Outbound bound").

the number of connections that accepted the message

Send a message to every admitted 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 an account close target on the send side: every connection for the account (session, bearer, and daemon-token) receives the message.

the number of connections that accepted the message

Send one serialized frame to a single admitted connection — the path register_action_ws sends every response, error frame, and socket-scoped notification through.

Never waits and never throws. A frame the connection's outbound budget does not fit closes the connection with WS_CLOSE_OUTBOUND_OVERFLOW before this returns (module doc, "Outbound bound").

false when the frame was not accepted: the connection is not registered, is still pending admission, or was just closed for the overflow this frame caused

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). A connection still pending admission answers connection_gone like an unknown one. 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.

the client's success result, or a PeerRequestError

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.

whether a pending request was resolved

Whether a connection is still registered — and admitted: a registration pending admission answers false, like every other reader of the registry.

register_action_ws checks it before dispatching each inbound message, so a socket the server has closed — revoked, superseded by the cap, or refused at admission — dispatches nothing more while its close handshake is still in flight. The twin of the Rust ConnectionRegistry::is_registered.

Number of currently admitted WebSocket connections.

Read-only counter intended for telemetry, logging, and tests. A registration still pending admission is not a connection yet and is counted by pending_connection_count instead. Includes connections that have been closed by the peer but not yet removed by the WS adapter's onClose callback.

Number of registrations awaiting admission — between register_pending and admit (or their refusal). Each lives for one credential re-check, so a count that stays high means upgrades are stalling there. For telemetry and tests.

Max concurrent connections per account_id, across every credential type (session, API token, daemon token — none exempt). The policy is evict-oldest: a connection past the cap is always admitted, and the account's oldest connections are closed with WS_CLOSE_CONNECTION_LIMIT to make room. Refusing the new one instead would let half-open sockets lock a user out with their own dead connections, and would let a stolen credential fill the slots ahead of the real user — revocation is the fix for a stolen credential, and evict-oldest never stands in its way.

The cap is per registry: endpoints sharing one registry share one count per account. null disables it.

Byte budget of the frames waiting to be written to one connection. Each waiting frame is charged its UTF-8 length plus OUTBOUND_FRAME_OVERHEAD_BYTES; a frame that does not fit closes the connection with WS_CLOSE_OUTBOUND_OVERFLOW, and a frame is always accepted when nothing is waiting, so one message larger than the whole budget is still deliverable (module doc, "Outbound bound"). Not derived from the inbound message cap.

Logger for cap evictions, outbound overflows and stalls, and failed sends or closes. An overflow or a stall logs one warn line — the connection, its account, and what was waiting. A cap eviction logs at info — the account, how many connections were closed, and the cap — so an operator can see a client that keeps meeting it. Unset falls back to a [ws] logger; null silences it. register_action_ws passes its own logger to the registry it creates.