Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2025-12-25 18:38:37 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

update with new endpoints

Browse source
This commit is contained in:
Sorunome 2020-01-19 13:30:46 +01:00
parent 776436a5f0
commit 53435d400d
No known key found for this signature in database
GPG key ID: 63E31F7B5993A9C4
1 changed files with 113 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

158
proposals/2403-knock.md
View file

@ -35,7 +35,7 @@ room. This means that a user that is banned or currently in the room can't knock
### Join Rules
The `join_rule` of `m.room.join_rules` must be set to "invite". This means that people can't knock
in public rooms. Additionaly the new join rule "private" is introduced. This is so that people can,
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
@ -57,7 +57,10 @@ as a way to limit who can knock and who can't.
```
## Client-Server API
The new endpoint for the client-server API is `POST /_matrix/client/r0/rooms/{roomId}/knock`.
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 you want to knock. It is required. The post body accepts
an optional parameter, `reason`, which is the reason you want to join the room. A request could look
as follows:
@ -71,14 +74,14 @@ Content-Type: application/json
}
```
### Responses:
#### Status code 200:
#### Responses:
##### Status code 200:
The user knocked successfully. Empty reply:
```json
{}
```
#### Status code 400:
##### Status code 400:
This request was invalid, e.g. bad JSON. Example reply:
```json
{
@ -86,7 +89,7 @@ This request was invalid, e.g. bad JSON. Example reply:
"error": "An unknown error occurred"}
```
#### Status code 403:
##### Status code 403:
The user wasn't allowed to knock (e.g. they are banned). Error reply:
```json
{
@ -95,7 +98,7 @@ The user wasn't allowed to knock (e.g. they are banned). Error reply:
}
```
#### Status code 429:
##### Status code 429:
This request was rate-limited. Example reply:
```json
{
@ -105,70 +108,130 @@ This request was rate-limited. Example reply:
}
```
## Server-Server API
The new endpoint for the server-server API is `PUT /_matrix/federation/v2/knock/{roomId}/{eventId}`.
The path parameters are the room id you want to knock and the event id of the knock event. The post
body consists of an `event` parameter, which is the knock event. A request could look as follows:
### `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. Additionally several `server_name` parameters can be specified via the query parameters. The
post body accepts an optional parameter, `reason`, which is the reason you want to join the room. A
request could look as follows:
```
PUT /_matrix/federation/v2/knock/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1
POST /_matrix/client/r0/knock/%23monkeys%3Amatrix.org?server_name=matrix.org&server_name=elsewhere.ca HTTP/1.1
Content-Type: application/json
{
"event": {
"sender": "@alice:example.org",
"origin": "example.org",
"origin_server_ts": 1234567890,
"type: "m.room.member",
"state_key": "@alice:example.org",
"content": {
"membership": "knock",
"displayname": "Alice",
"avatar_url": "mxc://example.org/avatar",
"reason": "I want to join this room as I really love foxes!"
}
}
"reason": "I want to join this room as I really love foxes!"
}
```
### Responses
#### Status code 200:
The knock was performed successfully. The knock event is sent back with the "event" key.
#### Responses:
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.
### `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
event to get into the room.
Request format:
| Parameter | Type | Description |
|-----------|------|-------------|
| Path parameters:
| roomId | string | Required. The room ID that should receive the knock.
| userId | string | Required. The user ID the knock event will be for.
| Query Parameters:
| ver | [string] | The room versions the sending server has support for. Defaults to `[1]`.
Response Format:
| Parameter | Type | Description |
|-----------|------|-------------|
| room_version | string | The version of the room where the server is trying to knock.
| event | Event Template | An unsigned template event. May differ between room versions.
#### Responses
##### Status code 200:
Returns a template to be used to knock rooms. May depend on room version.
```json
{
"room_version": "2",
"event": {
"sender": "@alice:example.org",
"origin": "example.org",
"origin_server_ts": 1234567890,
"type": "m.room.member",
"state_key": "@alice:example.org",
"room_id": "!somewhere:example.org",
"content": {
"membership": "knock",
"displayname": "Alice",
"avatar_url": "mxc://example.org/avatar",
"reason": "I want to join this room as I really love foxes!"
}
"membership": "knock"
},
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org"
}
}
```
#### Status code 400:
##### Status code 400:
This request was invalid, e.g. bad JSON. Example reply:
```json
{
"errcode": "M_UNKNOWN",
"error": "An unknown error occurred"}
"errcode": "M_INCOMPATIBLE_ROOM_VERSION",
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
```
#### Status code 403:
The user wasn't allowed to knock. Error reply:
```json
### `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.
Request format:
| Parameter | Type | Description |
|-----------|------|-------------|
| Path parameters:
| roomId | string | Required. The room ID that should receive the knock.
| eventId | string | Required. The event ID for the knock event.
The JSON body is expected to be the full event.
Response Format:
| Parameter | Type | Description |
|-----------|------|-------------|
| <body> | [integer, Empty Object] |
A request could look as follows:
```
PUT /_matrix/federation/v1/send_knock/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1
Content-Type: application/json
{
"errcode": "M_FORBIDDEN",
"error": "The user isn't allowed to knock in this room."
"sender": "@someone:example.org",
"origin": "matrix.org",
"origin_server_ts": 1234567890,
"type": "m.room.member",
"state_key": "@someone:example.org",
"content": {
"membership": "knock",
"displayname": "Alice",
"avatar_url": "mxc://example.org/avatar",
"reason": "I want to join this room as I really love foxes!"
}
}
```
#### Response:
##### Status code 200:
The event was successfully accepted into the graph by the receiving homeserver.
```json
[
200,
{}
]
```
# 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
@ -179,5 +242,10 @@ As for the join rule "invite", instead the join rule "knock" could be introduced
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 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.