matrix-org / matrix-org/matrix-spec
Include guidelines how to backfill with `/messages` and `/context`
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
**Link to problem area**:
https://spec.matrix.org/v1.1/server-server-api/#backfilling-and-retrieving-missing-events
**Issue**
As brought up in https://github.com/matrix-org/complement/pull/492#pullrequestreview-1135936213 and https://github.com/matrix-org/matrix-spec-proposals/pull/3030#discussion_r992983073, there is no right answer for when and how to backfill events.
The spec just says this:
> Since users in that room are able to request the history by the `/messages` client API endpoint, it’s possible that they might step backwards far enough into history before the homeserver itself was a member of that room.
>
> To cover this case, the federation API provides a server-to-server analog of the `/messages` client API, allowing one homeserver to fetch history from another. This is the `/backfill` API.
>
> *-- https://spec.matrix.org/v1.1/server-server-api/#backfilling-and-retrieving-missing-events*
But it should probably also mention that `/context` should backfill at the very least. And have some heuristics for when exactly to backfill. Is it acceptable to have gaps ([MSC3871](https://github.com/matrix-org/matrix-spec-proposals/pull/3871))? etc
Contributor guide
Research direction
Start with the server-server API section on backfilling and retrieving missing events, then compare the roles of `/messages`, `/context`, and `/backfill` with MSC3871. Done means the specification gives actionable guidance on when `/context` should backfill, when to use `/backfill`, and how to handle possible gaps.
Written by the indexing model from the issue text.
Assessment
- Domain
- distributed-systems, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100