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.
matrix-spec/content/client-server-api/modules/room_upgrades.md

76 lines
2.8 KiB
Markdown

---
type: module
---
### Room Upgrades
From time to time, a room may need to be upgraded to a different room
version for a variety of reasons. This module defines a way for rooms
to upgrade to a different room version when needed.
#### Events
{{% event event="m.room.tombstone" %}}
#### 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.
{{% http-api spec="client-server" api="room_upgrades" %}}
#### 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. {{< changed-in v="1.4" >}} Creates a replacement room with a `m.room.create` event containing a
`predecessor` field, the applicable `room_version`, and a `type` field
which is copied from the `predecessor` room. If no `type` is set on the
previous room, no `type` is specified on the new room's create event
either.
3. Replicates transferable state events to the new room. The exact
details for what is transferred is left as an implementation detail,
however the recommended state events to transfer are:
- `m.room.server_acl`
- `m.room.encryption`
- `m.room.name`
- `m.room.avatar`
- `m.room.topic`
- `m.room.guest_access`
- `m.room.history_visibility`
- `m.room.join_rules`
- `m.room.power_levels`
Membership events should not be transferred to the new room due to
technical limitations of servers not being able to impersonate
people from other homeservers. Additionally, servers should not
transfer state events which are sensitive to who sent them, such as
events outside of the Matrix namespace where clients may rely on the
sender to match certain criteria.
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 should automatically
transfer/replicate some of the user's personalized settings such as
notifications, tags, etc.