matrix-org / matrix-org/matrix-spec

Include guidelines how to backfill with `/messages` and `/context`

Open
#1,281 0 comments 0 reactions 0 assignees View on GitHub
A-S2S clarification
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.