actions/room_action_specs.ts

The room verbs' wire: the room_* request specs, the room_* notifications the registry fans out, their schemas, refusal reasons, and bounds — the TS twin of the Rust spine's fuz_actions::room specs and fuz_realtime::room_registry notification shapes.

A room is a key (RoomId) the consumer chooses and parses, holding seats (members, each with a random MemberId and a small client-encoded state) and watches (occupancy without a seat). actions/room_registry.ts holds the state and the fan-out; actions/room_actions.ts builds the handlers over it. Every verb is WebSocket-only — a room belongs to a socket — so a consumer mounts them on a WS endpoint and never on an RPC one, actor-required (acting selects the actor on a multi-actor account), and without side effects (the registry is memory, so no transaction opens).

payload and state are strings the client encodes, so both twins measure their bounds alike, in UTF-8 bytes, and charge the per-connection limiter their JSON-escaped length (json_escaped_len). Refusals carry data.reason, the ERROR_ROOM_* constants, plus rate_limited with data.retry_after. Every member event carries the room's seq (actions/room_registry.ts says what it promises).

view source

Declarations
#

55 declarations

all_room_action_specs
#

actions/room_action_specs.ts view source

readonly [{ readonly method: "room_join"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; readonly side_effects: false; ... 5 more ...; readonly description: "Seat the caller in a room; answers the room's members as of t... import {all_room_action_specs} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The room verbs, in the order create_room_actions builds them.

all_room_specs
#

DEFAULT_ROOM_MAX_MEMBERS
#

actions/room_action_specs.ts view source

32 import {DEFAULT_ROOM_MAX_MEMBERS} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Default RoomRegistryOptions.max_members_per_room: generous for a full-mesh call, where every member holds a peer connection to every other.

DEFAULT_ROOM_MAX_PAYLOAD_BYTES
#

actions/room_action_specs.ts view source

number import {DEFAULT_ROOM_MAX_PAYLOAD_BYTES} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Default RoomRegistryOptions.max_payload_bytes: room for a session description with many candidates, small beside the outbound budget.

DEFAULT_ROOM_MAX_STATE_BYTES
#

actions/room_action_specs.ts view source

1024 import {DEFAULT_ROOM_MAX_STATE_BYTES} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Default RoomRegistryOptions.max_state_bytes: a few flags, encoded.

DEFAULT_ROOM_MAX_WATCHES_PER_CONNECTION
#

actions/room_action_specs.ts view source

256 import {DEFAULT_ROOM_MAX_WATCHES_PER_CONNECTION} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Default RoomRegistryOptions.max_watches_per_connection.

ERROR_ROOM_FULL
#

ERROR_ROOM_JOIN_SUPERSEDED
#

actions/room_action_specs.ts view source

"room_join_superseded" import {ERROR_ROOM_JOIN_SUPERSEDED} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The caller's own leave of the room overtook the join. A conflict.

ERROR_ROOM_MEMBER_NOT_FOUND
#

actions/room_action_specs.ts view source

"room_member_not_found" import {ERROR_ROOM_MEMBER_NOT_FOUND} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The addressee is not a member of the room, or is the sender's own seat. A not_found.

ERROR_ROOM_NOT_FOUND
#

actions/room_action_specs.ts view source

"room_not_found" import {ERROR_ROOM_NOT_FOUND} from '@fuzdev/fuz_app/actions/room_action_specs.js';

No such room, or one the caller may not join or watch (the IDOR mask), or one an eviction closed to the request while it was in flight. A not_found.

ERROR_ROOM_NOT_JOINED
#

actions/room_action_specs.ts view source

"room_not_joined" import {ERROR_ROOM_NOT_JOINED} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The caller's connection holds no seat in the room. A conflict.

ERROR_ROOM_PAYLOAD_TOO_LARGE
#

actions/room_action_specs.ts view source

"room_payload_too_large" import {ERROR_ROOM_PAYLOAD_TOO_LARGE} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The payload is over the registry's bound. An invalid_params.

ERROR_ROOM_SEAT_MOVED
#

actions/room_action_specs.ts view source

"room_seat_moved" import {ERROR_ROOM_SEAT_MOVED} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A rejoin names a seat that has moved since — its actor sits elsewhere now (exclusive registries). A conflict.

ERROR_ROOM_STATE_TOO_LARGE
#

actions/room_action_specs.ts view source

"room_state_too_large" import {ERROR_ROOM_STATE_TOO_LARGE} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The state is over the registry's bound. An invalid_params.

ERROR_ROOM_WATCH_LIMIT
#

actions/room_action_specs.ts view source

"room_watch_limit" import {ERROR_ROOM_WATCH_LIMIT} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The connection watches its maximum of rooms. A conflict.

JSON_ESCAPE_MAX_EXPANSION
#

actions/room_action_specs.ts view source

6 import {JSON_ESCAPE_MAX_EXPANSION} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The most bytes one byte of a string can take escaped in a JSON frame: \u00XX, for a control character without a two-byte escape. A lone surrogate takes six too (\udXXX), from a single UTF-16 code unit.

json_escaped_len
#

actions/room_action_specs.ts view source

(text: string): number import {json_escaped_len} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The bytes text takes inside a JSON string in a frame — what the room limiter charges a payload or state, and what the frame grows by. Twin of the Rust json_escaped_len, byte for byte over well-formed text.

" and \ take 2; backspace, form feed, newline, carriage return, and tab take 2 (\b \f \n \r \t); every other control character below U+0020 takes 6 (\u00XX); everything else is its UTF-8 length — U+007F and non-ASCII text are not escaped, U+2028 and U+2029 included. A surrogate pair is 4.

A lone surrogate counts 6, which is what JSON.stringify writes for one (\udXXX), so the count stays exactly the frame's growth for any string a TS handler holds. A Rust string can't hold one, and no frame delivers one to either spine: both refuse an escaped lone surrogate as a parse_error (http/json_text.ts), and a raw one is invalid UTF-8 a WebSocket refuses. So the twins never charge one differently over the wire.

text

the payload or state

type string

returns

number

its escaped length in bytes, without the surrounding quotes

MemberId
#

actions/room_action_specs.ts view source

value + type

Branded<string, "Uuid">

type Branded

import {MemberId} from '@fuzdev/fuz_app/actions/room_action_specs.js';

One seat's id — random per join, so a client addresses members without ever seeing a connection id, and a rejoin gets a new one. A UUID on the wire.

external types

Infer<typeof MemberId>

ROOM_ID_MAX_LENGTH
#

room_join_action_spec
#

actions/room_action_specs.ts view source

{ readonly method: "room_join"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; readonly side_effects: false; ... 5 more ...; readonly description: "Seat the caller in a room; answers the room's members as of the join."; } import {room_join_action_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

room_join — seat the caller in a room. Two phases on the server (a reserve before the consumer's authorizer reads, an admit after), so an eviction committing while the authorizer reads still reaches the join. Charges the per-account rate-limit class (the authorizer reads the database, and one account may hold many sockets) and the connection's room limiter (one request, plus the state's escaped bytes).

room_leave_action_spec
#

actions/room_action_specs.ts view source

{ readonly method: "room_leave"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; readonly side_effects: false; readonly input: ObjectSchema<...>; readonly output: ObjectSchema<...>; readonly async: true; readonly descrip... import {room_leave_action_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

room_leave — end the acting actor's seat in the room on this connection, and refuse that actor's joins of the room still in flight on it. Idempotent.

room_member_joined_notification_spec
#

actions/room_action_specs.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ObjectSchema<{ room_id: PipeSchema<string, StringSchema>; seq: PipeSchema<...>; member: ObjectSchema<...>; }>; output: VoidSchema; async: true; description: string; } import {room_member_joined_notification_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A member was seated — to the room's other members and its watchers.

room_member_left_notification_spec
#

actions/room_action_specs.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ObjectSchema<{ room_id: PipeSchema<string, StringSchema>; seq: PipeSchema<...>; member_id: BrandSchema<...>; reason: OneOfSchema<...>; }>; output: VoidSchema; async: true; description: string; } import {room_member_left_notification_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A member's seat ended — to the room's remaining members and its watchers.

room_member_state_notification_spec
#

actions/room_action_specs.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ObjectSchema<{ room_id: PipeSchema<string, StringSchema>; seq: PipeSchema<...>; member_id: BrandSchema<...>; state: NullableSchema<...>; }>; output: VoidSchema; async: true; description: string; } import {room_member_state_notification_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A member set its state — to the room's other members and its watchers.

room_message_notification_spec
#

actions/room_action_specs.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ObjectSchema<{ room_id: PipeSchema<string, StringSchema>; seq: PipeSchema<...>; from: BrandSchema<...>; to: NullableSchema<...>; payload: StringSchema; }>; output: VoidSchema; async: true; description: string; } import {room_message_notification_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A member's payload — to its addressee, or to the room minus its sender.

room_notification_action_specs
#

room_notification_actions
#

actions/room_action_specs.ts view source

readonly Action<ActionSpecUnion>[]

type readonly Action<ActionSpecUnion>[]

import {room_notification_actions} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The room notifications as handler-less actions, for a WS endpoint's action list beside create_room_actions' verbs, so its surface lists what the registry pushes as remote_notification methods. With no handler they never reach dispatch: an inbound frame for one is answered method_not_found.

room_seat_lost_notification_spec
#

actions/room_action_specs.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ObjectSchema<{ room_id: PipeSchema<string, StringSchema>; member_id: BrandSchema<...>; reason: OneOfSchema<...>; moved_to: NullableSchema<...>; }>; output: VoidSchema; async: true; description: string; } import {room_seat_lost_notification_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The server ended a seat — to the seat's own connection.

room_send_action_spec
#

actions/room_action_specs.ts view source

{ readonly method: "room_send"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; readonly side_effects: false; ... 4 more ...; readonly description: "Relay a payload to one member of a room, or to every other member."; } import {room_send_action_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

room_send — relay a payload from the caller's seat to one member, or to the room minus the sender (room_message). Watchers get no messages; a seat never addresses itself (room_member_not_found). Charges the connection's room limiter one request plus the payload's escaped bytes.

room_state_set_action_spec
#

actions/room_action_specs.ts view source

{ readonly method: "room_state_set"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; ... 5 more ...; readonly description: "Set the caller's member state in a room."; } import {room_state_set_action_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

room_state_set — set the caller's member state, telling the other members and the watchers (room_member_state). Charges the connection's room limiter one request plus the state's escaped bytes.

room_unwatch_action_spec
#

actions/room_action_specs.ts view source

{ readonly method: "room_unwatch"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; readonly side_effects: false; readonly input: ObjectSchema<...>; readonly output: ObjectSchema<...>; readonly async: true; readonly descr... import {room_unwatch_action_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

room_unwatch — stop watching a room. Idempotent.

room_watch_action_spec
#

actions/room_action_specs.ts view source

{ readonly method: "room_watch"; readonly kind: "request_response"; readonly initiator: "frontend"; readonly auth: { readonly account: "required"; readonly actor: "required"; }; readonly side_effects: false; ... 5 more ...; readonly description: "Watch a room's members without joining."; } import {room_watch_action_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

room_watch — see a room's members without joining: answers its occupancy, then the member events. Two phases like a join, and on the per-account rate-limit class; a watch fans out nothing, so the room limiter doesn't charge it. Watching a room already watched answers its occupancy again.

room_watch_ended_notification_spec
#

actions/room_action_specs.ts view source

{ method: string; kind: "remote_notification"; initiator: "backend"; auth: null; side_effects: true; input: ObjectSchema<{ room_id: PipeSchema<string, StringSchema>; reason: OneOfSchema<...>; }>; output: VoidSchema; async: true; description: string; } import {room_watch_ended_notification_spec} from '@fuzdev/fuz_app/actions/room_action_specs.js';

The server ended a watch — to the watcher.

RoomEvictReason
#

actions/room_action_specs.ts view source

value + type

"evicted" | "room_closed"

type "evicted" | "room_closed"

import {RoomEvictReason} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Why the consumer evicts — what members, seats, and watches are told: evicted (the actor lost its access), room_closed (the room itself is gone).

RoomId
#

actions/room_action_specs.ts view source

value + type

string import {RoomId} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A room's key — an opaque string the consumer chooses and parses (a voice room keyed by a space id, say): 1 to ROOM_ID_MAX_LENGTH printable ASCII characters (! through ~, so no whitespace or control characters). ASCII keeps the bound one number on both twins, where a UTF-16 length and a UTF-8 one would differ. Twin of the Rust RoomId::parse.

RoomIdInput
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; acting?: Branded<string, "Uuid"> | undefined; } import {RoomIdInput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Input for room_leave, room_watch, and room_unwatch.

room_id

type string

acting?

type Branded

RoomJoinInput
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; state?: string | undefined; rejoin_of?: Branded<string, "Uuid"> | undefined; acting?: Branded<string, "Uuid"> | undefined; } import {RoomJoinInput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Input for room_join.

room_id

type string

state?

The member's initial state; omitted, null to the room until it sets one.

type string

rejoin_of?

The seat this join takes up again after a reconnect — refused as room_seat_moved on an exclusive registry when that seat has moved since.

type Branded

acting?

type Branded

RoomJoinOutput
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; member_id: Branded<string, "Uuid">; seq: number; members: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }[]; topology: "mesh"; extra: unknown; } import {RoomJoinOutput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Output of room_join: 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; extra is the consumer's join_extra value, null without one.

room_id

type string

member_id

type Branded

seq

type number

members

type RoomMember[]

topology

type "mesh"

extra

type unknown

RoomLeaveOutput
#

actions/room_action_specs.ts view source

value + type

{ left: boolean; } import {RoomLeaveOutput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Output of room_leave: whether it ended a seat or refused a join in flight.

left

type boolean

RoomLeftReason
#

actions/room_action_specs.ts view source

value + type

"left" | "disconnected" | "moved" | "evicted" | "room_closed"

type "left" | "disconnected" | "moved" | "evicted" | "room_closed"

import {RoomLeftReason} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Why a member left, as room_member_left says: left (it left), disconnected (its socket closed), moved (its actor was seated elsewhere on an exclusive registry, or its connection rejoined the room), evicted (the consumer evicted it), room_closed (the consumer closed the room).

RoomMember
#

actions/room_action_specs.ts view source

value + type

{ member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; } import {RoomMember} from '@fuzdev/fuz_app/actions/room_action_specs.js';

One seated member, as members and watchers see it.

member_id

type Branded

actor_id

type Branded

state

The member's client-encoded state, null until it sets one.

type string | null

RoomMemberJoinedParams
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; seq: number; member: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }; } import {RoomMemberJoinedParams} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Params of room_member_joined.

room_id

type string

seq

type number

member

type RoomMember

RoomMemberLeftParams
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; seq: number; member_id: Branded<string, "Uuid">; reason: "left" | "disconnected" | "moved" | "evicted" | "room_closed"; } import {RoomMemberLeftParams} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Params of room_member_left.

room_id

type string

seq

type number

member_id

type Branded

reason

type "left" | "disconnected" | "moved" | "evicted" | "room_closed"

RoomMemberStateParams
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; seq: number; member_id: Branded<string, "Uuid">; state: string | null; } import {RoomMemberStateParams} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Params of room_member_state.

room_id

type string

seq

type number

member_id

type Branded

state

type string | null

RoomMessageParams
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; seq: number; from: Branded<string, "Uuid">; to: Branded<string, "Uuid"> | null; payload: string; } import {RoomMessageParams} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Params of room_message: to is null for a room-wide send.

room_id

type string

seq

type number

from

type Branded

to

type Branded | null

payload

type string

RoomOccupancy
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; seq: number; members: { member_id: Branded<string, "Uuid">; actor_id: Branded<string, "Uuid">; state: string | null; }[]; } import {RoomOccupancy} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A room's members as of seq — what a watch answers, and what RoomRegistry.occupancy reads.

room_id

type string

seq

type number

members

type RoomMember[]

RoomSeatLostParams
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; member_id: Branded<string, "Uuid">; reason: "moved" | "evicted" | "room_closed"; moved_to: string | null; } import {RoomSeatLostParams} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Params of room_seat_lost: moved_to names the new seat's room for moved, else null.

room_id

type string

member_id

type Branded

reason

type "moved" | "evicted" | "room_closed"

moved_to

type string | null

RoomSeatLostReason
#

actions/room_action_specs.ts view source

value + type

"moved" | "evicted" | "room_closed"

type "moved" | "evicted" | "room_closed"

import {RoomSeatLostReason} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Why the server ended a seat, as room_seat_lost tells the seat's own connection: moved (a newer seat took over; moved_to names its room), evicted, room_closed.

RoomSendInput
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; to: Branded<string, "Uuid"> | null; payload: string; acting?: Branded<string, "Uuid"> | undefined; } import {RoomSendInput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Input for room_send.

room_id

type string

to

The addressee's member id, or null for every other member of the room. Required.

type Branded | null

payload

The client-encoded payload, at most the registry's max_payload_bytes in UTF-8.

type string

acting?

type Branded

RoomSeq
#

actions/room_action_specs.ts view source

value + type

number import {RoomSeq} from '@fuzdev/fuz_app/actions/room_action_specs.js';

A room's seq: the count of its events, starting again at zero when the room is deleted.

RoomStateSetInput
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; state: string; acting?: Branded<string, "Uuid"> | undefined; } import {RoomStateSetInput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Input for room_state_set.

room_id

type string

state

The client-encoded state, at most the registry's max_state_bytes in UTF-8.

type string

acting?

type Branded

RoomStateSetOutput
#

actions/room_action_specs.ts view source

value + type

{ seq: number; } import {RoomStateSetOutput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Output of room_state_set: the seq of the room_member_state it caused.

seq

type number

RoomTopology
#

actions/room_action_specs.ts view source

value + type

"mesh" import {RoomTopology} from '@fuzdev/fuz_app/actions/room_action_specs.js';

How a room's members reach each other's media — what the join answers, so a client knows whom to connect to. mesh: every member connects to every other; the server relays only the members' messages.

RoomUnwatchOutput
#

actions/room_action_specs.ts view source

value + type

{ unwatched: boolean; } import {RoomUnwatchOutput} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Output of room_unwatch: whether the connection was watching.

unwatched

type boolean

RoomWatchEndedParams
#

actions/room_action_specs.ts view source

value + type

{ room_id: string; reason: "evicted" | "room_closed"; } import {RoomWatchEndedParams} from '@fuzdev/fuz_app/actions/room_action_specs.js';

Params of room_watch_ended.

room_id

type string

reason

type "evicted" | "room_closed"

Depends on
#

Imported by
#