diff options
| -rw-r--r-- | docs/server-server/specification.rst | 68 |
1 files changed, 59 insertions, 9 deletions
diff --git a/docs/server-server/specification.rst b/docs/server-server/specification.rst index f3c571aa86..5a1f28745c 100644 --- a/docs/server-server/specification.rst +++ b/docs/server-server/specification.rst @@ -29,15 +29,40 @@ can also be performed. | |<--------( HTTP )-----------| | +------------------+ +------------------+ +There are three main kinds of communication that occur between home servers: -Transactions and PDUs -===================== + * Queries + These are single request/response interactions between a given pair of + servers, initiated by one side sending an HTTP request to obtain some + information, and responded by the other. They are not persisted and contain + no long-term significant history. They simply request a snapshot state at the + instant the query is made. -The communication between home servers is performed by a bidirectional exchange -of messages. These messages are called Transactions, and are encoded as JSON -objects with a dict as the top-level element, passed over HTTP. A Transaction is -meaningful only to the pair of home servers that exchanged it; they are not -globally-meaningful. + * EDUs - Ephemeral Data Units + These are notifications of events that are pushed from one home server to + another. They are not persisted and contain no long-term significant history, + nor does the receiving home server have to reply to them. + + * PDUs - Persisted Data Units + These are notifications of events that are broadcast from one home server to + any others that are interested in the same "context" (namely, a Room ID). + They are persisted to long-term storage and form the record of history for + that context. + +Where Queries are presented directly across the HTTP connection as GET requests +to specific URLs, EDUs and PDUs are further wrapped in an envelope called a +Transaction, which is transferred from the origin to the destination home server +using a PUT request. + + +Transactions and EDUs/PDUs +========================== + +The transfer of EDUs and PDUs between home servers is performed by an exchange +of Transaction messages, which are encoded as JSON objects with a dict as the +top-level element, passed over an HTTP PUT request. A Transaction is meaningful +only to the pair of home servers that exchanged it; they are not globally- +meaningful. Each transaction has an opaque ID and timestamp (UNIX epoch time in miliseconds) generated by its origin server, an origin and destination server name, a list of @@ -49,7 +74,8 @@ Transaction carries. "origin":"red", "destination":"blue", "prev_ids":["e1da392e61898be4d2009b9fecce5325"], - "pdus":[...]} + "pdus":[...], + "edus":[...]} The "previous IDs" field will contain a list of previous transaction IDs that the origin server has sent to this destination. Its purpose is to act as a @@ -58,7 +84,9 @@ successfully received that Transaction, or ask for a retransmission if not. The "pdus" field of a transaction is a list, containing zero or more PDUs.[*] Each PDU is itself a dict containing a number of keys, the exact details of -which will vary depending on the type of PDU. +which will vary depending on the type of PDU. Similarly, the "edus" field is +another list containing the EDUs. This key may be entirely absent if there are +no EDUs to transfer. (* Normally the PDU list will be non-empty, but the server should cope with receiving an "empty" transaction, as this is useful for informing peers of other @@ -112,6 +140,15 @@ so on. This part needs refining. And writing in its own document as the details relate to the server/system as a whole, not specifically to server-server federation.]] +EDUs, by comparison to PDUs, do not have an ID, a context, or a list of +"previous" IDs. The only mandatory fields for these are the type, origin and +destination home server names, and the actual nested content. + + {"edu_type":"m.presence", + "origin":"blue", + "destination":"orange", + "content":...} + Protocol URLs ============= @@ -179,3 +216,16 @@ To stream events all the events: Retrieves all of the transactions later than any version given by the "v" arguments. [[TODO(paul): I'm not sure what the "origin" argument does because I think at some point in the code it's got swapped around.]] + + +To make a query: + + GET .../query/:query_type + Query args: as specified by the individual query types + + Response: JSON encoding of a response object + + Performs a single query request on the receiving home server. The Query Type + part of the path specifies the kind of query being made, and its query + arguments have a meaning specific to that kind of query. The response is a + JSON-encoded object whose meaning also depends on the kind of query. |