From 8a18446d549b2f112a33d66732e3746ebe5e1a3c Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Tue, 3 Jan 2023 18:46:08 +0000
Subject: [PATCH] Extend `/v2/send_join` to handle `omit_members`

Per MSC3706
---
 .../server_server/newsfragments/1391.feature  |  1 +
 data/api/server-server/joins-v2.yaml          | 52 +++++++++++++++----
 2 files changed, 43 insertions(+), 10 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1391.feature

diff --git a/changelogs/server_server/newsfragments/1391.feature b/changelogs/server_server/newsfragments/1391.feature
new file mode 100644
index 00000000..e5ca05a5
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1391.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/joins-v2.yaml b/data/api/server-server/joins-v2.yaml
index 9ce7beec..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
@@ -191,38 +199,52 @@ paths:
               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: |-
-                  The auth chain for the entire current room state prior to the join event.
+                  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
-                  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: {}
+                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.
 
-                  The event format varies depending on the room version - check the [room version specification](/rooms)
-                  for precise event formats.
+                  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
-                  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: {}
+                x-changedInMatrixVersion:
+                  "1.6": |-
+                    permit omission of membership events.
               event:
                 type: object
                 title: SignedMembershipEvent
@@ -231,11 +253,21 @@ paths:
                   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"]
             }