actions/room_registry.ts

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.

view source

Declarations
#

16 declarations

MAX_POISONED_SCOPES
#

actions/room_registry.ts view source

16 import {MAX_POISONED_SCOPES} from '@fuzdev/fuz_app/actions/room_registry.js';

The most scope evictions one join or watch in flight records; past it the join or watch is refused outright, whatever its verdict's scope.

A client sees what any eviction of its request in flight answers: the join or watch is refused as if the room were missing (room_not_found from the verbs). It trips only when more distinct scopes than this are evicted during one authorizer read. Both twins hold the same bound.

PendingSeat
#

actions/room_registry.ts view source

import {PendingSeat} from '@fuzdev/fuz_app/actions/room_registry.js';

A join in flight, between RoomRegistry.reserve_seat and RoomRegistry.admit_seat. The admit consumes it; a caller that never reaches the admit — a refusal, a cancelled request, a throwing authorizer — calls withdraw, which removes it (in a finally, as the Rust guard's drop does). Withdrawing an admitted or withdrawn seat does nothing.

member_id

The member id the seat will have once admitted.

type Branded

readonly

room_id

The room the join is for.

type string

readonly

constructor

type new (member_id: Branded<string, "Uuid">, room_id: string): PendingSeat

member_id

type Branded

room_id

type string

withdraw

Withdraw the join, if it is still in flight.

type (): void

returns void

PendingWatch
#

actions/room_registry.ts view source

import {PendingWatch} from '@fuzdev/fuz_app/actions/room_registry.js';

A watch in flight, between RoomRegistry.reserve_watch and RoomRegistry.admit_watch — the watch half of PendingSeat.

room_id

The room the watch is for.

type string

readonly

constructor

type new (room_id: string): PendingWatch

room_id

type string

withdraw

Withdraw the watch, if it is still in flight.

type (): void

returns void

ROOM_REJOIN_TOMBSTONE_TTL_MS
#

actions/room_registry.ts view source

number import {ROOM_REJOIN_TOMBSTONE_TTL_MS} from '@fuzdev/fuz_app/actions/room_registry.js';

How long an exclusive registry remembers a seat that ended without a leave, for the rejoin guard (module doc). Twin of the Rust ROOM_REJOIN_TOMBSTONE_TTL (15 minutes).

ROOM_REJOIN_TOMBSTONES_PER_ACTOR
#

actions/room_registry.ts view source

8 import {ROOM_REJOIN_TOMBSTONES_PER_ACTOR} from '@fuzdev/fuz_app/actions/room_registry.js';

The most tombstones an exclusive registry keeps per actor; past it the oldest goes.

RoomError
#

actions/room_registry.ts view source

RoomError

type "connection_closed" | "evicted" | "join_superseded" | "seat_moved" | "full" | "not_joined" | "member_not_found" | "payload_too_large" | "state_too_large" | "watch_limit"

import type {RoomError} from '@fuzdev/fuz_app/actions/room_registry.js';

A room operation's refusal — the twin of the Rust RoomError:

  • connection_closed — the connection is gone or closing, so nothing is seated on it
  • evicted — an eviction reached the join or watch while it was in flight
  • join_superseded — the connection left the room while its join was in flight
  • seat_moved — the seat a rejoin names moved elsewhere since
  • full — the room seats its maximum already
  • not_joined — the connection holds no seat in the room
  • member_not_found — the addressee is not a member of the room
  • payload_too_large — the payload is over max_payload_bytes
  • state_too_large — the state is over max_state_bytes
  • watch_limit — the connection watches max_watches_per_connection rooms already

RoomEvicted
#

actions/room_registry.ts view source

RoomEvicted import type {RoomEvicted} from '@fuzdev/fuz_app/actions/room_registry.js';

What one RoomRegistry.evict removed.

seats

Seated members removed.

type number

watches

Watches removed.

type number

pending

Joins and watches in flight it reached: refused outright by an actor or room target, marked by a scope target (refused at admission only if their verdict names the scope).

type number

RoomEvictTarget
#

actions/room_registry.ts view source

RoomEvictTarget

type { readonly kind: "actor"; readonly actor_id: Branded<string, "Uuid">; } | { readonly kind: "actor_in_scope"; readonly actor_id: Branded<string, "Uuid">; readonly scope: string; } | { readonly kind: "room"; readonly room_id: string; } | { readonly kind: "scope"; readonly scope: string; }

import type {RoomEvictTarget} from '@fuzdev/fuz_app/actions/room_registry.js';

What RoomRegistry.evict removes.

RoomJoined
#

actions/room_registry.ts view source

RoomJoined import type {RoomJoined} from '@fuzdev/fuz_app/actions/room_registry.js';

What an admitted join answers: the seat, and the room as of seq — the seq of the joiner's own room_member_joined, so a client drops every buffered event at or below it. members holds every member, the joiner included, in seating order.

room_id

type string

readonly

member_id

type Branded

readonly

seq

type number

readonly

members

type RoomMember[]

readonly

topology

type "mesh"

readonly

RoomRegistry
#

actions/room_registry.ts view source

import {RoomRegistry} from '@fuzdev/fuz_app/actions/room_registry.js';

The room registry: see the module doc.

Build one over the connection registry its WebSocket endpoint uses (new RoomRegistry(connections, options)); a connection id from any other registry names no socket here, so its reserves refuse as connection_closed. Two WS endpoints sharing one connection registry share one room registry.

options

The registry's resolved bounds and rules.

type RoomRegistryLimits

readonly

constructor

type new (connections: ConnectionRegistry, options?: RoomRegistryOptions): RoomRegistry

connections

options?

optional default {}

throws

  • Error - when a bound is not an integer in range (`max_members_per_room` at least 1, the byte and watch bounds at least 0)

reserve_seat

Phase one of a join: put it in flight before the authorizer runs (module doc, "Two-phase join").

type (request: RoomSeatRequest): RoomResult<PendingSeat>

request

returns RoomResult

the join in flight, or connection_closed when the connection is gone or closing, or seat_moved when the request is a rejoin of a seat that has moved (exclusive registries)

mutates

  • this — records the join in flight, and on the connection's first reserve adds its one disconnect listener

admit_seat

Phase two of a join: seat the member (module doc). Consumes pending, whatever it answers.

Moves the actor's own seat in the room on this connection, and on an exclusive registry the actor's seat anywhere, to this one: each hears room_seat_lost with reason moved, its room room_member_left with reason moved. Then the room hears room_member_joined.

type (pending: PendingSeat, admit?: RoomSeatAdmit): RoomResult<RoomJoined>

pending

admit?

optional default {}
returns RoomResult

the seat and the room, or state_too_large; evicted, join_superseded, or connection_closed when the join was refused in flight or its socket closed; seat_moved for a rejoin of a moved seat; full when the room seats its cap (the lower of the registry's and admit.max_members) after the moves this join makes

throws

  • Error - when `admit.max_members` is not a non-negative integer (a consumer's authorizer bug), checked once the join passes its other refusals; `pending` is consumed all the same

mutates

  • this — seats the member, moving what the join displaces

leave

End actor_id's seat in the room on the connection (room_member_left with reason left), and refuse that actor's joins of the room still in flight on it (join_superseded). Another actor's seat on the same connection is untouched. Idempotent.

type (connection_id: Branded<string, "Uuid">, actor_id: Branded<string, "Uuid">, room_id: string): boolean

connection_id

type Branded

actor_id

type Branded

room_id

type string
returns boolean

true when it ended or refused anything

mutates

  • this — removes the seat, marks the joins in flight

send

Relay payload from actor_id's seat in the room on the connection to the member to, or with null to every other member (room_message). Watchers get no messages.

type (connection_id: Branded<string, "Uuid">, actor_id: Branded<string, "Uuid">, room_id: string, to: Branded<string, "Uuid"> | null, payload: string): RoomResult<...>

connection_id

type Branded

actor_id

type Branded

room_id

type string

to

type Branded | null

payload

type string
returns RoomResult

the message's seq, or payload_too_large, not_joined, or member_not_found when to names no member of the room — or names the sender's own seat: a seat never addresses itself

set_state

Set actor_id's member state in the room on the connection, telling the other members and the watchers (room_member_state).

type (connection_id: Branded<string, "Uuid">, actor_id: Branded<string, "Uuid">, room_id: string, member_state: string): RoomResult<number>

connection_id

type Branded

actor_id

type Branded

room_id

type string

member_state

type string
returns RoomResult

its seq, or state_too_large or not_joined

reserve_watch

Phase one of a watch, as reserve_seat is of a join.

type (connection_id: Branded<string, "Uuid">, actor_id: Branded<string, "Uuid">, room_id: string): RoomResult<PendingWatch>

connection_id

type Branded

actor_id

type Branded

room_id

type string
returns RoomResult

the watch in flight, or connection_closed, or watch_limit when the connection watches its maximum of other rooms

mutates

  • this — records the watch in flight, and on the connection's first reserve adds its one disconnect listener

admit_watch

Phase two of a watch: from now on the connection hears the room's member events. Watching a room already watched answers its occupancy again and takes the new scope and actor. Consumes pending, whatever it answers.

type (pending: PendingWatch, scope?: string | null): RoomResult<{ room_id: string; seq: number; members: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }[]; }>

pending

scope?

type string | null
optional default null
returns RoomResult

the room's occupancy, or evicted or connection_closed when the watch was refused in flight or its socket closed, or watch_limit

mutates

  • this — records the watch

unwatch

Stop the connection's watch of the room. Idempotent. A watch still in flight is untouched — a client stops one by cancelling its request.

type (connection_id: Branded<string, "Uuid">, room_id: string): boolean

connection_id

type Branded

room_id

type string
returns boolean

true when it was watching

evict

Remove the seats and watches target names, and refuse its joins and watches in flight (module doc, "Eviction"). Each removed seat hears room_seat_lost, its room room_member_left, each removed watch room_watch_ended, all with reason.

A join in flight has no scope until its verdict, so a scope target marks it instead, and its admit refuses when its verdict's scope is that one; a join marked by more scopes than MAX_POISONED_SCOPES is refused outright.

type (target: RoomEvictTarget, reason: "evicted" | "room_closed"): RoomEvicted

target

reason

returns RoomEvicted

what it removed and reached

occupancy

The room's members as of its current seq.

type (room_id: string): { room_id: string; seq: number; members: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }[]; } | null

room_id

type string
returns RoomOccupancy | null

the occupancy, or null when no room by that id exists (no seats and no watches)

clear

Drop every room, seat, watch, and tombstone, telling no one, and refuse every join and watch in flight (evicted). For a test server's reset between cases; the connections' disconnect listeners stay.

type (): void

returns void

mutates

  • this — empties the registry

connection_count

Connections the registry tracks — each that reserved a seat or watch and has not closed — each holding the one disconnect listener. For tests and telemetry.

type (): number

returns number

RoomRegistryLimits
#

actions/room_registry.ts view source

RoomRegistryLimits import type {RoomRegistryLimits} from '@fuzdev/fuz_app/actions/room_registry.js';

A registry's resolved options — every bound set.

exclusive

type boolean

readonly

max_members_per_room

type number

readonly

max_payload_bytes

type number

readonly

max_state_bytes

type number

readonly

max_watches_per_connection

type number

readonly

topology

type "mesh"

readonly

RoomRegistryOptions
#

actions/room_registry.ts view source

RoomRegistryOptions import type {RoomRegistryOptions} from '@fuzdev/fuz_app/actions/room_registry.js';

A RoomRegistry's bounds and rules; each omitted field takes its default.

exclusive?

One seat per actor across the whole registry: an admitted join moves the actor's other seat, wherever it is, and the newest admitted seat wins (room_seat_lost with reason moved to the seat it displaced). Default false.

type boolean

readonly

max_members_per_room?

The most members a room seats, a positive integer; an authorizer's verdict may lower it for one join, never raise it. Default DEFAULT_ROOM_MAX_MEMBERS.

type number

readonly

max_payload_bytes?

The longest message payload, in UTF-8 bytes. Default DEFAULT_ROOM_MAX_PAYLOAD_BYTES.

type number

readonly

max_state_bytes?

The longest member state, in UTF-8 bytes. Default DEFAULT_ROOM_MAX_STATE_BYTES.

type number

readonly

max_watches_per_connection?

The most rooms one connection watches at once. Default DEFAULT_ROOM_MAX_WATCHES_PER_CONNECTION.

type number

readonly

topology?

What the join answers as the room's topology. Default 'mesh'.

type "mesh"

readonly

now?

The monotonic clock the tombstones age by, in ms. Default performance.now; a test passes its own to drive the expiry.

type (): number

readonly
returns number

RoomResult
#

actions/room_registry.ts view source

RoomResult<T>

type ({ ok: true; } & { value: T; }) | ({ ok: false; } & { error: RoomError; })

import type {RoomResult} from '@fuzdev/fuz_app/actions/room_registry.js';

A room operation's outcome: its value, or its refusal.

generics

RoomResult<T>
T

RoomScope
#

actions/room_registry.ts view source

string import type {RoomScope} from '@fuzdev/fuz_app/actions/room_registry.js';

A consumer's tag for the authority a seat or watch was admitted under, from the authorizer's verdict — e.g. the group whose membership let the actor in. Eviction targets it: when that authority changes, the consumer evicts the scope, or an actor within it.

RoomSeatAdmit
#

actions/room_registry.ts view source

RoomSeatAdmit import type {RoomSeatAdmit} from '@fuzdev/fuz_app/actions/room_registry.js';

What the authorizer's verdict and the request add at admission.

scope?

The authority the seat is admitted under, for eviction.

type string | null

readonly

max_members?

This join's member cap, a non-negative integer, below the registry's; omitted keeps the registry's.

type number | null

readonly

state?

The member's initial state.

type string | null

readonly

RoomSeatRequest
#

actions/room_registry.ts view source

RoomSeatRequest import type {RoomSeatRequest} from '@fuzdev/fuz_app/actions/room_registry.js';

A join to seat: who, on which connection, into which room.

connection_id

type Branded

readonly

actor_id

type Branded

readonly

room_id

type string

readonly

rejoin_of?

The seat this join takes up again after a reconnect — refused as seat_moved on an exclusive registry when that seat has moved since (module doc); ignored otherwise.

type Branded | null

readonly

Depends on
#

Imported by
#