From b8411b5159b6418fccc0402b926d95ab94c7598d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 4 Jan 2023 12:12:49 +0000 Subject: [PATCH] Spec `omit_members` for `/v2/send_join` (#1393) Per MSC3706 --- .../server_server/newsfragments/1393.feature | 1 + .../definitions/send_join_response.yaml | 68 ---------------- data/api/server-server/joins-v1.yaml | 41 +++++++++- data/api/server-server/joins-v2.yaml | 81 ++++++++++++++++++- 4 files changed, 120 insertions(+), 71 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1393.feature delete mode 100644 data/api/server-server/definitions/send_join_response.yaml diff --git a/changelogs/server_server/newsfragments/1393.feature b/changelogs/server_server/newsfragments/1393.feature new file mode 100644 index 00000000..e5ca05a5 --- /dev/null +++ b/changelogs/server_server/newsfragments/1393.feature @@ -0,0 +1 @@ +Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). \ No newline at end of file diff --git a/data/api/server-server/definitions/send_join_response.yaml b/data/api/server-server/definitions/send_join_response.yaml deleted file mode 100644 index 12b020a2..00000000 --- a/data/api/server-server/definitions/send_join_response.yaml +++ /dev/null @@ -1,68 +0,0 @@ -# Copyright 2018 New Vector Ltd -# Copyright 2020 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: Room State -description: The state for the room. -properties: - origin: - type: string - description: The resident server's DNS name. - auth_chain: - type: array - description: |- - The auth chain for the entire current room state prior to the join event. - - Note that events have a different format depending on the room version - check the - [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - example: - $ref: "../examples/minimal_pdu.json" - state: - type: array - description: |- - The resolved current room state prior to the join event. - - The event format varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - example: - $ref: "../examples/minimal_pdu.json" - event: - type: object - title: SignedMembershipEvent - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed - copy of the membership event sent to other servers by the resident server, including the resident - server's signature. - example: - $ref: "../examples/minimal_pdu.json" -required: ["auth_chain", "state", "origin"] diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index b45a49e2..1b850266 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -333,7 +333,46 @@ paths: - type: integer description: The value `200`. example: 200 - - $ref: "./definitions/send_join_response.yaml" + - type: object + title: Room State + description: The state for the room. + properties: + origin: + type: string + description: The resident server's DNS name. + auth_chain: + type: array + description: |- + The auth chain for the entire current room state prior to the join event. + + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + schema: + type: object + properties: {} + state: + type: array + description: |- + The resolved current room state prior to the join event. + + The event format varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + schema: + type: object + properties: {} + required: ["auth_chain", "state", "origin"] examples: application/json: [ 200, diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 78560c86..49467c21 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -65,6 +65,14 @@ paths: description: The event ID for the join event. required: true x-example: "$abc123:example.org" + - in: query + name: omit_members + type: boolean + description: |- + If `true`, indicates that that calling server can accept a reduced + response, in which membership events are omitted from `state` and + redundant events are omitted from `auth_chain`. + x-addedInMatrixVersion: "1.6" - in: body name: body type: object @@ -186,11 +194,80 @@ paths: description: |- The join event has been accepted into the room. schema: - $ref: "./definitions/send_join_response.yaml" + type: object + properties: + origin: + type: string + description: The resident server's DNS name. + members_omitted: + type: boolean + description: "`true` if `m.room.member` events have been omitted from `state`." + x-addedInMatrixVersion: "1.6" + auth_chain: + type: array + description: |- + All events in the auth chain for the new join event, as well + as those in the auth chains for any events returned in + `state`. + + If the `omit_members` query parameter was set to `true`, then + any events that are returned in `state` may be omitted from + `auth_chain`, whether or not membership events are omitted + from `state`. + + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + schema: + type: object + properties: {} + x-changedInMatrixVersion: + "1.6": |- + reworded to include only consider state events returned in + `state`, and to allow elision of redundant events. + state: + type: array + description: |- + The resolved current room state prior to the join event. + + If the request had `omit_members` set to `true`, events of + type `m.room.member` may be omitted from the response to + reduce the size of the response. If this is done, + `members_omitted` must be set to `true`. + items: + type: object + title: PDU + schema: + type: object + properties: {} + x-changedInMatrixVersion: + "1.6": |- + permit omission of membership events. + event: + type: object + title: SignedMembershipEvent + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed + copy of the membership event sent to other servers by the resident server, including the resident + server's signature. + servers_in_room: + type: array + description: |- + **Required** if `members_omitted` is true. + + A list of the servers active in the room (ie, those with joined members) before the join. + items: + type: string + required: ["auth_chain", "state", "origin"] examples: application/json: { "origin": "matrix.org", "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], "state": [{"$ref": "examples/minimal_pdu.json"}], - "event": {"$ref": "examples/pdu_v4_join_membership.json"} + "event": {"$ref": "examples/pdu_v4_join_membership.json"}, + "members_omitted": true, + "servers_in_room": ["matrix.org", "example.com"] }