Merge pull request #2019 from matrix-org/travis/1.0/msc1884-msc2002-v4-rooms
Add version 4 rooms to the specpull/977/head
commit
e610f085a9
@ -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