Spec for MSC3981

This writes up matrix-org/matrix-spec-proposals#3981

Hopefully this is relatively straightforward, apart from having to add
the parameters and response field in all three places. I tried to factor
these out but it seems references just aren't supported in the right
places currently (see #1745
for my efforts). Path parameters can't be optional, so it can't be done
that way either.

content/client-server-api/_index.md

@@ -2156,6 +2156,19 @@ following endpoint.
 This endpoint is particularly useful if the client has lost context on the aggregation for
 a parent event and needs to rebuild/verify it.
 
+When using the `recurse` parameter, note that there no way for a client to
+affect how much the server recurses. If the client decides that the server's
+recursion level is insufficient, it could, for example, perform the recursion
+manually, or disable whatever feature requires more recursion.
+
+Filters specified via `event_type` or `rel_type` will be applied to all events
+returned, whether direct or indirect relations. Events that would match the filter,
+but whose only relation to the original given event is through a non-matching
+intermediate event, will not be included. This means that supplying a `rel_type`
+parameter of `m.thread` is not appropriate for fetching all events in a thread since
+relations to the threaded events would be filtered out. For this purpose, clients should
+omit the `rel_type` parameter and perform any necessary filtering on the client side.
+
 {{% boxes/note %}}
 Because replies do not use `rel_type`, they will not be accessible via this API.
 {{% /boxes/note %}}

data/api/client-server/relations.yaml

@@ -1,4 +1,4 @@
-# Copyright 2022 The Matrix.org Foundation C.I.C.
+# Copyright 2022,2024 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.
@@ -96,6 +96,26 @@ paths:
             enum:
               - b
               - f
+        - in: query
+          name: recurse
+          x-addedInMatrixVersion: "1.10"
+          required: false
+          description: |-
+            Whether to additionally include events which only relate indirectly to the
+            given event, ie. events related to the root events via one or more direct relationships.
+
+            If set to `false`, only events which have direct a relation with the given
+            event will be included.
+
+            If set to `true`, all events which relate to the given event, or relate to
+            events that relate to the given event, will be included.
+
+            It is recommended that at least 3 levels of relationships are traversed.
+            Implementations may perform more but should be careful to not infinitely recurse.
+
+            The default value is `false`.
+          schema:
+            type: boolean
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -127,6 +147,12 @@ paths:
                     description: |-
                       An opaque string representing a pagination token. The absence of this token
                       means this is the start of the result set, i.e. this is the first batch/page.
+                  recursion_depth:
+                    type: integer
+                    description: |-
+                      If the `recurse` parameter was supplied by the client, this response field is
+                      mandatory and gives the actual depth to which the server recursed. The the client
+                      did not specify the `recurse` parameter, this field must be absent.
                 required:
                   - chunk
               examples:
@@ -253,6 +279,24 @@ paths:
             enum:
               - b
               - f
+        - in: query
+          name: recurse
+          x-addedInMatrixVersion: "1.10"
+          required: false
+          description: |-
+            Whether to additionally include events which only relate indirectly to the
+            given event, ie. events related to the root events via one or more direct relationships.
+
+            If set to `false`, only events which have direct a relation with the given
+            event will be included.
+
+            If set to `true`, all events which relate to the given event, or relate to
+            events that relate to the given event, will be included.
+
+            It is recommended that at least 3 levels of relationships are traversed.
+            Implementations may perform more but should be careful to not infinitely recurse.
+
+            The default value is `false`.
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -286,6 +330,12 @@ paths:
                     description: |-
                       An opaque string representing a pagination token. The absence of this token
                       means this is the start of the result set, i.e. this is the first batch/page.
+                  recursion_depth:
+                    type: integer
+                    description: |-
+                      If the `recurse` parameter was supplied by the client, this response field is
+                      mandatory and gives the actual depth to which the server recursed. The the client
+                      did not specify the `recurse` parameter, this field must be absent.
                 required:
                   - chunk
               examples:
@@ -424,6 +474,24 @@ paths:
             enum:
               - b
               - f
+        - in: query
+          name: recurse
+          x-addedInMatrixVersion: "1.10"
+          required: false
+          description: |-
+            Whether to additionally include events which only relate indirectly to the
+            given event, ie. events related to the root events via one or more direct relationships.
+
+            If set to `false`, only events which have direct a relation with the given
+            event will be included.
+
+            If set to `true`, all events which relate to the given event, or relate to
+            events that relate to the given event, will be included.
+
+            It is recommended that at least 3 levels of relationships are traversed.
+            Implementations may perform more but should be careful to not infinitely recurse.
+
+            The default value is `false`.
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -457,6 +525,12 @@ paths:
                     description: |-
                       An opaque string representing a pagination token. The absence of this token
                       means this is the start of the result set, i.e. this is the first batch/page.
+                  recursion_depth:
+                    type: integer
+                    description: |-
+                      If the `recurse` parameter was supplied by the client, this response field is
+                      mandatory and gives the actual depth to which the server recursed. The the client
+                      did not specify the `recurse` parameter, this field must be absent.
                 required:
                   - chunk
               examples: