mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-03 21:03:42 +01:00
Reflow text to <79 chars
This commit is contained in:
Andrew Morgan
parent
d47cb1fec3
commit
c92752d1b8
|
|
@ -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.
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue