Rooms over the WebSocket connection registry: members seated in a room by
key, relayed messages, per-member state, and occupancy watches. The TS twin
of the Rust spine's fuz_realtime::RoomRegistry.
A room is a key (RoomId) the consumer chooses — e.g. a voice room keyed
by a space id — holding seats and watches. A seat is one actor's
membership on one connection, with a random MemberId that clients address
each other by (a connection id never reaches the wire) and a small
client-encoded state string. Seats are keyed by connection and actor: a
connection whose requests act as different actors of one account (the
dispatcher's acting selector) holds a seat per actor, and a leave, send,
or state set touches only the acting actor's own seat; an event skips the
seat that caused it, not its connection. A watch sees the members without
joining; it is one per connection and room, whichever actor last asked for
it. The registry relays opaque payloads between members and knows nothing of
what they carry. Rooms live in memory and die with the process: a restart
drops every room and clients rejoin.
The verbs over it — the specs, the authorizer hook, the per-connection
limiter — are actions/room_action_specs.ts and actions/room_actions.ts;
this module holds the state and the fan-out.
One step, one order
The Rust registry holds rooms, seats, watches, joins in flight, and the
per-connection and per-actor indexes under one lock, since exclusivity and
eviction span rooms. Here every method runs to completion without an
await, so JavaScript's single thread gives the same guarantee: no check is
ever separated from the mutation it guards. Every notification is queued
inside that step through ConnectionRegistry.send_to, which never waits, so
each room's events carry a seq that orders them: one counter per room,
bumped by every event in the room. A room with no seats and no watches is
deleted; a new one starts its seq again at zero.
seq orders a room's events, and lets a client drop the events at or below
the snapshot a join or watch answered; it is not contiguous per client (an
addressed message bumps it, and only the addressee sees that one), and it
restarts when a room is deleted and created again. Event order across rooms
is unspecified; within a room it is the seq.
Nothing here waits: a recipient that cannot take a frame is closed for the
overflow (WS_CLOSE_OUTBOUND_OVERFLOW) by the connection registry, and its
seats are then released like any other disconnect.
Two-phase join
A join is reserve_seat, the consumer's authorizer, then admit_seat. The
reserve puts the join in flight before the authorizer reads anything,
refused when the socket has already closed, and returns a PendingSeat;
admit_seat always consumes it, and a caller that never reaches the admit
calls withdraw (in a finally — the Rust guard's drop). While in flight
the join is reachable: an eviction that names its actor or room refuses it,
one that names a scope marks it, so the admit refuses when the verdict's
scope is that one, and the connection's own leave of the room refuses it
as superseded. That closes the race of an eviction against an authorizer: a
consumer evicts after its write commits, and its authorizer reads under READ
COMMITTED, so the eviction either precedes the reserve — then its commit
precedes the authorizer's read, which denies — or follows it and reaches the
join in flight.
The argument holds only for authority the authorizer reads inside that
window, after the reserve, from the database. Anything loaded before the
reserve — the request's own role grants, which the dispatcher reads before
the handler runs — may predate an eviction that also precedes the reserve
and so found nothing in flight to reach: the stale read would admit an
evicted actor. The authorizer hook (RoomAuthorize) therefore gets the
caller's ids and the database, never the request's grants. Watches run the
same two phases (reserve_watch, admit_watch).
Unlike the Rust join, whose request future is dropped when its socket
closes, a TS join keeps running after the close: the admit refuses it, since
the close marks every join in flight on the connection and the admit reads
the socket's signal.
The admit seats the member unless it was refused meanwhile, its socket
closed, or the room is full. A refused join displaces nothing.
Exclusivity and the rejoin guard
With exclusive an actor holds one seat across the registry: the newest
admitted join wins (two sockets racing settle by which admits last, not
which sent first), and the seat it displaces hears room_seat_lost with
reason moved and moved_to, the new seat's room. Either way a connection
holds one seat per room for each actor; joining again as that actor moves its
old seat the same way.
A seat whose socket died never hears that it moved. Its client, on
reconnecting, rejoins naming the seat it held (rejoin_of), and must not
take back the seat its actor holds now. So an exclusive registry keeps a
short per-actor tombstone of seats that ended without a leave: each seat
moved away, and each released by its disconnect, which counts as moved once
the actor is seated again by any other join. A rejoin naming a moved seat is
refused (seat_moved) instead of seated; one naming a seat released by its
disconnect and not moved since is seated, as is any other. Tombstones last
ROOM_REJOIN_TOMBSTONE_TTL_MS, at most ROOM_REJOIN_TOMBSTONES_PER_ACTOR
per actor; past either bound a rejoin is seated like a fresh join.
Disconnect
The first seat or watch a connection reserves adds one listener to the
connection's socket signal (ConnectionRegistry.socket_signal — the signal
every close path aborts), and the connection keeps it for its life, however
many joins and leaves it makes. When the signal aborts, the registry
releases every seat (room_member_left with reason disconnected), watch,
and join in flight the connection holds — on the next microtask, as the Rust
waiter runs as its own task, so a close made inside a fan-out (an overflow)
never re-enters the registry mid-step.
Eviction
evict is the consumer's call when its own authority changes, made after
the change commits: by actor, by actor within a scope, by room, or by scope
(RoomEvictTarget), covering seats, watches, and joins in flight alike, so
an evicted actor keeps neither a seat nor a watch. Its socket still hears the
room while another actor of the same account is seated there or holds the
watch, on that actor's own authority.
Bounds
Seats are bounded by the rooms' cap (and by one per actor when exclusive),
watches per connection, joins in flight by the connection's in-flight
request cap, listeners at one per connection, and tombstones as above.