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
76 changes: 76 additions & 0 deletions proposals/4366-resident-public-rooms.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:

  • Client
  • Server

Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# MSC4366: Resident servers in and around the 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 forbidding non-resident rooms in local directory queries
and matching the `server` and `via` query parameters.

## Proposal

When either of the client-server endpoints

- [`GET /_matrix/client/v3/publicRooms`]
- [`POST /_matrix/client/v3/publicRooms`]

is called with an empty or missing `server` parameter, the server MUST only return rooms listed on
its directory that it has at least one joined member in.

Similarly, the server-server endpoints

- [`GET /_matrix/federation/v1/publicRooms`]
- [`POST /_matrix/federation/v1/publicRooms`]

MUST only include rooms from the server's local directory if the server has at least one joined
member in them.
Copy link
Member

@tulir tulir Oct 14, 2025

Choose a reason for hiding this comment

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

This looks like it will completely forbid directory-only servers like https://matrixrooms.info/

I think it'd be better to define a via field in the response entries instead of this proposal. Basically, let the origin server figure out if it can find a route rather than mandating a single allowed route in the spec. The spec could still mandate that vias must be returned

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I was struggling with how to best express this but I had intended it to only apply to rooms from the local directory, meaning the server MAY continue to additionally include rooms from other server's directories like today. That only half-solves the problem of course, as stated under potential issues.

Maybe we should combine both? For any room in the response the server must either be resident or include a via value in the response?

Copy link
Member

Choose a reason for hiding this comment

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

For any room in the response the server must either be resident or include a via value in the response?

Is that any different than just requiring all entries include a via value, which may simply be the server itself?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I guess not. 😄

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Have captured this in #4367.


Clients that use the `server` parameter on room directory queries and subsequently call
[`POST /_matrix/client/v3/join/{roomIdOrAlias}`] to join a room found in the response, SHOULD
include the same server name in the `via` parameter.

Together, the changes above increase the chances that clients can actually join rooms found in the
directory.

## Potential issues

As per the current [spec], the server-server endpoints are discouraged but not banned from including
rooms listed on *other* homeserver's directories. A client querying `/publicRooms` with a specific
`server` may, therefore, still receive rooms which that server isn't joined to. Matching the
`server` and `via` parameters as described in this proposal would still not allow clients to join
these rooms. This problem already exists today, however, and is deemed out of scope for this
proposal.

## Alternatives

Non-resident rooms could be allowed in room directory responses if the server would accompany them
with suitable `via` values. This approach is covered in [MSC4367].

## Security considerations

None.

## Unstable prefix

None.

## 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
[spec]: https://spec.matrix.org/v1.16/server-server-api/#published-room-directory
[MSC4367]: https://github.com/matrix-org/matrix-spec-proposals/pull/4367