Merge pull request #1406 from turt2live/travis/s2s/transactions-swagger

Convert things that mention "Transaction" to swagger

api/server-server/definitions/edu.yaml

@@ -0,0 +1,40 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# TODO: Address any concerns about this being inaccurate (flagged as such in the EDUs section)
+
+type: object
+title: Ephemeral Data Unit
+description: An ephemeral data unit
+example:
+  $ref: "../examples/edu.json"
+properties:
+  edu_type:
+    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.

api/server-server/definitions/pdu.yaml

@@ -0,0 +1,52 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: Persistent Data Unit
+description: A persistent data unit (event)
+example:
+  $ref: "../examples/pdu.json"
+allOf:
+  - $ref: "unsigned_pdu.yaml"
+  - type: object
+    properties:
+      hashes:
+        type: object
+        title: Event Hash
+        description: Hashes of the PDU, following the algorithm specified in `Signing Events`_.
+        example: {
+          "sha256": "thishashcoversallfieldsincasethisisredacted"
+        }
+        properties:
+          sha256:
+            type: string
+            description: The hash.
+            example: thishashcoversallfieldsincasthisisredacted
+        required: ['sha256']
+      signatures:
+        type: object
+        description: |-
+          Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_.
+        example: {
+          "example.com": {
+            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+          }
+        }
+        additionalProperties:
+          type: object
+          title: Server Signatures
+          additionalProperties:
+            type: string
+    required:
+      - hashes
+      - signatures

api/server-server/definitions/transaction.yaml

@@ -0,0 +1,35 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: Transaction
+description: Transaction
+example:
+  $ref: "../examples/transaction.json"
+properties:
+  origin:
+    type: string
+    description: |-
+      The ``server_name`` of the homeserver sending this transaction.
+    example: "example.org"
+  origin_server_ts:
+    type: integer
+    format: int64
+    description: Timestamp in milliseconds on originating homeserver when this transaction started.
+    example: 1234567890
+  pdus:
+    type: array
+    description: List of persistent updates to rooms.
+    items:
+      $ref: "pdu.yaml"
+required: ['origin', 'origin_server_ts', 'pdus']

api/server-server/definitions/unsigned_pdu.yaml

