archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reflow text to <79 chars

Browse Source
pull/977/head
Andrew Morgan 4 years ago
parent d47cb1fec3
commit c92752d1b8
1 changed files with 67 additions and 52 deletions
Show Stats Download Patch File Download Diff File

119
proposals/2403-knock.md
Unescape Escape View File

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

Write Preview
Loading…
Cancel
Save