Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC3874: Filtering threads from the /messages endpoint #3874

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
75 changes: 75 additions & 0 deletions proposals/3874-messages-endpoint-threads-filter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# MSC3874 Loading Messages excluding Threads

## Motivation

In our beta deployment of threads, it's become a noticeable issue where a room may have activity in a long-running
justjanne marked this conversation as resolved.
Show resolved Hide resolved
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.
justjanne marked this conversation as resolved.
Show resolved Hide resolved

## Proposal

### Allow filtering the /messages API to not include threaded messages
justjanne marked this conversation as resolved.
Show resolved Hide resolved

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.
justjanne marked this conversation as resolved.
Show resolved Hide resolved

This means, if this filter is specified, only message which match none of the given relation types will be returned.

```
GET /_matrix/client/v3/rooms/!room_id:domain/messages?filter=...
justjanne marked this conversation as resolved.
Show resolved Hide resolved
```

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
justjanne marked this conversation as resolved.
Show resolved Hide resolved
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
justjanne marked this conversation as resolved.
Show resolved Hide resolved
relates to it via `m.thread`.

### Server capabilities
justjanne marked this conversation as resolved.
Show resolved Hide resolved

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
justjanne marked this conversation as resolved.
Show resolved Hide resolved

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.

## 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
justjanne marked this conversation as resolved.
Show resolved Hide resolved

## 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ß)
justjanne marked this conversation as resolved.
Show resolved Hide resolved
justjanne marked this conversation as resolved.
Show resolved Hide resolved

<!-- inline links -->
[Event filters]: https://spec.matrix.org/v1.2/client-server-api/#filtering