actions/room_client.svelte.ts

The frontend side of rooms: RoomClient keeps, for each room a page joins or watches, a reactive RoomState — its members and their state, the caller's own seat — over the WS-only room_* verbs and the room_* notifications the server pushes (actions/room_action_specs.ts).

Desired state, converged one request at a time

RoomState.join, leave, watch, unwatch, and set_state record what the page wants; one runner per room then sends whatever requests close the gap, one at a time. The server dispatches a socket's requests concurrently, so a leave sent right after a join could otherwise reach the registry first (and refuse the join as superseded), and two state sets could land out of order. A burst of calls converges: join, leave, join while the first join is in flight sends that one join, whose seat stands; a leave while seated is sent before the next join. While the socket is down nothing is sent and the wants wait for it. RoomState.send is the exception: it goes out at once, since a caller that cares about the order of its sends (the WebRTC mesh, rtc/rtc_mesh.svelte.ts) serializes them itself.

Every verb runs untracked, so a page may call join or watch from an $effect (with leave or unwatch in its teardown) without the effect depending on the room state the verb reads and writes.

Listeners are isolated: one that throws is logged and the others still hear the event, and the join, replay, or teardown that called it carries on.

seq

Every member event carries its room's seq, and a join or watch answers the room as of a seq. Events can arrive before that answer, so while a room's first answer is outstanding they are buffered; the answer's members are applied, then the buffer replays, dropping every event at or below the answer's seq. Once a room is live, an event at or below the last applied seq is dropped, so a connection that both watches a room and sits in it, which the server tells each event once, applies it once. A later answer whose seq is behind the live stream is not applied over it. A message (which reaches only a seat) that arrives on a live watch while the join is in flight is held, and delivered once the seat is taken.

Seats lost, and reconnects

room_seat_lost ends a seat the server took: moved (a newer join of the same actor took over, moved_to naming its room), evicted, or room_closed. None is rejoined. A socket that closes loses every seat and watch with it, and the client tells them apart: a seat lost to the disconnect is rejoined on the next connection, naming the seat it held (rejoin_of), and a refusal as room_seat_moved — the actor took a seat elsewhere meanwhile — ends it as moved, so two tabs never trade a seat back and forth. A rejoin refused rate_limited is retried after the refusal's retry_after, still naming the seat, up to ROOM_REJOIN_RATE_LIMITED_RETRIES_MAX times. Watches are taken again.

The client learns of a new connection through RoomRpc.connection, an identity that changes each time the socket opens. The client follows it on its own: its constructor makes an $effect.root whose effect reads it and calls sync_connection, so a close and a reopen are seen even when they land in one batch, and dispose ends it. On the server the compiler makes $effect.root a no-op, and nothing follows; sync_connection stays public for that case and for tests, and runs on its own before each request and notification.

const rooms = new RoomClient(create_room_rpc(socket));

Notifications reach the client through receive, from the RPC client's lookup_action_handler for the 'receive' phase (with room_notification_action_specs among the RPC client's specs):

lookup_action_handler: (method, phase) => phase === 'receive' && is_room_notification_method(method) ? (event) => rooms.receive(method, event.data.input) : undefined

dispose leaves every seat and drops every watch, for a clean teardown.

view source

Declarations
#

15 declarations

create_room_rpc
#

actions/room_client.svelte.ts view source

(socket: RoomRpcSocket): RoomRpc import {create_room_rpc} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

The room verbs straight over the socket's request, never through the RPC client's transports: those fall back to HTTP while the socket is down, and the room verbs are mounted only on a WebSocket endpoint. A request is never queued — while the socket is down it fails at once, and RoomClient sends it again on the next connection. Answers are parsed with the verbs' output schemas, forward-compatibly as the RPC client reads a remote result (keys a newer server added are dropped, safe_parse_dropping_unknown_keys); one that still doesn't parse is an internal_error.

socket

the socket the room verbs go over

returns

RoomRpc

the verbs, and connection — the open WebSocket, else null

is_room_notification_method
#

actions/room_client.svelte.ts view source

(method: string): boolean import {is_room_notification_method} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

