Merge pull request #1461 from turt2live/travis/s2s/transactions
Improve documentation on how Transactions work
This commit is contained in:
Travis Ralston
GitHub
commit
d48f1e1713
3 changed files with 58 additions and 46 deletions
|
|
@ -25,8 +25,10 @@ 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.
|
||||
|
|
|
|||
|
|
@ -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."
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
|
|
|
|||
|
|
@ -164,41 +164,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
|
||||
----
|
||||
|
|
@ -604,8 +570,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…
Add table
Add a link
Reference in a new issue