MSC3874: Filtering threads from the /messages endpoint

proposals/3874-messages-endpoint-threads-filter.md

@@ -0,0 +1,82 @@
+# MSC3874 Loading Messages excluding Threads
+
+## Motivation
+
+In Element's beta implementation of threads, it's become a noticeable issue where a room may have activity in a 
+long-running thread while the main timeline is inactive. If a user starts their client and tries to paginate through the 
+main timeline, loading will feel sluggish, as lots of events have to be loaded that won’t be displayed.
+
+This proposal would allow reducing the number of requests and amount of data transmitted. 
+
+## Proposal
+
+### Allow filtering the /messages API to not include threaded messages
+
+This proposal recommends extending the existing [Event filters] are extended with a new filter, named
+`not_related_by_rel_types`, which acts exactly like the opposite of the existing `related_by_rel_types` filter.
+
+This means, if this filter is specified, only message which match none of the given relation types will be returned.
+
+```
+GET /_matrix/client/unstable/org.matrix.msc3874/rooms/!room_id:domain/messages?filter=...
+```
+
+The filter string includes the new fields, above. In this example, the URL encoded JSON is presented unencoded and
+formatted for legibility:
+
+```jsonc
+{
+  "types": ["m.room.message"],
+  "not_related_by_rel_types": ["m.thread"]
+}
+```
+
+Note that the newly added filtering parameters return events based on information in related events. Consider the
+following events in a room:
+
+* `A`: a `m.room.message` event sent by `alice`
+* `B`: a `m.room.message` event sent by `bob`
+* `C`: a `m.room.message` event sent by `charlie` which relates to `A` with type `m.thread`
+
+Using a filter of `"not_related_by_rel_types": ["m.thread"]` would return only event `B` as it has no event which
+relates to it via `m.thread`.
+
+### Server capabilities
+
+Threads might have sporadic support across servers, to simplify feature detections for clients, a homeserver must
+advertise unstable support for threads as part of the `/versions` API:
+
+```jsonc
+{
+  "unstable_features": {
+    "org.matrix.msc3874": true,
+    // ...
+  }
+}
+```
+
+## Potential issues
+
+This proposal moves the loading and processing of these hidden events onto the server. Depending on the server’s
+architecture, this may have a non-negligible performance impact. 
+
+## Limitations
+
+This proposal only considers events which have a direct relationship with the thread itself. Events such as reactions
+don’t, so they won’t be able to be filtered by this proposal.
+
+## Alternatives
+
+- A suitable workaround, depending on the ratio of thread-messages compared to main timeline messages in a room, may be 
+  an increase of the page size
+
+## Dependencies
+
+- [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674)
+- [MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675)
+- [MSC3567](https://github.com/matrix-org/matrix-doc/pull/3567)
+- [MSC3676](https://github.com/matrix-org/matrix-doc/pull/3676)
+- [MSC3440](https://github.com/matrix-org/matrix-doc/pull/344ß)
+
+<!-- inline links -->
+[Event filters]: https://spec.matrix.org/v1.2/client-server-api/#filtering