diff --git a/api/server-server/definitions/full_transaction.yaml b/api/server-server/definitions/full_transaction.yaml deleted file mode 100644 index 39250433..00000000 --- a/api/server-server/definitions/full_transaction.yaml +++ /dev/null @@ -1,28 +0,0 @@ -# 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 index b3f25ccf..2b6328be 100644 --- a/api/server-server/definitions/pdu.yaml +++ b/api/server-server/definitions/pdu.yaml @@ -16,131 +16,37 @@ 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" - } +allOf: + - $ref: "unsigned_pdu.yaml" + - type: object 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 + 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 + required: + - hashes + - signatures diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml new file mode 100644 index 00000000..173bddd4 --- /dev/null +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -0,0 +1,119 @@ +# 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 + 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 + 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 diff --git a/api/server-server/examples/full_transaction.json b/api/server-server/examples/full_transaction.json deleted file mode 100644 index c453d6ed..00000000 --- a/api/server-server/examples/full_transaction.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "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 index 531f4a37..81981b23 100644 --- a/api/server-server/examples/pdu.json +++ b/api/server-server/examples/pdu.json @@ -1,16 +1,5 @@ { - "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"} - ] - ], + "$ref": "unsigned_pdu.json", "hashes": { "sha256": "thishashcoversallfieldsincasethisisredacted" }, @@ -18,8 +7,5 @@ "example.com": { "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" } - }, - "content": { - "key": "value" } } \ No newline at end of file diff --git a/api/server-server/examples/unsigned_pdu.json b/api/server-server/examples/unsigned_pdu.json new file mode 100644 index 00000000..6ed4b79d --- /dev/null +++ b/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" + } +} \ No newline at end of file diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 389eecc7..13ba6826 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -43,8 +43,21 @@ paths: - in: body name: body type: object + required: true schema: - $ref: "definitions/full_transaction.yaml" + 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) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 7819dbf9..8037bb61 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -138,6 +138,10 @@ def inherit_parents(obj): Recurse through the 'allOf' declarations in the object """ logger.debug("inherit_parents %r" % obj) + + if isinstance(obj, list): + return [inherit_parents(obj[i]) for i in range(0, len(obj))] + parents = obj.get("allOf", []) if not parents: return obj @@ -379,6 +383,10 @@ 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 isinstance(schema, list): + return [get_example_for_schema(v) for v in schema] + if 'example' in schema: example = schema['example'] return example @@ -398,7 +406,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'])] + result = get_example_for_schema(schema['items']) + if isinstance(result, list): + return result + return [result] if proptype == 'integer': return 0