Move room version spec to /rooms (#3423)
* Cut/paste room version spec to its own page * Move grammar to bottom + add feature matrix The version grammar is not as interesting as the actual room versions, so this moves that whole section to the bottom. * Fix all links to room versions
This commit is contained in:
Travis Ralston
GitHub
parent
f295e828dc
commit
649fc2bdd2
25 changed files with 152 additions and 145 deletions
|
|
@ -19,19 +19,17 @@ To propose a change to the Matrix Spec, see the explanations at
|
|||
|
||||
The specification consists of the following parts:
|
||||
|
||||
* [Client-Server API](client-server-api)
|
||||
* [Server-Server API](server-server-api)
|
||||
* [Application Service API](application-service-api)
|
||||
* [Identity Service API](identity-service-api)
|
||||
* [Push Gateway API](push-gateway-api)
|
||||
* [Client-Server API](/client-server-api)
|
||||
* [Server-Server API](/server-server-api)
|
||||
* [Application Service API](/application-service-api)
|
||||
* [Identity Service API](/identity-service-api)
|
||||
* [Push Gateway API](/push-gateway-api)
|
||||
* [Room Versions](/rooms)
|
||||
* [Appendices](/appendices)
|
||||
|
||||
Additionally, this introduction page contains the key baseline
|
||||
information required to understand the specific APIs, including the
|
||||
sections on [room versions](#room-versions) and [overall
|
||||
architecture](#architecture).
|
||||
|
||||
The [Appendices](/appendices) contain supplemental information not
|
||||
specific to one of the above APIs.
|
||||
section the [overall architecture](#architecture).
|
||||
|
||||
The [Matrix Client-Server API Swagger
|
||||
Viewer](https://matrix.org/docs/api/client-server/) is useful for
|
||||
|
|
@ -426,82 +424,6 @@ Unless otherwise stated, timestamps are measured as milliseconds since
|
|||
the Unix epoch. Throughout the specification this may be referred to as
|
||||
POSIX, Unix, or just "time in milliseconds".
|
||||
|
||||
## Room Versions
|
||||
|
||||
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.
|
||||
|
||||
### 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
|
||||
SHOULD 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-beta`
|
||||
- `com.example.version`
|
||||
|
||||
### 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 6** as
|
||||
the default room version when creating new rooms.
|
||||
|
||||
The available room versions are:
|
||||
|
||||
- [Version 1](/rooms/v1) - **Stable**. The current version of most
|
||||
rooms.
|
||||
- [Version 2](/rooms/v2) - **Stable**. Implements State Resolution
|
||||
Version 2.
|
||||
- [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs
|
||||
are the event's hash.
|
||||
- [Version 4](/rooms/v4) - **Stable**. Builds on v3 by using
|
||||
URL-safe base64 for event IDs.
|
||||
- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
|
||||
signing key validity periods.
|
||||
- [Version 6](/rooms/v6) - **Stable**. Alters several
|
||||
authorization rules for events.
|
||||
- [Version 7](/rooms/v7) - **Stable**. Introduces knocking.
|
||||
|
||||
## Specification Versions
|
||||
|
||||
Matrix as a whole is released under a single specification number in the
|
||||
|
|
|
|||
|
|
@ -384,7 +384,7 @@ the following:
|
|||
## Identifier Grammar
|
||||
|
||||
Some identifiers are specific to given room versions, please refer to
|
||||
the [room versions specification](/#room-versions) for more
|
||||
the [room versions specification](/rooms) for more
|
||||
information.
|
||||
|
||||
### Server Name
|
||||
|
|
@ -599,7 +599,7 @@ A room has exactly one room ID. A room ID has the format:
|
|||
!opaque_id:domain
|
||||
|
||||
An event has exactly one event ID. The format of an event ID depends
|
||||
upon the [room version specification](/#room-versions).
|
||||
upon the [room version specification](/rooms).
|
||||
|
||||
The `domain` of a room ID is the [server name](#server-name) of the
|
||||
homeserver which created the room/event. The domain is used only for
|
||||
|
|
@ -680,7 +680,7 @@ the client if possible.
|
|||
{{% boxes/note %}}
|
||||
Clients should be aware that decoding a matrix.to URI may result in
|
||||
extra slashes appearing due to some [room
|
||||
versions](/#room-versions). These slashes should normally be
|
||||
versions](/rooms). These slashes should normally be
|
||||
encoded when producing matrix.to URIs, however.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -1200,7 +1200,7 @@ An example of the capability API's response for this capability is:
|
|||
```
|
||||
|
||||
This capability mirrors the same restrictions of [room
|
||||
versions](../index.html#room-versions) to describe which versions are
|
||||
versions](/rooms) to describe which versions are
|
||||
stable and unstable. Clients should assume that the `default` version is
|
||||
`stable`. Any version not explicitly labelled as `stable` in the
|
||||
`available` versions is to be treated as `unstable`. For example, a
|
||||
|
|
@ -1290,7 +1290,7 @@ any given point in time:
|
|||
|
||||
{{% boxes/warning %}}
|
||||
The format of events can change depending on room version. Check the
|
||||
[room version specification](../index.html#room-versions) for specific
|
||||
[room version specification](/rooms) for specific
|
||||
details on what to expect for event formats. Examples contained within
|
||||
the client-server specification are expected to be compatible with all
|
||||
specified room versions, however some differences may still apply.
|
||||
|
|
@ -1598,7 +1598,7 @@ content from the databases. Servers should include a copy of the
|
|||
when serving the redacted event to clients.
|
||||
|
||||
The exact algorithm to apply against an event is defined in the [room
|
||||
version specification](../index.html#room-versions).
|
||||
version specification](/rooms).
|
||||
|
||||
When a client receives an `m.room.redaction` event, it should change
|
||||
the affected event in the same way a server does.
|
||||
|
|
@ -1730,7 +1730,7 @@ This room can only be joined if you were invited.
|
|||
`knock`
|
||||
This room can only be joined if you were invited, and allows anyone to
|
||||
request an invite to the room. Note that this join rule is only available
|
||||
to rooms based upon [room version 7](/rooms/v7).
|
||||
in room versions [which support knocking](/rooms/#feature-matrix).
|
||||
|
||||
The allowable state transitions of membership are:
|
||||
|
||||
|
|
|
|||
|
|
@ -4,10 +4,96 @@ type: docs
|
|||
weight: 60
|
||||
---
|
||||
|
||||
* [Room Version 1](v1)
|
||||
* [Room Version 2](v2)
|
||||
* [Room Version 3](v3)
|
||||
* [Room Version 4](v4)
|
||||
* [Room Version 5](v5)
|
||||
* [Room Version 6](v6)
|
||||
* [Room Version 7](v7)
|
||||
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 implementation are still welcome
|
||||
to reference the following table, however the detailed per-version
|
||||
specifications are more likely to be of interest.
|
||||
|
||||
<!--
|
||||
Dev note: When the room version columns get overwhelming, merge versions
|
||||
1 through 6 as "1 ... 6" or similar given they don't add any features.
|
||||
|
||||
Alternatively, consider flipping the column/row organization to be features
|
||||
up top and versions on the left.
|
||||
-->
|
||||
|
||||
| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|
||||
|-------------------|---|---|---|---|---|---|---|
|
||||
| **Knocking** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |
|
||||
|
||||
## 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 6** as
|
||||
the default room version when creating new rooms.
|
||||
|
||||
The available room versions are:
|
||||
|
||||
- [Version 1](/rooms/v1) - **Stable**. The current version of most
|
||||
rooms.
|
||||
- [Version 2](/rooms/v2) - **Stable**. Implements State Resolution
|
||||
Version 2.
|
||||
- [Version 3](/rooms/v3) - **Stable**. Introduces events whose IDs
|
||||
are the event's hash.
|
||||
- [Version 4](/rooms/v4) - **Stable**. Builds on v3 by using
|
||||
URL-safe base64 for event IDs.
|
||||
- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
|
||||
signing key validity periods.
|
||||
- [Version 6](/rooms/v6) - **Stable**. Alters several
|
||||
authorization rules for events.
|
||||
- [Version 7](/rooms/v7) - **Stable**. Introduces knocking.
|
||||
|
||||
## 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
|
||||
SHOULD 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-beta`
|
||||
- `com.example.version`
|
||||
|
|
@ -348,7 +348,7 @@ a child:
|
|||
E4
|
||||
|
||||
For a full schema of what a PDU looks like, see the [room version
|
||||
specification](../index.html#room-versions).
|
||||
specification](/rooms).
|
||||
|
||||
### Checks performed on receipt of a PDU
|
||||
|
||||
|
|
@ -398,7 +398,7 @@ state. A given event is checked multiple times against different sets of
|
|||
state, as specified above. Each room version can have a different
|
||||
algorithm for how the rules work, and which rules are applied. For more
|
||||
detailed information, please see the [room version
|
||||
specification](../index.html#room-versions).
|
||||
specification](/rooms).
|
||||
|
||||
##### Auth events selection
|
||||
|
||||
|
|
@ -609,7 +609,7 @@ the room. What should the name of the room be at E5?
|
|||
|
||||
The algorithm to be used for state resolution depends on the room
|
||||
version. For a description of each room version's algorithm, please see
|
||||
the [room version specification](/#room-versions).
|
||||
the [room version specification](/rooms).
|
||||
|
||||
## Backfilling and retrieving missing events
|
||||
|
||||
|
|
@ -1111,7 +1111,7 @@ the full copy it received.
|
|||
The *reference hash* of an event covers the essential fields of an
|
||||
event, including content hashes. It is used for event identifiers in
|
||||
some room versions. See the [room version
|
||||
specification](/#room-versions) for more information. It is
|
||||
specification](/rooms) for more information. It is
|
||||
calculated as follows.
|
||||
|
||||
1. The event is put through the redaction algorithm.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue