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.
|
