From 5e9f6dd1304b3de47ee5c3ddf29260eb095a27b6 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 19 Mar 2025 14:44:17 +0100 Subject: [PATCH 1/5] Clarify the meaning of "public rooms" in the room directory Signed-off-by: Johannes Marbach --- content/client-server-api/_index.md | 22 ++++- content/server-server-api.md | 7 +- data/api/client-server/create_room.yaml | 8 +- .../definitions/public_rooms_chunk.yaml | 2 +- .../definitions/public_rooms_response.yaml | 21 +---- data/api/client-server/list_public_rooms.yaml | 36 ++++---- data/api/server-server/public_rooms.yaml | 85 +++---------------- 7 files changed, 62 insertions(+), 119 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 94dfe35f..b8e7878f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2831,7 +2831,27 @@ re-invited. {{% http-api spec="client-server" api="banning" %}} -### Listing rooms +### Room directory + +Homeservers MAY publish a room directory to allow users to discover rooms. A room +can have one of two visibility settings in the directory: + +`public` +The room will be shown in the published room directory. + +`private` +The room will be hidden from the published room directory. + +Clients can define a room's initial visibility in the directory via the `visibility` +parameter in [`/createRoom`](#post_matrixclientv3createroom). Irrespective of room +creation, clients can query and change a room's visibility in the directory through +the endpoints listed below, provided that the server permits this. + +{{% boxes/warning %}} +A visibility setting of `public` should not be confused with a `public` [join rule](#mroomjoin_rules) +or a `world_readable` [history visibility](#room-history-visibility). The visibility merely defines +whether a room is included in the published room directory or not. +{{% /boxes/warning %}} {{% http-api spec="client-server" api="list_public_rooms" %}} diff --git a/content/server-server-api.md b/content/server-server-api.md index 65494f80..fae87f19 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1045,11 +1045,10 @@ user's Matrix ID and the token delivered when the invite was stored, this verification will prove that the `m.room.member` invite event comes from the user owning the invited third-party identifier. -## Public Room Directory +## Room Directory -To complement the [Client-Server -API](/client-server-api)'s room directory, -homeservers need a way to query the public rooms for another server. +To complement the [room directory in the Client-Server API](/client-server-api#room-directory), +homeservers need a way to query the published rooms of another server. This can be done by making a request to the `/publicRooms` endpoint for the server the room directory should be retrieved for. diff --git a/data/api/client-server/create_room.yaml b/data/api/client-server/create_room.yaml index 3992fdfe..79f51ce7 100644 --- a/data/api/client-server/create_room.yaml +++ b/data/api/client-server/create_room.yaml @@ -87,12 +87,8 @@ paths: - public - private description: |- - A `public` visibility indicates that the room will be shown - in the published room list. A `private` visibility will hide - the room from the published room list. Rooms default to - `private` visibility if this key is not included. NB: This - should not be confused with `join_rules` which also uses the - word `public`. + The room's visibility in the server's [room directory](#room-directory). + Defaults to `private`. room_alias_name: type: string description: |- diff --git a/data/api/client-server/definitions/public_rooms_chunk.yaml b/data/api/client-server/definitions/public_rooms_chunk.yaml index 9c6ae6fc..79cbd89d 100644 --- a/data/api/client-server/definitions/public_rooms_chunk.yaml +++ b/data/api/client-server/definitions/public_rooms_chunk.yaml @@ -13,7 +13,7 @@ # limitations under the License. type: object -title: "PublicRoomsChunk" +title: "PublishedRoomsChunk" properties: canonical_alias: type: string diff --git a/data/api/client-server/definitions/public_rooms_response.yaml b/data/api/client-server/definitions/public_rooms_response.yaml index ba2b712c..4df62b08 100644 --- a/data/api/client-server/definitions/public_rooms_response.yaml +++ b/data/api/client-server/definitions/public_rooms_response.yaml @@ -13,28 +13,15 @@ # limitations under the License. type: object -description: A list of the rooms on the server. +description: A list of the published rooms on the server. required: ["chunk"] properties: chunk: type: array description: |- - A paginated chunk of public rooms. + A paginated chunk of published rooms. items: - allOf: - - $ref: "public_rooms_chunk.yaml" - - type: object - title: PublicRoomsChunk - properties: - # Override description of join_rule - join_rule: - type: string - description: |- - The room's join rule. When not present, the room is assumed to - be `public`. Note that rooms with `invite` join rules are not - expected here, but rooms with `knock` rules are given their - near-public nature. - example: "public" + $ref: "public_rooms_chunk.yaml" next_batch: type: string description: |- @@ -50,7 +37,7 @@ properties: total_room_count_estimate: type: integer description: |- - An estimate on the total number of public rooms, if the + An estimate on the total number of published rooms, if the server has an estimate. example: { "chunk": [ diff --git a/data/api/client-server/list_public_rooms.yaml b/data/api/client-server/list_public_rooms.yaml index ffd202a4..7b6adc00 100644 --- a/data/api/client-server/list_public_rooms.yaml +++ b/data/api/client-server/list_public_rooms.yaml @@ -19,8 +19,7 @@ paths: "/directory/list/room/{roomId}": get: summary: Gets the visibility of a room in the directory - description: Gets the visibility of a given room on the server's public room - directory. + description: Gets the visibility of a given room in the server's room directory. operationId: getRoomVisibilityOnDirectory parameters: - in: path @@ -32,7 +31,7 @@ paths: type: string responses: "200": - description: The visibility of the room in the directory + description: The visibility of the room in the directory. content: application/json: schema: @@ -50,7 +49,7 @@ paths: "visibility": "public" } "404": - description: The room is not known to the server + description: The room is not known to the server. content: application/json: schema: @@ -66,12 +65,11 @@ paths: put: summary: Sets the visibility of a room in the room directory description: |- - Sets the visibility of a given room in the server's public room - directory. + Sets the visibility of a given room in the server's room directory. - Servers may choose to implement additional access control checks - here, for instance that room visibility can only be changed by - the room creator or a server administrator. + Servers MAY implement additional access control checks, for instance, + to ensure that a room's visibility can only be changed by the room creator + or a server administrator. operationId: setRoomVisibilityOnDirectory security: - accessTokenQuery: [] @@ -97,7 +95,7 @@ paths: - public description: |- The new visibility setting for the room. - Defaults to 'public'. + Defaults to `public`. example: { "visibility": "public" } @@ -114,7 +112,7 @@ paths: response: value: {} "404": - description: The room is not known to the server + description: The room is not known to the server. content: application/json: schema: @@ -129,9 +127,9 @@ paths: - Room discovery /publicRooms: get: - summary: Lists the public rooms on the server. + summary: Lists a server's published room directory description: |- - Lists the public rooms on the server. + Lists a server's published room directory. This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first. @@ -154,13 +152,13 @@ paths: - in: query name: server description: |- - The server to fetch the public room lists from. Defaults to the + The server to fetch the room directory from. Defaults to the local server. Case sensitive. schema: type: string responses: "200": - description: A list of the rooms on the server. + description: A list of the published rooms on the server. content: application/json: schema: @@ -168,9 +166,9 @@ paths: tags: - Room discovery post: - summary: Lists the public rooms on the server with optional filter. + summary: Lists a server's published room directory with an optional filter description: |- - Lists the public rooms on the server, with optional filter. + Lists a server's published room directory with an optional filter. This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first. @@ -182,7 +180,7 @@ paths: - in: query name: server description: |- - The server to fetch the public room lists from. Defaults to the + The server to fetch the room directory from. Defaults to the local server. Case sensitive. schema: type: string @@ -253,7 +251,7 @@ paths: required: true responses: "200": - description: A list of the rooms on the server. + description: A filtered list of the published rooms on the server. content: application/json: schema: diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 565f1aa4..07743fc1 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -13,16 +13,20 @@ # limitations under the License. openapi: 3.1.0 info: - title: Matrix Federation Public Rooms API + title: Matrix Federation Room Directory API version: 1.0.0 paths: /publicRooms: get: - summary: Get all the public rooms for a homeserver + summary: Lists the server's published room directory. description: |- - Gets all the public rooms for the homeserver. This should not return - rooms that are listed on another homeserver's directory, just those - listed on the receiving homeserver's directory. + Lists the server's published room directory. + + This API returns paginated responses. The rooms are ordered by the number + of joined members, with the largest rooms first. + + This should not return rooms that are listed on another homeserver's directory, + just those listed on the receiving homeserver's directory. operationId: getPublicRooms security: - signedRequest: [] @@ -62,21 +66,18 @@ paths: type: string responses: "200": - description: The public room list for the homeserver. + description: A list of the published rooms on the server. content: application/json: schema: $ref: ../client-server/definitions/public_rooms_response.yaml post: - summary: Gets the public rooms on the server with optional filter. + summary: Lists the server's published room directory with an optional filter description: |- - Lists the public rooms on the server, with optional filter. + Lists the server's published room directory with an optional filter. This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first. - - Note that this endpoint receives and returns the same format that is seen - in the Client-Server API's `POST /publicRooms` endpoint. operationId: queryPublicRooms security: - signedRequest: [] @@ -147,69 +148,11 @@ paths: required: true responses: "200": - description: A list of the rooms on the server. + description: A filtered list of the published rooms on the server. content: application/json: schema: - type: object - description: A list of the rooms on the server. - required: - - chunk - properties: - chunk: - title: PublicRoomsChunks - type: array - description: A paginated chunk of public rooms. - items: - allOf: - - $ref: ../client-server/definitions/public_rooms_chunk.yaml - - type: object - properties: - # Override description of join_rule - join_rule: - type: string - description: |- - The room's join rule. When not present, the room is assumed to - be `public`. Note that rooms with `invite` join rules are not - expected here, but rooms with `knock` rules are given their - near-public nature. - next_batch: - type: string - description: |- - A pagination token for the response. The absence of this token - means there are no more results to fetch and the client should - stop paginating. - prev_batch: - type: string - description: |- - A pagination token that allows fetching previous results. The - absence of this token means there are no results before this - batch, i.e. this is the first batch. - total_room_count_estimate: - type: integer - description: |- - An estimate on the total number of public rooms, if the - server has an estimate. - examples: - response: - value: { - "chunk": [ - { - "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", - "guest_can_join": false, - "name": "CHEESE", - "num_joined_members": 37, - "room_id": "!ol19s:bleecker.street", - "topic": "Tasty tasty cheese", - "world_readable": true, - "join_rule": "public", - "room_type": "m.space" - } - ], - "next_batch": "p190q", - "prev_batch": "p1902", - "total_room_count_estimate": 115 - } + $ref: ../client-server/definitions/public_rooms_response.yaml servers: - url: "{protocol}://{hostname}{basePath}" variables: From 5be34d8f2baab8725db6c237e0b42c16c19a6b0d Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 19 Mar 2025 14:48:12 +0100 Subject: [PATCH 2/5] Add changelogs --- changelogs/client_server/newsfragments/2104.clarification | 1 + changelogs/server_server/newsfragments/2104.clarification | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2104.clarification create mode 100644 changelogs/server_server/newsfragments/2104.clarification diff --git a/changelogs/client_server/newsfragments/2104.clarification b/changelogs/client_server/newsfragments/2104.clarification new file mode 100644 index 00000000..fc064c62 --- /dev/null +++ b/changelogs/client_server/newsfragments/2104.clarification @@ -0,0 +1 @@ +Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. diff --git a/changelogs/server_server/newsfragments/2104.clarification b/changelogs/server_server/newsfragments/2104.clarification new file mode 100644 index 00000000..fc064c62 --- /dev/null +++ b/changelogs/server_server/newsfragments/2104.clarification @@ -0,0 +1 @@ +Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility. From 03c96e505b08fae6d106f0fb3f6690e005deb969 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 20 Mar 2025 10:47:51 +0100 Subject: [PATCH 3/5] Mention knockable rooms in warning --- content/client-server-api/_index.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b8e7878f..da5ddecb 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2848,9 +2848,16 @@ creation, clients can query and change a room's visibility in the directory thro the endpoints listed below, provided that the server permits this. {{% boxes/warning %}} -A visibility setting of `public` should not be confused with a `public` [join rule](#mroomjoin_rules) -or a `world_readable` [history visibility](#room-history-visibility). The visibility merely defines -whether a room is included in the published room directory or not. +The visibility setting merely defines whether a room is included in the published +room directory or not. It doesn't make any guarantees about the room's +[join rule](#mroomjoin_rules) or [history visibility](#room-history-visibility). + +In particular, a visibility setting of `public` should not be confused with a `public` +join rule. Rooms with a join rule of `knock`, for instance, could reasonably be published +in the directory, too. + +Similarly, a visibility setting of `public` does not necessarily imply a `world_readable` +history visibility. {{% /boxes/warning %}} {{% http-api spec="client-server" api="list_public_rooms" %}} From 2933ab5f527fb073629cb17f4d75a12cc00766af Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 21 Mar 2025 15:27:04 +0100 Subject: [PATCH 4/5] Mention optional serverside filters --- content/client-server-api/_index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index da5ddecb..05ac42c3 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2858,6 +2858,10 @@ in the directory, too. Similarly, a visibility setting of `public` does not necessarily imply a `world_readable` history visibility. + +To increase performance, servers MAY apply additional filters when listing the +directory, for instance, by automatically excluding rooms with `invite` join rules +that are not `world_readable` regarless of their visibility. {{% /boxes/warning %}} {{% http-api spec="client-server" api="list_public_rooms" %}} From 264f8fed7aa05f17489bec61d6f6dc0f44313268 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 31 Mar 2025 10:06:10 +0200 Subject: [PATCH 5/5] Fix typo --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 05ac42c3..f867a008 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2861,7 +2861,7 @@ history visibility. To increase performance, servers MAY apply additional filters when listing the directory, for instance, by automatically excluding rooms with `invite` join rules -that are not `world_readable` regarless of their visibility. +that are not `world_readable` regardless of their visibility. {{% /boxes/warning %}} {{% http-api spec="client-server" api="list_public_rooms" %}}