Merge pull request #2538 from matrix-org/travis/spec/clarify-num-ev-limit

Clarify the limits of prev_events and auth_events

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}":

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

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

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

changelogs/server_server/newsfragments/2538.clarification

@@ -0,0 +1 @@
+Clarify the limits of ``prev_events`` and ``auth_events`` for PDUs.