From 4fde94767f0e92c8cc44ccc7c3b745eb3a3b14af Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 12 Mar 2024 17:38:07 +0000 Subject: [PATCH 01/10] 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. --- content/client-server-api/_index.md | 13 +++++ data/api/client-server/relations.yaml | 76 ++++++++++++++++++++++++++- 2 files changed, 88 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0e7e8473a..b20f1316f 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 +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 %}} diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 65c3491ad..9002130e6 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. @@ -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: From 58c5c9cdcea08637c7b3f203cce0376119d970cc Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 12 Mar 2024 17:44:40 +0000 Subject: [PATCH 02/10] Missed schemas --- data/api/client-server/relations.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 9002130e6..255a80616 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -297,6 +297,8 @@ paths: 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. @@ -492,6 +494,8 @@ paths: 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. From 94a84ea5079f760720abfa332466adbc13683c73 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 12 Mar 2024 17:47:01 +0000 Subject: [PATCH 03/10] newsfile --- changelogs/client_server/newsfragments/1746.feature | 1 + 1 file changed, 1 insertion(+) 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 000000000..cc8589470 --- /dev/null +++ b/changelogs/client_server/newsfragments/1746.feature @@ -0,0 +1 @@ +Add support for recursion on the /relations endpoints ([MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981)). From a62ab1bc4cc9378d2e445668ae6c33afdf67affb Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 12 Mar 2024 17:49:09 +0000 Subject: [PATCH 04/10] Actually it clearly isn't going to support markdown, is it? --- changelogs/client_server/newsfragments/1746.feature | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/client_server/newsfragments/1746.feature b/changelogs/client_server/newsfragments/1746.feature index cc8589470..a36730744 100644 --- a/changelogs/client_server/newsfragments/1746.feature +++ b/changelogs/client_server/newsfragments/1746.feature @@ -1 +1 @@ -Add support for recursion on the /relations endpoints ([MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981)). +Add support for recursion on the /relations endpoints (MSC3981). From 65f532e8874759a38db8fa5cb269c75dc16cf4aa Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:02:57 +0000 Subject: [PATCH 05/10] grammar Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- data/api/client-server/relations.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index c43ea2f35..ed9bee96b 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -304,7 +304,7 @@ components: 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. + given event, i.e. 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. From e23a1c37c2bf8f4e8f48464b9d0f077557bda829 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:03:24 +0000 Subject: [PATCH 06/10] grammar Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b20f1316f..4e4d3a5ba 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2157,7 +2157,7 @@ This endpoint is particularly useful if the client has lost context on the aggre 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 +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 manually, or disable whatever feature requires more recursion. From e8961e3aa1756e690f802a73bba0f9c8a5765082 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:03:35 +0000 Subject: [PATCH 07/10] Clarity Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4e4d3a5ba..11023a33e 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2159,7 +2159,7 @@ 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 -manually, or disable whatever feature requires more 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, From 0ac093eacbb885ab485b6d5bc4a3153dfba22f8d Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:03:48 +0000 Subject: [PATCH 08/10] Clarity Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- data/api/client-server/relations.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index ed9bee96b..cc59c15b4 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -312,7 +312,7 @@ components: 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. + 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`. From fe05497aaa71f56b70f6c29dddf741b214190ded Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:04:02 +0000 Subject: [PATCH 09/10] Typo Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- data/api/client-server/relations.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index cc59c15b4..bf3ba862e 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -336,7 +336,7 @@ components: 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 + 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": From 1ba0ab9de8c45cfcaaf40244459446a6dfd81cc6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 18:10:04 +0000 Subject: [PATCH 10/10] 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. --- data/api/client-server/relations.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index bf3ba862e..25c701997 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -304,7 +304,7 @@ components: required: false description: |- Whether to additionally include events which only relate indirectly to the - given event, i.e. events related to the root events via one or more direct relationships. + 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.