From b24e29c573a48841e4d001469df51d650faf569a Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 21 Jan 2022 12:26:41 -0500 Subject: [PATCH 1/6] Initial commit. --- .../xxxx-bundled-aggregations-for-search.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 proposals/xxxx-bundled-aggregations-for-search.md diff --git a/proposals/xxxx-bundled-aggregations-for-search.md b/proposals/xxxx-bundled-aggregations-for-search.md new file mode 100644 index 00000000000..130169f15d7 --- /dev/null +++ b/proposals/xxxx-bundled-aggregations-for-search.md @@ -0,0 +1,71 @@ +# MSC0000: Bundled aggregations for server side search + +[MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) defines a way for +homeservers to include events related to a requested event via "bundled aggregations". +These bundled aggregations help a client render a requested event without needing +to fetch additional information from the server. + +As part of MSC2675 the following APIs should include bundled aggregations: + +* `GET /rooms/{roomId}/messages` +* `GET /rooms/{roomId}/context/{eventId}` +* `GET /rooms/{roomId}/event/{eventId}` +* `GET /sync`, only for room sections in the response where limited field is true; + this amounts to all rooms in the response if the since request parameter was + not passed, also known as an initial sync. +* `GET /rooms{roomId}/relations/{eventId}` + +A noticeable missing API from here is the server side search feature (`POST /search`) +where it is common for a client to not have the full timeline of a room when +receiving results. This would benefit from having the bundled aggregations. + + +## Proposal + +The server side search API (`POST /search`) for the `room_events` category will +include bundled aggregations for any matching events returned to the client. +Per MSC2675 the `unsigned` field of the results would include `m.relations` where +appropriate. This applies to any events themselves, as well as contextual events +returned, these appear as the following fields: + +* The event itself: `results["search_categories"]["room_events"]["results"]["result"]` +* Each contextual event in: + * `results["search_categories"]["room_events"]["results"]["context"]["events_before"]` + * `results["search_categories"]["room_events"]["results"]["context"]["events_after"]` + + +## Potential issues + +The `/search` API is already fairly complicated and can be slow for large rooms. +Returning more data from it could cause performance issues. + + +## Alternatives + +The status quo is that a client can call `/rooms{roomId}/relations/{eventId}` for +each event in the search results in order to fully render each event. This is +expensive, slow, and bandwidth heavy since clients generally need the aggregated +relations, not each related event. + +Older versions of MSC2675 included an `/rooms{roomId}/aggregations/{eventId}` API +to fetch the bundled aggregations for an event directly. This would save on bandwidth +and simplify the work that clients need to achieve, but would still need result +in needless roundtrips as it would have to be called per event. + + +## Security considerations + +None. + + +## Unstable prefix + +N/A + + +## Dependencies + +This MSC builds on [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) +and [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675), which have +been accepted, but are not yet in a released version of the spec at the time of +writing. From 19b1acacfaeb782311c7ed901c345649e10e8cee Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 21 Jan 2022 12:28:03 -0500 Subject: [PATCH 2/6] MSC number. --- ...ns-for-search.md => 3666-bundled-aggregations-for-search.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-bundled-aggregations-for-search.md => 3666-bundled-aggregations-for-search.md} (98%) diff --git a/proposals/xxxx-bundled-aggregations-for-search.md b/proposals/3666-bundled-aggregations-for-search.md similarity index 98% rename from proposals/xxxx-bundled-aggregations-for-search.md rename to proposals/3666-bundled-aggregations-for-search.md index 130169f15d7..37abcdb3ea1 100644 --- a/proposals/xxxx-bundled-aggregations-for-search.md +++ b/proposals/3666-bundled-aggregations-for-search.md @@ -1,4 +1,4 @@ -# MSC0000: Bundled aggregations for server side search +# MSC3666: Bundled aggregations for server side search [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) defines a way for homeservers to include events related to a requested event via "bundled aggregations". From 33d72e21a638be99fa61a7571c0b558d90c9c037 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 22 Mar 2022 11:34:17 -0400 Subject: [PATCH 3/6] Link to the current specification. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3666-bundled-aggregations-for-search.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3666-bundled-aggregations-for-search.md b/proposals/3666-bundled-aggregations-for-search.md index 37abcdb3ea1..b203dbf098b 100644 --- a/proposals/3666-bundled-aggregations-for-search.md +++ b/proposals/3666-bundled-aggregations-for-search.md @@ -22,7 +22,8 @@ receiving results. This would benefit from having the bundled aggregations. ## Proposal -The server side search API (`POST /search`) for the `room_events` category will +The server side search API ([`POST /search`](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3search)) +for the `room_events` category will include bundled aggregations for any matching events returned to the client. Per MSC2675 the `unsigned` field of the results would include `m.relations` where appropriate. This applies to any events themselves, as well as contextual events From d5589023e2d11db65e3467dc20c2814037801bd6 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 22 Mar 2022 11:35:07 -0400 Subject: [PATCH 4/6] Clarify that this is a change (and not part of MSC2675). Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3666-bundled-aggregations-for-search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3666-bundled-aggregations-for-search.md b/proposals/3666-bundled-aggregations-for-search.md index b203dbf098b..1825e22cede 100644 --- a/proposals/3666-bundled-aggregations-for-search.md +++ b/proposals/3666-bundled-aggregations-for-search.md @@ -25,9 +25,9 @@ receiving results. This would benefit from having the bundled aggregations. The server side search API ([`POST /search`](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3search)) for the `room_events` category will include bundled aggregations for any matching events returned to the client. -Per MSC2675 the `unsigned` field of the results would include `m.relations` where +As in MSC2675, the `unsigned` field of the results would include `m.relations` where appropriate. This applies to any events themselves, as well as contextual events -returned, these appear as the following fields: +returned; these appear as the following fields: * The event itself: `results["search_categories"]["room_events"]["results"]["result"]` * Each contextual event in: From a9c28643320f92b7fe5acd56d3713e9b5dd826ea Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 29 Mar 2022 14:40:06 -0400 Subject: [PATCH 5/6] Remove extra work. Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/3666-bundled-aggregations-for-search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3666-bundled-aggregations-for-search.md b/proposals/3666-bundled-aggregations-for-search.md index 1825e22cede..81c9aba7b16 100644 --- a/proposals/3666-bundled-aggregations-for-search.md +++ b/proposals/3666-bundled-aggregations-for-search.md @@ -50,7 +50,7 @@ relations, not each related event. Older versions of MSC2675 included an `/rooms{roomId}/aggregations/{eventId}` API to fetch the bundled aggregations for an event directly. This would save on bandwidth -and simplify the work that clients need to achieve, but would still need result +and simplify the work that clients need to achieve, but would still result in needless roundtrips as it would have to be called per event. From fb0a9a1de7c1ae5f90d022f577c4aa3bd67d0a9e Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 29 Mar 2022 14:41:39 -0400 Subject: [PATCH 6/6] Add missing slashes and some links. --- .../3666-bundled-aggregations-for-search.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/proposals/3666-bundled-aggregations-for-search.md b/proposals/3666-bundled-aggregations-for-search.md index 81c9aba7b16..8de216e5266 100644 --- a/proposals/3666-bundled-aggregations-for-search.md +++ b/proposals/3666-bundled-aggregations-for-search.md @@ -13,7 +13,7 @@ As part of MSC2675 the following APIs should include bundled aggregations: * `GET /sync`, only for room sections in the response where limited field is true; this amounts to all rooms in the response if the since request parameter was not passed, also known as an initial sync. -* `GET /rooms{roomId}/relations/{eventId}` +* `GET /rooms/{roomId}/relations/{eventId}` A noticeable missing API from here is the server side search feature (`POST /search`) where it is common for a client to not have the full timeline of a room when @@ -25,9 +25,10 @@ receiving results. This would benefit from having the bundled aggregations. The server side search API ([`POST /search`](https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3search)) for the `room_events` category will include bundled aggregations for any matching events returned to the client. -As in MSC2675, the `unsigned` field of the results would include `m.relations` where -appropriate. This applies to any events themselves, as well as contextual events -returned; these appear as the following fields: +As in [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675), the `unsigned` +field of the results would include `m.relations` where appropriate. This applies to +any events themselves, as well as contextual events returned; these appear as the +following fields: * The event itself: `results["search_categories"]["room_events"]["results"]["result"]` * Each contextual event in: @@ -43,15 +44,16 @@ Returning more data from it could cause performance issues. ## Alternatives -The status quo is that a client can call `/rooms{roomId}/relations/{eventId}` for +The status quo is that a client can call `/rooms/{roomId}/relations/{eventId}` for each event in the search results in order to fully render each event. This is expensive, slow, and bandwidth heavy since clients generally need the aggregated relations, not each related event. -Older versions of MSC2675 included an `/rooms{roomId}/aggregations/{eventId}` API -to fetch the bundled aggregations for an event directly. This would save on bandwidth -and simplify the work that clients need to achieve, but would still result -in needless roundtrips as it would have to be called per event. +Older versions of [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) +included an `/rooms/{roomId}/aggregations/{eventId}` API to fetch the bundled +aggregations for an event directly. This would save on bandwidth and simplify +the work that clients need to achieve, but would still result in needless +roundtrips as it would have to be called per event. ## Security considerations