From 848c1e0348f64ce16f749227f3fc4bf4b457cf19 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:12:32 +0000 Subject: [PATCH] Spec for MSC3981 (#1746) * Spec for MSC3981 This writes up https://github.com/matrix-org/matrix-spec-proposals/pull/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 https://github.com/matrix-org/matrix-spec/pull/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> --- .../client_server/newsfragments/1746.feature | 1 + content/client-server-api/_index.md | 13 ++++++++ data/api/client-server/relations.yaml | 32 ++++++++++++++++++- 3 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1746.feature diff --git a/changelogs/client_server/newsfragments/1746.feature b/changelogs/client_server/newsfragments/1746.feature new file mode 100644 index 00000000..a3673074 --- /dev/null +++ b/changelogs/client_server/newsfragments/1746.feature @@ -0,0 +1 @@ +Add support for recursion on the /relations endpoints (MSC3981). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0e7e8473..11023a33 100644 --- a/content/client-server-api/_index.md +++ b/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 %}} diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index fc35bf5d..25c70199 100644 --- a/data/api/client-server/relations.yaml +++ b/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: |-