Whether method is one of the room_* notifications RoomClient.receive takes.

method

type string

returns

boolean

ROOM_REJOIN_RATE_LIMITED_RETRIES_MAX
#

actions/room_client.svelte.ts view source

3 import {ROOM_REJOIN_RATE_LIMITED_RETRIES_MAX} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

How many times a rejoin refused rate_limited is retried, each after the refusal's retry_after, before the seat is given up as refused.

RoomClient
#

actions/room_client.svelte.ts view source

import {RoomClient} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

The rooms one page joins and watches over one socket, for one actor. See the module doc for the wiring: the client follows the connection on its own, and receive takes the RPC client's room notifications.

rpc

type RoomRpc

readonly

acting

type Branded | undefined

readonly

log

type Logger | null

readonly

rooms

Every room this client has touched, by id.

type SvelteMap<string, RoomState>

readonly

disposed

Whether dispose was called; the verbs then do nothing.

type boolean

$state.raw

constructor

type new (rpc: RoomRpc, options?: RoomClientOptions | undefined): RoomClient

rpc

type RoomRpc

options?

optional

room

The room by id, created on first use. A $derived or a template may ask for one it hasn't made yet, but Svelte doesn't track state made in the reaction reading it: a $derived that makes the room and reads its state in one expression (client.room(id).seat_status) never updates. Ask in one $derived and read in another, or make the room beforehand.

type (room_id: string): RoomState

room_id

type string
returns RoomState

the room's state

sync_connection

Read RoomRpc.connection, and when it changed since the last read, drop every seat and watch the old connection held (seats lost this way are rejoined), then converge every room over the new one. The client's own effect calls it whenever the connection changes, and it runs on its own before each request and notification; only rpc.connection is read tracked.

type (): void

returns void

mutates

  • this — every room, when the connection changed

receive

Take a pushed notification. A room notification is parsed with its params schema and routed to its room; one for a room this client doesn't hold is dropped.

type (method: string, params: unknown): boolean

method

the notification's method

type string

params

its params, unparsed

type unknown
returns boolean

whether method is a room notification

dispose

Leave every seat and drop every watch, stop following the connection, then refuse further use. The leaves still go out: each request syncs the connection on its own.

type (): Promise<void>

returns Promise<void>

resolves once the leaves have been answered (or the socket is down)

mutates

  • this — sets `disposed`

RoomClientOptions
#

actions/room_client.svelte.ts view source

RoomClientOptions import type {RoomClientOptions} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

Options for RoomClient.

acting?

The actor every verb acts as, on a multi-actor account (the acting selector); omitted, the account's default actor. One client serves one actor: the server tells a connection each event once, whichever of its actors it concerns.

type Branded

log?

Where dispatch diagnostics go; null or omitted, nowhere.

type Logger | null

set_timeout?

setTimeout, for a rate-limited rejoin's wait; omitted, the global.

type (callback: () => void, ms: number): unknown

callback

type () => void

ms

type number
returns unknown

clear_timeout?

clearTimeout, given what set_timeout returned; omitted, the global.

type (handle: unknown): void

handle

type unknown
returns void

RoomJoinOptions
#

actions/room_client.svelte.ts view source

RoomJoinOptions import type {RoomJoinOptions} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

Options for RoomState.join.

state?

The member state to join with, kept as RoomState.local_state; omitted, the state set last (or none).

type string

RoomListener
#

actions/room_client.svelte.ts view source

RoomListener import type {RoomListener} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

A subscriber to one room's events, in seq order, except a message held for a join in flight, which is heard once the seat is taken, after the member events that passed it. Member events come through a seat or a watch alike; seated and unseated bracket a seat, and message reaches only a seat. Every member is the room's own value, the same one RoomState.members holds.

seated?

A seat was taken — RoomState.members already holds the room as of the answer.

type (seat: RoomSeat): void

seat

returns void

unseated?

The seat ended.

type (seat: RoomSeat, reason: RoomUnseatedReason): void

seat

reason

returns void

member_joined?

type (member: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }): void

member

returns void

member_left?

type (member_id: Branded<string, "Uuid">, reason: "left" | "disconnected" | "moved" | "evicted" | "room_closed"): void

