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.

api/server-server/definitions/transaction.yaml

@@ -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']

api/server-server/transactions.yaml

@@ -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."
+                  }
+                }
+              }
+            ]

specification/server_server_api.rst

@@ -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}}