@@ -0,0 +1,118 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: Unsigned Persistent Data Unit
+description: An unsigned persistent data unit (event)
+example:
+  $ref: "../examples/unsigned_pdu.json"
+properties:
+  room_id:
+    type: string
+    description: Room identifier.
+    example: "!abc123:matrix.org"
+  sender:
+    type: string
+    description: The ID of the user sending the event.
+    example: "@someone:matrix.org"
+  origin:
+    type: string
+    description: The ``server_name`` of the homeserver that created this event.
+    example: "matrix.org"    
+  origin_server_ts:
+    type: integer
+    format: int64
+    description: Timestamp in milliseconds on origin homeserver when this event was created.
+    example: 1234567890
+  type:
+    type: string
+    description: Event type
+    example: "m.room.message"
+  state_key:
+    type: string
+    description: |-
+      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.
+    example: "my_key"
+  content:
+    type: object
+    description: The content of the event.
+    example: {"key": "value"}
+  prev_events:
+    type: array
+    description: |-
+      Event IDs and hashes of the most recent events in the room that the homeserver was aware
+      of when it made this event.
+    items:
+      type: array
+      maxItems: 2
+      minItems: 2
+      items:
+        - type: string
+          title: Event ID
+          example: "$abc123:matrix.org"
+        - type: object
+          title: Event Hash
+          example: {
+            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+          }
+          properties:
+            sha256:
+              type: string
+              description: The event hash.
+              example: abase64encodedsha256hashshouldbe43byteslong
+          required: ['sha256']
+  depth:
+    type: integer
+    description: The maximum depth of the ``prev_events``, plus one.
+    example: 12
+  auth_events:
+    type: array
+    description: Event IDs and hashes for the "auth events" of this event.
+    items:
+      type: array
+      maxItems: 2
+      minItems: 2
+      items:
+        - type: string
+          title: Event ID
+          example: "$abc123:matrix.org"
+        - type: object
+          title: Event Hash
+          example: {
+            "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+          }
+          properties:
+            sha256:
+              type: string
+              description: The event hash.
+              example: abase64encodedsha256hashshouldbe43byteslong
+          required: ['sha256']
+  redacts:
+    type: string
+    description: For redaction events, the ID of the event being redacted.
+    example: "$def456:matrix.org"
+  unsigned:
+    type: object
+    description: Additional data added by the origin server but not covered by the ``signatures``.
+    example: {"key": "value"}
+required:
+  - room_id
+  - sender
+  - origin
+  - origin_server_ts
+  - type
+  - content
+  - prev_events
+  - depth
+  - auth_events

api/server-server/events.yaml

@@ -0,0 +1,93 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Events API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/state/{roomId}":
+    get:
+      summary: Get all the state of a given room
+      description: |-
+        Retrieves a snapshot of the entire current state of the given room.
+      operationId: getRoomState
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to get state for.
+          required: true
+          x-example: "!abc123:matrix.org"
+      responses:
+        200:
+          description: The room state for the room (kept under ``pdus``).
+          schema:
+            $ref: "definitions/transaction.yaml"
+  "/event/{eventId}":
+    get:
+      summary: Get a single event
+      description: |-
+        Retrieves a single event.
+      operationId: getEvent
+      parameters:
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID to get.
+          required: true
+          x-example: "$abc123:matrix.org"
+      responses:
+        200:
+          description: A transaction containing a single PDU which is the event requested.
+          schema:
+            $ref: "definitions/transaction.yaml"
+  "/backfill/{roomId}":
+    get:
+      summary: Retrieves the events which precede the given event
+      description: |-
+        Retreives a sliding-window history of previous PDUs that occurred in the given room.
+        Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
+        are retrieved, up to the total number given by the ``limit``.
+      operationId: backfillRoom
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID to backfill.
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: query
+          name: v
+          type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it
+          description: The event ID to backfill from.
+          required: true
+          x-example: "$abc123:matrix.org"
+        - in: query
+          name: limit
+          type: integer
+          description: The maximum number of events to retrieve.
+          required: true
+          x-example: 10
+      responses:
+        200:
+          description: A transaction containing the PDUs that preceded the given event(s).
+          schema:
+            $ref: "definitions/transaction.yaml"

api/server-server/examples/edu.json

@@ -0,0 +1,8 @@
+{
+    "edu_type": "m.presence",
+    "origin": "blue",
+    "destination": "orange",
+    "content": {
+        "key": "value"
+    }
+}

api/server-server/examples/pdu.json

@@ -0,0 +1,11 @@
+{
+    "$ref": "unsigned_pdu.json",
+    "hashes": {
+        "sha256": "thishashcoversallfieldsincasethisisredacted"
+    },
+    "signatures": {
+        "example.com": {
+            "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+        }
+    }
+}

api/server-server/examples/transaction.json

@@ -0,0 +1,5 @@
+{
+    "origin": "matrix.org",
+    "origin_server_ts": 1234567890,
+    "pdus": [{"$ref": "pdu.json"}]
+}

api/server-server/examples/unsigned_pdu.json

@@ -0,0 +1,17 @@
+{
+    "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"}
+        ]
+    ],
+    "content": {
+        "key": "value"
+    }
+}

api/server-server/transactions.yaml

@@ -0,0 +1,64 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Transaction API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/send/{txnId}":
+    put:
+      summary: Send a transaction
+      description: |-
+        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.
+      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.
+          required: true
+          x-example: TODO # No examples in the spec so far
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            allOf:
+              - $ref: "definitions/transaction.yaml"
+              - type: object
+                properties:
+                  edus:
+                    type: array
+                    description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
+                    items:
+                      $ref: "definitions/edu.yaml"
+          example: {
+            "$ref": "examples/transaction.json",
+            "edus": [{"$ref": "edu.json"}] # Relative to the examples directory
+          }
+      responses:
+        200:
+          # TODO: Spec this (and figure out what it is)
+          description: TODO

scripts/templating/matrix_templates/units.py

