The Rooms protocol
Rooms defines methods and values for rooms, membership, and messages over OCapN’s CapTP. A client calls an object it holds. It starts by fetching the public directory object, which hands back rooms and other members’ inboxes. Optional operator and diagnostic objects are published separately under secret names.
If OCapN is new to you, Why OCapN explains references, promises, and introductions from the ground up, and Concepts covers locators and durable links.
The objects
Each card shows how to obtain an object, the calls it answers, and what it returns. Cool cards live on the server, warm cards are handed to you to use or pass on, and the inbox is the one you make yourself.
Published by the server
directory
Fetch it by name. The public entry point.
open openPrivateLink openManaged enter list watch register introduce offerInbox link listPublications namedPublications watchPublications enterPublication linkPublication unwatchPublications
Hands back a room, a name, another member's inbox, or a room link. The publication calls list the server's published rooms and links. listPublications answers one page at a time, with a cursor to pass back for the next page.
inspect, peering, listeners
Each is a secret the server prints when started with --capabilities naming diagnostics, peering, or admin-listeners. Fetch it like the directory.
snapshot publishDurableRoom list up down
Hands back what the server holds right now, the live listeners as rows, or a lease that answers ready and revoke.
operator
The server's operator secret, pasted into the Holdings tab. It fills the admin pages under /ops.
operatorSnapshot operatorRetireMatching watch unwatch changed giveSteward giveManager revokeSteward revokeRoomLink unregisterRoom setRoomPolicy revokeRoomAuthority revokeNick disconnectSession removeOperatorRoom releaseOperatorReference
Answers for the server's rooms, names, live connections, and the references each holds, and hands back a room's steward.
Handed back by the directory
room
open or enter, or a room link.
subscribe called private roomPolicy managedRoomIdentity link
Hands back a seat, a subject, or a room link.
name
register, with the name you want.
voucher signalCheck
Hands back proof that you hold this name, for a second connection, and answers a route's recheck of an exact registered name.
bootstrap
openManaged's second answer, good exactly once.
roomAuthorities
Hands back the room's durable entry and manager sturdyrefs, as strings.
manager
The management link openManaged hands you.
link giveSteward revokeSteward revokeRoomLink setRoomPolicy unregisterRoom managedRoomIdentity
Hands back a reissued room link or the room's steward.
Handed back by the manager
steward
giveSteward on the manager, or the operator's admin page. It is created once per room, and asking again hands back the same one.
kick governs
Hands back nothing. A member is asked to leave.
Handed back by a room
seat
subscribe, with your inbox.
post history typing away leave membershipKind mintInvitation
Hands back a line, an invitation, or the lines the room kept.
files
The fourth slot of subscribe's answer, in a room that can hold files.
attach postFiles
Hands back an upload per file, and posts a line with its files.
subject
The third slot of subscribe's answer, for participants.
setSubject
Hands back nothing. The room tells everyone.
Handed back by your seat and files
line
post. The line you just said.
edit withdraw refile
Hands back nothing. The room tells everyone through their inbox.
upload and blob
attach hands you one upload per file. The room hands everyone a blob for it.
write discard read
Bytes go in through the upload and come out of the blob, from an offset, up to a length.
invitation
mintInvitation on a seat.
claimInvitation
Hands back the room, exactly once. Then subscribe for a seat.
Yours
inbox
You make it, and hand it to rooms and to the directory. Rooms call notify on it. Other members call the rest.
notify dm typing directReady handRoom offerRoom handArchive offerArchive offer candidate
Receives every line a room sends you, whatever another member hands you directly, and the signaling offers and candidates a WebRTC exchange routes to you.
Editing a line requires its line reference. You can pass that reference to someone else, giving them access to edit or take down the line. A bot holding the subject reference can update the subject through the same methods as any other holder. A subject reference works for as long as the seat it came with, and joining again gives a new one.
A subject describes the room and can link to a related object, such as a board or game, through its ocapn:// sturdyref. The room checks that the link parses and tells it to everyone in the room, but never calls the object. Whoever set it hosts the object and decides what that reference may do. A subject with no link is a plain topic.
What the room tells you
The room calls notify on your inbox. After the text, a line carries a tag that says what kind of thing it is. A client that does not know a tag skips it and draws the line anyway, so the room can say more over time without every client being rebuilt first.
| Tag | Then | Meaning |
|---|---|---|
line | id, then any file records | An ordinary line, under the id this room knows it by |
edited | id | That line now reads as this text |
refiled | id, then the new file records | That line’s files are now these |
withdrawn | id | That line is taken back |
roster | names | Who is here, sent when you arrive |
join, leave | name | Someone came or went |
typing | name, on or off | Someone is typing, never stored. It ends at off, at a line from that name, when that name leaves or goes offline, or after some seconds with no repeat |
away | name, reason | Someone stepped away. An empty reason means they are back |
subject | description, then an optional link | What the room is about. An empty description means taken down |
line-bytes | a number | The longest line this room will carry |
listed, unlisted | Whether this room is on the public list, sent when you arrive | |
membershipEnded | This room has released the seat behind your inbox |
Typing in a direct conversation ends the same way. A client whose member is still typing says on again before that time runs out, and again when a line it sent arrives while they type. It needs no off beside a line it sends.
How long each thing lives
| What | Lives as long as | To get it again |
|---|---|---|
| A room entrance reference | Your connection to the server | enter by name, or redeem the room’s link |
| A seat | Until you leave, are kicked, or disconnect | subscribe again |
| A line reference | Your connection | It is not reissued. Hand it on if someone else should hold it |
| A room link | Until the manager releases it | It is a string. Keep it |
| An invitation | One use | mintInvitation again |
| A direct connection | Until either side closes it | Ask the directory to introduce you again |
| A steward | Until the room’s moderator capability is rotated | Ask the manager again. It hands back the same one |
| An admin secret | Until the server restarts without a data directory | It is written into the data directory |
A live reference dies with its connection. To enter again later, Rooms asks the server for a durable link, an OCapN sturdyref. The link keeps the right to enter and the room’s identity, not a live room or seat. Redeeming it gives a fresh entrance reference, and the first member to join brings the room back after a restart or after everyone left. A private room’s link says nothing about the room’s label, and the label says nothing about the link.
An introduction, call by call
A direct conversation is the introduction OCapN calls a three-party handoff. Here Mira asks to message the lead bot:
| Step | Who calls | Call | What happens |
|---|---|---|---|
| 1 | Both, before introduction | register on the directory, then offerInbox | Each has a name and has offered the server an inbox for introductions |
| 2 | Mira | introduce on the directory, naming the bot | The server hands Mira a reference to the inbox the bot offered |
| 3 | Mira’s peer | Redeems that reference with the bot’s peer | A connection opens between the two peers. The server is not on it |
| 4 | Mira | dm on the bot’s inbox, with her own reply inbox alongside | The first line arrives, and the bot’s replies come back to that inbox. When the bot cannot dial Mira’s side, it dials the other way and sends directReady to set up the reply route with no chat message |
| 5 | Either | handRoom, offerRoom, handArchive, offerArchive | References move between them over the same connection, as live handoffs or as durable links |
When the two peers are browsers, WebRTC’s connection details travel through the directory as offerSignaling, signalOffer, signalAnswer, signalCandidate, and signalDone, until the two are talking and the server drops out. A peer that will not answer an offer sends signalDecline with its reason, and the offering peer hears it right away.
Files, call by call
| Step | Call | On | What happens |
|---|---|---|---|
| 1 | attach | your files reference | One upload reference per file |
| 2 | postFiles | your files reference | The line is posted with its file records, and every member gets a blob per file at once |
| 3 | write, chunk by chunk | the upload | Bytes arrive at the room |
| 4 | read with offset and length | the blob | A member reads. A read that reaches bytes still on their way in waits for them |
In a direct conversation the sender hosts the file on the direct connection and the other side reads it the same way. The room never sees those bytes.
What OCapN gives Rooms
- No ambient authority. There is no account table and no permission check by name in the calls above. You call an object through a reference you hold, subject to the object’s limits and the reference’s lifetime.
- Introductions across three parties. The server can hand you a reference to something another peer hosts, and your peer redeems it with them directly. Direct messages, invitations, and shared archives are all this one move.
- Promises. A call answers a promise, so a client can keep sending to a room while its
openis still on the way back. - Durable links. A sturdyref names something a host can bring back across restarts and connections. Room links, invitations, and admin secrets are all sturdyrefs.
Clients in Zig, Rust, Python, Racket, TypeScript, and the browser all speak this protocol. So does a Spritely Goblins program: it can sit in a room and answer a direct message without any change to Goblins, because Rooms uses only OCapN.
The specification and reasons for each method are in protocol.ts for the directory, rooms, seats, lines, files, and introductions. Other files cover handover, IRC, and the admin objects. zig build gen-rooms-protocol generates the core verbs into each client. How Rooms works shows how the code that speaks it is divided.