Merge pull request #1791 from matrix-org/travis/spec/rver-upgrades

Add room version upgrades

api/client-server/room_upgrades.yaml

@@ -0,0 +1,95 @@
+# Copyright 2019 New Vector Ltd
+#
+# 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.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Upgrades API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/upgrade":
+    post:
+      summary: Upgrades a room to a new room version.
+      description: |-
+        Upgrades the given room to a particular room version, migrating as much
+        data as possible over to the new room. See the `room_upgrades <#room-upgrades>`_
+        module for more information on what this entails.
+      operationId: upgradeRoom
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: The ID of the room to upgrade.
+          x-example: "!oldroom:example.org"
+        - in: body
+          name: body
+          required: true
+          description: The request body
+          schema:
+            type: object
+            properties:
+              new_version:
+                type: string
+                description: The new version for the room.
+            example: {"new_version": "2"}
+            required: [new_version]
+      responses:
+        200:
+          description: The room was successfully upgraded.
+          examples:
+            application/json: {
+              "replacement_room": "!newroom:example.org"
+            }
+          schema:
+            type: object
+            properties:
+              replacement_room:
+                type: string
+                description: The ID of the new room.
+            required: [replacement_room]
+        400:
+          description: |-
+            The request was invalid. One way this can happen is if the room version
+            requested is not supported by the homeserver.
+          examples:
+            application/json: {
+              "errcode": "M_UNSUPPORTED_ROOM_VERSION",
+              "error": "This server does not support that room version"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        403:
+          description: |-
+            The user is not permitted to upgrade the room.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You cannot upgrade this room"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - Room ugprades

changelogs/client_server/newsfragments/1791.feature

@@ -0,0 +1 @@
+Add room version upgrades

event-schemas/examples/m.room.create

@@ -5,6 +5,10 @@
   "content": {
     "creator": "@example:example.org",
     "room_version": "1",
-    "m.federate": true
+    "m.federate": true,
+    "predecessor": {
+      "event_id": "$something:example.org",
+      "room_id": "!oldroom:example.org"
+    }
   }
 }

event-schemas/examples/m.room.tombstone

@@ -0,0 +1,9 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.room.tombstone",
+  "state_key": "",
+  "content": {
+    "body": "This room has been replaced",
+    "replacement_room": "!newroom:example.org"
+  }
+}

event-schemas/schema/m.room.create

@@ -14,6 +14,18 @@ properties:
       room_version:
         description: The version of the room. Defaults to ``"1"`` if the key does not exist.
         type: string
+      predecessor:
+        description: A reference to the room this room replaces, if the previous room was upgraded.
+        type: object
+        title: Previous Room
+        properties:
+          room_id:
+            type: string
+            description: The ID of the old room.
+          event_id:
+            type: string
+            description: The event ID of the last known event in the old room.
+        required: [room_id, event_id]
     required:
       - creator
     type: object

event-schemas/schema/m.room.tombstone

@@ -0,0 +1,27 @@
+---
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: 'A state event signifying that a room has been upgraded to a different room version, and that clients should go there.'
+properties:
+  content:
+    properties:
+      body:
+        type: string
+        description: A server-defined message.
+      replacement_room:
+        type: string
+        description: The new room the client should be visiting.
+    required:
+      - replacement_room
+      - body
+    type: object
+  state_key:
+    description: A zero-length string.
+    pattern: '^$'
+    type: string
+  type:
+    enum:
+      - m.room.tombstone
+    type: string
+title: Indication that the room has been upgraded.
+type: object

proposals/1501-room-version-upgrades.md

@@ -48,7 +48,7 @@ When this is called, the server:
        "state_key": "",
        "room_id": "!QtykxKocfsgujksjgd:matrix.org",
        "content": {
-           "version": "2",
+           "room_version": "2",
            "predecessor": {
                "room_id": "!cURbaf:matrix.org",
                "event_id": "$1235135aksjgdkg:matrix.org"

specification/modules/room_upgrades.rst

@@ -0,0 +1,61 @@
+.. Copyright 2019 New Vector Ltd
+..
+.. 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 Upgrades
+=============
+
+.. _module:room-upgrades:
+
+From time to time, a room may need to be upgraded to a different room version for a
+variety for reasons. This module defines a way for rooms to upgrade to a different
+room version when needed.
+
+Events
+------
+
+{{m_room_tombstone_event}}
+
+Client behaviour
+----------------
+
+Clients which understand ``m.room.tombstone`` events and the ``predecessor`` field on
+``m.room.create`` events should communicate to the user that the room was upgraded.
+One way of accomplishing this would be hiding the old room from the user's room list
+and showing banners linking between the old and new room - ensuring that permalinks
+work when referencing the old room. Another approach may be to virtually merge the
+rooms such that the old room's timeline seamlessly continues into the new timeline
+without the user having to jump between the rooms.
+
+{{room_upgrades_cs_http_api}}
+
+Server behaviour
+----------------
+
+When the client requests to upgrade a known room to a known version, the server:
+
+1. Checks that the user has permission to send ``m.room.tombstone`` events in the room.
+2. Creates a replacement room with a ``m.room.create`` event containing a ``predecessor``
+   field and the applicable ``room_version``.
+3. Replicates the power levels, privacy, topic, and other transferable state events to
+   the new room. This generally excludes membership events but may include client-specified
+   events and other presentation details.
+4. Moves any local aliases to the new room.
+5. Sends a ``m.room.tombstone`` event to the old room to indicate that it is not intended
+   to be used any further.
+6. If possible, the power levels in the old room should also be modified to prevent sending
+   of events and inviting new users. For example, setting ``events_default`` and ``invite``
+   to the greater of ``50`` and ``users_default + 1``.
+
+When a user joins the new room, the server may wish to automatically transfer/replicate
+some of the user's personalized settings such as notifications, tags, etc.

specification/targets.yaml

@@ -70,6 +70,7 @@ groups:  # reusable blobs of files when prefixed with 'group:'
     - modules/openid.rst
     - modules/server_acls.rst
     - modules/mentions.rst
+    - modules/room_upgrades.rst
 
 
 title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]