actions/room_actions.ts

The room verbs over RoomRegistry (actions/room_registry.ts): join, leave, send, state, watch, and unwatch, as actions a consumer mounts on a WebSocket endpoint — the TS twin of the Rust spine's fuz_actions::room.

create_room_actions returns the handlers over the specs of actions/room_action_specs.ts. Each is WebSocket-only — mount them on a ws_endpoints entry, never on an RPC endpoint (a room belongs to a socket; the Rust spine answers them method_not_found over HTTP, and a handler reached without a connection answers the same) — actor-required, and without side effects: the registry is memory, not the database, so no transaction opens for a relayed message. The registry does the work and the fan-out; this module parses, bounds, authorizes, and limits.

Seats are keyed by connection and actor: under the dispatcher's acting selector, a leave, send, or state set acts on the acting actor's own seat, never another actor's on the same socket.

The consumer's seams

  • RoomAuthorize decides each join and watch: {allow: false} answers room_not_found, the same as a room that doesn't exist, so a caller learns nothing of rooms it can't enter; `{allow: true, scope, max_members} carries the RoomScope` the seat or watch is admitted under, for eviction, and an optional member cap below the registry's. It gets the caller's ids and the database, not the request's role grants: authority is read through the database inside the reserve window (RoomAuthorize's doc).
  • Eviction is the consumer calling RoomRegistry.evict after its own authority change commits — from the handler's emit_after_commit — never before.
  • Rate limits. room_join and room_watch carry the per-account class (rate_limit: 'account', charged by the dispatcher): each runs the consumer's database authorizer, and one account may hold many sockets. RoomRateLimiter is per connection, outside the account budget: it bounds the count of joins, sends, and state sets, and the bytes of payloads and states as each frame carries them (JSON-escaped, json_escaped_len), because every room-wide byte lands in each member's outbound queue (DEFAULT_WS_OUTBOUND_QUEUE_BYTES) and a member reading slower than its room sends is closed for the overflow. A join stays on it too, since its state and the seats it moves fan out to every member; a watch fans out nothing, so it costs only its account charge.
  • join_extra, a hook whose value the join answers as extra (null without one) — for what a consumer mints per seat.

A join, step by step

The dispatcher's account charge and input parse; refuse a state over the registry's bound; charge the connection's limiter; reserve_seat (the join is now reachable by evictions); the authorizer; then the request's own signal — a client cancel of the join, or its socket closing, answers request_cancelled — and admit_seat. A join whose socket closes mid-authorizer keeps running here, unlike the Rust one, whose request future is dropped; its admit refuses (connection_closed, answered request_cancelled), so it seats nothing either way. A watch runs the same steps through the watch halves, without the connection's limiter.

view source

Declarations
#

16 declarations

check_room_limits
#

create_room_actions
#

actions/room_actions.ts view source

(deps: RoomActionsDeps, options?: RoomActionsOptions): RpcAction[] import {create_room_actions} from '@fuzdev/fuz_app/actions/room_actions.js';

Build the room verbs (module doc), ready for a WebSocket endpoint's action list — beside room_notification_actions (actions/room_action_specs.ts) for the surface to list what the registry pushes.

deps

the registry, the authorizer, and the limiter

options?

the join's extra

optional default {}

returns

RpcAction[]

the actions, in all_room_action_specs order

throws

  • Error - when the limiter can never cover a request the registry's bounds admit (`check_room_limits`): no request budget, or a byte budget below a max-size payload's or state's worst-case escaped charge

DEFAULT_ROOM_RATE_LIMIT
#

actions/room_actions.ts view source

RoomRateLimitOptions import {DEFAULT_ROOM_RATE_LIMIT} from '@fuzdev/fuz_app/actions/room_actions.js';

The default budgets — the Rust DEFAULT_ROOM_RATE_LIMIT.