@@ -139,6 +139,7 @@ def inherit_parents(obj):
     Recurse through the 'allOf' declarations in the object
     """
     logger.debug("inherit_parents %r" % obj)
+
     parents = obj.get("allOf", [])
     if not parents:
         return obj
@@ -293,6 +294,17 @@ def process_data_type(prop, required=False, enforce_title=True):
         is_object = True
 
     elif prop_type == "array":
+        items = prop["items"]
+        # Items can be a list of schemas or a schema itself
+        # http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4
+        if isinstance(items, list):
+            nested_titles = []
+            for i in items:
+                nested = process_data_type(i)
+                tables.extend(nested['tables'])
+                nested_titles.append(nested['title'])
+            prop_title = "[%s]" % (", ".join(nested_titles), )
+        else:
             nested = process_data_type(prop["items"])
             prop_title = "[%s]" % nested["title"]
             tables = nested["tables"]
@@ -371,6 +383,7 @@ def get_tables_for_response(schema):
 def get_example_for_schema(schema):
     """Returns a python object representing a suitable example for this object"""
     schema = inherit_parents(schema)
+
     if 'example' in schema:
         example = schema['example']
         return example
@@ -390,7 +403,10 @@ def get_example_for_schema(schema):
     if proptype == 'array':
         if 'items' not in schema:
             raise Exception('"array" property has neither items nor example')
-        return [get_example_for_schema(schema['items'])]
+        items = schema['items']
+        if isinstance(items, list):
+            return [get_example_for_schema(i) for i in items]
+        return [get_example_for_schema(items)]
 
     if proptype == 'integer':
         return 0
@@ -506,6 +522,10 @@ class MatrixUnits(Units):
                 if val_type == "array":
                     items = param.get("items")
                     if items:
+                        if isinstance(items, list):
+                            types = ", ".join(i.get("type") for i in items)
+                            val_type = "[%s]" % (types,)
+                        else:
                             val_type = "[%s]" % items.get("type")
 
                 if param.get("enum"):

specification/server_server_api.rst

@@ -288,6 +288,10 @@ the destination.
 PDU Fields
 ~~~~~~~~~~
 
+.. TODO-spec
+
+  Figure out how to embed swagger definitions in here (or improve the section)
+
 ==================== ================== =======================================
  Key                  Type               Description
 ==================== ================== =======================================
@@ -677,57 +681,10 @@ All these URLs are name-spaced within a prefix of::
 
   /_matrix/federation/v1/...
 
-For active pushing of messages representing live activity "as it happens"::
-
-  PUT .../send/<transaction_id>/
-    Body: JSON encoding of a single Transaction
-    Response: TODO-doc
-
-The transaction_id path argument will override any ID given in the JSON body.
-The destination name will be set to that of the receiving server itself. Each
-embedded PDU in the transaction body will be processed.
-
-
-To fetch all the state of a given room::
-
-  GET .../state/<room_id>/
-    Response: JSON encoding of a single Transaction containing multiple PDUs
-
-Retrieves a snapshot of the entire current state of the given room. The
-response will contain a single Transaction, inside which will be a list of PDUs
-that encode the state.
-
-
-To fetch a particular event::
-
-  GET .../event/<event_id>/
-    Response: JSON encoding of a partial Transaction containing the event
-
-Retrieves a single event. The response will contain a partial Transaction,
-having just the ``origin``, ``origin_server_ts`` and ``pdus`` fields; the
-event will be encoded as the only PDU in the ``pdus`` list.
-
-
-To backfill events on a given room::
-
-  GET .../backfill/<room_id>/
-    Query args: v, limit
-    Response: JSON encoding of a single Transaction containing multiple PDUs
-
-Retrieves a sliding-window history of previous PDUs that occurred on the given
-room. Starting from the PDU ID(s) given in the "v" argument, the PDUs that
-preceded it are retrieved, up to a total number given by the "limit" argument.
-
-
-To stream all the events::
-
-  GET .../pull/
-    Query args: origin, v
-    Response: JSON encoding of a single Transaction consisting of multiple PDUs
 
-Retrieves all of the transactions later than any version given by the "v"
+{{transactions_ss_http_api}}
-arguments.
 
+{{events_ss_http_api}}
 
 {{query_general_ss_http_api}}