|
|
|
@ -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
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|