Improve documentation on how Transactions work

The response is based upon various sections of the Synapse code in how it generates a response.

There are no new fields added to the transaction. Originally, `previous_ids` and `pdu_failures` were to be documented however neither of these are used in the real world.
pull/977/head
Travis Ralston 6 years ago
parent 1b374eafbc
commit 7679b4f1d1

@ -25,11 +25,13 @@ properties:
origin_server_ts:
type: integer
format: int64
description: Timestamp in milliseconds on originating homeserver when this transaction started.
example: 1234567890
description: |-
POSIX timestamp in milliseconds on originating homeserver when this
transaction started.
example: 1532991320875
pdus:
type: array
description: List of persistent updates to rooms.
items:
$ref: "pdu.yaml"
required: ['origin', 'origin_server_ts', 'pdus']
required: ['origin', 'origin_server_ts', 'pdus']

@ -30,16 +30,18 @@ paths:
Push messages representing live activity to another server. The destination name
will be set to that of the receiving server itself. Each embedded PDU in the
transaction body will be processed.
The sending server must wait and retry for a 200 OK response before sending a
transaction with a different ``txnId`` to the receiving server.
operationId: sendTransaction
parameters:
- in: path
name: txnId
type: string
# TODO: "Overrides any ID given in the JSON body" - What does this mean?
description: |-
The transaction ID. Overrides any ID given in the JSON body.
The transaction ID.
required: true
x-example: TODO # No examples in the spec so far
x-example: S0meTransacti0nId
- in: body
name: body
type: object
@ -51,7 +53,9 @@ paths:
properties:
edus:
type: array
description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
description: |-
List of ephemeral messages. May be omitted if there are no ephemeral
messages to be sent.
items:
$ref: "definitions/edu.yaml"
example: {
@ -60,5 +64,47 @@ paths:
}
responses:
200:
# TODO: Spec this (and figure out what it is)
description: TODO
description: |-
The result of processing the transaction. The server is to use this response even in
the event of one or more PDUs failing to be processed.
schema:
type: array
minItems: 2
maxItems: 2
items:
- type: integer
description: The value ``200``.
example: 200
- type: object
title: PDU Processing Results
description: The results for the processing of each PDU in the transaction.
properties:
pdus:
type: object
description: |-
The PDUs from the original transaction. The string key represents the ID of the
PDU (event) that was processed.
additionalProperties:
type: object
title: PDU Processing Result
description: Information about how the PDU was handled.
properties:
error:
type: string
description: |-
A human readable description about what went wrong in processing this PDU.
If no error is present, the PDU can be considered successfully handled.
example: "You are not allowed to send a message to this room."
required: ['pdus']
examples:
application/json: [
200,
{
"pdus": {
"$successful_event:domain.com": {},
"$failed_event:example.org": {
"error": "You are not allowed to send a message to this room."
}
}
}
]

@ -242,41 +242,7 @@ of Transaction messages, which are encoded as JSON objects, passed over an HTTP
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, 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 PDUs and EDUs - the actual message payload that the Transaction
carries.
Transaction Fields
~~~~~~~~~~~~~~~~~~
==================== =================== ======================================
Key Type Description
==================== =================== ======================================
``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.
``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
{
"origin_server_ts": 1404835423000,
"origin": "matrix.org",
"pdus": [...],
"edus": [...]
}
{{transactions_ss_http_api}}
PDUs
----
@ -682,8 +648,6 @@ All these URLs are name-spaced within a prefix of::
/_matrix/federation/v1/...
{{transactions_ss_http_api}}
{{events_ss_http_api}}
{{query_general_ss_http_api}}

Loading…
Cancel
Save