Improve documentation around EDUs and PDUs

Clarify fields, improve examples, and make the tables in the spec be generated rather than duplicated.
pull/1463/head
Travis Ralston 6 years ago
parent ea307b5bdb
commit 5027a9a59a

@ -16,7 +16,7 @@
type: object type: object
title: Ephemeral Data Unit title: Ephemeral Data Unit
description: An ephemeral data unit description: An ephemeral data unit.
example: example:
$ref: "../examples/edu.json" $ref: "../examples/edu.json"
properties: properties:
@ -24,17 +24,15 @@ properties:
type: string type: string
description: The type of ephemeral message. description: The type of ephemeral message.
example: "m.presence" example: "m.presence"
required: true
origin: origin:
type: string type: string
description: The server name sending the ephemeral message. description: The server name sending the ephemeral message.
example: "matrix.org" example: "matrix.org"
required: true
destination: destination:
type: string type: string
description: The server name receiving the ephemeral message. description: The server name receiving the ephemeral message.
example: "elsewhere.com" example: "elsewhere.com"
required: true
content: content:
type: object type: object
description: The content of the ephemeral message. description: The content of the ephemeral message.
required: ['edu_type', 'origin', 'destination', 'content']

@ -108,8 +108,39 @@ properties:
example: "$def456:matrix.org" example: "$def456:matrix.org"
unsigned: unsigned:
type: object type: object
description: Additional data added by the origin server but not covered by the ``signatures``. title: Example Unsigned Data
description: |-
Additional data added by the origin server but not covered by the ``signatures``. More
keys than those defined here may be used.
example: {"key": "value"} example: {"key": "value"}
properties:
age:
type: integer
description: The number of milliseconds that have passed since this message was sent.
example: 4612
age_ts:
type: integer
format: int64
description: The POSIX timestamp this message was sent at in milliseconds.
replaces_state:
type: string
description: The event ID of the state event this event replaces.
example: "$state_event:domain.com"
prev_sender:
type: string
description: The sender of the replaced state event.
example: "@someone:domain.com"
prev_content:
type: string
description: The content of the replaced state event.
example: {
"membership": "join",
"displayname": "Bob"
}
redacted_because:
type: string
description: A reason for why the event was redacted.
example: "Inappropriate content"
required: required:
- event_id - event_id
- room_id - room_id

@ -1,7 +1,7 @@
{ {
"edu_type": "m.presence", "edu_type": "m.presence",
"origin": "blue", "origin": "matrix.org",
"destination": "orange", "destination": "elsewhere.com",
"content": { "content": {
"key": "value" "key": "value"
} }

@ -20,5 +20,8 @@
], ],
"content": { "content": {
"key": "value" "key": "value"
},
"unsigned": {
"age": 4612
} }
} }

@ -284,78 +284,6 @@ PDUs
Each PDU contains a single Room Event which the origin server wants to send to Each PDU contains a single Room Event which the origin server wants to send to
the destination. the destination.
PDU Fields
~~~~~~~~~~
.. TODO-spec
Figure out how to embed swagger definitions in here (or improve the section)
==================== ================== =======================================
Key Type Description
==================== ================== =======================================
``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 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 For redaction events, the ID of the
event being redacted.
``unsigned`` Object Additional data added by the origin
server but not covered by the
``signatures``.
==================== ================== =======================================
Example:
.. code:: json
{
"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": {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
},
"content": {...}
}
The ``prev_events`` field of a PDU identifies the "parents" of the event, and 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 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 into a Directed Acyclic Graph (DAG). The sending server should populate this
@ -386,6 +314,8 @@ following subset of the room state:
- The current ``m.room.join_rules`` event, if any. - The current ``m.room.join_rules`` event, if any.
- The sender's current ``m.room.member`` event, if any. - The sender's current ``m.room.member`` event, if any.
{{definition_ss_pdu}}
Authorization of PDUs Authorization of PDUs
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@ -555,32 +485,11 @@ The rules are as follows:
EDUs EDUs
---- ----
.. WARNING::
This section may be misleading or inaccurate.
EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of
"previous" IDs. The only mandatory fields for these are the type, origin and "previous" IDs. They are intended to be non-persistent data such as user
destination homeserver names, and the actual nested content. presence, typing notifications, etc.
======================== ============ ========================================= {{definition_ss_edu}}
Key Type Description
======================== ============ =========================================
``edu_type`` String The type of the ephemeral message.
``origin`` String The server name sending the ephemeral
message.
``destination`` String The server name receiving the ephemeral
message.
``content`` Object Content of the ephemeral message.
======================== ============ =========================================
.. code:: json
{
"edu_type": "m.presence",
"origin": "blue",
"destination": "orange",
"content": {...}
}
Room State Resolution Room State Resolution
--------------------- ---------------------

Loading…
Cancel
Save