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.

TagThenMeaning
lineid, then any file recordsAn ordinary line, under the id this room knows it by
editedidThat line now reads as this text
refiledid, then the new file recordsThat line’s files are now these
withdrawnidThat line is taken back
rosternamesWho is here, sent when you arrive
join, leavenameSomeone came or went
typingname, on or offSomeone 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
awayname, reasonSomeone stepped away. An empty reason means they are back
subjectdescription, then an optional linkWhat the room is about. An empty description means taken down
line-bytesa numberThe longest line this room will carry
listed, unlistedWhether this room is on the public list, sent when you arrive
membershipEndedThis 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

WhatLives as long asTo get it again
A room entrance referenceYour connection to the serverenter by name, or redeem the room’s link
A seatUntil you leave, are kicked, or disconnectsubscribe again
A line referenceYour connectionIt is not reissued. Hand it on if someone else should hold it
A room linkUntil the manager releases itIt is a string. Keep it
An invitationOne usemintInvitation again
A direct connectionUntil either side closes itAsk the directory to introduce you again
A stewardUntil the room’s moderator capability is rotatedAsk the manager again. It hands back the same one
An admin secretUntil the server restarts without a data directoryIt 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:

StepWho callsCallWhat happens
1Both, before introductionregister on the directory, then offerInboxEach has a name and has offered the server an inbox for introductions
2Miraintroduce on the directory, naming the botThe server hands Mira a reference to the inbox the bot offered
3Mira’s peerRedeems that reference with the bot’s peerA connection opens between the two peers. The server is not on it
4Miradm on the bot’s inbox, with her own reply inbox alongsideThe 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
5EitherhandRoom, offerRoom, handArchive, offerArchiveReferences 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

StepCallOnWhat happens
1attachyour files referenceOne upload reference per file
2postFilesyour files referenceThe line is posted with its file records, and every member gets a blob per file at once
3write, chunk by chunkthe uploadBytes arrive at the room
4read with offset and lengththe blobA 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 open is 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.