Room for a join into a full-mesh room (an offer and its candidates to every member) several times over. A full burst stays under half of a reader's default outbound queue (DEFAULT_WS_OUTBOUND_QUEUE_BYTES, 4 MiB), by construction: a charge is exactly the bytes the payload or state adds to its frame, and each charged request puts at most four frames in any other reader's queue (for a join, which moves at most one seat: the moved seat leaving, its room_seat_lost, the join's room_member_joined, and the uncharged leave that later ends the new seat), so one member's burst queues at most max_bytes plus four frames' fixed overhead per request.

RoomAccess
#

actions/room_actions.ts view source

RoomAccess

type "join" | "watch"

import type {RoomAccess} from '@fuzdev/fuz_app/actions/room_actions.js';

Which access an authorizer decides: a seat (join), or occupancy only (watch).

RoomActionsDeps
#

actions/room_actions.ts view source

RoomActionsDeps import type {RoomActionsDeps} from '@fuzdev/fuz_app/actions/room_actions.js';

The capabilities the room verbs run on.

registry

The registry, over the connection registry of the WebSocket endpoint the verbs are mounted on.

type RoomRegistry

readonly

authorize

type RoomAuthorize

readonly

limiter

The per-connection limiter; null leaves the verbs unlimited — a test server's choice, not a deployment's.

type RoomRateLimiter | null

readonly

RoomActionsOptions
#

RoomAuthorize
#

actions/room_actions.ts view source

RoomAuthorize import type {RoomAuthorize} from '@fuzdev/fuz_app/actions/room_actions.js';

The consumer's decision on each join and watch.

Runs between the registry's reserve and admit, so an eviction landing while it reads still reaches the request (RoomRegistry's two-phase join). It reads through db, the request's pool-level client (the specs have no side effects, so there is no transaction), under READ COMMITTED, and must only read. A room it doesn't know is {allow: false}.

Authority is read through db, inside the reserve window, never from the request. The dispatcher loads the actor's role grants before the handler runs, so before the reserve: a consumer's eviction (its write committed, then RoomRegistry.evict) landing between that load and the reserve finds no join in flight to reach, and a verdict on those grants would seat the evicted actor. A read after the reserve sees the committed write, or the eviction reaches the join — the race closes either way. So the input carries the caller's ids (RoomAuthorizeInput), not its grants.

A throw is a hard failure (a query that failed), answered as it is — a ThrownJsonrpcError with its code, anything else internal_error.

authorize

type (input: RoomAuthorizeInput, db: Db): RoomVerdict | Promise<RoomVerdict>

readonly

input

db

type Db
returns RoomVerdict | Promise<RoomVerdict>

RoomAuthorizeInput
#

actions/room_actions.ts view source

RoomAuthorizeInput import type {RoomAuthorizeInput} from '@fuzdev/fuz_app/actions/room_actions.js';

What RoomAuthorize decides on: who asks, for which room and access.

It carries the caller's identity, never its authority. Each field is fixed for the request's life, so none can go stale between the dispatcher's resolve and the authorizer's read:

  • actor_id — the acting actor (after the acting selector), the key a policy reads its grants and memberships by;
  • account_id — the actor's account, which an actor never changes, for a policy keyed by account;
  • room_id, access — the request itself.

Whether the actor or account is still live (not soft-deleted since the dispatcher resolved it) is the authorizer's to read with its grants, as any live-grant read does.

actor_id

type Branded

readonly

account_id

type Branded

readonly

room_id

type string

readonly

access

type RoomAccess

readonly

RoomJoinExtra
#

actions/room_actions.ts view source

RoomJoinExtra import type {RoomJoinExtra} from '@fuzdev/fuz_app/actions/room_actions.js';

A consumer's addition to every admitted join's answer, as extra — a JSON value; undefined answers extra: null.

(call)

type (input: RoomJoinExtraInput): unknown

input

returns unknown

RoomJoinExtraInput
#

actions/room_actions.ts view source

RoomJoinExtraInput import type {RoomJoinExtraInput} from '@fuzdev/fuz_app/actions/room_actions.js';

What RoomJoinExtra gets for an admitted seat.

auth