member_id

type Branded

reason

returns void

member_state?

type (member: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }): void

member

returns void

message?

type (message: { room_id: string; seq: number; from: Branded<string, "Uuid">; to: Branded<string, "Uuid"> | null; payload: string; }): void

message

returns void

RoomRpc
#

actions/room_client.svelte.ts view source

RoomRpc import type {RoomRpc} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

The room verbs over one socket, and the socket's identity — what RoomClient needs of the connection. create_room_rpc builds it over a FrontendWebsocketClient; a test passes a fake.

room_join

type (input: { room_id: string; state?: string | undefined; rejoin_of?: Branded<string, "Uuid"> | undefined; acting?: Branded<string, "Uuid"> | undefined; }): Promise<RoomRpcResult<...>>

input

returns Promise<RoomRpcResult>

room_leave

type (input: { room_id: string; acting?: Branded<string, "Uuid"> | undefined; }): Promise<RoomRpcResult<{ left: boolean; }>>

input

returns Promise<RoomRpcResult>

room_send

type (input: { room_id: string; to: Branded<string, "Uuid"> | null; payload: string; acting?: Branded<string, "Uuid"> | undefined; }): Promise<RoomRpcResult<null>>

input

returns Promise<RoomRpcResult>

room_state_set

type (input: { room_id: string; state: string; acting?: Branded<string, "Uuid"> | undefined; }): Promise<RoomRpcResult<{ seq: number; }>>

input

returns Promise<RoomRpcResult>

room_watch

type (input: { room_id: string; acting?: Branded<string, "Uuid"> | undefined; }): Promise<RoomRpcResult<{ room_id: string; seq: number; members: { member_id: Branded<string, "Uuid">; actor_id: Branded<...>; state: string | null; }[]; }>>

input

returns Promise<RoomRpcResult>

room_unwatch

type (input: { room_id: string; acting?: Branded<string, "Uuid"> | undefined; }): Promise<RoomRpcResult<{ unwatched: boolean; }>>

input

returns Promise<RoomRpcResult>

connection

The open connection — a value that changes each time the socket opens, compared by identity — or null while the socket is down. Seats and watches belong to one connection; when this changes they are gone. Reactive when it reads reactive state, so an $effect calling RoomClient.sync_connection reruns on a change.

type object | null

readonly

RoomRpcResult
#

actions/room_client.svelte.ts view source

RoomRpcResult<T>

type ({ ok: true; } & { value: T; }) | ({ ok: false; } & { error: { code: -32700 | -32600 | -32601 | -32602 | -32603 | Branded<number, "JsonrpcServerErrorCode">; message: string; data?: unknown; } & Record<string, unknown>; })

import type {RoomRpcResult} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

A room verb's answer: its output, or the JSON-RPC error that refused it.

generics

RoomRpcResult<T>
T

RoomRpcSocket
#

actions/room_client.svelte.ts view source

RoomRpcSocket import type {RoomRpcSocket} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

What create_room_rpc needs of the socket — a FrontendWebsocketClient satisfies it. ws is the current WebSocket, a new one per connection.

connected

type boolean

readonly

ws

type object | null

readonly

request

type (method: string, params: unknown, options?: { signal?: AbortSignal | undefined; queue?: boolean | undefined; id?: string | number | undefined; } | undefined): Promise<unknown>

method

type string

params

type unknown

options?

type { signal?: AbortSignal | undefined; queue?: boolean | undefined; id?: string | number | undefined; }
optional
returns Promise<unknown>

RoomSeat
#

actions/room_client.svelte.ts view source

RoomSeat import type {RoomSeat} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

The caller's seat in a room, from the join's answer.

room_id

type string

member_id

type Branded

topology

type "mesh"

extra

The consumer's join_extra value (ICE servers, say), null without one.

type unknown

RoomSeatEnded
#

actions/room_client.svelte.ts view source

RoomSeatEnded import type {RoomSeatEnded} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

Why the server ended the caller's seat — room_seat_lost, or a rejoin refused as moved.

reason

type RoomSeatLostReason

moved_to

