diff --git a/api/server-server/definitions/edu.yaml b/api/server-server/definitions/edu.yaml new file mode 100644 index 00000000..4597ca62 --- /dev/null +++ b/api/server-server/definitions/edu.yaml @@ -0,0 +1,37 @@ +# 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: "!abc123:matrix.org" + origin: + type: string + description: The server name sending the ephemeral message + example: "matrix.org" + destination: + type: string + description: The server name receiving the ephemeral message + example: "elsewhere.com" + content: + type: object + description: The content of the ephemeral message diff --git a/api/server-server/definitions/full_transaction.yaml b/api/server-server/definitions/full_transaction.yaml new file mode 100644 index 00000000..39250433 --- /dev/null +++ b/api/server-server/definitions/full_transaction.yaml @@ -0,0 +1,28 @@ +# 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/full_transaction.json" +allOf: + - $ref: "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: "edu.yaml" +required: ['origin', 'origin_server_ts', 'pdus'] \ No newline at end of file diff --git a/api/server-server/definitions/pdu.yaml b/api/server-server/definitions/pdu.yaml new file mode 100644 index 00000000..b3f25ccf --- /dev/null +++ b/api/server-server/definitions/pdu.yaml @@ -0,0 +1,146 @@ +# 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" +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 + required: true + 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 + 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'] + 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: thishashcoversallfieldsincasethisisredacted + 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 + 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`` +required: + - room_id + - sender + - origin + - origin_server_ts + - type + - content + - prev_events + - depth + - auth_events + - hashes + - signatures diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml new file mode 100644 index 00000000..630d2ba3 --- /dev/null +++ b/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 hoemserver 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'] \ No newline at end of file diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml new file mode 100644 index 00000000..055883c2 --- /dev/null +++ b/api/server-server/events.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. + +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 on the given room. + Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it + are retrived, 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 # TODO: Verify + x-example: 10 + responses: + 200: + description: A transaction containing the PDUs that preceded the given event(s). + schema: + $ref: "definitions/transaction.yaml" + "/pull": + get: + summary: Stream events later than a given point in history + description: |- + Retrieves all of the transactions later than any version given by the ``v`` arguments. + operationId: pull + parameters: + - 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: origin + type: string + description: The origin # TODO: What is this actually? + required: true # TODO: Verify + x-example: "matrix.org" + responses: + 200: + # TODO: This could do with a better description + description: A transaction containing multiple PDUs + schema: + $ref: "definitions/transaction.yaml" \ No newline at end of file diff --git a/api/server-server/examples/edu.json b/api/server-server/examples/edu.json new file mode 100644 index 00000000..95a7b55d --- /dev/null +++ b/api/server-server/examples/edu.json @@ -0,0 +1,8 @@ +{ + "edu_type": "m.presence", + "origin": "blue", + "destination": "orange", + "content": { + "key": "value" + } +} \ No newline at end of file diff --git a/api/server-server/examples/full_transaction.json b/api/server-server/examples/full_transaction.json new file mode 100644 index 00000000..c453d6ed --- /dev/null +++ b/api/server-server/examples/full_transaction.json @@ -0,0 +1,6 @@ +{ + "origin": "matrix.org", + "origin_server_ts": 1234567890, + "pdus": [{"$ref": "pdu.json"}], + "edus": [{"$ref": "edu.json"}] +} \ No newline at end of file diff --git a/api/server-server/examples/pdu.json b/api/server-server/examples/pdu.json new file mode 100644 index 00000000..531f4a37 --- /dev/null +++ b/api/server-server/examples/pdu.json @@ -0,0 +1,25 @@ +{ + "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"} + ] + ], + "hashes": { + "sha256": "thishashcoversallfieldsincasethisisredacted" + }, + "signatures": { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + }, + "content": { + "key": "value" + } +} \ No newline at end of file diff --git a/api/server-server/examples/transaction.json b/api/server-server/examples/transaction.json new file mode 100644 index 00000000..bd8ac3dc --- /dev/null +++ b/api/server-server/examples/transaction.json @@ -0,0 +1,5 @@ +{ + "origin": "matrix.org", + "origin_server_ts": 1234567890, + "pdus": [{"$ref": "pdu.json"}] +} \ No newline at end of file diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml new file mode 100644 index 00000000..389eecc7 --- /dev/null +++ b/api/server-server/transactions.yaml @@ -0,0 +1,51 @@ +# 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 + schema: + $ref: "definitions/full_transaction.yaml" + responses: + 200: + # TODO: Spec this (and figure out what it is) + description: TODO diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index dac183d1..7819dbf9 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -292,10 +292,19 @@ def process_data_type(prop, required=False, enforce_title=True): is_object = True elif prop_type == "array": - nested = process_data_type(prop["items"]) - prop_title = "[%s]" % nested["title"] - tables = nested["tables"] - enum_desc = nested["enum_desc"] + items = prop["items"] + if isinstance(items, list): + prop_title = "[" + for i in items: + nested = process_data_type(i) + tables.extend(nested['tables']) + prop_title = "%s%s, " % (prop_title, nested['title']) + prop_title = prop_title[:-2] + "]" + else: + nested = process_data_type(prop["items"]) + prop_title = "[%s]" % nested["title"] + tables = nested["tables"] + enum_desc = nested["enum_desc"] else: prop_title = prop_type @@ -505,7 +514,13 @@ class MatrixUnits(Units): if val_type == "array": items = param.get("items") if items: - val_type = "[%s]" % items.get("type") + if isinstance(items, list): + val_type = "[" + for i in items: + val_type += "%s, " % items.get("type") + val_type = val_type[:-2] + "]" + else: + val_type = "[%s]" % items.get("type") if param.get("enum"): val_type = "enum" diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f2b3204a..7b66584d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -360,6 +360,10 @@ the destination. PDU Fields ~~~~~~~~~~ +.. TODO-spec + + Figure out how to embed swagger definitions in here (or improve the section) + ==================== ================== ======================================= Key Type Description ==================== ================== ======================================= @@ -749,57 +753,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// - 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// - 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// - 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// - 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" -arguments. +{{transactions_ss_http_api}} +{{events_ss_http_api}} To make a query::