Clarify the meaning of "public rooms" in the room directory

[Johennes]

Relates to: #633

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr2104--matrix-spec-previews.netlify.app

[Johennes]

This came in through fa6cc8a but I cannot find any references to it in matrix-org/matrix-spec-proposals#2403. I think it is trying to say that knockable rooms can be made visible in the directory? If so, I think this should rather be moved to where the meaning of visibility is described because here it makes it seem as if servers should do this automatically.

[zecakeh]

I believe that it's more a clarification about which join rules clients can expect to find here.

I agree that this should be next to the meaning of visibility.

[Johennes]

Have added a phrase about knockable rooms in the warning box.

[Johennes]

@anoadragon453 says:

@Johennes Synapse considers rooms with knock and knock_restricted join rules part of its /publicRooms response. This stems from MSC2403, which specifically added rooms with the knock join rule to /publicRooms, so that users could find rooms to knock on.

Does this change the definition of a "public room" to one that has the join_rule public, knock or knock_restricted?

[Johennes]

Thanks for the context @anoadragon453! 🙏

So when responding to /publicRooms, Synapse first retrieves all rooms with public visibility but then applies an additional filter to only include these cases:

join_rules = '{JoinRules.PUBLIC}'
OR join_rules = '{JoinRules.KNOCK}'
OR join_rules = '{JoinRules.KNOCK_RESTRICTED}'
OR history_visibility = 'world_readable'

I'm struggling a bit with understanding how the room directory is meant to work. Other than the slightly unclear statement "rooms with knock rules are given their near-public nature", the spec doesn't mention any restrictions on what rooms can be included in /publicRooms. Therefore, my assumption was that rooms with a public visibility would show up regardless of their join rules or history visibility.

In fact, MSC2403 seems to only define join_rule as a new field in the response of /publicRooms. It doesn't appear to specify any filtering and instead says:

The spec does not prevent us from adding rooms with 'knock' join_rules to the public rooms directory.

That matches my assumption but not what Synapse actually does.

😵‍💫

[anoadragon453]

Correct, the room is only considered if visibility is public when modifying the public rooms list with PUT /_matrix/client/v3/directory/list/room/{roomId}.

To speak to Synapse's implementation, the join_rule restriction within the query was only added during a performance improvement change. I could see this requirement being useful, in that if a room is set to private, it would immediately no longer show in the public rooms list (as it is not publicly-joinable). While the spec may not require homeservers to manage their lists in that way, Synapse can choose to do so.

Regardless, it's clear that Synapse's filtering of its public rooms list here should not influence the spec's definition of a public room. So I think we can ignore this and consider a join_rule of public the only variant that constitutes a room as public.

[Johennes]

To speak to Synapse's implementation, the join_rule restriction within the query was only added during a performance improvement change. I could see this requirement being useful, in that if a room is set to private, it would immediately no longer show in the public rooms list (as it is not publicly-joinable). While the spec may not require homeservers to manage their lists in that way, Synapse can choose to do so.

Oh, interesting. This sounds sensible. Maybe we could add this additional filtering as a MAY hint into the spec?

So I think we can ignore this and consider a join_rule of public the only variant that constitutes a room as public.

You mean visibility of public?

[anoadragon453]

Oh, interesting. This sounds sensible. Maybe we could add this additional filtering as a MAY hint into the spec?

Sounds reasonable to me.

You mean visibility of public?

Hah, yes sorry. join_rules aren't mandated affect the filtering. Terminology!

[Johennes]

This felt slightly confusing because the CS endpoint has a server parameter that is missing here. I think the identity of the request and response bodies is clear enough without this note.

[Johennes]

AFAICT this is the only difference to public_rooms_response.yaml. I cannot imagine that chunk was supposed to be required on only one of the four endpoints so I have made this reuse the shared schema.