Spec for MSC3981 (#1746)

* 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.

* Missed schemas

* newsfile

* Actually it clearly isn't going to support markdown, is it?

* grammar

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* grammar

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Clarity

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Clarity

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Typo

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* More clarity.

Note this is counter what the MSC actually proposed to add, but
I think it's clear that this is what it meant.

---------

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/1746.feature

@@ -0,0 +1 @@
+Add support for recursion on the /relations endpoints (MSC3981).

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
+control how far the server recurses. If the client decides that the server's
+recursion level is insufficient, it could, for example, perform the recursion
+itself, 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.
@@ -39,6 +39,7 @@ paths:
         - $ref: '#/components/parameters/to'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/dir'
+        - $ref: '#/components/parameters/recurse'
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -96,6 +97,7 @@ paths:
         - $ref: '#/components/parameters/to'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/dir'
+        - $ref: '#/components/parameters/recurse'
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -167,6 +169,7 @@ paths:
         - $ref: '#/components/parameters/to'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/dir'
+        - $ref: '#/components/parameters/recurse'
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
@@ -294,6 +297,27 @@ components:
       example: org.example.my_relation
       schema:
         type: string
+    recurse:
+      in: query
+      name: recurse
+      x-addedInMatrixVersion: "1.10"
+      required: false
+      description: |-
+        Whether to additionally include events which only relate indirectly to the
+        given event, i.e. events related to the given event via two 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 homeservers traverse at least 3 levels of relationships.
+        Implementations may perform more but should be careful to not infinitely recurse.
+
+        The default value is `false`.
+      schema:
+        type: boolean
   schemas:
     response:
       type: object
@@ -308,6 +332,12 @@ components:
           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. If the client
+            did not specify the `recurse` parameter, this field must be absent.
   responses:
     "404":
       description: |-