Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions proposals/4367-public-rooms-via.md
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation requirements:

  • Server that returns via in both APIs, and passes it through in the C-S API when querying a remote server
  • Client that uses the returned via for /join calls

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Original file line number Diff line number Diff line change
@@ -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