You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
62 lines
2.6 KiB
ReStructuredText
62 lines
2.6 KiB
ReStructuredText
.. 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.
|