actions/register_action_ws.ts

Mount path (e.g., /api/ws).

The Hono app to mount on.

Hono's upgradeWebSocket helper from the runtime adapter.

The actions registered on this endpoint — each carries a spec (drives method lookup, per-action auth, input/output validation) and an optional handler (omit for client-only specs like inbound notifications). Spread protocol_actions from actions/protocol.ts here to complete the disconnect-detection + per-request cancel pairing with the frontend client.

Pool-level DB. The dispatcher wraps in db.transaction for side_effects: true actions, the same way HTTP RPC does. Per-message authorization phase reads through this pool.

Audit writes and other rollback-resilient fire-and-forget calls run through AppDeps.audit.emit from the action factory's closure — the dispatcher never holds an audit-side pool reference; the bound emitter owns the pool.

Existing transport to register connections with. When omitted, a fresh one is created and returned in the result. Pass your own to keep a handle for create_ws_auth_guard and send_to/broadcast.

Server-side heartbeat policy. Default-on (receive-silence detection, 60s timeout). false disables the timer entirely — only do this if the upstream stack (TCP keepalive, Cloudflare idle timeout, etc.) already owns disconnect detection. Pass an object to tune the timeout.

Optional per-message delay for testing loading states. Ignored when 0.

Optional logger; defaults to [ws] namespace.

Called once per socket, after the transport registers the connection. Awaited before any message is dispatched. Throwing logs an error and closes the socket with an internal_error frame — a failing bootstrap should not leave a partially-initialized socket alive.

Called once per socket on close, *before* the transport removes the connection. Receives connection_id and identity captured at open time, so it is safe to read even when the audit guard has already torn down the transport's internal state. Errors are logged and swallowed.

Per-IP rate limiter consulted for actions whose spec declares rate_limit: 'ip' or 'both'. null (or omitted) disables the IP check. Same limiter is shared with the HTTP RPC dispatcher so one budget covers both transports per action. Resolved at upgrade time and reused for every message on the socket.

Per-account rate limiter consulted for actions whose spec declares rate_limit: 'account' or 'both'. Keyed on request_context.account.id. null (or omitted) disables the account check. Same limiter is shared with the HTTP RPC dispatcher.

The transport bound to the endpoint — supplied or freshly created.

Receive-silence (ms) past which the server closes the socket with WS_CLOSE_SERVER_HEARTBEAT_TIMEOUT. Any incoming message resets the counter — chatty clients never trip it. First timeout window after socket open is exempt (cold-start grace).

The raw WebSocket context at close time.

Connection id captured at open time.

Auth identity captured at open time — still valid even if the transport already cleaned up.

The raw WebSocket context — exposed for edge cases; prefer notify for sends.

Connection id assigned by BackendWebsocketTransport.add_connection.

Auth identity registered for this connection.

Send a JSON-RPC notification to just this socket. Mirrors ctx.notify on per-message handler contexts — same socket-scoped semantics.

Fires when this socket closes — threaded through to every handler's ctx.signal.