matrix-spec-proposals/specification/rooms/v4.rst

.. Copyright 2019 The Matrix.org Foundation C.I.C.
..
.. 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 4
==============

This room version builds on `version 3 <v3.html>`_ using a different encoding for
event IDs.

.. contents:: Table of Contents
.. sectnum::


Client considerations
---------------------

This room version changes the format form event IDs sent to clients. Clients should
already be treating event IDs as opaque identifiers, and should not be concerned with
the format of them. Clients should still encode the event ID when including it in a
request path.

Clients should expect to see event IDs changed from the format of ``$randomstring:example.org``
to something like ``$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`` (note the lack of domain).


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 4 uses the same algorithms defined in `room version 3 <v3.html>`_, however
using URL-safe base64 to generate the event ID.

Event IDs
~~~~~~~~~

.. admonition:: Rationale

   Room version 3 generated event IDs that were difficult for client implementations
   which were not encoding the event ID to function in those rooms. It additionally
   raised concern due to the ``/`` character being interpretted differently by some
   reverse proxy software, and generally made administration harder.

The event ID is the `reference hash`_ of the event encoded using a variation of
`Unpadded Base64`_ which replaces the 62nd and 63rd characters with ``-`` and ``_``
instead of using ``+`` and ``/``. This matches `RFC4648's definition of URL-safe base64
<https://tools.ietf.org/html/rfc4648#section-5>`_. Event IDs are still prefixed
with ``$`` and may result in looking like ``$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg``.

Just like in room version 3, 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. Room version 3 also changes the format
of ``auth_events`` and ``prev_events`` in a PDU.

{{definition_ss_pdu_v4}}

.. _`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