f97d2944ae
* Placeholder * i++ * Room version 12 Template out a v12 room version Make v12 default, per MSC4304 Update PDU checks and auth event selection per MSC4291 Describe new room_id format per MSC4291 Move v6 depth definition to a component for easier referencing Move room_id to a component to prep for v12, per MSC4291 Create and use a new room_id component for v12+ per MSC4291 Reflect auth events selection change onto all room versions per MSC4291 The MSC asks the `description` of `auth_events` to be adjusted, however this feels like a better representation of the change. Add `room_id` format rules and renumber per MSC4291 Reflect change to rule 1.2 per MSC4291 Insert same room_id check to v1-12 auth rules per MSC4307 and MSC4291 Deprecate `predecessor.event_id` per MSC4291 Insert auth rule to validate `additional_creators` per MSC4289 Insert rule for `users` validation of creators and renumber per MSC4289 Define "room creator(s)" per MSC4289 Spec `additional_creators` on create events per MSC4289 Spec `additional_creators` on `/upgrade` per MSC4289 The MSC doesn't mention how to handle unsupported room versions, but the Synapse implementation used for FCP ignores the field in such room versions. This feels like a good approach, and will need clarifying in the MSC too (if accepted at the spec level). Add notes to `/upgrade` behaviour per MSC4289 and MSC4291 Describe how additional creators work during room creation per MSC4289 Fix default user power level descriptions per MSC4289 Describe tombstone power level changes per MSC4289 Warn clients about event format changes in v12 per MSC4289 and MSC4291 Flag additional room creators support for client reference per MSC4289 Remove TODO now that it's fully addressed Copy state res into v12 as-is for modification Apply Modification 1 to SR2.1 per MSC4297 Apply Modification 2 to SR2.1 per MSC4297 Add summary box to the top of SR2.1 for ease of developer reference Modification 2 was split into items 2 and 3 for further ease of understanding. Add all the changelogs `x` is used until a real PR number can be assigned. Some changelogs are duplicated to the Client-Server API to increase visibility of the changes to v12. Review: Minor phrasing adjustments in changelogs Review: Clarify that v12 isn't quite the default yet in the changelog Review: Clarify to clients that creators are immutable Review: Improve 'how to parse a domain' advice for legacy apps Review: Add a bit more detail as to why a room ID might be required Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Clarify that clients can override the tombstone default Mention creatorship UI label by finishing the Permissions section We probably should have removed the WIP note in v1.0, but alas. Add changelog for tombstone changes Use assigned spec PR number in changelogs (cherry picked from commit ec81eea7e4532fd398b8013071d6981c97117d9e)
5.4 KiB
| title | type | weight |
|---|---|---|
| Room Versions | docs | 60 |
Rooms are central to how Matrix operates, and have strict rules for what is allowed to be contained within them. Rooms can also have various algorithms that handle different tasks, such as what to do when two or more events collide in the underlying DAG. To allow rooms to be improved upon through new algorithms or rules, "room versions" are employed to manage a set of expectations for each room. New room versions are assigned as needed.
There is no implicit ordering or hierarchy to room versions, and their principles are immutable once placed in the specification. Although there is a recommended set of versions, some rooms may benefit from features introduced by other versions. Rooms move between different versions by "upgrading" to the desired version. Due to versions not being ordered or hierarchical, this means a room can "upgrade" from version 2 to version 1, if it is so desired.
Feature matrix
Some functionality is only available in specific room versions, such as knocking. The table below shows which versions support which features from a client's perspective. Server implementations are still welcome to reference the following table, however the detailed per-version specifications are more likely to be of interest.
| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Knocking | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| Restricted join rules | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ | ✔ |
knock_restricted join rule |
❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ |
| Additional room creators | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |
Complete list of room versions
Room versions are divided into two distinct groups: stable and unstable. Stable room versions may be used by rooms safely. Unstable room versions are everything else which is either not listed in the specification or flagged as unstable for some other reason. Versions can switch between stable and unstable periodically for a variety of reasons, including discovered security vulnerabilities and age.
Clients should not ask room administrators to upgrade their rooms if the room is running a stable version. Servers SHOULD use room version 12 as the default room version when creating new rooms.
{{% boxes/note %}}
{{% added-in v="1.16" %}}
Room version 12 is introduced and made default in this specification release. Servers are encouraged to continue using room version 11 as the default room version for the early days and weeks following this specification release, and then gradually switch the default over when they deem appropriate.
{{% /boxes/note %}}
The available room versions are:
- Version 1 - Stable. The initial room version.
- Version 2 - Stable. Implements State Resolution Version 2.
- Version 3 - Stable. Introduces events whose IDs are the event's hash.
- Version 4 - Stable. Builds on v3 by using URL-safe base64 for event IDs.
- Version 5 - Stable. Introduces enforcement of signing key validity periods.
- Version 6 - Stable. Alters several authorization rules for events.
- Version 7 - Stable. Introduces knocking.
- Version 8 - Stable. Adds a join rule to allow members of another room to join without invite.
- Version 9 - Stable. Builds on v8 to fix issues when redacting some membership events.
- Version 10 - Stable. Enforces integer-only power levels
and adds
knock_restrictedjoin rule. - Version 11 - Stable. Clarifies the redaction algorithm.
- Version 12 - Stable. Changes room IDs to be hashes of the create event, formalizes room creators with infinite power level, and iterates on state resolution.
Room version grammar
Room versions are used to change properties of rooms that may not be compatible with other servers. For example, changing the rules for event authorization would cause older servers to potentially end up in a split-brain situation due to not understanding the new rules.
A room version is defined as a string of characters which MUST NOT
exceed 32 codepoints in length. Room versions MUST NOT be empty and
MUST contain only the characters a-z, 0-9, ., and -.
Room versions are not intended to be parsed and should be treated as
opaque identifiers. Room versions consisting only of the characters
0-9 and . are reserved for future versions of the Matrix protocol.
The complete grammar for a legal room version is:
room_version = 1*room_version_char
room_version_char = DIGIT
/ %x61-7A ; a-z
/ "-" / "."
Examples of valid room versions are:
1(would be reserved by the Matrix protocol)1.2(would be reserved by the Matrix protocol)1.2-betacom.example.version