Improve documentation for backfilling rooms #1469
Conversation
There's not a whole lot to improve here - most of the changes are about reorganization and minor clarifications.
This also adds a previously-undocumented endpoint: /state_ids Backfill is technically not part of this section, however it is being left untouched to make the merge with matrix-org#1469 easier (which moves it out of the file). Reference material: * Some calls to synapse on these endpoints with a relatively simple private room.
api/server-server/backfill.yaml
Outdated
| earliest_events: | ||
| type: array | ||
| description: |- | ||
| The events the sender is missing. The response will only contain events |
There was a problem hiding this comment.
We have the events in earliest_events, no? (Otherwise how do we know about them?
There was a problem hiding this comment.
These are the prev_events to the latest_events that the sender is missing, so it only knows the event IDs.
There was a problem hiding this comment.
https://github.com/matrix-org/synapse/blob/master/synapse/handlers/federation.py#L344 suggests that they are latest events the sender already has?
There was a problem hiding this comment.
Looks like it, although I'm suitably confused as to how this endpoint works again. For the sake of understanding: earliest_events are the edges the server has and latest_events are the events the server wants? I'm not totally understanding what the receiver is supposed to do with this information.
There was a problem hiding this comment.
Its to get all the missing events between earliest_events (which the server has), and latest_events (which the server has just found out about, but doesn't have the prev events for).
The original text wasn't far off, except for being wrong about what the fields actually do. This commit also adds a bit of clarity for how the server is expected to behave.
Rendered: see 'docs' commit status
There's not a whole lot to improve here - most of the changes are about reorganization and minor clarifications.
Most of my time was spent verifying that the endpoint does what it says it does: namely that it looks up previous events for a given set.
Fixes #1385