From 5d434681cc9ca3c7d85fe133e6c849b36b03c024 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 14 Oct 2025 14:06:24 +0200 Subject: [PATCH 1/3] MSC4367: via routes in the published room directory Signed-off-by: Johannes Marbach --- proposals/4367-public-rooms-via.md | 75 ++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 proposals/4367-public-rooms-via.md diff --git a/proposals/4367-public-rooms-via.md b/proposals/4367-public-rooms-via.md new file mode 100644 index 000000000..e63235d2d --- /dev/null +++ b/proposals/4367-public-rooms-via.md @@ -0,0 +1,75 @@ +# MSC4367: `via` routes in the published room directory + +The [published room directory] allows clients to discover rooms on their own or other homeservers. +Naturally, clients will want to join rooms found in the directory which requires knowledge of a +resident server to facilitate the join. The spec doesn't make it clear how to find such a server, +however. + +To begin with, it is unclear whether the endpoints for listing a server's directory may return rooms +that the server is not joined to. Additionally, there is no recommendation on what `via` parameter +clients should use when attempting to join rooms found in the directory. As a result, clients can +end up browsing published rooms without being able to join them.[^1] + +This proposal addresses the situation by adding `via` values in the room directory responses. + +## Proposal + +A new required property `via` is added on the `PublishedRoomsChunk` returned by + +- [`GET /_matrix/client/v3/publicRooms`] +- [`POST /_matrix/client/v3/publicRooms`] +- [`GET /_matrix/federation/v1/publicRooms`] +- [`POST /_matrix/federation/v1/publicRooms`] + +``` json5 +{ + "chunk": [ + { + "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", + "room_id": "!ol19s:bleecker.street", + "via": [ "bleecker.street" ], + ... + } + ] +} +``` + +Servers MUST populate `via` with at least one resident server of the room or, if they cannot +determine any, omit the room from their response. + +Clients SHOULD include the values provided in `via` when subsequently joining rooms with +[`POST /_matrix/client/v3/join/{roomIdOrAlias}`]. + +Together, the changes above increase the chances that clients can actually join rooms found in the +directory. + +## Potential issues + +None. + +## Alternatives + +[MSC4366] deals with the same problem by forbidding unroutable rooms from the local directory. This +is only a partial solution, however. + +## Security considerations + +None. + +## Unstable prefix + +While this MSC is not considered stable, `via` should be referred to as `org.matrix.msc4367.via`. + +## Dependencies + +None. + +[^1]: These issues were initially raised in . + + [published room directory]: https://spec.matrix.org/v1.16/client-server-api/#published-room-directory + [`GET /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3publicrooms + [`POST /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.16/client-server-api/#post_matrixclientv3publicrooms + [`GET /_matrix/federation/v1/publicRooms`]: https://spec.matrix.org/v1.16/server-server-api/#get_matrixfederationv1publicrooms + [`POST /_matrix/federation/v1/publicRooms`]: https://spec.matrix.org/v1.16/server-server-api/#post_matrixfederationv1publicrooms + [`POST /_matrix/client/v3/join/{roomIdOrAlias}`]: https://spec.matrix.org/v1.16/client-server-api/#post_matrixclientv3joinroomidoralias + [MSC4366]: https://github.com/matrix-org/matrix-spec-proposals/pull/4366 From 6987a9d2f8d3f5217972f8ca96ad9bf2636dd05a Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 26 Nov 2025 10:16:36 +0100 Subject: [PATCH 2/3] Clarify that servers may include unjoined rooms in their directory responses Signed-off-by: Johannes Marbach --- proposals/4367-public-rooms-via.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/proposals/4367-public-rooms-via.md b/proposals/4367-public-rooms-via.md index e63235d2d..df2a23295 100644 --- a/proposals/4367-public-rooms-via.md +++ b/proposals/4367-public-rooms-via.md @@ -14,13 +14,17 @@ This proposal addresses the situation by adding `via` values in the room directo ## Proposal -A new required property `via` is added on the `PublishedRoomsChunk` returned by +Servers MAY include rooms that they are not joined to in responses returned by the following +endpoints: - [`GET /_matrix/client/v3/publicRooms`] - [`POST /_matrix/client/v3/publicRooms`] - [`GET /_matrix/federation/v1/publicRooms`] - [`POST /_matrix/federation/v1/publicRooms`] +To help clients join such rooms, a new required property `via` is added on the `PublishedRoomsChunk` +returned by the above endpoints. + ``` json5 { "chunk": [ From d4c5696855439004dc259e470affcec8559d62b3 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 26 Nov 2025 10:19:29 +0100 Subject: [PATCH 3/3] Add matrixrooms.info as an example Signed-off-by: Johannes Marbach --- proposals/4367-public-rooms-via.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposals/4367-public-rooms-via.md b/proposals/4367-public-rooms-via.md index df2a23295..df7136a6d 100644 --- a/proposals/4367-public-rooms-via.md +++ b/proposals/4367-public-rooms-via.md @@ -6,9 +6,12 @@ resident server to facilitate the join. The spec doesn't make it clear how to fi however. To begin with, it is unclear whether the endpoints for listing a server's directory may return rooms -that the server is not joined to. Additionally, there is no recommendation on what `via` parameter -clients should use when attempting to join rooms found in the directory. As a result, clients can -end up browsing published rooms without being able to join them.[^1] +that the server is not joined to. One example where including such rooms is desirable are +directory-only servers like [matrixrooms.info]. + +Additionally, there is no recommendation on what `via` parameter clients should use when attempting +to join rooms found in the directory. As a result, clients can end up browsing published rooms +without being able to join them.[^1] This proposal addresses the situation by adding `via` values in the room directory responses. @@ -71,6 +74,7 @@ None. [^1]: These issues were initially raised in . [published room directory]: https://spec.matrix.org/v1.16/client-server-api/#published-room-directory + [matrixrooms.info]: https://matrixrooms.info/ [`GET /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.16/client-server-api/#get_matrixclientv3publicrooms [`POST /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.16/client-server-api/#post_matrixclientv3publicrooms [`GET /_matrix/federation/v1/publicRooms`]: https://spec.matrix.org/v1.16/server-server-api/#get_matrixfederationv1publicrooms