wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve formatting and update PDU and transaction key names

Browse source
This commit is contained in:
Mark Haines 2014-10-23 10:51:19 +01:00
parent ebd30834d0
commit 36fa322c5d
1 changed files with 97 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

252
specification/30_server_server_api.rst
View file

@ -15,19 +15,19 @@ currently under consideration.
There are three main kinds of communication that occur between home servers: There are three main kinds of communication that occur between home servers:
:Queries: Queries:
These are single request/response interactions between a given pair of These are single request/response interactions between a given pair of
servers, initiated by one side sending an HTTPS GET request to obtain some servers, initiated by one side sending an HTTPS GET request to obtain some
information, and responded by the other. They are not persisted and contain information, and responded by the other. They are not persisted and contain
no long-term significant history. They simply request a snapshot state at no long-term significant history. They simply request a snapshot state at
the instant the query is made. the instant the query is made.
:Ephemeral Data Units (EDUs): Ephemeral Data Units (EDUs):
These are notifications of events that are pushed from one home server to These are notifications of events that are pushed from one home server to
another. They are not persisted and contain no long-term significant another. They are not persisted and contain no long-term significant
history, nor does the receiving home server have to reply to them. history, nor does the receiving home server have to reply to them.
:Persisted Data Units (PDUs): Persisted Data Units (PDUs):
These are notifications of events that are broadcast from one home server to These are notifications of events that are broadcast from one home server to
any others that are interested in the same "context" (namely, a Room ID). any others that are interested in the same "context" (namely, a Room ID).
They are persisted to long-term storage and form the record of history for They are persisted to long-term storage and form the record of history for
@ -57,30 +57,22 @@ Each transaction has:
- 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.
``origin`` Transaction Fields
Type: ~~~~~~~~~~~~~~~~~~
String
Description:
DNS name of homeserver making this transaction.
``ts`` ==================== =================== ======================================
Type: Key Type Description
Integer ==================== =================== ======================================
Description: ``origin`` String DNS name of homeserver making this
Timestamp in milliseconds on originating homeserver when this transaction transaction.
started. ``origin_server_ts`` Integer Timestamp in milliseconds on
originating homeserver when this
``previous_ids`` transaction started.
Type: ``previous_ids`` List of Strings List of transactions that were sent
List of strings immediately prior to this transaction.
Description: ``pdus`` List of Objects List of persistent updates to rooms.
List of transactions that were sent immediately prior to this transaction. ``edus`` List of Objects List of ephemeral messages.
==================== =================== ======================================
``pdus``
Type:
List of Objects.
Description:
List of updates contained in this transaction.
:: ::
@ -88,7 +80,6 @@ Each transaction has:
"transaction_id":"916d630ea616342b42e98a3be0b74113", "transaction_id":"916d630ea616342b42e98a3be0b74113",
"ts":1404835423000, "ts":1404835423000,
"origin":"red", "origin":"red",
"destination":"blue",
"prev_ids":["e1da392e61898be4d2009b9fecce5325"], "prev_ids":["e1da392e61898be4d2009b9fecce5325"],
"pdus":[...], "pdus":[...],
"edus":[...] "edus":[...]
@ -97,7 +88,7 @@ Each transaction has:
The ``prev_ids`` field contains a list of previous transaction IDs that the 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 ``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 sequence checking mechanism - the destination server can check whether it has
successfully received that Transaction, or ask for a retransmission if not. 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.[*] 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 Each PDU is itself a JSON object containing a number of keys, the exact details
@ -108,141 +99,63 @@ are no EDUs to transfer.
(* Normally the PDU list will be non-empty, but the server should cope with (* Normally the PDU list will be non-empty, but the server should cope with
receiving an "empty" transaction.) receiving an "empty" transaction.)
PDUs and EDUs PDUs
------------- ----
Common PDU Fields
~~~~~~~~~~~~~~~~~
All PDUs have: All PDUs have:
- An ID
- A context
- A declaration of their type
- A list of other PDU IDs that have been seen recently on that context
(regardless of which origin sent them)
``context`` - An ID
+++++++++++ - A context
Type: - A declaration of their type
String - A list of other PDU IDs that have been seen recently on that context
Description: (regardless of which origin sent them)
Event context identifier
``origin`` Required PDU Fields
++++++++++ ~~~~~~~~~~~~~~~~~~~
Type:
String
Description:
DNS name of homeserver that created this PDU.
``pdu_id`` ==================== ================== =======================================
++++++++++ Key Type Description
Type: ==================== ================== =======================================
String ``context`` String Event context identifier
Description: ``user_id`` String The ID of the user sending the PDU
Unique identifier for PDU within the context for the originating homeserver ``origin`` String DNS name of homeserver that created
this PDU
``ts`` ``pdu_id`` String Unique identifier for PDU on the
++++++ originating homeserver
Type: ``origin_server_ts`` Integer Timestamp in milliseconds on origin
Integer homeserver when this PDU was created.
Description: ``pdu_type`` String PDU event type
Timestamp in milliseconds on originating homeserver when this PDU was ``content`` Object The content of the PDU.
created. ``prev_pdus`` List of (String, The originating homeserver, PDU ids and
String, Object) hashes of the most recent PDUs the
``pdu_type`` Triplets homeserver was aware of for the context
++++++++++++ when it made this PDU
Type: ``depth`` Integer The maximum depth of the previous PDUs
String plus one
Description: ``is_state`` Boolean True if this PDU is updating room state
PDU event type. ==================== ================== =======================================
``prev_pdus``
+++++++++++++
Type:
List of pairs of strings
Description:
The originating homeserver and PDU ids of the most recent PDUs the
homeserver was aware of for this context when it made this PDU.
``depth``
+++++++++
Type:
Integer
Description:
The maximum depth of the previous PDUs plus one.
.. TODO-spec paul
- Update this structure so that 'pdu_id' is a two-element [origin,ref] pair
like the prev_pdus are
State Update PDU Fields
~~~~~~~~~~~~~~~~~~~~~~~
For state updates:
``is_state``
++++++++++++
Type:
Boolean
Description:
True if this PDU is updating state.
``state_key``
+++++++++++++
Type:
String
Description:
Optional key identifying the updated state within the context.
``power_level``
+++++++++++++++
Type:
Integer
Description:
The asserted power level of the user performing the update.
``required_power_level``
++++++++++++++++++++++++
Type:
Integer
Description:
The required power level needed to replace this update.
``prev_state_id``
+++++++++++++++++
Type:
String
Description:
PDU event type.
``prev_state_origin``
+++++++++++++++++++++
Type:
String
Description:
The PDU id of the update this replaces.
``user_id``
+++++++++++
Type:
String
Description:
The user updating the state.
:: ::
{ {
"context":"#example:green.example.com",
"origin":"green.example.com",
"pdu_id":"a4ecee13e2accdadf56c1025af232176", "pdu_id":"a4ecee13e2accdadf56c1025af232176",
"context":"#example.green", "origin_server_ts":1404838188000,
"origin":"green", "pdu_type":"m.room.message",
"ts":1404838188000, "prev_pdus":[
"pdu_type":"m.text", ["blue.example.com","99d16afbc8",
"prev_pdus":[["blue","99d16afbc857975916f1d73e49e52b65"]], {"sha256":"abase64encodedsha256hashshouldbe43byteslong"}]
"content":... ],
"is_state":false "hashes":{"sha256":"thishashcoversallfieldsincasethisisredacted"},
"signatures":{
"green.example.com":{
"ed25519:key_version:":"these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
},
"is_state":false,
"content": {...}
} }
In contrast to Transactions, it is important to note that the ``prev_pdus`` In contrast to Transactions, it is important to note that the ``prev_pdus``
@ -258,23 +171,52 @@ 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 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. 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 PDUs fall into two main categories: those that deliver Events, and those that
synchronise State. For PDUs that relate to State synchronisation, additional synchronise State. For PDUs that relate to State synchronisation, additional
keys exist to support this: 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
``required_power_level`` Integer The required power level needed to
replace this update.
``prev_state_id`` String The homeserver of the update this
replaces
``prev_state_origin`` String The PDU id of the update this replaces.
``user_id`` String The user updating the state.
======================== ============ =========================================
:: ::
{..., {...,
"is_state":true, "is_state":true,
"state_key":TODO-doc "state_key":TODO-doc
"power_level":TODO-doc "required_power_level":TODO-doc
"prev_state_id":TODO-doc "prev_state_id":TODO-doc
"prev_state_origin":TODO-doc} "prev_state_origin":TODO-doc
}
EDUs
----
EDUs, by comparison to PDUs, do not have an ID, a context, or a list of EDUs, by comparison to PDUs, do not have an ID, a context, or a list of
"previous" IDs. The only mandatory fields for these are the type, origin and "previous" IDs. The only mandatory fields for these are the type, origin and
destination home server names, and the actual nested content. destination home server names, and the actual nested content.
======================== ============ =========================================
Key Type Description
======================== ============ =========================================
``edu_type`` String The type of the ephemeral message.
``content`` Object Content of the ephemeral message.
======================== ============ =========================================
:: ::
{"edu_type":"m.presence", {"edu_type":"m.presence",
@ -288,7 +230,7 @@ Protocol URLs
.. WARNING:: .. WARNING::
This section may be misleading or inaccurate. This section may be misleading or inaccurate.
All these URLs are namespaced within a prefix of:: All these URLs are name-spaced within a prefix of::
/_matrix/federation/v1/... /_matrix/federation/v1/...