Improve documentation around EDUs and PDUs

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

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

@ -108,8 +108,39 @@ properties:
example: "$def456:matrix.org"
unsigned:
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"}
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:
- event_id
- room_id

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

@ -20,5 +20,8 @@
],
"content": {
"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
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
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
@ -386,6 +314,8 @@ following subset of the room state:
- The current ``m.room.join_rules`` event, if any.
- The sender's current ``m.room.member`` event, if any.
{{definition_ss_pdu}}
Authorization of PDUs
~~~~~~~~~~~~~~~~~~~~~
@ -555,32 +485,11 @@ The rules are as follows:
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
"previous" IDs. The only mandatory fields for these are the type, origin and
destination homeserver names, and the actual nested content.
======================== ============ =========================================
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
"previous" IDs. They are intended to be non-persistent data such as user
presence, typing notifications, etc.
{
"edu_type": "m.presence",
"origin": "blue",
"destination": "orange",
"content": {...}
}
{{definition_ss_edu}}
Room State Resolution
---------------------

Loading…
Cancel
Save