From cbcbde8f3cf0105ceee86c335181aa22bd2c9851 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 31 Mar 2025 14:13:08 +0200 Subject: [PATCH 1/4] Spec for MSC3266: Room Summary API Signed-off-by: Johannes Marbach --- content/client-server-api/_index.md | 4 + .../definitions/room_summary.yaml | 48 ++++++ data/api/client-server/room_summary.yaml | 138 ++++++++++++++++++ data/api/client-server/space_hierarchy.yaml | 13 +- data/api/server-server/space_hierarchy.yaml | 36 ++--- 5 files changed, 207 insertions(+), 32 deletions(-) create mode 100644 data/api/client-server/definitions/room_summary.yaml create mode 100644 data/api/client-server/room_summary.yaml diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 94dfe35f..c9eb0d2a 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2835,6 +2835,10 @@ re-invited. {{% http-api spec="client-server" api="list_public_rooms" %}} +### Room Summaries + +{{% http-api spec="client-server" api="room_summary" %}} + ## User Data ### User Directory diff --git a/data/api/client-server/definitions/room_summary.yaml b/data/api/client-server/definitions/room_summary.yaml new file mode 100644 index 00000000..a8682e51 --- /dev/null +++ b/data/api/client-server/definitions/room_summary.yaml @@ -0,0 +1,48 @@ +# Copyright 2025 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: RoomSummary +allOf: + - $ref: public_rooms_chunk.yaml + - type: object + properties: + room_type: + type: string + description: The `type` of room (from + [`m.room.create`](/client-server-api/#mroomcreate)), + if any. + allowed_room_ids: + type: array + items: + type: string + description: |- + If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which + are specified by the join rules. Empty or omitted otherwise. + encryption: + type: string + enum: + - "m.megolm.v1.aes-sha2" + description: |- + The encryption algorithm to be used to encrypt messages sent in the + room. + room_version: + description: The version of the room. + type: string + +required: + - room_id + - num_joined_members + - world_readable + - guest_can_join diff --git a/data/api/client-server/room_summary.yaml b/data/api/client-server/room_summary.yaml new file mode 100644 index 00000000..9548e3ca --- /dev/null +++ b/data/api/client-server/room_summary.yaml @@ -0,0 +1,138 @@ +# Copyright 2025 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server Room Summary API + version: 1.0.0 +paths: + "/room_summary/{roomIdOrAlias}": + get: + x-addedInMatrixVersion: "1.15" + summary: Retrieves a summary for a room. + description: |- + Retrieves a summary for a room. + + Clients should note that requests for rooms where the user's membership + is `invite` or `knock` might yield outdated, partial or even no data + since the server may not have access to the current state of the room. + + Servers MAY allow unauthenticated access to this API if at least one of + the following conditions holds true: + + - The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or + `knock_restricted`. + - The room has a `world_readable` [history visibility](#room-history-visibility). + + Servers should consider rate limiting federation requests more heavily, + if the client is unauthenticated. + operationId: getRoomSummary + security: + - signedRequest: [] + parameters: + - in: path + name: roomIdOrAlias + description: The room identifier or alias to summarise. + required: true + example: "#monkeys:matrix.org" + schema: + type: string + - in: query + name: via + description: |- + The servers to attempt to request the summary from when + the local server cannot generate it (for instance, because + it has no local user in the room). + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + responses: + "200": + description: A summary of the room. + content: + application/json: + schema: + description: A summary of the room. + allOf: + - $ref: ../client-server/definitions/room_summary.yaml + - type: object + properties: + room_type: + x-addedInMatrixVersion: # Overrides room_summary.yaml + membership: + description: |- + The membership state of the user if the user is joined to the room. Absent + if the API was called unauthenticated. + enum: + - invite + - join + - knock + - leave + - ban + type: string + required: + - guest_can_join + - num_joined_members + - room_id + - world_readable + examples: + response: + value: { + room_id: "!ol19s:bleecker.street", + avatar_url: "mxc://bleecker.street/CHEDDARandBRIE", + guest_can_join: false, + name: "CHEESE", + num_joined_members: 37, + topic: "Tasty tasty cheese", + world_readable: true, + join_rule: "public", + room_type: "m.space", + membership: "invite", + encryption: "m.megolm.v100", + room_version: "9001", + } + "404": + description: |- + The room could not be found. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Room not found." + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + accessTokenQuery: + $ref: definitions/security.yaml#/accessTokenQuery + accessTokenBearer: + $ref: definitions/security.yaml#/accessTokenBearer diff --git a/data/api/client-server/space_hierarchy.yaml b/data/api/client-server/space_hierarchy.yaml index 3a4a14a5..480e4a62 100644 --- a/data/api/client-server/space_hierarchy.yaml +++ b/data/api/client-server/space_hierarchy.yaml @@ -102,15 +102,10 @@ paths: * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`. items: allOf: - - $ref: definitions/public_rooms_chunk.yaml + - $ref: definitions/room_summary.yaml - type: object title: SpaceHierarchyRoomsChunk properties: - room_type: - type: string - description: The `type` of room (from - [`m.room.create`](/client-server-api/#mroomcreate)), - if any. children_state: type: array description: |- @@ -130,6 +125,12 @@ paths: description: The `origin_server_ts` for the event. required: - origin_server_ts + allowed_room_ids: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml + encryption: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml + room_version: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml required: - children_state next_batch: diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml index 8394588b..63d41304 100644 --- a/data/api/server-server/space_hierarchy.yaml +++ b/data/api/server-server/space_hierarchy.yaml @@ -61,22 +61,10 @@ paths: room: description: A summary of the room requested. allOf: - - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - $ref: ../client-server/definitions/room_summary.yaml - type: object title: SpaceHierarchyParentRoom properties: - room_type: - type: string - description: The `type` of room (from - [`m.room.create`](/client-server-api/#mroomcreate)), - if any. - allowed_room_ids: - type: array - items: - type: string - description: |- - If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which - are specified by the join rules. Empty or omitted otherwise. children_state: type: array description: |- @@ -96,6 +84,10 @@ paths: description: The `origin_server_ts` for the event. required: - origin_server_ts + encryption: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml + room_version: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml required: - children_state children: @@ -105,22 +97,14 @@ paths: be excluded. items: allOf: - - $ref: ../client-server/definitions/public_rooms_chunk.yaml + - $ref: ../client-server/definitions/room_summary.yaml - type: object title: SpaceHierarchyChildRoomsChunk properties: - room_type: - type: string - description: The `type` of room (from - [`m.room.create`](/client-server-api/#mroomcreate)), - if any. - allowed_room_ids: - type: array - items: - type: string - description: |- - If the room is a [restricted room](/server-server-api/#restricted-rooms), these are the room IDs which - are specified by the join rules. Empty or omitted otherwise. + encryption: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml + room_version: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml inaccessible_children: type: array items: From 54842585db212be532e8e2915dbbcbb08a2eae95 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 31 Mar 2025 14:22:49 +0200 Subject: [PATCH 2/4] Add changelog --- changelogs/client_server/newsfragments/2125.feature | 1 + changelogs/server_server/newsfragments/2125.feature | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2125.feature create mode 100644 changelogs/server_server/newsfragments/2125.feature diff --git a/changelogs/client_server/newsfragments/2125.feature b/changelogs/client_server/newsfragments/2125.feature new file mode 100644 index 00000000..f9275b0d --- /dev/null +++ b/changelogs/client_server/newsfragments/2125.feature @@ -0,0 +1 @@ +Add `/_matrix/client/v1/room_summary/{roomIdOrAlias}` and extend `/_matrix/client/v1/rooms/{roomId}/hierarchy` with the new optional properties `allowed_room_ids`, `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). diff --git a/changelogs/server_server/newsfragments/2125.feature b/changelogs/server_server/newsfragments/2125.feature new file mode 100644 index 00000000..0a369ea0 --- /dev/null +++ b/changelogs/server_server/newsfragments/2125.feature @@ -0,0 +1 @@ +Extend `/_matrix/federation/v1/hierarchy/{roomId}` with the new optional properties `encryption` and `room_version` as per [MSC3266](https://github.com/matrix-org/matrix-spec-proposals/pull/3266). From a96aeb5882ef9ccacc397109df547993bc3ccc89 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 31 Mar 2025 14:25:45 +0200 Subject: [PATCH 3/4] Fix indentation --- data/api/server-server/space_hierarchy.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/data/api/server-server/space_hierarchy.yaml b/data/api/server-server/space_hierarchy.yaml index 63d41304..99c25ffa 100644 --- a/data/api/server-server/space_hierarchy.yaml +++ b/data/api/server-server/space_hierarchy.yaml @@ -84,10 +84,10 @@ paths: description: The `origin_server_ts` for the event. required: - origin_server_ts - encryption: - x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml - room_version: - x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml + encryption: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml + room_version: + x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml required: - children_state children: From 7b3083885b0c0409d5fcf74ef67302fefbc6d13b Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 31 Mar 2025 14:27:09 +0200 Subject: [PATCH 4/4] Fix example --- data/api/client-server/room_summary.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/room_summary.yaml b/data/api/client-server/room_summary.yaml index 9548e3ca..3269f862 100644 --- a/data/api/client-server/room_summary.yaml +++ b/data/api/client-server/room_summary.yaml @@ -102,7 +102,7 @@ paths: join_rule: "public", room_type: "m.space", membership: "invite", - encryption: "m.megolm.v100", + encryption: "m.megolm.v1.aes-sha2", room_version: "9001", } "404":