Add room version upgrades
Implements https://github.com/matrix-org/matrix-doc/issues/1501pull/1791/head
Travis Ralston
5 years ago
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