125 lines
5.5 KiB
ReStructuredText
125 lines
5.5 KiB
ReStructuredText
.. Copyright 2018-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 3
|
|
==============
|
|
|
|
This room version builds on `version 2 <v2.html>`_ with an improved event format.
|
|
|
|
.. note:
|
|
All requirements listed in this room version specification are scoped to rooms
|
|
which actually use this room version. For example, a requirement of "all APIs must
|
|
accept the new event format" does in fact apply to all APIs, but only so much as
|
|
where the contextual room of the request is using this room version. Rooms using
|
|
other room versions should not be affected by these sweeping requirements.
|
|
|
|
.. contents:: Table of Contents
|
|
.. sectnum::
|
|
|
|
|
|
Client considerations
|
|
---------------------
|
|
|
|
This room version changes the format for event IDs sent to clients. Clients should be
|
|
aware that these event IDs may contain slashes and other potentially problematic
|
|
characters. Clients should be treating event IDs as opaque identifiers and should not
|
|
be attempting to parse them into a usable form, just like with other room versions.
|
|
|
|
Clients should expect to see event IDs changed from the format of ``$randomstring:example.org``
|
|
to something like ``$acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk`` (note the lack of
|
|
domain and the potentially problematic slash).
|
|
|
|
|
|
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
|
|
intricacies contained here. The section above regarding client considerations
|
|
is the resource that Client-Server API use cases should reference.
|
|
|
|
|
|
Room version 3 uses the state resolution algorithm defined in `room version 2 <v2.html>`_,
|
|
and the event format defined here.
|
|
|
|
Event IDs
|
|
~~~~~~~~~
|
|
|
|
.. admonition:: Rationale
|
|
|
|
In other room versions (namely version 1 and 2) the event ID is a distinct field
|
|
from the remainder of the event, which must be tracked as such. This leads to
|
|
complications where servers receive multiple events with the same ID in either the
|
|
same or different rooms where the server cannot easily keep track of which event it
|
|
should be using. By removing the use of a dedicated event ID, servers are required
|
|
to track the hashes on an event to determine its ID.
|
|
|
|
The event ID is the `reference hash`_ of the event encoded using `Unpadded Base64`_,
|
|
prefixed with ``$``. A resulting event ID using this approach should look similar to
|
|
``$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o``.
|
|
|
|
Event IDs should not be sent over federation to servers when the room uses
|
|
this room version. On the receiving end of an event, the server should compute
|
|
the relevant event ID for itself.
|
|
|
|
Additionally, the ``auth_events`` and ``prev_events`` have had a format change
|
|
compared to other room versions to make it easier to handle. Instead of a tuple
|
|
of values, they are now plain lists of events.
|
|
|
|
{{definition_ss_pdu_v3}}
|
|
|
|
Changes to APIs
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Due to the event ID being removed from the event, some APIs need to change. All
|
|
APIs which currently accept an event ID must do so with the new format. Servers
|
|
must append the calculated event ID to all events sent to clients where an event
|
|
ID would normally be expected.
|
|
|
|
Because the format of events has changed, servers must be aware of the room version
|
|
where the event resides so that the server may parse and handle the event. The
|
|
federation API has taken this concern into consideration by ensuring that servers
|
|
are aware of (or can find) the room version during a request.
|
|
|
|
Authorization rules for events
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The authorization rules for a given event have changed in this room version due
|
|
to the change in event format:
|
|
|
|
* The event no longer needs to be signed by the domain of the event ID (as there
|
|
is no domain in the event ID), but still needs to be signed by the sender's
|
|
domain.
|
|
|
|
* In past room versions, redactions were only permitted to enter the DAG if the
|
|
sender's domain matched the domain in the event ID being redacted, or the sender
|
|
had appropriate permissions per the power levels. Due to servers now not being
|
|
able to determine where an event came from during event authorization, redaction
|
|
events are always accepted (provided the event is allowed by ``events`` and
|
|
``events_default`` in the power levels). However, servers should not apply or send
|
|
redactions to clients until both the redaction event and original event have been
|
|
seen, and are valid. Servers should only apply redactions to events where the
|
|
sender's domains match, or the sender of the redaction has the appropriate
|
|
permissions per the power levels.
|
|
|
|
|
|
The remaining rules are the same as `room version 1 <v1.html#authorization-rules>`_.
|
|
|
|
|
|
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
|
|
.. _`Canonical JSON`: ../appendices.html#canonical-json
|
|
.. _`Signing Events`: ../server_server/%SERVER_RELEASE_LABEL%.html#signing-events
|
|
.. _`reference hash`: ../server_server/%SERVER_RELEASE_LABEL%.html#reference-hashes
|