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 — locally. Nothing here talks to another server; federation is Phase 5, and every operation that would need it is refused with a message that says so rather than a bare M_FORBIDDEN.

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 3 ships without one; this is the seam /sync plugs into in Phase 4.

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 will need in Phase 5.

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.

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 does not have	403, naming federation
Inviting @user:other.example	403, naming federation
Resolving #alias:other.example	403, naming federation
publicRooms?server=other.example	403, naming federation
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, so it normally needs a key fetcher — but while federation is off every room is local, this server's own key is in hand, and the rule can be applied in full. A join authorised via a remote user 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 room-level, not per-event. A read of a room's state or members is allowed for a joined member, and for anybody at all when the room is world_readable. A user who has left a room should see the state as it was when they left; they are refused instead. Doing it properly means answering every state read from a historical snapshot and filtering each event by the visibility in force when it was sent — the same machinery /messages and /context need, so it belongs with them in Phase 4 rather than being built twice. The current behaviour errs towards showing too little.

GET /rooms/{roomID}/members?at= is accepted and ignored. There is one stream position in this build, because /sync has no stream to be at until Phase 4, so the membership as of any token a client can hold is the current membership. Phase 4 has to honour it.

No /messages, /context or /sync of rooms. Phase 4. Until then a client can create a room, send into it and read its state, but cannot page its history.

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 (Phase 9). 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.