From c92752d1b86e59c3656c1d7d1d10825ba562e58b Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Mon, 17 Aug 2020 14:25:34 +0100 Subject: [PATCH] Reflow text to <79 chars --- proposals/2403-knock.md | 119 ++++++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 52 deletions(-) diff --git a/proposals/2403-knock.md b/proposals/2403-knock.md index bec2b4d3..39d985c9 100644 --- a/proposals/2403-knock.md +++ b/proposals/2403-knock.md @@ -1,15 +1,16 @@ # MSC2403: Add "knock" feature -Many people are in invite-only rooms. Sometimes, someone wants to join such a room and can't, as -they aren't invited. This proposal adds a feature for a user to indicate that they want to join -a room. +Many people are in invite-only rooms. Sometimes, someone wants to join such a +room and can't, as they aren't invited. This proposal adds a feature for a +user to indicate that they want to join a room. # Proposal -This proposal implements the reserved "knock" membership type for the `m.room.member` state event. -This state event indicates that when a user knocks on a room, they are asking for permission to join. It -contains an optional "reason" parameter to specify the reason you want to join. Like other -membership types the parameters, "displayname" and "avatar_url" are optional. This membership can -be set from users who aren't currently in said room. An example for the membership would look like the -following: +This proposal implements the reserved "knock" membership type for the +`m.room.member` state event. This state event indicates that when a user +knocks on a room, they are asking for permission to join. It contains an +optional "reason" parameter to specify the reason you want to join. Like +other membership types the parameters, "displayname" and "avatar_url" are +optional. This membership can be set from users who aren't currently in said +room. An example for the membership would look like the following: ```json { "membership": "knock", @@ -19,35 +20,40 @@ following: } ``` -After a knock is received in a room, it is expected to be displayed in the timeline, similar to other -membership changes. It is recommended to not display the reason until the user interacts with the -client in some way (e.g. clicking on a "show reason" button), as else this would essentially allow -outsiders to send messages into the room. Clients can optionally add a way for users of a room to -review all current knocks. After a knock in a room, a member of the room can invite the knocker. +After a knock is received in a room, it is expected to be displayed in the +timeline, similar to other membership changes. It is recommended to not +display the reason until the user interacts with the client in some way (e.g. +clicking on a "show reason" button), as else this would essentially allow +outsiders to send messages into the room. Clients can optionally add a way +for users of a room to review all current knocks. After a knock in a room, a +member of the room can invite the knocker. -To be able to implement this properly, two new endpoints need to be added: one in the Client-Server -API and one in the Server-Server API. +To be able to implement this properly, two new endpoints need to be added: +one in the Client-Server API and one in the Server-Server API. ## Restrictions There are restrictions to being able to set this membership. ### Current membership -Only users without a current membership or with their current membership being "leave" can knock on a -room. This means that a user that is banned or currently in the room cannot knock on it. +Only users without a current membership or with their current membership +being "leave" can knock on a room. This means that a user that is banned or +currently in the room cannot knock on it. ### Join Rules -The `join_rule` of `m.room.join_rules` must be set to "invite" for a knock to succeed. This means that people can't knock -in public rooms. Additionally the new join rule "private" is introduced. This is so that people can, -when creating a new room, prevent anyone from knocking. +The `join_rule` of `m.room.join_rules` must be set to "invite" for a knock to +succeed. This means that people can't knock in public rooms. Additionally the +new join rule "private" is introduced. This is so that people can, when +creating a new room, prevent anyone from knocking. ### Power levels -The default power level for "knock" is the default power level for the room. If a user has a too low -power level to knock, then they aren't allowed to do so. As power levels can be set for users not currently -in the room, this can be used as a way to limit who can and can't knock. +The default power level for "knock" is the default power level for the room. +If a user has a too low power level to knock, then they aren't allowed to do +so. As power levels can be set for users not currently in the room, this can +be used as a way to limit who can and can't knock. #### Example: -`@alice:example.org` CAN knock, but `@bob:example.org` CANNOT: The (incomplete) content of -`m.room.power_levels` is as follows: +`@alice:example.org` CAN knock, but `@bob:example.org` CANNOT: The +(incomplete) content of `m.room.power_levels` is as follows: ```json { "users": { @@ -67,13 +73,14 @@ that user can be transitioned to the following possible states: been rejected. ## Client-Server API -Two new endpoints are introduced in the Client-Server API (similarly to join): -`POST /_matrix/client/r0/rooms/{roomId}/knock` and `POST /_matrix/client/r0/knock/{roomIdOrAlias}`. +Two new endpoints are introduced in the Client-Server API (similarly to +join): `POST /_matrix/client/r0/rooms/{roomId}/knock` and +`POST /_matrix/client/r0/knock/{roomIdOrAlias}`. ### `POST /_matrix/client/r0/rooms/{roomId}/knock` -The path parameter (`roomId`) is the room on which you want to knock. It is required. The post body accepts -an optional string parameter, `reason`, which is the reason you want to join the room. A request could look -as follows: +The path parameter (`roomId`) is the room on which you want to knock. It is +required. The post body accepts an optional string parameter, `reason`, which +is the reason you want to join the room. A request could look as follows: ``` POST /_matrix/client/r0/rooms/%21d41d8cd%3Amatrix.org/knock HTTP/1.1 @@ -120,9 +127,10 @@ This request was rate-limited. Example reply: ``` ### `POST /_matrix/client/r0/knock/{roomIdOrAlias}` -The path parameter (`roomIdOrAlias`) is either the room ID or the alias of the room you want to -knock on. Additionally several `server_name` parameters can be specified via the query parameters. The -post body accepts an optional string parameter, `reason`, which is the reason you want to join the room. A +The path parameter (`roomIdOrAlias`) is either the room ID or the alias of +the room you want to knock on. Additionally several `server_name` parameters +can be specified via the query parameters. The post body accepts an optional +string parameter, `reason`, which is the reason you want to join the room. A request could look as follows: ``` @@ -135,15 +143,18 @@ Content-Type: application/json ``` #### Responses: -The possible responses are the same as for the `POST /_matrix/client/r0/rooms/{roomId}/knock` endpoint. +The possible responses are the same as for the `POST +/_matrix/client/r0/rooms/{roomId}/knock` endpoint. ## Server-Server API -Similarly to join and leave over federation, a ping-pong game with two new endpoints is introduced: -`make_knock` and `send_knock`. Both endpoints must be protected via server ACLs. +Similarly to join and leave over federation, a ping-pong game with two new +endpoints is introduced: `make_knock` and `send_knock`. Both endpoints must +be protected via server ACLs. ### `GET /_matrix/federation/v1/make_knock/{roomId}/{userId}` -Asks the receiving server to return information that the sending server will need to prepare a knock +Asks the receiving server to return information that the sending server will +need to prepare a knock event. Request format: @@ -194,8 +205,8 @@ This request was invalid, e.g. bad JSON. Example reply: ``` ### `PUT /_matrix/federation/v1/send_knock/{roomId}/{eventId}` -Submits a signed knock event to the resident server for it to accept into the room's graph. Note -that event format may differ between room versions. +Submits a signed knock event to the resident server for it to accept into the +room's graph. Note that event format may differ between room versions. Request format: @@ -235,7 +246,8 @@ Content-Type: application/json #### Response: ##### Status code 200: -The event was successfully accepted into the graph by the receiving homeserver. +The event was successfully accepted into the graph by the receiving +homeserver. ```json [ 200, @@ -244,19 +256,22 @@ The event was successfully accepted into the graph by the receiving homeserver. ``` # Potential issues -This new feature would allow users to spam rooms that they don't partake in. That is why this proposal -adds both the new join rule and the new power level, in order to allow room admins to mitigate such -potential spam. +This new feature would allow users to spam rooms that they don't partake in. +That is why this proposal adds both the new join rule and the new power +level, in order to allow room admins to mitigate such potential spam. # Alternatives -As for the join rule "invite", instead the join rule "knock" could be introduced, meaning the room -is like "invite" only that people can also knock. The difference is for existing rooms: With this -proposal people can knock in existing "invite" rooms, with the alternative suggestion being that they can't. - -The two endpoints for the Client-Server API seem redundant, this MSC followed how JOIN is working -currently: One "proper" endpoint (`/rooms/{roomId}/join`) and one to work properly over federation -(`/join/{roomIdOrAlias}`). They could both be merged into one, however, as that would also affect -the join endpoint it seems out-of-scope for this MSC. +As for the join rule "invite", instead the join rule "knock" could be +introduced, meaning the room is like "invite" only that people can also +knock. The difference is for existing rooms: With this proposal people can +knock in existing "invite" rooms, with the alternative suggestion being that +they can't. + +The two endpoints for the Client-Server API seem redundant, this MSC followed +how JOIN is working currently: One "proper" endpoint (`/rooms/{roomId}/join`) +and one to work properly over federation (`/join/{roomIdOrAlias}`). They +could both be merged into one, however, as that would also affect the join +endpoint it seems out-of-scope for this MSC. # Security considerations None. This doesn't allow users access to a room in any way.