From 5bfd65c59fa682e5bdf72d6ea1d3fef0cdac0f85 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 28 Aug 2020 13:56:09 +0100 Subject: [PATCH] Federation knock_room_state and minor cleanup --- proposals/2403-knock.md | 67 ++++++++++++++++++++++++++++++++--------- 1 file changed, 53 insertions(+), 14 deletions(-) diff --git a/proposals/2403-knock.md b/proposals/2403-knock.md index 926561a1..f0443f5a 100644 --- a/proposals/2403-knock.md +++ b/proposals/2403-knock.md @@ -61,7 +61,7 @@ join): `POST /_matrix/client/r0/rooms/{roomId}/knock` and `POST /_matrix/client/r0/knock/{roomIdOrAlias}`. These allow the client to state their intent to knock on a room. -Additionally, additions to the `GET /_matrix/client/r0/sync` endpoint are +Additionally, extensions to the `GET /_matrix/client/r0/sync` endpoint are introduced. These allow a client to receive information about the status of their knock attempt. @@ -70,7 +70,7 @@ 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: -``` +```json POST /_matrix/client/r0/rooms/%21d41d8cd%3Amatrix.org/knock HTTP/1.1 Content-Type: application/json @@ -121,7 +121,7 @@ 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: -``` +```json POST /_matrix/client/r0/knock/%23foxes%3Amatrix.org?server_name=matrix.org&server_name=elsewhere.ca HTTP/1.1 Content-Type: application/json @@ -180,7 +180,7 @@ Response: "knock": { "!abcdefghijklmo:example.com": { "knock_state": { - events: [ + "events": [ { "content": { "join_rule": "knock" @@ -211,14 +211,9 @@ Response: "displayname": "Knocking User", "membership": "knock" }, - "origin_server_ts": 1598548763903, "sender": "@knocking_user:example.org", "state_key": "@knocking_user:example.org", "type": "m.room.member", - "unsigned": { - "age": 5 - }, - "event_id": "$12345" } ] } @@ -313,10 +308,10 @@ Response Format: | Parameter | Type | Description | |-----------|------|-------------| -| `` | Empty Object | +| `knock_room_state` | [StrippedStateEvent] | Required. State events providing public room metadata A request could look as follows: -``` +```json PUT /_matrix/federation/v1/send_knock/%21abc123%3Amatrix.org/%24abc123%3Aexample.org HTTP/1.1 Content-Type: application/json @@ -338,9 +333,53 @@ Content-Type: application/json #### Response: ##### Status code 200: The event was successfully accepted into the graph by the receiving -homeserver. +homeserver. The response contains `StrippedStateEvent`s with room metadata +(room name, avatar ...) that the knocking homeserver can pass to the client. +The event types that can be sent here should match those of the `/sync` +extensions mentioned above. + +This is loosely based off of the +[federated invite](https://matrix.org/docs/spec/server_server/r0.1.4#put-matrix-federation-v2-invite-roomid-eventid) +request content. ```json -{} +{ + "knock_room_state": [ + { + "content": { + "join_rule": "knock" + }, + "sender": "@room_admin:example.com", + "state_key": "", + "type": "m.room.join_rules" + }, + { + "content": { + "name": "Some cool room" + }, + "sender": "@room_admin:example.com", + "state_key": "", + "type": "m.room.name" + }, + { + "content": { + "url": "mxc://example.com/xyz54321" + }, + "sender": "@room_admin:example.com", + "state_key": "", + "type": "m.room.avatar" + }, + { + "content": { + "avatar_url": "mxc://example.org/abc1234", + "displayname": "Knocking User", + "membership": "knock" + }, + "sender": "@knocking_user:example.org", + "state_key": "@knocking_user:example.org", + "type": "m.room.member", + } + ] +} ``` # Potential issues @@ -373,4 +412,4 @@ essentially allow outsiders to send messages into the room. It is still theoretically possible for a server admin to create many users with different user IDs or display names, all spelling out an abusive message, and then having each of them knock in order. In this case, room -admins should employ typical abuse mitigation tools, such as Server ACLs. \ No newline at end of file +admins should employ typical abuse mitigation tools, such as Server ACLs.