From 1d6acfc0928ff4043dbd15b9349dd8b56988e640 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 27 May 2022 16:00:05 +0200 Subject: [PATCH 1/9] Write `Filtering of /publicRooms by room type` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/3827-space-explore.md | 73 +++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 proposals/3827-space-explore.md diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md new file mode 100644 index 0000000000..e6835537f9 --- /dev/null +++ b/proposals/3827-space-explore.md @@ -0,0 +1,73 @@ +# MSC3827: Filtering of `/publicRooms` by room type + +[MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) defines Spaces as +rooms with `type` of `m.space`. One of the most requested features for Spaces is +to have [a way to to discover +them](https://github.com/vector-im/element-web/issues/17264). To solve this +issue, this MSC proposes a mechanism for filtering the response of +`/publicRooms` by room type. + +## Proposal + +This MSC proposes adding a `room_type` filter to the `/publicRooms` endpoint. +The value of `room_type` is an array of room types - possible values of the +`type` field in the `m.room.create` state event - which should be returned. + +An example request could look like this: + +```HTTP +POST /_matrix/client/v3/publicRooms +{ + "filter": { + "room_type": ["m.space"] + }, + "limit": 10 +} +``` + +the response then also includes a `room_type` field, so that clients can show +the room type metadata. + +```json +{ + "chunk": [{ + "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", + "guest_can_join": false, + "join_rule": "public", + "name": "CHEESE", + "num_joined_members": 37, + "room_id": "!ol19s:bleecker.street", + "topic": "Tasty tasty cheese", + "world_readable": true, + "room_type": "m.space" + }], + "next_batch": "p190q", + "prev_batch": "p1902", + "total_room_count_estimate": 115 +} + +``` + +## Alternatives + +### Using a special endpoint + +A special endpoint for spaces and other room types could be used. Then each new +room type would require a special MSC and there would be no way to filter by +custom room types. Filtering by multiple types would be impossible. + +### Replacing the room directory with a server-wide space + +[A matrix-spec issue](https://github.com/matrix-org/matrix-spec/issues/830) +suggests replacing the room directory with a server-wide space; while this +solution certainly has benefits, it would require a lot of changes both on the +client and the server side. + +## Unstable prefix + +While this MSC is not considered stable, implementations should use +`org.matrix.msc3827` as a namespace. + +|Release |Development | +|-----------|------------------------------| +|`room_type`|`org.matrix.msc3827.room_type`| From 4140ec3a44c777960372213e16378e4edf23a5c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 27 May 2022 16:26:41 +0200 Subject: [PATCH 2/9] Improve wording to be more clear Co-authored-by: Jonathan de Jong --- proposals/3827-space-explore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index e6835537f9..750978c9c5 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -25,7 +25,7 @@ POST /_matrix/client/v3/publicRooms } ``` -the response then also includes a `room_type` field, so that clients can show +The response is also modified to include a `room_type` field, so that clients can show the room type metadata. ```json From ae782b19f4248cae5a5ba8fda0d83bb04f8e60b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Sat, 18 Jun 2022 11:11:12 +0200 Subject: [PATCH 3/9] Specify handling of edge cases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/3827-space-explore.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 750978c9c5..47e18890ce 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -46,6 +46,11 @@ the room type metadata. "total_room_count_estimate": 115 } +If the client wants to get rooms of the default type, it should include `null` in +the `room_type` array. If the `room_type` filter is not specified, the server should +return only the rooms of the default type. If the `room_type` array is empty, the +server should return _all_ rooms no matter the type. + ``` ## Alternatives From 748b258609e5984c01ba23192b699ab4e82271de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Sat, 18 Jun 2022 11:48:58 +0200 Subject: [PATCH 4/9] Use plural MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/3827-space-explore.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 47e18890ce..640b998ae0 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -9,8 +9,8 @@ issue, this MSC proposes a mechanism for filtering the response of ## Proposal -This MSC proposes adding a `room_type` filter to the `/publicRooms` endpoint. -The value of `room_type` is an array of room types - possible values of the +This MSC proposes adding a `room_types` filter to the `/publicRooms` endpoint. +The value of `room_types` is an array of room types - possible values of the `type` field in the `m.room.create` state event - which should be returned. An example request could look like this: @@ -19,7 +19,7 @@ An example request could look like this: POST /_matrix/client/v3/publicRooms { "filter": { - "room_type": ["m.space"] + "room_types": ["m.space"] }, "limit": 10 } @@ -45,14 +45,13 @@ the room type metadata. "prev_batch": "p1902", "total_room_count_estimate": 115 } +``` If the client wants to get rooms of the default type, it should include `null` in -the `room_type` array. If the `room_type` filter is not specified, the server should -return only the rooms of the default type. If the `room_type` array is empty, the +the `room_types` array. If the `room_types` filter is not specified, the server should +return only the rooms of the default type. If the `room_types` array is empty, the server should return _all_ rooms no matter the type. -``` - ## Alternatives ### Using a special endpoint @@ -73,6 +72,7 @@ client and the server side. While this MSC is not considered stable, implementations should use `org.matrix.msc3827` as a namespace. -|Release |Development | -|-----------|------------------------------| -|`room_type`|`org.matrix.msc3827.room_type`| +|Release |Development | +|------------|-------------------------------| +|`room_type` |`org.matrix.msc3827.room_type` | +|`room_types`|`org.matrix.msc3827.room_types`| From f5ca17f68a453213c9721256dd79331f48e0eb92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 29 Jun 2022 17:18:39 +0200 Subject: [PATCH 5/9] Don't change the defautl behaviour MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/3827-space-explore.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 640b998ae0..826f58e31b 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -47,10 +47,10 @@ the room type metadata. } ``` -If the client wants to get rooms of the default type, it should include `null` in -the `room_types` array. If the `room_types` filter is not specified, the server should -return only the rooms of the default type. If the `room_types` array is empty, the -server should return _all_ rooms no matter the type. +If the client wants to get rooms of the default type, it should include `null` +in the `room_types` array. If the `room_types` filter is not specified or the +`room_types` array is empty, the server should return _all_ rooms no matter the +type. ## Alternatives From 3382b6a565742f4a9779441f89da59ba894c2bb8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 5 Jul 2022 13:11:40 +0200 Subject: [PATCH 6/9] Specify POST Co-authored-by: Hubert Chathi --- proposals/3827-space-explore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 826f58e31b..5e641a91d6 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -9,7 +9,7 @@ issue, this MSC proposes a mechanism for filtering the response of ## Proposal -This MSC proposes adding a `room_types` filter to the `/publicRooms` endpoint. +This MSC proposes adding a `room_types` filter to the `POST /publicRooms` endpoint. The value of `room_types` is an array of room types - possible values of the `type` field in the `m.room.create` state event - which should be returned. From b1f0e90559df525d65216b98f105a505b24541e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 5 Jul 2022 13:12:00 +0200 Subject: [PATCH 7/9] Specify POST and GET Co-authored-by: Hubert Chathi --- proposals/3827-space-explore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 5e641a91d6..1eb21b312c 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -25,7 +25,7 @@ POST /_matrix/client/v3/publicRooms } ``` -The response is also modified to include a `room_type` field, so that clients can show +The response for both `POST /publicRooms` and `GET /publicRooms` is also modified to include a `room_type` field, so that clients can show the room type metadata. ```json From 8b07b715959d221632fde495ff6438029501e7e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 12 Jul 2022 16:10:06 +0200 Subject: [PATCH 8/9] Improve wording Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/3827-space-explore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 1eb21b312c..3f2266994f 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -11,7 +11,7 @@ issue, this MSC proposes a mechanism for filtering the response of This MSC proposes adding a `room_types` filter to the `POST /publicRooms` endpoint. The value of `room_types` is an array of room types - possible values of the -`type` field in the `m.room.create` state event - which should be returned. +`type` field in the `m.room.create` state event's `content` dictionary - which should be returned. An example request could look like this: From f0f054e01ae2c0ce92cb4fe4035e20bc780353f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 20 Jul 2022 12:44:30 +0200 Subject: [PATCH 9/9] Link to the original spec Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3827-space-explore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3827-space-explore.md b/proposals/3827-space-explore.md index 3f2266994f..b3eff801d4 100644 --- a/proposals/3827-space-explore.md +++ b/proposals/3827-space-explore.md @@ -9,7 +9,7 @@ issue, this MSC proposes a mechanism for filtering the response of ## Proposal -This MSC proposes adding a `room_types` filter to the `POST /publicRooms` endpoint. +This MSC proposes adding a `room_types` filter to the [`POST /publicRooms`](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3publicrooms) endpoint. The value of `room_types` is an array of room types - possible values of the `type` field in the `m.room.create` state event's `content` dictionary - which should be returned.