From 5027a9a59a4ca257f6b71f78f6f0fe3811940400 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 31 Jul 2018 13:58:23 -0600 Subject: [PATCH] Improve documentation around EDUs and PDUs Clarify fields, improve examples, and make the tables in the spec be generated rather than duplicated. --- api/server-server/definitions/edu.yaml | 6 +- .../definitions/unsigned_pdu.yaml | 33 +++++- api/server-server/examples/edu.json | 4 +- api/server-server/examples/unsigned_pdu.json | 3 + specification/server_server_api.rst | 101 +----------------- 5 files changed, 44 insertions(+), 103 deletions(-) diff --git a/api/server-server/definitions/edu.yaml b/api/server-server/definitions/edu.yaml index c89573feb..bc1f0cce0 100644 --- a/api/server-server/definitions/edu.yaml +++ b/api/server-server/definitions/edu.yaml @@ -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'] \ No newline at end of file diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml index 0aeede514..dad015376 100644 --- a/api/server-server/definitions/unsigned_pdu.yaml +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -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 diff --git a/api/server-server/examples/edu.json b/api/server-server/examples/edu.json index 95a7b55d9..9ff40dc38 100644 --- a/api/server-server/examples/edu.json +++ b/api/server-server/examples/edu.json @@ -1,7 +1,7 @@ { "edu_type": "m.presence", - "origin": "blue", - "destination": "orange", + "origin": "matrix.org", + "destination": "elsewhere.com", "content": { "key": "value" } diff --git a/api/server-server/examples/unsigned_pdu.json b/api/server-server/examples/unsigned_pdu.json index 0b585a639..f4d2e749f 100644 --- a/api/server-server/examples/unsigned_pdu.json +++ b/api/server-server/examples/unsigned_pdu.json @@ -20,5 +20,8 @@ ], "content": { "key": "value" + }, + "unsigned": { + "age": 4612 } } \ No newline at end of file diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f1825f270..3ac15fa70 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -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 ---------------------