From f4097da04ef9b14642880f14ddef43012cf40ec6 Mon Sep 17 00:00:00 2001 From: Kevin Cox Date: Wed, 22 Sep 2021 17:51:31 -0400 Subject: [PATCH] Remove backwards compatibility. Since the new `allow_knock` attribute allows non-members to submit events to the room it needs to be understood by all servers to maintain sync. Therefore a new room version is required. Since a new room version is required it makes sense to drop all backwards compatibility to keep the new `join_rules` as clean and consistent as possible. See https://github.com/matrix-org/matrix-doc/pull/3386#discussion_r703919255 for more context. --- proposals/3386-unified-join-rules.md | 144 ++++++++++++++++++--------- 1 file changed, 99 insertions(+), 45 deletions(-) diff --git a/proposals/3386-unified-join-rules.md b/proposals/3386-unified-join-rules.md index 95614182c..a14dace2c 100644 --- a/proposals/3386-unified-join-rules.md +++ b/proposals/3386-unified-join-rules.md @@ -4,19 +4,29 @@ This MSC aims to solve the proliferation of `join_rule`s and allow these features to interoperate. -As an added benefit this MSC is backwards-compatible. The `allow_knock` field can be added to an existing `join_rules: restricted` room and people can start knocking as it is supported by their servers and clients. - ## Proposal +In a future room version the meaning of the `m.room.join_rules` state event will be changed to the following. + +### `join_rule` + +The `join_rule` key is removed. + +### `allow_join` + +`allow` will be renamed to `allow_join`. Otherwise its meaning is unchanged. + +The `allow_join` key may be absent in which case it is treated as if it was set to `[]` (the empty list). In this case no one is allowed to join without an invite. + ### `allow_knock` -`join_rule: restricted` will be updated with the `allow_knock` key. This functions identically to the `allow` key except that it controls who can knock, instead of controlling who can join. Please see [MSC3083 Restricting room membership based on membership in other rooms](https://github.com/matrix-org/matrix-doc/pull/3083) for how the rules are evaluated and [MSC2403 Knock](https://github.com/matrix-org/matrix-doc/pull/2403) for what it means to knock. +An `allow_knock` key will be allowed. This functions identically to the `allow_join` key except that it controls who can knock, instead of controlling who can join. Please see [MSC3083 Restricting room membership based on membership in other rooms](https://github.com/matrix-org/matrix-doc/pull/3083) for how the rules are evaluated and [MSC2403 Knock](https://github.com/matrix-org/matrix-doc/pull/2403) for what it means to knock. The `allow_knock` key may be absent in which case it is treated as if it was set to `[]` (the empty list). In this case no one is allowed to knock. ### `m.any` -The `m.any` allow type will be defined. This type allows any user to perform the relevant action. The may be used in both the `allow` and `allow_knock` fields. +The `m.any` allow type will be defined. This type allows any user to perform the relevant action. The may be used in both the `allow_join` and `allow_knock` fields. ### Example: Anyone can knock @@ -27,8 +37,7 @@ This shows an example of a room where you can join if you are a member of `!user "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [{ + "allow_join": [{ "type": "m.room_membership" "room_id": "!users:example.org" }] @@ -48,8 +57,7 @@ This shows an example of a room where anyone in the `!users:example.org` room (o "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [{ + "allow_join": [{ "type": "m.room_membership" "room_id": "!mods:example.org" }] @@ -61,42 +69,80 @@ This shows an example of a room where anyone in the `!users:example.org` room (o } ``` -## Potential issues +### Conversion + +When upgrading a room the following rules can be used to generate a new `join_rules` that matches the previous `join_rules`. -### Useless allow_knock entires. +#### `invite` -It is possible that entries in `allow_knock` are redundant because they are also included in `allow` so could simply join directly. While this is unsightly it is non-harmful and will not affect users or servers. +A `join_rules` state event with `join_rule: invite` can be replaced by the following `join_rules`. + +```json5 +{ + "type": "m.room.join_rules" + "state_key": "" + "content": {} +} +``` + +#### `public` + +A `join_rules` state event with `join_rule: public` can be replaced by the following `join_rules`. ```json5 { "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [{ + "allow_join": [{ "type": "m.any" }] - // This is irrelevant because anyone can directly join. + } +} +``` + +#### `knock` + +A `join_rules` state event with `join_rule: knock` can be replaced by the following `join_rules`. + +```json5 +{ + "type": "m.room.join_rules" + "state_key": "" + "content": { "allow_knock": [{ - "type": "m.room_membership" - "room_id": "!users:example.org" + "type": "m.any" }] } } ``` +#### `restricted` + +A `join_rules` state event with `join_rule: restricted` can be replaced by an event with the following template. Substitute the previous elements from the `allow` attribute into the `allow_join` attribute. + +```json5 +{ + "type": "m.room.join_rules" + "state_key": "" + "content": { + "allow_join": // Value from `allow` attribute of previous `join_rules`. + } +} +``` + +For example the following `join_rules`... + ```json5 { "type": "m.room.join_rules" "state_key": "" "content": { "join_rule": "restricted" - "allow": [{ - "type": "m.room_membership", - "room_id": "!users:example.org" - }] - // This is irrelevant because everyone in this room can join directly. - "allow_knock": [{ + "allow": [ { + "type": "m.room_membership" + "room_id": "!mods:example.org" + }, { "type": "m.room_membership" "room_id": "!users:example.org" }] @@ -104,75 +150,83 @@ It is possible that entries in `allow_knock` are redundant because they are also } ``` +...becomes... + ```json5 { "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [{ - "type": "m.any" + "allow_join": [{ + "type": "m.room_membership" + "room_id": "!mods:example.org" }, { - // This is irrelevant because of the m.any rule. - "type": "m.room_membership", + "type": "m.room_membership" "room_id": "!users:example.org" }] } } ``` -Clients may consider helping users to clean up unnecessary elements from the `allow` and `allow_knock` lists. - -### Multiple ways to specify the same rules. - -After this MSC is implemented it will be possible to specify all other (current) `join_rule` types in terms of `join_rule: restricted`. +## Potential issues -This is considered a feature. Once this MSC is widely supported it is expected that rooms are created using `join_rule: restricted` preferentially for simplicity. The other types can be considered deprecated. In order to simplify the protocol a future room version may consider dropping support for anything but `restricted`. +### Useless `allow_knock` entires. -The following is equivalent to `join_rule: public` (as far as join rules are concerned). +It is possible that entries in `allow_knock` are redundant because they are also included in `allow_join` so could simply join directly. While this is unsightly it is non-harmful and will not affect users or servers. ```json5 { "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [{ + "allow_join": [{ "type": "m.any" }] + // This is irrelevant because anyone can directly join. + "allow_knock": [{ + "type": "m.room_membership" + "room_id": "!users:example.org" + }] } } ``` -The following is equivalent to `join_rule: invite`. - ```json5 { "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [] + "allow_join": [{ + "type": "m.room_membership", + "room_id": "!users:example.org" + }] + // This is irrelevant because everyone in this room can join directly. + "allow_knock": [{ + "type": "m.room_membership" + "room_id": "!users:example.org" + }] } } ``` -The following is equivalent to `join_rule: knock`. - ```json5 { "type": "m.room.join_rules" "state_key": "" "content": { - "join_rule": "restricted" - "allow": [] - "allow_knock": [{ + "allow_join": [{ "type": "m.any" + }, { + // This is irrelevant because of the m.any rule. + "type": "m.room_membership", + "room_id": "!users:example.org" }] } } ``` +Clients may consider helping users to clean up unnecessary elements from the `allow_join` and `allow_knock` lists. + ## Alternatives ### Introduce a new mechanism for knock.