MSC3666: Bundled aggregations for server side search (#3666)

* Initial commit.

* MSC number.

* Link to the current specification.

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

* Clarify that this is a change (and not part of MSC2675).

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

* Remove extra work.

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>

* Add missing slashes and some links.

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

proposals/3666-bundled-aggregations-for-search.md

@@ -0,0 +1,74 @@
+# 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".
+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`](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](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:
+  * `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](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
+
+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.