Merge pull request #1461 from turt2live/travis/s2s/transactions

Improve documentation on how Transactions work
pull/1472/head^2
Travis Ralston 6 years ago committed by GitHub
commit d48f1e1713
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -25,8 +25,10 @@ properties:
origin_server_ts: origin_server_ts:
type: integer type: integer
format: int64 format: int64
description: Timestamp in milliseconds on originating homeserver when this transaction started. description: |-
example: 1234567890 POSIX timestamp in milliseconds on originating homeserver when this
transaction started.
example: 1532991320875
pdus: pdus:
type: array type: array
description: List of persistent updates to rooms. description: List of persistent updates to rooms.

@ -30,16 +30,18 @@ paths:
Push messages representing live activity to another server. The destination name 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 will be set to that of the receiving server itself. Each embedded PDU in the
transaction body will be processed. 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 operationId: sendTransaction
parameters: parameters:
- in: path - in: path
name: txnId name: txnId
type: string type: string
# TODO: "Overrides any ID given in the JSON body" - What does this mean?
description: |- description: |-
The transaction ID. Overrides any ID given in the JSON body. The transaction ID.
required: true required: true
x-example: TODO # No examples in the spec so far x-example: S0meTransacti0nId
- in: body - in: body
name: body name: body
type: object type: object
@ -51,7 +53,9 @@ paths:
properties: properties:
edus: edus:
type: array 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: items:
$ref: "definitions/edu.yaml" $ref: "definitions/edu.yaml"
example: { example: {
@ -60,5 +64,47 @@ paths:
} }
responses: responses:
200: 200:
# TODO: Spec this (and figure out what it is) description: |-
description: TODO 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 PUT request. A Transaction is meaningful only to the pair of homeservers that
exchanged it; they are not globally-meaningful. exchanged it; they are not globally-meaningful.
Each transaction has: {{transactions_ss_http_api}}
- 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": [...]
}
PDUs PDUs
---- ----
@ -604,8 +570,6 @@ All these URLs are name-spaced within a prefix of::
/_matrix/federation/v1/... /_matrix/federation/v1/...
{{transactions_ss_http_api}}
{{events_ss_http_api}} {{events_ss_http_api}}
{{query_general_ss_http_api}} {{query_general_ss_http_api}}

Loading…
Cancel
Save