Warp/docs/event-core.md

The event core

server/internal/matrix is the heart of the homeserver: the operations whose results every server in a room must agree on, byte for byte. It is pure library code — no HTTP, no database, no clock — and that is deliberate. Everything here is deterministic and therefore testable against the spec's own vectors, which is the only way to be confident a room's history will still verify on somebody else's server in five years.

It corresponds to PLAN.md Phase 2.

The packages

Package	What
canonicaljson	the canonical JSON encoding: sorted keys, no whitespace, integers only, minimal escaping
signing	ed25519 server keys (Phase 0) plus the Signing JSON algorithm
id	the identifier grammars as they appear inside events, which are laxer than the ones for new accounts
roomversion	the registry of room versions and of what each one changes
event	the PDU model: parsing, validation, content and reference hashes, event IDs, redaction, signing
auth	the authorisation rules, power levels, and the auth events selection algorithm
stateres	state resolution v2, and version 12's amendment to it

They stack in that order. canonicaljson depends on nothing, and stateres depends on everything.

Reading the code against the spec

The authorisation rules in auth are written in the order and the shape the spec gives them, and the comments name the rule numbers from the room version 11 and version 12 pages, so the two can be read side by side. That is worth more here than concision: a rule that is subtly wrong does not fail a test, it forks a room.

Where the room versions differ, the difference is a field on roomversion.Rules rather than a comparison on the version string. Adding a room version should mean adding one entry to the table in roomversion.go and nothing else.

What the tests check

The spec publishes test vectors, and they are the backbone of the suite:

• canonicaljson runs the worked examples from the appendices.
• signing runs the two JSON signing vectors, byte for byte.
• event runs the two event signing vectors, byte for byte — the content hash, the redaction, and the signature over the redacted form.
• stateres ports several scenarios from Synapse's state resolution tests, including the topic reset that the algorithm is known to produce.

Beyond the vectors, the suite leans on properties rather than examples where it can: canonical JSON is idempotent, an event's ID survives redaction, a signature survives a rewritten unsigned, and state resolution does not depend on the order the state sets arrive in. Both canonicaljson.Encode and event.Parse have fuzz targets, since both read bytes straight off the network.

cd server
go test ./internal/matrix/...
go test ./internal/matrix/canonicaljson -fuzz FuzzEncode -fuzztime 60s
go test ./internal/matrix/event -fuzz FuzzParse -fuzztime 60s

Room versions

Versions 3 to 12 are implemented. createRoom will default to 11: the spec says servers SHOULD default to 12 but asks them to stay on 11 for a while after the Matrix 1.16 release so that clients and bridges catch up, and we follow that advice.

Versions 1 and 2 are in the registry but marked unsupported, so roomversion.Get refuses them with a clear error. They carry the event ID inside the event, write prev_events and auth_events as [id, hashes] tuples rather than plain lists, and version 1 uses state resolution v1 — enough of a separate event format to be its own piece of work. They are only needed to join rooms created before 2018 on other servers, so they wait for federation in Phase 5.

Known gaps

• Out-of-range integers in old rooms. Room versions 1 to 5 may contain integers outside the range canonical JSON permits, and the spec asks servers to cope where they can. Warp rejects such an event whatever its room version. Handling it means a second, lenient encoder; it can wait until federation makes those rooms reachable.
• Signature checking during state resolution. The restricted join rule asks for a signature from the server authorising the join. stateres does not re-check it, on the grounds that the event was checked when it was accepted into the room, and that state resolution must not do network I/O. Synapse draws the line in the same place. The consequence is that event intake must never be skipped — see intakeVerified in stateres.go.
• State resolution v1 is not implemented, for the same reason room versions 1 and 2 are not.

What is not here

Two decisions that look like they belong to the authorisation rules do not:

• Whether a redaction is applied. The rules allow nearly every m.room.redaction event; whether the redaction takes effect is auth.ShouldApplyRedaction, which the roomserver runs once it holds both events.
• Soft failure. An event can pass the rules against its own auth events and still be denied a place among the room's forward extremities because it fails against the current state. That is the roomserver's business, in Phase 3.

Neither needs the event core, and both need storage.