archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve Transaction and PDU documentation

Browse Source 
Fix a bunch of lies about the fields in these structures.
pull/1075/head
Richard van der Hoff 7 years ago
parent 9b0bdb799e
commit 632ba032af
1 changed files with 87 additions and 101 deletions
Show Stats Download Patch File Download Diff File

188
specification/server_server_api.rst
Unescape Escape View File

@ -289,7 +289,7 @@ at ``/_matrix/key/v1``.
"ed25519:auto": "Base+64+Encoded+Signature" "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": { "verify_keys": {
"ed25519:auto": "Base+64+Encoded+Signature+Verification+Key" "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 Transactions
------------ ------------
.. WARNING::
This section may be misleading or inaccurate.
The transfer of EDUs and PDUs between homeservers is performed by an exchange 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 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. exchanged it; they are not globally-meaningful.
Each transaction has: 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 - A timestamp (UNIX epoch time in milliseconds) generated by its origin
server. server.
- An origin and destination server name. - An origin and destination server name.
- A list of "previous IDs".
- A list of PDUs and EDUs - the actual message payload that the Transaction - A list of PDUs and EDUs - the actual message payload that the Transaction
carries. carries.
@ -325,134 +322,123 @@ Transaction Fields
==================== =================== ====================================== ==================== =================== ======================================
Key Type Description Key Type Description
==================== =================== ====================================== ==================== =================== ======================================
``origin`` String DNS name of homeserver making this ``origin`` String **Required**. ``server_name`` of homeserver sending
transaction. this transaction.
``origin_server_ts`` Integer Timestamp in milliseconds on ``origin_server_ts`` Integer **Required**. Timestamp in milliseconds on
originating homeserver when this originating homeserver when this
transaction started. transaction started.
``previous_ids`` List of Strings List of transactions that were sent ``pdus`` List of Objects **Required**. List of persistent updates to rooms.
immediately prior to this transaction. ``edus`` List of Objects List of ephemeral messages. May be omitted
``pdus`` List of Objects List of persistent updates to rooms. if there are no ephemeral messages to
``edus`` List of Objects List of ephemeral messages. be sent.
==================== =================== ====================================== ==================== =================== ======================================
Example:
.. code:: json .. code:: json
{ {
"transaction_id":"916d630ea616342b42e98a3be0b74113", "origin_server_ts":1404835423000,
"ts":1404835423000, "origin":"matrix.org",
"origin":"red",
"prev_ids":["e1da392e61898be4d2009b9fecce5325"],
"pdus":[...], "pdus":[...],
"edus":[...] "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 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)
PDU Fields
Required PDU Fields ~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~
==================== ================== ======================================= ==================== ================== =======================================
Key Type Description Key Type Description
==================== ================== ======================================= ==================== ================== =======================================
``context`` String Room identifier ``room_id`` String **Required**. Room identifier.
``user_id`` String The ID of the user sending the PDU ``sender`` String **Required**. The ID of the user sending
``origin`` String DNS name of homeserver that created the event.
this PDU ``origin`` String **Required**. ``server_name`` of the
``pdu_id`` String Unique identifier for PDU on the homeserver that created this event.
originating homeserver ``event_id`` String **Required**. Unique identifier for the
``origin_server_ts`` Integer Timestamp in milliseconds on origin event being sent.
homeserver when this PDU was created. ``origin_server_ts`` Integer **Required**. Timestamp in milliseconds
``pdu_type`` String PDU event type on origin homeserver when this event
``content`` Object The content of the PDU. was created.
``prev_pdus`` List of (String, The originating homeserver, PDU ids and ``type`` String **Required**. Event type
String, Object) hashes of the most recent PDUs the ``state_key`` String Optional. If this key is present, the
Triplets homeserver was aware of for the room event is a state event, and it will
when it made this PDU replace previous events with the same
``depth`` Integer The maximum depth of the previous PDUs ``type`` and ``state_key`` in the room
plus one state.
``is_state`` Boolean True if this PDU is updating 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 .. code:: json
{ {
"context":"#example:green.example.com", "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
"origin":"green.example.com", "sender": "@alice:example.com",
"pdu_id":"a4ecee13e2accdadf56c1025af232176", "origin": "example.com",
"origin_server_ts":1404838188000, "event_id": "$a4ecee13e2accdadf56c1025:example.com",
"pdu_type":"m.room.message", "origin_server_ts": 1404838188000,
"prev_pdus":[ "type": "m.room.message",
["blue.example.com","99d16afbc8", "prev_events": [
{"sha256":"abase64encodedsha256hashshouldbe43byteslong"}] ["$af232176:example.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
], ],
"hashes":{"sha256":"thishashcoversallfieldsincasethisisredacted"}, "hashes": {"sha256": "thishashcoversallfieldsincasethisisredacted"},
"signatures":{ "signatures": {
"green.example.com":{ "example.com": {
"ed25519:key_version:":"these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
} }
}, },
"is_state":false,
"content": {...} "content": {...}
} }
In contrast to Transactions, it is important to note that the ``prev_pdus`` The ``prev_events`` field of a PDU identifies the "parents" of the event, and
field of a PDU refers to PDUs that any origin server has sent, rather than thus establishes a partial ordering on events within the room by linking them
previous IDs that this ``origin`` has sent. This list may refer to other PDUs into a Directed Acyclic Graph (DAG). The sending server should populate this
sent by the same origin as the current one, or other origins. 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 Authorization of PDUs
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~

Write Preview
Loading…
Cancel
Save