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

Merge pull request #1469 from turt2live/travis/s2s/backfill

Browse source 
Improve documentation for backfilling rooms
This commit is contained in:
Travis Ralston 2018-08-09 08:00:43 -06:00 • committed by GitHub
commit 56dbeeb22a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 153 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

142
api/server-server/backfill.yaml Normal file
View file

@ -0,0 +1,142 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Federation Events API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
paths:
"/backfill/{roomId}":
get:
summary: Retrieves the events which precede the given event
description: |-
Retrieves a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
are retrieved, up to the total number given by the ``limit``.
operationId: backfillRoom
parameters:
- in: path
name: roomId
type: string
description: The room ID to backfill.
required: true
x-example: "!SomeRoom:matrix.org"
- in: query
name: v
type: array
items:
type: string
description: The event IDs to backfill from.
required: true
x-example: ["$abc123:matrix.org"]
- in: query
name: limit
type: integer
description: The maximum number of PDUs to retrieve, including the given events.
required: true
x-example: 2
responses:
200:
description: |-
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
schema:
$ref: "definitions/transaction.yaml"
# Override the example to show the response of the request a bit better
examples:
application/json: {
"$ref": "examples/transaction.json",
"pdus": [
{
"$ref": "pdu.json",
"room_id": "!SomeRoom:matrix.org",
"event_id": "$abc123:matrix.org"
},
{
"$ref": "pdu.json",
"room_id": "!SomeRoom:matrix.org"
},
]
}
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing
description: |-
Retrieves previous events that the sender is missing. This is done by doing a breadth-first
walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events``
and stopping at the ``limit``.
operationId: getMissingPreviousEvents
parameters:
- in: path
name: roomId
type: string
description: The room ID to search in.
required: true
x-example: "!SomeRoom:matrix.org"
- in: body
name: body
schema:
type: object
properties:
limit:
type: integer
description: The maximum number of events to retrieve. Defaults to 10.
example: 10
min_depth:
type: integer
description: The minimum depth of events to retrieve. Defaults to 0.
example: 0
earliest_events:
type: array
description: |-
The latest events that the sender already has. These are skipped when retrieving
the previous events of ``latest_events``.
items:
type: string
example: ["$missing_event:domain.com"]
latest_events:
type: array
description: The events to retrieve the previous events for.
items:
type: string
example: ["$event_that_has_the_missing_event_as_a_previous_event:domain.com"]
required: ['earliest_events', 'latest_events']
responses:
200:
description: |-
The previous events for ``latest_events``, excluding any ``earliest_events``, up to the
provided ``limit``.
schema:
type: object
properties:
events:
type: array
description: The missing events.
items:
$ref: definitions/pdu.yaml
required: ['events']
examples:
application/json: {
"events": [
{"$ref": "examples/pdu.json"}
]
}

32
api/server-server/events.yaml
View file

@ -129,35 +129,3 @@ paths:
description: A transaction containing a single PDU which is the event requested.
schema:
$ref: "definitions/transaction.yaml"
"/backfill/{roomId}":
get:
summary: Retrieves the events which precede the given event
description: |-
Retreives a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
are retrieved, up to the total number given by the ``limit``.
operationId: backfillRoom
parameters:
- in: path
name: roomId
type: string
description: The room ID to backfill.
required: true
x-example: "!abc123:matrix.org"
- in: query
name: v
type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it
description: The event ID to backfill from.
required: true
x-example: "$abc123:matrix.org"
- in: query
name: limit
type: integer
description: The maximum number of events to retrieve.
required: true
x-example: 10
responses:
200:
description: A transaction containing the PDUs that preceded the given event(s).
schema:
$ref: "definitions/transaction.yaml"

33
specification/server_server_api.rst
View file

@ -580,8 +580,8 @@ participating in the room.
here. What purpose does it serve expanding them out in full, when surely
they'll appear in the state anyway?
Backfilling
-----------
Backfilling and retrieving missing events
-----------------------------------------
Once a homeserver has joined a room, it receives all the events emitted by
other homeservers in that room, and is thus aware of the entire history of the
@ -594,32 +594,21 @@ 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.
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 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 requester in the ``v`` parameter).
Similar to backfilling a room's history, a server may not have all the events
in the graph. That server may use the ``/get_missing_events`` API to acquire
the events it is missing.
.. TODO-spec
Specify (or remark that it is unspecified) how the server handles divergent
history. DFS? BFS? Anything weirder?
{{backfill_ss_http_api}}
Retrieving events
----------------