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](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](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](federation.md#history-backfill).

**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](sync.md#visibility).

**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.