Warp/docs/rooms.md

Rooms

internal/roomserver and the room half of internal/storage: PLAN.md Phase 3. This is what turns the event core of Phase 2 into rooms a client can use. Phase 3 built it local only; Phase 5 taught the same pipeline to take in events from other servers and to join, leave and invite across them, which federation.md describes.

Where the decisions live

Question	Answered by
Is this event well-formed?	internal/matrix/event
May this event be in the room?	internal/matrix/auth
Which of two conflicting states wins?	internal/matrix/stateres
What are this room's prev_events, depth and auth_events?	roomserver
Who may call this endpoint?	nobody — see below
How is any of it stored?	storage.RoomStore

The third row is the important one. internal/matrix is pure library code with no storage and no HTTP; the roomserver is what connects those rules to a database and to a room's history. It is the only thing in Warp that creates an event.

The fifth row is not a joke. The Client-Server handlers do no authorisation of their own: whether Alice may kick Bob, rename the room or send a message is a question about the room's power levels and membership, and the one place that is answered correctly is the authorisation rules inside the pipeline. A handler-level check would be a second, worse copy of them. The handlers do check the two things the rules cannot see — that the caller is who their token says, and that a path parameter is a well-formed ID.

The input pipeline

Every event goes through one function, roomserver.send, whatever sent it. The stages are:

1. Validate — the sender is a user of this server (we can only sign as ourselves), and the content is a JSON object within the size limit.
2. Authorise — the event is built against the room's state with exactly the auth_events the selection algorithm asks for, then run through auth.CheckAuthEvents (rule 3) and auth.Check (everything else).
3. Resolve — the state the event is judged against is the state after the room's forward extremities, resolved with state resolution v2 when there is more than one.
4. Persist — the event, its state snapshot, the new current state, the new forward extremity and any transaction ID go down in one transaction.
5. Emit — the Notifier is told. Phase 4 plugs the syncapi in here, so that a client blocked in /sync hears about an event in milliseconds rather than when its timeout expires. See sync.md.

Why there is a lock per room

Two events racing into one room would each pick up the same forward extremities, both become one, and fork the room for no reason — which would then need state resolution to put back together. A mutex per room instead keeps every locally created event a child of the one before it, so a room this server fills on its own always has exactly one forward extremity. The admin room detail reports the extremities for that reason: more than one means something unusual happened.

Why state resolution is here at all

With that lock, a Phase 3 room cannot fork, so the resolution path is unreachable from outside. It is implemented anyway because the alternative is a pipeline that authorises against one arbitrary branch of a fork without saying so — and because stateAfter, which it needs, is also what federation needs, and since Phase 5 uses.

Soft failure

An event can be allowed by the rules against its own auth_events and still fail against the room's current state; the spec calls that soft failure and asks a server to keep the event but not let it into the forward extremities. There is no soft-failure check here, because for an event created on this server the two states are the same one. It arrives with events that come from somewhere else.

Room versions

Versions 3 to 12 all work, and the tests create a room at each of them and send a message into it. Version 12 is the one that earns the coverage: its room ID is the create event's ID, its create event carries no room_id at all, and the create event is left out of every other event's auth_events. Two consequences worth knowing:

• createRoom has to build the create event before it can name the room, which is why that one event does not go through send.
• The state auth.Check is given is the event's auth_events plus the create event, because from version 12 the create event is identified by the room ID rather than cited. The rules still need it: it is what says who the room's creators are.

createRoom defaults to version 11, which is what the registry says and why (internal/matrix/roomversion): the spec asks servers to stay there for a while after 1.16 so clients and bridges catch up.

Storage

Events are keyed by event ID rather than by a numeric surrogate. An event ID appears in prev_events, auth_events, state snapshots and client requests alike, so a surrogate would have to be translated at every one of those boundaries.

Stream ordering is this server's own monotonic position for an event, handed out by a counter row inside the write transaction. Neither AUTOINCREMENT nor a sequence would do: the two engines spell those differently, and a PostgreSQL sequence is explicitly not transactional, so a rolled-back write would leave a hole that /sync would have to be taught to skip. History backfilled from other servers is numbered by a second counter that runs downwards from -1, so that it sorts below everything already held; see federation.md.

