diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/python_architecture.rst | 2 | ||||
| -rw-r--r-- | docs/server-server/specification.rst | 4 | ||||
| -rw-r--r-- | docs/terminology.rst | 10 | ||||
| -rw-r--r-- | docs/versioning.rst | 8 |
4 files changed, 12 insertions, 12 deletions
diff --git a/docs/python_architecture.rst b/docs/python_architecture.rst index eca36a1902..8beaa615d0 100644 --- a/docs/python_architecture.rst +++ b/docs/python_architecture.rst @@ -24,7 +24,7 @@ Where the bottom (the transport layer) is what talks to the internet via HTTP, a * duplicate pdu_id's - i.e., it makes sure we ignore them. * responding to requests for a given pdu_id * responding to requests for all metadata for a given context (i.e. room) - * handling incoming pagination requests + * handling incoming backfill requests So it has to parse incoming messages to discover which are metadata and which aren't, and has to correctly clobber existing metadata where appropriate. diff --git a/docs/server-server/specification.rst b/docs/server-server/specification.rst index a386bd3e7d..f3c571aa86 100644 --- a/docs/server-server/specification.rst +++ b/docs/server-server/specification.rst @@ -155,9 +155,9 @@ To fetch all the state of a given context: PDUs that encode the state. -To paginate events on a given context: +To backfill events on a given context: - GET .../paginate/:context/ + GET .../backfill/:context/ Query args: v, limit Response: JSON encoding of a single Transaction containing multiple PDUs diff --git a/docs/terminology.rst b/docs/terminology.rst index 575cc0c808..cc6e6760ac 100644 --- a/docs/terminology.rst +++ b/docs/terminology.rst @@ -11,6 +11,11 @@ medium-term goal we should encourage the unification of this terminology. Terms ===== +Backfilling: + The process of synchronising historic state from one home server to another, + to backfill the event storage so that scrollback can be presented to the + client(s). (Formerly, and confusingly, called 'pagination') + Context: A single human-level entity of interest (currently, a chat room) @@ -28,11 +33,6 @@ Event: [[NOTE(paul): The current server-server implementation calls these simply "messages" but the term is too ambiguous here; I've called them Events]] -Pagination: - The process of synchronising historic state from one home server to another, - to backfill the event storage so that scrollback can be presented to the - client(s). - PDU (Persistent Data Unit): A message that relates to a single context, irrespective of the server that is communicating it. PDUs either encode a single Event, or a single State diff --git a/docs/versioning.rst b/docs/versioning.rst index 2f94bb6ef6..ffda60633f 100644 --- a/docs/versioning.rst +++ b/docs/versioning.rst @@ -1,11 +1,11 @@ -Versioning is, like, hard for paginating backwards because of the number of Home Servers involved. +Versioning is, like, hard for backfilling backwards because of the number of Home Servers involved. -The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For pagination purposes, this is done on a per context basis. +The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis. When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C. Problems with opaque version strings: - How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote home server at a time. - If you have multiple transactions sent at once, then you might drop one transaction, receive anotherwith a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION. - - How do you do pagination? A version string defines a point in a stream w.r.t. a single home server, not a point in the context. + If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION. + - How do you do backfilling? A version string defines a point in a stream w.r.t. a single home server, not a point in the context. We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges. |