The request's context as the dispatcher resolved it, before the reserve: its role_grants may predate an eviction, so derive nothing from them that needs current authority (the seat itself was admitted on the authorizer's live read).

type RequestActorContext

readonly

room_id

type string

readonly

member_id

type Branded

readonly

RoomLimitsError
#

actions/room_actions.ts view source

RoomLimitsError

type { readonly kind: "no_request_budget"; } | { readonly kind: "byte_budget_below_bound"; readonly bound: "state" | "payload"; readonly charge: number; readonly max_bytes: number; }

import type {RoomLimitsError} from '@fuzdev/fuz_app/actions/room_actions.js';

Why a limiter can't serve a registry: it would refuse a request the registry's bounds admit, forever. The twin of the Rust RoomSpecSetError.

RoomRateLimited
#

actions/room_actions.ts view source

RoomRateLimited import type {RoomRateLimited} from '@fuzdev/fuz_app/actions/room_actions.js';

A charge the budgets can't cover: whole seconds, at least one, until they would.

retry_after

type number

readonly

RoomRateLimiter
#

actions/room_actions.ts view source

import {RoomRateLimiter} from '@fuzdev/fuz_app/actions/room_actions.js';

The room verbs' limiter, one budget pair per connection (RoomRateLimitOptions) — the twin of the Rust RoomRateLimiter.

A connection's buckets are forgotten once full again — a full bucket is what a fresh one is — so the map holds only connections that spent recently, swept as it grows.

options

type RoomRateLimitOptions

readonly

constructor

type new (options?: RoomRateLimitOptions, now?: () => number): RoomRateLimiter

options?

the budgets

optional default DEFAULT_ROOM_RATE_LIMIT

now?

the monotonic clock in ms; default performance.now, a test passes its own to drive the refill

type () => number
optional default () => performance.now()

throws

  • Error - when a budget is not a non-negative safe integer, or the window is not positive

charge

Spend one request and bytes from connection_id's budgets, both or neither.

type (connection_id: Branded<string, "Uuid">, bytes: number): Result<object, RoomRateLimited>

connection_id

type Branded

bytes

type number
returns Result

ok, or the wait when either budget can't cover it — nothing is spent then

mutates

  • this — spends the connection's buckets

tracked

Connections tracked — those whose buckets aren't full again. For tests.

type (): number

returns number

RoomRateLimitOptions
#

actions/room_actions.ts view source

RoomRateLimitOptions import type {RoomRateLimitOptions} from '@fuzdev/fuz_app/actions/room_actions.js';

A RoomRateLimiter's budgets. Each is a bucket holding at most its maximum, refilled at that maximum per window_ms: a burst may spend it all at once, and the sustained rate is the maximum per window.

max_requests

Joins, sends, and state sets — each costs one.

type number

readonly

max_bytes

Payload and state bytes as their frames carry them (json_escaped_len). At least a max-size payload's and state's worst case (JSON_ESCAPE_MAX_EXPANSION times the registry's bound), or create_room_actions refuses the pair.

type number

readonly

window_ms

The refill window, in ms.

type number

readonly

RoomVerdict
#

actions/room_actions.ts view source

RoomVerdict

type { readonly allow: false; } | { readonly allow: true; readonly scope?: string | null | undefined; readonly max_members?: number | null | undefined; }

import type {RoomVerdict} from '@fuzdev/fuz_app/actions/room_actions.js';

An authorizer's answer: {allow: false} is answered room_not_found, as a missing room is; {allow: true} admits under scope (eviction's handle on it), and max_members, a non-negative integer, lowers the registry's cap for this join — a watch ignores it, and any other value is a bug the join throws on (RoomRegistry.admit_seat).

to_room_jsonrpc_error
#

actions/room_actions.ts view source

(error: RoomError): ThrownJsonrpcError import {to_room_jsonrpc_error} from '@fuzdev/fuz_app/actions/room_actions.js';

The answer for a registry refusal — the codes and reasons of the Rust room_error.

error

the registry's refusal

returns

ThrownJsonrpcError

the error to throw

Depends on
#

Imported by
#