From 5d434681cc9ca3c7d85fe133e6c849b36b03c024 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 14 Oct 2025 14:06:24 +0200 Subject: [PATCH] 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 00000000000..e63235d2d78 --- /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