Add version 4 rooms to the spec
As per [MSC1884](https://github.com/matrix-org/matrix-doc/pull/1884) and [MSC2002](https://github.com/matrix-org/matrix-doc/pull/2002). No known changes since the proposals were accepted. Due to being in the area: This fixes https://github.com/matrix-org/matrix-doc/issues/1863pull/977/head
Travis Ralston
6 years ago
parent
415212c3a0
commit
3b0e194ff7
@ -0,0 +1,47 @@
|
||||
# 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.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room version 3 and beyond.
|
||||
example:
|
||||
$ref: "../examples/pdu_v4.json"
|
||||
allOf:
|
||||
- $ref: "pdu_v3.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def_456-oldevent"
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"$ref": "pdu_v3.json",
|
||||
"auth_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
],
|
||||
"prev_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
],
|
||||
"redacts": "$some-old_event"
|
||||
}
|
||||
@ -0,0 +1,76 @@
|
||||
.. 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/r0.1.1.html#signing-events
|
||||
.. _`reference hash`: ../server_server/r0.1.1.html#reference-hashes
|
||||
Loading…
Reference in New Issue