Merge pull request #1791 from matrix-org/travis/spec/rver-upgrades
Add room version upgradespull/1821/head
Travis Ralston
5 years ago
committed by
GitHub
commit
052d68d83d
@ -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
|
||||
@ -0,0 +1 @@
|
||||
Add room version upgrades
|
||||
@ -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,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.
|
||||
Loading…
Reference in New Issue