Add room version upgrades
Implements https://github.com/matrix-org/matrix-doc/issues/1501pull/1791/head
parent
b067d671fb
commit
b85f7bb248
@ -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`_ 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
|
@ -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"
|
||||||
|
}
|
||||||
|
}
|
@ -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
|
@ -0,0 +1,76 @@
|
|||||||
|
.. 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 MUST:
|
||||||
|
|
||||||
|
* Hide the old room from the user's list of rooms. Permalinks, backlinks, etc should
|
||||||
|
still be accessible to this room, however.
|
||||||
|
* At the very bottom of the old room's timeline/message view, display a message which
|
||||||
|
indicates the room has been upgraded with a permalink to the new room. When the user
|
||||||
|
accesses the permalink, they are to be joined to the new room.
|
||||||
|
|
||||||
|
* Note that if the homeserver doesn't support the room version that the user may
|
||||||
|
receive an error upon trying to join.
|
||||||
|
* If the replacement room has a tombstone event, the client may automatically follow
|
||||||
|
the chain until it finds a room which does not have a tombstone in it.
|
||||||
|
|
||||||
|
* Optionally, the client may wish to improve the presentation of unread messages when
|
||||||
|
the user is in both the old and new rooms. For example, if the user was not active
|
||||||
|
during the upgrade and had unread messages in the old room, the new room may have an
|
||||||
|
indicator which shows the sum of unread notifications between the rooms.
|
||||||
|
|
||||||
|
Clients which understand ``m.room.tombstone`` events must also understand the ``predecessor``
|
||||||
|
field on ``m.room.create`` events such that:
|
||||||
|
|
||||||
|
* At the top of the scrollback/message view for the new room a message is displayed
|
||||||
|
indicating that the room is a continuation of a previous room, with a permalink to
|
||||||
|
the old room.
|
||||||
|
* Optionally supporting search and other functions of the room to span across the old
|
||||||
|
and new 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.
|
||||||
|
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``.
|
Loading…
Reference in New Issue