The room a moved seat moved to, null when not known (a rejoin refused as moved).

type string | null

RoomSeatStatus
#

actions/room_client.svelte.ts view source

RoomSeatStatus

type "idle" | "joining" | "rejoining" | "joined"

import type {RoomSeatStatus} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

Where a room's seat stands: idle (not wanted), joining, rejoining (a seat lost to a disconnect, waiting to be taken again), joined.

RoomState
#

actions/room_client.svelte.ts view source

import {RoomState} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

One room as the client sees it: the members (through a seat, a watch, or both), the caller's seat, and what the page wants of it. Built by RoomClient.room; every verb here records a want and lets the room's runner converge on it (see the module doc).

room_id

type string

readonly

members

The room's members in seating order, the caller's own seat included; empty until a seat or watch answers.

type readonly RoomMember[]

$state.raw

seat

The caller's seat, or null.

type RoomSeat | null

$state.raw

watching

Whether a watch is live — the server answered it and hasn't ended it.

type boolean

$state.raw

ended

Why the server last ended the seat; cleared by the next join.

type RoomSeatEnded | null

$state.raw

watch_ended

Why the server last ended the watch; cleared by the next watch.

type RoomEvictReason | null

$state.raw

error

The last refusal of a join, watch, or state set in this room; null once one succeeds, and cleared by the next join.

type JsonrpcErrorObject | null

$state.raw

local_state

The member state the caller wants, sent with the join and with every change while seated.

type string | null

$state.raw

want_seat

Whether a seat is wanted.

type boolean

$state.raw

want_watch

Whether a watch is wanted.

type boolean

$state.raw

rejoin_of

The seat this room rejoins on the next connection, after a disconnect took it.

type Branded | null

$state.raw

constructor

Built by RoomClient.room.

type new (host: RoomHost, room_id: string): RoomState

host

type RoomHost

room_id

type string

add_listener

Subscribe to the room's events.

type (listener: RoomListener): () => void

listener

returns () => void

the remover

join

Want a seat. Resolves once it is taken (at once when it already is), or with the refusal; a leave before it is taken resolves it as room_join_superseded. While the socket is down it waits for the next connection.

type (options?: RoomJoinOptions | undefined): Promise<RoomRpcResult<RoomSeat>>

options?

optional
returns Promise<RoomRpcResult>

the seat, or why there is none

leave

Stop wanting the seat: it ends here at once (unseated with left), and the server hears a room_leave once the socket allows. A rejoin waiting on a reconnect is dropped.

type (): Promise<void>

returns Promise<void>

resolves once the room's requests have settled

watch

Want a watch: the members without a seat. A watch the server ends (room_watch_ended) is not taken again.

type (): Promise<void>

returns Promise<void>

resolves once the room's requests have settled

unwatch

Stop wanting the watch.

type (): Promise<void>

returns Promise<void>

resolves once the room's requests have settled

set_state

Set the caller's member state: sent now when seated, else with the next join. Only the latest state is sent; a burst sends at most one per answer.

type (state: string): Promise<void>

state

type string
returns Promise<void>

resolves once the room's requests have settled

send

Relay payload to one member (to), or to every other member (null). Sent at once, never ordered against other sends: a caller that needs an order waits for each answer before the next send.

type (to: Branded<string, "Uuid"> | null, payload: string): Promise<RoomRpcResult<null>>

to

type Branded | null

payload

type string
returns Promise<RoomRpcResult>

null, or the refusal — room_not_joined without a seat

seat_status

Where the seat stands. A getter, not a $derived: a room outlives the effect that first asked for it, and a $derived would freeze with it.

type RoomSeatStatus

getter

RoomUnseatedReason
#

actions/room_client.svelte.ts view source

RoomUnseatedReason

type "left" | "disconnected" | "closed" | RoomSeatLostReason

import type {RoomUnseatedReason} from '@fuzdev/fuz_app/actions/room_client.svelte.js';

Why a seat ended, as RoomListener.unseated hears it: the caller left, the socket closed (disconnected, rejoined on the next connection), the server ended it (RoomSeatLostReason), or the client was disposed (closed).

Depends on
#

Imported by
#