From 42ae5c966a1256e3ff2ec1945c45529dc92fae68 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Tue, 12 May 2020 19:02:39 -0600
Subject: [PATCH] Clarify the limits of prev_events and auth_events

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

These restrictions are due to a Synapse change which never made it to the spec prior to the MSC process. This is therefore documenting an omission.

Synapse's numbers are verified here: https://github.com/matrix-org/synapse/blob/207b1737ee0acd226359d59ce3b7f7d46111b1c8/synapse/handlers/federation.py#L1183-L1213

... and Synapse's handling of the backfill endpoint is described here: https://github.com/matrix-org/synapse/blob/207b1737ee0acd226359d59ce3b7f7d46111b1c8/synapse/handlers/federation.py#L829-L837

This also includes a mention that https://github.com/matrix-org/matrix-doc/pull/1594 should render the `auth_events` limitation unnecessary.

No changes are required to the the "checks on receipt of a PDU" section of the server-server spec as it starts with "must be a valid event", to which an event is invalid if it contains too many prev or auth events.
---
 api/server-server/backfill.yaml                      | 8 ++++++++
 api/server-server/definitions/pdu_v3.yaml            | 6 ++++++
 api/server-server/definitions/pdu_v4.yaml            | 6 ++++++
 api/server-server/definitions/unsigned_pdu_base.yaml | 6 ++++++
 4 files changed, 26 insertions(+)

diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml
index 2ed6298c..d53de6c0 100644
--- a/api/server-server/backfill.yaml
+++ b/api/server-server/backfill.yaml
@@ -63,6 +63,14 @@ paths:
           description: |-
             A transaction containing the PDUs that preceded the given event(s), including the given
             event(s), up to the given limit.
+
+            .. Note::
+               Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited
+               in number, the response of backfill MUST NOT be validated on these specific restrictions.
+
+               Due to historical reasons, it is possible that events which were previously accepted
+               would now be rejected by these limitations. The events should be rejected per usual by
+               the ``/send``, ``/get_missing_events``, and remaining endpoints.
           schema:
             $ref: "definitions/unlimited_pdu_transaction.yaml"
   "/get_missing_events/{roomId}":
diff --git a/api/server-server/definitions/pdu_v3.yaml b/api/server-server/definitions/pdu_v3.yaml
index 38105098..3e69d941 100644
--- a/api/server-server/definitions/pdu_v3.yaml
+++ b/api/server-server/definitions/pdu_v3.yaml
@@ -32,6 +32,10 @@ allOf:
         description: |-
           Event IDs for the authorization events that would
           allow this event to be in the room.
+
+          Must contain less than or equal to 10 events. Note that if the relevant
+          auth event selection rules are used, this restriction should never be
+          encountered.
         example: ["$base64EncodedHash", "$AnotherEvent"]
       prev_events:
         type: array
@@ -41,6 +45,8 @@ allOf:
         description: |-
           Event IDs for the most recent events in the room
           that the homeserver was aware of when it made this event.
+
+          Must contain less than or equal to 20 events.
         example: ["$base64EncodedHash", "$AnotherEvent"]
       hashes:
         type: object
diff --git a/api/server-server/definitions/pdu_v4.yaml b/api/server-server/definitions/pdu_v4.yaml
index a045e657..d22956c6 100644
--- a/api/server-server/definitions/pdu_v4.yaml
+++ b/api/server-server/definitions/pdu_v4.yaml
@@ -32,6 +32,10 @@ allOf:
         description: |-
           Event IDs for the authorization events that would
           allow this event to be in the room.
+
+          Must contain less than or equal to 10 events. Note that if the relevant
+          auth event selection rules are used, this restriction should never be
+          encountered.
         example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
       prev_events:
         type: array
@@ -41,6 +45,8 @@ allOf:
         description: |-
           Event IDs for the most recent events in the room
           that the homeserver was aware of when it made this event.
+
+          Must contain less than or equal to 20 events.
         example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
     required:
       - auth_events
diff --git a/api/server-server/definitions/unsigned_pdu_base.yaml b/api/server-server/definitions/unsigned_pdu_base.yaml
index 283e4fed..f1485b55 100644
--- a/api/server-server/definitions/unsigned_pdu_base.yaml
+++ b/api/server-server/definitions/unsigned_pdu_base.yaml
@@ -53,6 +53,8 @@ properties:
     description: |-
       Event IDs and reference hashes for the most recent events in the room
       that the homeserver was aware of when it made this event.
+
+      Must contain less than or equal to 20 events.
     items:
       type: array
       maxItems: 2
@@ -84,6 +86,10 @@ properties:
     description: |-
       Event IDs and reference hashes for the authorization events that would
       allow this event to be in the room.
+
+      Must contain less than or equal to 10 events. Note that if the relevant
+      auth event selection rules are used, this restriction should never be
+      encountered.
     items:
       type: array
       maxItems: 2