MSC4367: via routes in the published room directory

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 <https://github.com/matrix-org/matrix-spec/issues/1375>.
+
+  [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