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

Merge pull request #1075 from matrix-org/rav/pdu_fields

Browse Source 
Improve documentation of Transactions and PDUs
pull/977/head
Richard van der Hoff 7 years ago committed by GitHub
parent fb9f7ccf41 6a653b742c
commit 58a3fa3d60
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 96 additions and 102 deletions
Show Stats Download Patch File Download Diff File

198
specification/server_server_api.rst
Unescape Escape View File

@ -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,131 @@ 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**. Event IDs and hashes for
{String: String}) the "auth events" of this event.
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.
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.
======================== ============ =========================================
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
The ``auth_events`` field of a PDU identifies the set of events which give the
sender permission to send the event. The ``auth_events`` for the
``m.room.create`` event in a room is empty; for other events, it should be the
following subset of the room state:
- The ``m.room.create`` event.
- The current ``m.room.power_levels`` event, if any.
- The sender's current ``m.room.member`` event, if any.
Authorization of PDUs
~~~~~~~~~~~~~~~~~~~~~

Write Preview
Loading…
Cancel
Save