session

Mint a broadcast-safe id at the width the room's media wire format assumes.

Reduce a caller-supplied id to what is safe in the export filename.

The exit archive is named after the session, and the export routes reject anything with path structure in it, so an id carrying a slash or a dot would produce an archive the parent could never fetch back.

Replace the module-level session with a fresh one built from the activate payload.

The controller starts with gamepad 1 and mouse/keyboard control; the viewer list starts empty and the save baseline is the moment of creation.

End the session, keeping what the state routes still have to answer with.

Exit captures a state and then tears the session down, but RomM only asks for that state once the teardown has replied, so clearing outright is what made every post-exit read a 409. Only the emulator is kept, and only the read routes consult it: nothing here can be played, written to or resumed.

Look up a viewer entry in the active session by its token.

Resolve a seat's real token to the non-sensitive id safe to broadcast for it.

Resolve a broadcast-safe public id back to the seat's real token.

The inverse of public_id_for, used to translate a room-management target (e.g. who a gamepad slot goes to) that a client can only name by its public id back into the token the rest of the session logic keys on.

Return the session's shareable invite token for a permission, minting it on first use.

The token identifies the session and the permission, not a person: every arrival on it is seated separately by add_viewer, so the same link can go to any number of friends and stays valid until the session ends.

Resolve an invite token to the permission it grants.

Drop a removed seat's rate-limit cooldowns and role, and detach its live connection.

Called for a seat leaving SESSION["viewers"] outside the normal disconnect path (a same-user rejoin replacing it, or the reclaim of a stale seat), both of which can happen while the seat still holds the speaker or MK role from the unvalidated set_designated_speaker/assign_mk actions, or a cooldowns entry, both cleared here. A rejoin can also evict a seat whose socket is still connected (a second tab, a reload racing the old tab's close): that connection is detached from ROOM["viewers"] here, synchronously, so nothing can look it up as the seat's connection anymore, but closing it is left to the caller. It must stay a synchronous pop rather than an awaited close here, since add_viewer's cap check right after this needs the whole admission decision to run without yielding control, or a concurrent join could interleave mid-decision and seat past the cap.

Mint a viewer token and add the viewer to the active session.

A re-join by the same user (matched by id, else username) replaces the old entry and invalidates its token. If that old seat still has a live room connection (a second tab, a reload racing the first tab's close), that connection is force-closed rather than left running on a token nothing recognizes anymore. The close is deferred until every seat has already been decided (see _release_seat), so it never interleaves with a concurrent join's own admission decision.

List every live room connection, the controller's first.

Queue a JSON message for every connected room member.

Each member's outbox sends it on its own time, so a member whose connection is backed up delays nobody but itself (see outbox).

Queue a binary media frame for every connected room member except its sender.

Runs inline in the sender's receive loop, so it never waits on a recipient.

Ask the member streaming under media_id to encode its next video frame as a keyframe.

Called by a recipient's outbox after it dropped one of that member's video frames. Requests to one member are spaced KEYFRAME_REQUEST_GAP apart, since keyframes are the largest frames and would add to the congestion.

Broadcast a state_update describing every room member to the room.

The controller is listed first, then each viewer with its online status and mouse/keyboard ownership. Members are identified by publicId, a non-sensitive stand-in for their seat token: broadcasting the real token would hand every room member, including anonymous viewers, the bearer credential needed to reconnect as (or impersonate) anyone else. While a member is connected its mediaId, the per-connection id its live socket tags binary media frames with, is included too. Does nothing when there is no session.

Each entry is assembled field by field rather than copied from the seat: everyone in the room reads this, so a seat's RomM user_id and the bookkeeping the room has no use for stay on the server side.

Assign a gamepad slot to a room member, or take theirs away.

A slot can only be held by one member, so whoever held it before is unassigned first. The new token map is pushed to selkies and a gamepad_change notification is broadcast for every change made, followed by a state update. Unknown tokens are logged and ignored.

A push selkies refuses is logged and the room is still told: the notification describes what the session now holds, and the next successful push carries the whole map, so nothing here is worth leaving the room's view of itself out of step with the broker's over.

Hand mouse and keyboard control to a room member.

The controller's own token and None both mean control returns to the controller. A no-op when the target already holds it; otherwise the token map is pushed to selkies and an mk_change notification and a state update are broadcast. A push selkies refuses is logged, since input keeps routing by the map it already has until some later push lands.

Tell the room the session has ended, then close and forget every connection.

Forgetting a socket does not end it: the handler behind it stays parked in receive() forever, so every connection of every ended session would survive as a live socket and a running task. Each one is detached from ROOM first and closed after, which also means a handler waking on the close finds itself already replaced and skips its per-member cleanup: the seat, role and token-map releases it would do are moot against a session being torn down, and its departure notice would go to a room that has already been told the whole session ended. Broadcasts only queue, so the notice is given up to SESSION_END_FLUSH_WAIT to go out before the sockets close under it.

Close one room socket, giving up after outbox.CLOSE_WAIT on one that cannot take it.