-
Notifications
You must be signed in to change notification settings - Fork 384
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1773 from matrix-org/travis/spec/rooms
Add a room version specification
- Loading branch information
Showing
9 changed files
with
447 additions
and
245 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
.. Copyright 2017,2019 New Vector Ltd | ||
.. | ||
.. Licensed under the Apache License, Version 2.0 (the "License"); | ||
.. you may not use this file except in compliance with the License. | ||
.. You may obtain a copy of the License at | ||
.. | ||
.. http://www.apache.org/licenses/LICENSE-2.0 | ||
.. | ||
.. Unless required by applicable law or agreed to in writing, software | ||
.. distributed under the License is distributed on an "AS IS" BASIS, | ||
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
.. See the License for the specific language governing permissions and | ||
.. limitations under the License. | ||
Room Version 1 | ||
============== | ||
|
||
This room version is the first ever version for rooms, and contains the building | ||
blocks for other room versions. | ||
|
||
Server implementation components | ||
-------------------------------- | ||
|
||
.. WARNING:: | ||
The information contained in this section is strictly for server implementors. | ||
Applications which use the Client-Server API are generally unaffected by the | ||
details contained here, and can safely ignore their presence. | ||
|
||
|
||
The algorithms defined here should only apply to version 1 rooms. Other algorithms | ||
may be used by other room versions, and as such servers should be aware of which | ||
version room they are dealing with prior to executing a given algorithm. | ||
|
||
.. WARNING:: | ||
Although room version 1 is the most popular room version, it is known to have | ||
undesirable effects. Servers implementing support for room version 1 should be | ||
aware that restrictions should be generally relaxed and that inconsistencies | ||
may occur until room version 2 (or later) is ready and adopted. | ||
|
||
State resolution | ||
~~~~~~~~~~~~~~~~ | ||
|
||
.. WARNING:: | ||
This section documents the state resolution algorithm as implemented by | ||
Synapse as of December 2017 (and therefore the de-facto Matrix protocol). | ||
However, this algorithm is known to have some problems. | ||
|
||
The room state :math:`S'(E)` after an event :math:`E` is defined in terms of | ||
the room state :math:`S(E)` before :math:`E`, and depends on whether | ||
:math:`E` is a state event or a message event: | ||
|
||
* If :math:`E` is a message event, then :math:`S'(E) = S(E)`. | ||
|
||
* If :math:`E` is a state event, then :math:`S'(E)` is :math:`S(E)`, except | ||
that its entry corresponding to :math:`E`'s ``event_type`` and ``state_key`` | ||
is replaced by :math:`E`'s ``event_id``. | ||
|
||
The room state :math:`S(E)` before :math:`E` is the *resolution* of the set of | ||
states :math:`\{ S'(E'), S'(E''), … \}` consisting of the states after each of | ||
:math:`E`'s ``prev_event``\s :math:`\{ E', E'', … \}`. | ||
|
||
The *resolution* of a set of states is defined as follows. The resolved state | ||
is built up in a number of passes; here we use :math:`R` to refer to the | ||
results of the resolution so far. | ||
|
||
* Start by setting :math:`R` to the union of the states to be resolved, | ||
excluding any *conflicting* events. | ||
|
||
* First we resolve conflicts between ``m.room.power_levels`` events. If there | ||
is no conflict, this step is skipped, otherwise: | ||
|
||
* Assemble all the ``m.room.power_levels`` events from the states to | ||
be resolved into a list. | ||
|
||
* Sort the list by ascending ``depth`` then descending ``sha1(event_id)``. | ||
|
||
* Add the first event in the list to :math:`R`. | ||
|
||
* For each subsequent event in the list, check that the event would be | ||
allowed by the `authorization rules`_ for a room in state :math:`R`. If the | ||
event would be allowed, then update :math:`R` with the event and continue | ||
with the next event in the list. If it would not be allowed, stop and | ||
continue below with ``m.room.join_rules`` events. | ||
|
||
* Repeat the above process for conflicts between ``m.room.join_rules`` events. | ||
|
||
* Repeat the above process for conflicts between ``m.room.member`` events. | ||
|
||
* No other events affect the authorization rules, so for all other conflicts, | ||
just pick the event with the highest depth and lowest ``sha1(event_id)`` that | ||
passes authentication in :math:`R` and add it to :math:`R`. | ||
|
||
A *conflict* occurs between states where those states have different | ||
``event_ids`` for the same ``(state_type, state_key)``. The events thus | ||
affected are said to be *conflicting* events. | ||
|
||
|
||
.. _`authorization rules`: ../server_server/unstable.html#authorization-rules |
Oops, something went wrong.