State snapshots are stored per event and deduplicated by a hash of their contents. That is what makes a per-event snapshot affordable: every message in a room whose state is not changing resolves to the snapshot the previous one already stored, so the table grows with state changes rather than with traffic. It is also what makes "the state after a forward extremity" answerable, which state resolution needs.

Current state is kept as its own table, which is derivable from the events and stored anyway because every authorisation decision reads it. The membership column is a denormalised copy of content.membership on member rows, so "the rooms @alice is joined to" is an index lookup rather than a scan that parses JSON.

The room's listing columns — name, topic, canonical alias, join rule, history visibility, guest access, room type and the joined-member count — live on the room row. The public room directory orders every published room by member count and pages the result, which cannot be done by reading each room's state in turn. The roomserver recomputes them when one of the state events behind them changes, and only then; a room full of chat does not rewrite its own row on every line.

Federation-disabled behaviour

PLAN.md section 3, enforced here:

Operation	While federation is off
/join a room this server is not in	403, naming federation; with it on, a join through a server that is
Inviting @user:other.example	403, naming federation; with it on, the invite is countersigned by their server
Resolving #alias:other.example	403, naming federation; with it on, the owning server is asked
publicRooms?server=other.example	403, naming federation; with it on, the other server is asked
Room and event IDs	unchanged — a room created offline federates normally if federation is later turned on
Signing	unchanged — every event is signed with the server key

The messages are explicit on purpose. M_FORBIDDEN alone sends a user to their operator and the operator hunting through power levels.

Restricted joins are the interesting case. The rule needs a signature from the authorising user's server checked. This server's own signatures are checked against the key in hand, so a restricted join authorised by a local user works whether or not federation is on; one authorised by a remote user needs the key ring, and while federation is off it is refused like everything else that would need another server.

Known gaps

These are deliberate, and each one is somebody else's phase.

History visibility is judged by the room's current setting, not by the one in force when each event was sent. Phase 4 built the rest of it: roomserver.VisibleRange works out the span of a room a user may read, which a user who has left is now served from rather than being refused, and ?at= on /members is honoured. What is left is that the span is computed from the room's current history_visibility, where the spec judges each event by the one in force when it was sent. Doing it exactly is a state read per event and belongs with the state storage work of open question 1. See sync.md.

No knocking endpoint. The knock join rule is enforced by the authorisation rules — a knock-rule room needs an invite to join — but POST /knock/{roomIdOrAlias} is not served.

No third-party invites. They go through an identity server, which Warp does not talk to: identity servers are a non-goal (PLAN.md section 1). createRoom with invite_3pid, and /invite with id_server, are refused rather than silently dropped.

No room upgrades. POST /rooms/{roomID}/upgrade and the tombstone handling that goes with it are not served.

A half-built room can be left behind. createRoom sends a dozen events through the pipeline one at a time, each authorised against what the ones before it produced, and a failure part-way through leaves a room that exists and is incomplete. That is the lesser evil: the alternative is holding every event of a new room in memory and writing them in one transaction, which would make the pipeline that authorises them a special case — and the pipeline is the one thing in here that must not have special cases. Such a room is visible only to its creator and can be purged. The one failure that is handled properly is an alias clash, which takes the room row back out, because it is the one a second client can cause at any time.

Tests

internal/roomserver tests run against the real event core and a real SQLite database, not fakes: what is under test is whether an event this server signs is one the authorisation rules accept, and a fake of either would only prove that the pipeline calls what the fake expects. internal/storage tests the room store against both SQL drivers. internal/clientapi and internal/adminapi test the HTTP surface through httptest.

Two things the local-only shape makes untestable here, both covered in internal/matrix/auth:

• The power-level half of the redaction test. A redaction applies when it comes from the same server as its target, and every user here is on one server, so that branch covers every pair of them.
• Soft failure, and state resolution across a real fork.