diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 8ffe4e6a..fc065147 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -289,7 +289,7 @@ at ``/_matrix/key/v1``. "ed25519:auto": "Base+64+Encoded+Signature" } }, - "tls_certificate": "Base+64+Encoded+DER+Encoded+X509+TLS+Certificate" + "tls_certificate": "Base+64+Encoded+DER+Encoded+X509+TLS+Certificate", "verify_keys": { "ed25519:auto": "Base+64+Encoded+Signature+Verification+Key" } @@ -302,8 +302,6 @@ and should check that the JSON signatures are correct for the supplied Transactions ------------ -.. WARNING:: - This section may be misleading or inaccurate. The transfer of EDUs and PDUs between homeservers is performed by an exchange of Transaction messages, which are encoded as JSON objects, passed over an HTTP @@ -311,11 +309,10 @@ PUT request. A Transaction is meaningful only to the pair of homeservers that exchanged it; they are not globally-meaningful. Each transaction has: - - An opaque transaction ID. + - An opaque transaction ID, unique among transactions from the same origin. - A timestamp (UNIX epoch time in milliseconds) generated by its origin server. - An origin and destination server name. - - A list of "previous IDs". - A list of PDUs and EDUs - the actual message payload that the Transaction carries. @@ -325,134 +322,123 @@ Transaction Fields ==================== =================== ====================================== Key Type Description ==================== =================== ====================================== -``origin`` String DNS name of homeserver making this - transaction. -``origin_server_ts`` Integer Timestamp in milliseconds on +``origin`` String **Required**. ``server_name`` of homeserver sending + this transaction. +``origin_server_ts`` Integer **Required**. Timestamp in milliseconds on originating homeserver when this transaction started. -``previous_ids`` List of Strings List of transactions that were sent - immediately prior to this transaction. -``pdus`` List of Objects List of persistent updates to rooms. -``edus`` List of Objects List of ephemeral messages. +``pdus`` List of Objects **Required**. List of persistent updates to rooms. +``edus`` List of Objects List of ephemeral messages. May be omitted + if there are no ephemeral messages to + be sent. ==================== =================== ====================================== +Example: + .. code:: json { - "transaction_id":"916d630ea616342b42e98a3be0b74113", - "ts":1404835423000, - "origin":"red", - "prev_ids":["e1da392e61898be4d2009b9fecce5325"], + "origin_server_ts":1404835423000, + "origin":"matrix.org", "pdus":[...], "edus":[...] } -The ``prev_ids`` field contains a list of previous transaction IDs that the -``origin`` server has sent to this ``destination``. Its purpose is to act as a -sequence checking mechanism - the destination server can check whether it has -successfully received that Transaction, or ask for a re-transmission if not. - -The ``pdus`` field of a transaction is a list, containing zero or more PDUs.[*] -Each PDU is itself a JSON object containing a number of keys, the exact details -of 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 -transaction IDs they should be aware of. This effectively acts as a push -mechanism to encourage peers to continue to replicate content.) - PDUs ---- -All PDUs have: +Each PDU contains a single Room Event which the origin server wants to send to +the destination. -- An ID to identify the PDU itself -- A room ID that it relates to -- A declaration of their type -- A list of other PDU IDs that have been seen recently in that room (regardless - of which origin sent them) - -Required PDU Fields -~~~~~~~~~~~~~~~~~~~ +PDU Fields +~~~~~~~~~~ ==================== ================== ======================================= Key Type Description ==================== ================== ======================================= -``context`` String Room identifier -``user_id`` String The ID of the user sending the PDU -``origin`` String DNS name of homeserver that created - this PDU -``pdu_id`` String Unique identifier for PDU on the - originating homeserver -``origin_server_ts`` Integer Timestamp in milliseconds on origin - homeserver when this PDU was created. -``pdu_type`` String PDU event type -``content`` Object The content of the PDU. -``prev_pdus`` List of (String, The originating homeserver, PDU ids and - String, Object) hashes of the most recent PDUs the - Triplets homeserver was aware of for the room - when it made this PDU -``depth`` Integer The maximum depth of the previous PDUs - plus one -``is_state`` Boolean True if this PDU is updating room state +``room_id`` String **Required**. Room identifier. +``sender`` String **Required**. The ID of the user sending + the event. +``origin`` String **Required**. ``server_name`` of the + homeserver that created this event. +``event_id`` String **Required**. Unique identifier for the + event being sent. +``origin_server_ts`` Integer **Required**. Timestamp in milliseconds + on origin homeserver when this event + was created. +``type`` String **Required**. Event type +``state_key`` String Optional. If this key is present, the + event is a state event, and it will + replace previous events with the same + ``type`` and ``state_key`` in the room + state. +``content`` Object **Required**. The content of the event. +``prev_events`` List of (String, **Required**. Event IDs and hashes of + {String: String}) the most recent events in the room that + pairs the homeserver was aware of when it + made this event +``depth`` Integer **Required**. The maximum depth of the + ``prev_events``, plus one +``auth_events`` List of (String, **Required**. TODO-doc + {String: String}) + pairs +``hashes`` {String: String} **Required**. Hashes of the PDU, + following the algorithm specified in + `Signing Events`_. +``signatures`` {String: **Required**. Signatures of the redacted + {String: String}} PDU, following the algorithm specified + in `Signing Events`_. +``redacts`` String Optional. For redaction events, the ID + of the event being redacted +``unsigned`` Object Optional. Additional data added by the + origin server but not covered by the + ``signatures``. ==================== ================== ======================================= +Example: + .. code:: json { - "context":"#example:green.example.com", - "origin":"green.example.com", - "pdu_id":"a4ecee13e2accdadf56c1025af232176", - "origin_server_ts":1404838188000, - "pdu_type":"m.room.message", - "prev_pdus":[ - ["blue.example.com","99d16afbc8", - {"sha256":"abase64encodedsha256hashshouldbe43byteslong"}] + "room_id": "!UcYsUzyxTGDxLBEvLy:example.org", + "sender": "@alice:example.com", + "origin": "example.com", + "event_id": "$a4ecee13e2accdadf56c1025:example.com", + "origin_server_ts": 1404838188000, + "type": "m.room.message", + "prev_events": [ + ["$af232176:example.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}] ], - "hashes":{"sha256":"thishashcoversallfieldsincasethisisredacted"}, - "signatures":{ - "green.example.com":{ - "ed25519:key_version:":"these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + "hashes": {"sha256": "thishashcoversallfieldsincasethisisredacted"}, + "signatures": { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" } }, - "is_state":false, "content": {...} } -In contrast to Transactions, it is important to note that the ``prev_pdus`` -field of a PDU refers to PDUs that any origin server has sent, rather than -previous IDs that this ``origin`` has sent. This list may refer to other PDUs -sent by the same origin as the current one, or other origins. +The ``prev_events`` field of a PDU identifies the "parents" of the event, and +thus establishes a partial ordering on events within the room by linking them +into a Directed Acyclic Graph (DAG). The sending server should populate this +field with all of the events in the room for which it has not yet seen a +child - thus demonstrating that the event comes after all other known events. + +For example, consider a room whose events form the DAG shown below. A server +creating a new event in this room should populate the new event's +``prev_events`` field with ``E4`` and ``E5``, since neither event yet has a child:: + + E1 + ^ + | + +-> E2 <-+ + | | + E3 E5 + ^ + | + E4 -Because of the distributed nature of participants in a Matrix conversation, it -is impossible to establish a globally-consistent total ordering on the events. -However, by annotating each outbound PDU at its origin with IDs of other PDUs -it has received, a partial ordering can be constructed allowing causality -relationships to be preserved. A client can then display these messages to the -end-user in some order consistent with their content and ensure that no message -that is semantically in reply of an earlier one is ever displayed before it. - -State Update PDU Fields -~~~~~~~~~~~~~~~~~~~~~~~ - -PDUs fall into two main categories: those that deliver Events, and those that -synchronise State. For PDUs that relate to State synchronisation, additional -keys exist to support this: - -======================== ============ ========================================= - Key Type Description -======================== ============ ========================================= -``state_key`` String Combined with the ``pdu_type`` this - identifies the which part of the room - state is updated -``prev_state_id`` String The PDU id of the update this replaces. -``prev_state_origin`` String The homeserver of the update this - replaces. -``user_id`` String The user updating the state. -======================== ============ ========================================= Authorization of PDUs ~~~~~~~~~~~~~~~~~~~~~