Improve Transaction and PDU documentation
Fix a bunch of lies about the fields in these structures.
This commit is contained in:
Richard van der Hoff
parent
9b0bdb799e
commit
632ba032af
1 changed files with 85 additions and 99 deletions
|
|
@ -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:
|
||||
|
||||
- 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)
|
||||
Each PDU contains a single Room Event which the origin server wants to send to
|
||||
the destination.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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::
|
||||
|
||||
State Update PDU Fields
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
E1
|
||||
^
|
||||
|
|
||||
+-> E2 <-+
|
||||
| |
|
||||
E3 E5
|
||||
^
|
||||
|
|
||||
E4
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue