From 67d46fa881169ee6cea9d20028189d1869c5c83b Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Mon, 25 May 2020 10:59:41 -0600
Subject: [PATCH] Clarify the auth_chain and state for send_join

Fixes https://github.com/matrix-org/matrix-doc/issues/2467
Fixes https://github.com/matrix-org/matrix-doc/issues/2464

This is based on looking at Synapse, not actually testing it. Within the send_join handling functions, an "event context" is acquired [here](https://github.com/matrix-org/synapse/blob/d14c4d6b6d02e8c55a6647ce0f0b3b44356d6173/synapse/handlers/federation.py#L1472) which then later uses the previous state (populated [here](https://github.com/matrix-org/synapse/blob/d14c4d6b6d02e8c55a6647ce0f0b3b44356d6173/synapse/state/__init__.py#L286-L289) in the event context) [here](https://github.com/matrix-org/synapse/blob/d14c4d6b6d02e8c55a6647ce0f0b3b44356d6173/synapse/handlers/federation.py#L1494-L1501) to return a response. Within the event context, the previous state IDs are populated [here](https://github.com/matrix-org/synapse/blob/d14c4d6b6d02e8c55a6647ce0f0b3b44356d6173/synapse/state/__init__.py#L351).
---
 .../definitions/send_join_response.yaml             | 13 ++++++++-----
 .../server_server/newsfragments/2575.clarification  |  1 +
 2 files changed, 9 insertions(+), 5 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/2575.clarification

diff --git a/api/server-server/definitions/send_join_response.yaml b/api/server-server/definitions/send_join_response.yaml
index 96ceaefc..2837556b 100644
--- a/api/server-server/definitions/send_join_response.yaml
+++ b/api/server-server/definitions/send_join_response.yaml
@@ -22,9 +22,10 @@ properties:
   auth_chain:
     type: array
     description: |-
-      The auth chain. Note that events have a different format depending on
-      the room version - check the `room version specification`_ for precise
-      event formats.
+      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`_ for precise event formats.
     items:
       type: object
       title: PDU
@@ -39,8 +40,10 @@ properties:
   state:
     type: array
     description: |-
-      The room state. The event format varies depending on the room version -
-      check the `room version specification`_ for precise event formats.
+      The resolved current room state prior to the join event.
+
+      The event format varies depending on the room version - check the `room version specification`_
+      for precise event formats.
     items:
       type: object
       title: PDU
diff --git a/changelogs/server_server/newsfragments/2575.clarification b/changelogs/server_server/newsfragments/2575.clarification
new file mode 100644
index 00000000..5eb18394
--- /dev/null
+++ b/changelogs/server_server/newsfragments/2575.clarification
@@ -0,0 +1 @@
+Clarify the state/auth chain requirements for ``/send_join``.