How Rooms works

Rooms runs in two places from the same Rust code. In a browser it is a full glowcap peer compiled to WebAssembly. On a server it runs over sockets, files, and a database. Joining, sending, recovery, and errors work the same way in both.

A room is something you hold

The server is the first thing your session reaches. It introduces you to rooms and to other members. When you join a room, the room hands you a seat, and your membership actions go through it: posting, leaving, and showing that you are typing. The seat carries that authority. Anyone you share the seat or your session with can act as that member.

Every line you post comes back with its own reference for editing or deleting it. A private room opens from a link, and an invitation works once. Admin and archive access are references too, so a host can hand out one narrow thing without adding roles to every message on the wire.

The server gives a person and a bot the same room and introduces them to each other. Their direct conversation uses a separate connection.

A direct conversation starts with an introduction between three parties. The server hands you an inbox the other member made just for you, and using it opens a connection between the two of you. The room does not carry the conversation. A relay may still carry the connection. The Rooms protocol names every one of these objects and the calls they answer.

What happens after a click

Rooms records each request before doing the work on disk or over the network. It then records the result or failure. The screen shows that record, including unfinished work and problems that need your attention.

A click becomes a saved request, Rooms does the work, the result is confirmed, and the screen shows what happened. A refused or unconfirmed request stays beside the same note, in view.

For example:

ActionWhat you asked forWhat you see afterwards
Join a roomThe server, the room, and the name you chose or left blank.Your seat in the room under the name you got, or a refusal that keeps your choice and the suggestion.
Send a lineYour exact text and files, for one conversation.The confirmed line, or your text back in the box, or a line marked unconfirmed that you will not be asked to resend blindly.
Change where history goesThe archive you picked and whether to keep recording.The new setting in force, or an erased history, or a visible problem while the existing setting stays in force.
Open a shared sessionThe link and the access you asked for.The session on screen, or a plain message saying whether the trouble was reaching it or being let in.

Rooms restores saved state when it starts. Browser sessions use IndexedDB, and the session service keeps its data in the data directory. Both restore state before reconnecting to directories. An interrupted operation can still have an unknown outcome after restart.

Rust on the C ABI

Rooms is built from Rust on glowcap’s C ABI, so it uses the C ABI and the WebAssembly build the way an outside user would. The application boundary keeps the application rules in a Rust crate built without the standard library, so it cannot touch files, sockets, or clocks. The services ship as binaries with no runtime to install. The cost is bundle size, build time, and a copy of each typed command where the page meets WebAssembly.

How the code is divided

The browser and the server both stand on one shared runtime. Under it, one crate holds the rules and one holds the glowcap clients, which stand on the glowcap protocol core. Only the two top crates and the platform crate touch a browser or an operating system.
CrateWhat it holds
rooms-applicationThe rules, with no I/O: limits, requests, state changes, name allocation, everything that can go wrong, and the shape of saved files.
rooms-glowcapThe clients for each Rooms reference, and the checks on what arrives over the wire, on top of glowcap’s C ABI.
rooms-runtimeThe order work runs in, what gets accepted, recovery, cleanup, and turning saved state into what the screen shows.
rooms-platformTokio, clocks, randomness, files, listening sockets, TLS, and WebSocket connections.
rooms-servicesThe server programs: the directory, the session service, the archive, the Rooms server that serves the page and relays for it, and the IRC bridge and IRC server.
rooms-browserBrowser storage, WebRTC, the JavaScript side, and the WebAssembly entry points.

Checks in the build keep each crate’s imports going one way. The shared crates cannot import the platform, the services, or the browser. The browser cannot import the server side. The services may use the platform, but they cannot push server behavior back into the shared rules.

Your browser is a peer

The page loads the same glowcap protocol core every other language binding uses. JavaScript supplies the clock and the byte connections. The Rust browser code owns your session, what is saved, and WebRTC. TypeScript draws the screen and turns what you do into requests.

Your browser can connect through an advertised noise-relay route, with encryption between the peers. It can also ask its Rooms server to open a TCP, iroh, or onion connection. On an iroh route, that server verifies the directory’s key and can read the CapTP traffic.

You also trust whoever serves the page, because their code runs in your browser and holds your session. This can be glowcap.org or a server you operate. For a direct message over WebRTC, the server passes along the connection details and the peers exchange messages over their own channel.

When something goes wrong

A known problem has a stable code, a subject, a plain sentence, and, where there is one, a suggested next step. A problem Rooms did not expect arrives in the same shape with a short diagnostic. If cleaning up after a problem also fails, the second failure is kept beside the first.

Rust and TypeScript share that shape, so the screen tells a taken name from an unreachable route, an expired invitation, a denied reference, a storage failure, or an unconfirmed request by its code, not its wording. A code it does not recognize shows as unknown instead of passing for success.

What is stored where

A local session, the session service, and the archive service store their data separately. Moving or sharing one does not move the others. The session service keeps your saved state, the record of unfinished work, your identity, which servers to connect to, your links, and which archive you picked. An archive keeps messages and whatever files it accepted. A device attached to a shared session keeps only its display settings and its local archive. A session kept locally is the device’s own, saved in the browser’s storage.

An attached device can disconnect while the shared session keeps running on its host. Each device keeps its own theme, open panels, and local history. Drafts and the selected conversation belong to the shared session. Clearing a session does not erase an archive somebody else still holds.

Continue with Operate Rooms to host it, or Run Rooms to see all of this on screen.