Add version 4 rooms to the spec

As per [MSC1884](#1884) and [MSC2002](#2002).

No known changes since the proposals were accepted.

Due to being in the area: This fixes #1863

api/server-server/definitions/pdu_v3.yaml

@@ -20,6 +20,10 @@ allOf:
   - $ref: "unsigned_pdu_base.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:

api/server-server/definitions/pdu_v4.yaml

@@ -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

api/server-server/examples/pdu_v3.json

@@ -15,5 +15,6 @@
     "prev_events": [
         "$base64encodedeventid",
         "$adifferenteventid"
-    ]
+    ],
+    "redacts": "$some/old+event"
 }

api/server-server/examples/pdu_v4.json

@@ -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"
+}

specification/index.rst

@@ -493,6 +493,7 @@ The available room versions are:
 * `Version 1 <rooms/v1.html>`_ - **Stable**. The current version of most rooms.
 * `Version 2 <rooms/v2.html>`_ - **Stable**. Implements State Resolution Version 2.
 * `Version 3 <rooms/v3.html>`_ - **Stable**. Introduces events whose IDs are the event's hash.
+* `Version 4 <rooms/v4.html>`_ - **Stable**. Builds on v3 by using URL-safe base64 for event IDs.
 
 Specification Versions
 ----------------------

specification/rooms/v4.rst

@@ -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

specification/targets.yaml

@@ -38,6 +38,10 @@ targets:
     files:
       - rooms/v3.rst
     version_label: v3
+  rooms@v4: # this is translated to be rooms/v4.html
+    files:
+      - rooms/v4.rst
+    version_label: v4
   appendices:
     files:
       - appendices.rst