From 4fde94767f0e92c8cc44ccc7c3b745eb3a3b14af Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 12 Mar 2024 17:38:07 +0000 Subject: [PATCH] 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 0e7e8473..b20f1316 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 65c3491a..9002130e 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: