wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Initial hack at some federation /backfill documentation

Browse source
This commit is contained in:
Paul "LeoNerd" Evans 2015-12-14 20:00:49 +00:00
parent 2e7b3052c2
commit b9bee6ee73
1 changed files with 35 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

40
specification/server_server_api.rst
View file

@ -512,7 +512,6 @@ To backfill events on a given room::
Retrieves a sliding-window history of previous PDUs that occurred on the given Retrieves a sliding-window history of previous PDUs that occurred on the given
room. Starting from the PDU ID(s) given in the "v" argument, the PDUs that room. Starting from the PDU ID(s) given in the "v" argument, the PDUs that
preceded it are retrieved, up to a total number given by the "limit" argument. preceded it are retrieved, up to a total number given by the "limit" argument.
These are then returned in a new Transaction containing all of the PDUs.
To stream events all the events:: To stream events all the events::
@ -690,11 +689,42 @@ following keys:
Backfilling Backfilling
----------- -----------
.. NOTE::
This section is a work in progress.
.. TODO-doc Once a homeserver has joined a room, it receives all the events emitted by
- What it is, when is it used, how is it done other homeservers in that room, and is thus aware of the entire history of the
room from that moment onwards. 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.
To request more history, the requesting homeserver picks another homeserver
that it thinks may have more (most likely this should be a homeserver for some
of the existing users in the room at the earliest point in history it has
currently), and makes a ``/backfill`` request. The parameters of this request
give an event ID that the requesting homeserver wishes to obtain, and a number
specifying how many more events of history before that one to return at most.
The response to this request is an object with the following keys:
==================== ======== ============
Key Type Description
==================== ======== ============
``pdus`` List A list of events
``origin`` String The name of the resident homeserver
``origin_server_ts`` Integer A timestamp added by the resident homeserver
==================== ======== ============
The list of events given in ``pdus`` is returned in reverse chronological
order; having the most recent event first (i.e. the event whose event ID is
that requested by the requestor in the ``v`` parameter).
.. TODO-spec
Specify (or remark that it is unspecified) how the server handles divergent
history. DFS? BFS? Anything weirder?
Authentication Authentication