77 lines
3.2 KiB
ReStructuredText
77 lines
3.2 KiB
ReStructuredText
.. 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
|