From 9b214ec16d1fe8db4f59100a35fcc9b5872da32c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 31 Jan 2019 23:46:22 -0700 Subject: [PATCH 1/9] Make the backfill response aware of event format changes --- api/server-server/backfill.yaml | 29 +++++-------------- .../definitions/transaction.yaml | 15 ++++++++-- api/server-server/examples/transaction.json | 6 ++-- 3 files changed, 24 insertions(+), 26 deletions(-) diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml index b196d17c..738e6efc 100644 --- a/api/server-server/backfill.yaml +++ b/api/server-server/backfill.yaml @@ -65,22 +65,6 @@ paths: event(s), up to the given limit. schema: $ref: "definitions/transaction.yaml" - # Override the example to show the response of the request a bit better - examples: - application/json: { - "$ref": "examples/transaction.json", - "pdus": [ - { - "$ref": "pdu.json", - "room_id": "!SomeRoom:matrix.org", - "event_id": "$abc123:matrix.org" - }, - { - "$ref": "pdu.json", - "room_id": "!SomeRoom:matrix.org" - }, - ] - } "/get_missing_events/{roomId}": post: summary: Retrieves events that the sender is missing @@ -114,14 +98,14 @@ paths: earliest_events: type: array description: |- - The latest events that the sender already has. These are skipped when retrieving + The latest event IDs that the sender already has. These are skipped when retrieving the previous events of ``latest_events``. items: type: string example: ["$missing_event:example.org"] latest_events: type: array - description: The events to retrieve the previous events for. + description: The event IDs to retrieve the previous events for. items: type: string example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"] @@ -136,13 +120,16 @@ paths: properties: events: type: array - description: The missing events. + description: |- + The missing events. The event format varies depending on the room version - check + the `room version specification`_ for precise event formats. items: - $ref: definitions/pdu.yaml + type: object + title: PDU required: ['events'] examples: application/json: { "events": [ - {"$ref": "examples/pdu.json"} + {"see_room_version_spec": "The event format changes depending on the room version."} ] } diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index 9833f785..7ec9386e 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -26,12 +26,21 @@ properties: type: integer format: int64 description: |- - POSIX timestamp in milliseconds on originating homeserver when this + POSIX timestamp in milliseconds on originating homeserver when this transaction started. example: 1532991320875 pdus: type: array - description: List of persistent updates to rooms. Must not include more than 50 PDUs. + description: |- + List of persistent updates to rooms. Must not include more than 50 PDUs. Note that + events have a different version depending on the room version - check the + `room version specification`_ for precise event formats. items: - $ref: "pdu.yaml" + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending + on the room version - check the `room version specification`_ for precise event formats. + properties: [] + example: {"see_room_version_spec": "The event format changes depending on the room version."} required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/api/server-server/examples/transaction.json b/api/server-server/examples/transaction.json index bd8ac3dc..6d77f79e 100644 --- a/api/server-server/examples/transaction.json +++ b/api/server-server/examples/transaction.json @@ -1,5 +1,7 @@ { "origin": "matrix.org", "origin_server_ts": 1234567890, - "pdus": [{"$ref": "pdu.json"}] -} \ No newline at end of file + "pdus": [{ + "see_room_version_spec": "The event format changes depending on the room version." + }] +} From d94a70f49de4770ec84a700058737384938d7ce4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 31 Jan 2019 23:54:14 -0700 Subject: [PATCH 2/9] Warn clients about changes in event format --- specification/client_server_api.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 40ac5588..8f4a9a1d 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1267,7 +1267,21 @@ point in time:: [E0]->[E1]->[E2]->[E3]->[E4]->[E5] +.. WARNING:: + The format of events can change depending on room version. Check the + `room version specification`_ for specific details on what to expect for + event formats. Examples contained within the client-server specification + are expected to be compatible with all specified room versions, however + some differences may still apply. + + For this version of the specification, clients only need to worry about + the event ID format being different depending on room version. Clients + should not be parsing the event ID, and instead be treating it as an + opaque string. No changes should be required to support the currently + available room versions. + +.. _`room version specification`: ../index.html#room-versions Types of room events ~~~~~~~~~~~~~~~~~~~~ From 33406e4662a101eaa23f9b74612f18856b902b25 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 10:08:30 -0700 Subject: [PATCH 3/9] Apply event format warnings to the remainder of the s2s spec --- api/server-server/backfill.yaml | 2 +- .../definitions/invite_event.yaml | 44 +-- .../definitions/transaction.yaml | 3 +- api/server-server/event_auth.yaml | 50 +++- api/server-server/events.yaml | 30 +- api/server-server/examples/minimal_pdu.json | 7 + api/server-server/examples/transaction.json | 2 +- api/server-server/invites-v1.yaml | 12 +- api/server-server/invites-v2.yaml | 12 +- api/server-server/joins.yaml | 266 ++++++++---------- api/server-server/leaving.yaml | 248 +++++++--------- api/server-server/transactions.yaml | 3 + 12 files changed, 316 insertions(+), 363 deletions(-) create mode 100644 api/server-server/examples/minimal_pdu.json diff --git a/api/server-server/backfill.yaml b/api/server-server/backfill.yaml index 738e6efc..0da0e234 100644 --- a/api/server-server/backfill.yaml +++ b/api/server-server/backfill.yaml @@ -130,6 +130,6 @@ paths: examples: application/json: { "events": [ - {"see_room_version_spec": "The event format changes depending on the room version."} + {"$ref": "examples/minimal_pdu.json"} ] } diff --git a/api/server-server/definitions/invite_event.yaml b/api/server-server/definitions/invite_event.yaml index d196339a..1f8b29d0 100644 --- a/api/server-server/definitions/invite_event.yaml +++ b/api/server-server/definitions/invite_event.yaml @@ -1,4 +1,4 @@ -# Copyright 2018 New Vector Ltd +# Copyright 2018-2019 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. @@ -13,15 +13,14 @@ # limitations under the License. type: object title: Invite Event -description: An invite event +description: |- + An invite event. Note that events have a different version depending on the + room version - check the `room version specification`_ for precise event formats. allOf: - - $ref: "pdu.yaml" - type: object properties: - # Note: we override a bunch of parameters to change their descriptions sender: type: string - # TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite description: |- The matrix ID of the user who sent the original ``m.room.third_party_invite``. example: "@someone:example.org" @@ -46,7 +45,7 @@ allOf: type: object title: Membership Event Content description: |- - The content of the event, matching what is available in the + The content of the event, matching what is available in the `Client-Server API`_. Must include a ``membership`` of ``invite``. example: {"membership": "invite"} properties: @@ -55,33 +54,10 @@ allOf: description: The value ``invite``. example: "invite" required: ['membership'] - auth_events: - type: array - description: |- - An event reference list containing the authorization events that would - allow the member to be invited to the room. - 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: Not used. required: - # Every other field is already flagged as required by the $ref - state_key + - sender + - origin + - origin_server_ts + - type + - content diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index 7ec9386e..a77f6f8a 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -42,5 +42,6 @@ properties: The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending on the room version - check the `room version specification`_ for precise event formats. properties: [] - example: {"see_room_version_spec": "The event format changes depending on the room version."} + example: + $ref: "../examples/minimal_pdu.json" required: ['origin', 'origin_server_ts', 'pdus'] diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml index 905b112f..262ea282 100644 --- a/api/server-server/event_auth.yaml +++ b/api/server-server/event_auth.yaml @@ -20,7 +20,7 @@ host: localhost:8448 schemes: - https basePath: /_matrix/federation/v1 -consumes: +consumes: - application/json produces: - application/json @@ -58,10 +58,19 @@ paths: type: array description: |- The full set of authorization events that make up the state of - the room, and their authorization events, recursively. + the room, and their authorization events, recursively. Note that + events have a different version depending on the room version - + check the `room version specification`_ for precise event formats. items: - $ref: "definitions/pdu.yaml" - example: [{"$ref": "examples/pdu.json"}] + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the auth chain. The event format + varies depending on the room version - check the `room version specification`_ + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" required: ['auth_chain'] "/query_auth/{roomId}/{eventId}": post: @@ -98,10 +107,20 @@ paths: properties: auth_chain: type: array - description: The auth chain (the "remote auth"). + description: |- + The auth chain (the "remote auth"). Note that events have a different + version depending on the room version - check the `room version specification`_ + for precise event formats. items: - $ref: "definitions/pdu.yaml" - example: [{"$ref": "examples/pdu.json"}] + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the auth chain. The event format + varies depending on the room version - check the `room version specification`_ + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" missing: type: array description: |- @@ -142,14 +161,23 @@ paths: type: array description: |- The auth chain the receiver has, and used to determine the auth - chain differences (the "local auth"). + chain differences (the "local auth"). Note that events have a different + version depending on the room version - check the `room version specification`_ + for precise event formats. items: - $ref: "definitions/pdu.yaml" - example: [{"$ref": "examples/pdu.json"}] + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the auth chain. The event format + varies depending on the room version - check the `room version specification`_ + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" missing: type: array description: |- - The list of event IDs that the receiver believes it is missing, + The list of event IDs that the receiver believes it is missing, after comparing the "remote auth" and "local auth" chains. items: type: string diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index d23456d1..e7cb52cd 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -59,17 +59,35 @@ paths: type: array description: |- The full set of authorization events that make up the state - of the room, and their authorization events, recursively. + of the room, and their authorization events, recursively. Note that + events have a different version depending on the room version - + check the `room version specification`_ for precise event formats. items: - $ref: "definitions/pdu.yaml" - example: [{"$ref": "examples/pdu.json"}] + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the auth chain. The event format + varies depending on the room version - check the `room version specification`_ + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" pdus: type: array description: |- - The fully resolved state of the room at the given event. + The fully resolved state of the room at the given event. Note that + events have a different version depending on the room version - + check the `room version specification`_ for precise event formats. items: - $ref: "definitions/pdu.yaml" - example: [{"$ref": "examples/pdu.json"}] + type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format + varies depending on the room version - check the `room version specification`_ + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" required: ['auth_chain', 'pdus'] "/state_ids/{roomId}": get: diff --git a/api/server-server/examples/minimal_pdu.json b/api/server-server/examples/minimal_pdu.json new file mode 100644 index 00000000..f8b8efc3 --- /dev/null +++ b/api/server-server/examples/minimal_pdu.json @@ -0,0 +1,7 @@ +{ + "type": "m.room.minimal_pdu", + "room_id": "!somewhere:example.org", + "content": { + "see_room_version_spec": "The event format changes depending on the room version." + } +} diff --git a/api/server-server/examples/transaction.json b/api/server-server/examples/transaction.json index 6d77f79e..bbc661d9 100644 --- a/api/server-server/examples/transaction.json +++ b/api/server-server/examples/transaction.json @@ -2,6 +2,6 @@ "origin": "matrix.org", "origin_server_ts": 1234567890, "pdus": [{ - "see_room_version_spec": "The event format changes depending on the room version." + "$ref": "minimal_pdu.json" }] } diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index 44db1f8d..8daaabab 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -38,6 +38,11 @@ paths: Servers should prefer to use the v2 API for invites instead of the v1 API. Servers which receive a v1 invite request must assume that the room version is either ``"1"`` or ``"2"``. + + Note that events have a different version depending on the room version - check the + `room version specification`_ for precise event formats. **The request and response + bodies here describe the common event fields in more detail and may be missing other + required fields for a PDU.** operationId: sendInviteV1 security: - signedRequest: [] @@ -107,7 +112,7 @@ paths: } ] example: { - "$ref": "examples/pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@joe:elsewhere.com", "unsigned": { @@ -143,7 +148,8 @@ paths: 200: description: |- The event with the invited server's signature added. All other fields of the events - should remain untouched. + should remain untouched. Note that events have a different version depending on the + room version - check the `room version specification`_ for precise event formats. schema: type: array minItems: 2 @@ -164,7 +170,7 @@ paths: 200, { "event": { - "$ref": "examples/pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "unsigned": { diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index f8695195..91e95d7f 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -42,6 +42,11 @@ paths: This endpoint is preferred over the v1 API as it is more useful for servers. Senders which receive a 400 or 404 response to this endpoint should retry using the v1 API as the server may be older, if the room version is "1" or "2". + + Note that events have a different version depending on the room version - check the + `room version specification`_ for precise event formats. **The request and response + bodies here describe the common event fields in more detail and may be missing other + required fields for a PDU.** operationId: sendInviteV2 security: - signedRequest: [] @@ -111,7 +116,7 @@ paths: example: { "room_version": "2", "event": { - "$ref": "examples/pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@joe:elsewhere.com", "content": { @@ -146,7 +151,8 @@ paths: 200: description: |- The event with the invited server's signature added. All other fields of the events - should remain untouched. + should remain untouched. Note that events have a different version depending on the + room version - check the `room version specification`_ for precise event formats. schema: type: object description: An object containing the signed invite event. @@ -158,7 +164,7 @@ paths: examples: application/json: { "event": { - "$ref": "examples/pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "unsigned": { diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 3c0ec48f..83f8d1c5 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -61,7 +61,11 @@ paths: responses: 200: description: |- - A template to be used for the rest of the `Joining Rooms`_ handshake. + A template to be used for the rest of the `Joining Rooms`_ handshake. Note that + events have a different version depending on the room version - check the + `room version specification`_ for precise event formats. **The response body + here describes the common event fields in more detail and may be missing other + required fields for a PDU.** schema: type: object properties: @@ -72,96 +76,61 @@ paths: the room version is assumed to be either "1" or "2". example: "2" event: - allOf: - - $ref: "definitions/unsigned_pdu.yaml" - - description: |- - An unsigned template event. + description: |- + An unsigned template event. Note that events have a different version + depending on the room version - check the `room version specification`_ + for precise event formats. + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value ``m.room.member``. + example: "m.room.member" + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "join"} properties: - # Note: we override a bunch of parameters to change their descriptions - sender: + membership: type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value ``m.room.member``. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} - properties: - membership: - type: string - description: The value ``join``. - example: "join" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - auth_events: - type: array - description: |- - An event reference list containing the authorization events that would - allow the member to join the room. This should normally be the - ``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules`` - events. - 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: Not used. - required: - # Every other field is already flagged as required by the $ref - - state_key + description: The value ``join``. + example: "join" + required: ['membership'] + required: + - state_key + - origin + - origin_server_ts + - type + - state_key + - content examples: application/json: { "room_version": "2", "event": { - "$ref": "examples/unsigned_pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "content": { "membership": "join" - }, - "auth_events": [ - ["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}], - ["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}], - ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}] - ] + } } } 400: @@ -193,7 +162,12 @@ paths: summary: Submit a signed join event to a resident server description: |- Submits a signed join event to the resident server for it - to accept it into the room's graph. + to accept it into the room's graph. Note that events have + a different version depending on the room version - check + the `room version specification`_ for precise event formats. + **The request and response body here describes the common + event fields in more detail and may be missing other required + fields for a PDU.** operationId: sendJoin security: - signedRequest: [] @@ -215,79 +189,50 @@ paths: type: object required: true schema: - allOf: - - $ref: "definitions/pdu.yaml" - - type: object + type: object + properties: + sender: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + origin: + type: string + description: The name of the joining homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the joining homeserver. + example: 1234567890 + type: + type: string + description: The value ``m.room.member``. + example: "m.room.member" + state_key: + type: string + description: The user ID of the joining member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "join"} properties: - # Note: we override a bunch of parameters to change their descriptions - sender: + membership: type: string - description: The user ID of the joining member. - example: "@someone:example.org" - origin: - type: string - description: The name of the joining homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the joining homeserver. - example: 1234567890 - type: - type: string - description: The value ``m.room.member``. - example: "m.room.member" - state_key: - type: string - description: The user ID of the joining member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "join"} - properties: - membership: - type: string - description: The value ``join``. - example: "join" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - auth_events: - type: array - description: |- - An event reference list containing the authorization events that would - allow the member to join the room. - 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: Not used. - required: - # Every other field is already flagged as required by the $ref - - state_key + description: The value ``join``. + example: "join" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - state_key + - content example: { - "$ref": "examples/pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "content": { @@ -315,11 +260,20 @@ paths: description: The resident server's DNS name. auth_chain: type: array - description: The auth chain. + description: |- + The auth chain. Note that events have a different version depending on + the room version - check the `room version specification`_ for precise + event formats. items: type: object - schema: - $ref: "definitions/pdu.yaml" + title: PDU + description: |- + The `PDUs <#pdus>`_ contained in the auth chain. The event format + varies depending on the room version - check the `room version specification`_ + for precise event formats. + properties: [] + example: + $ref: "examples/minimal_pdu.json" state: type: array description: The room state. @@ -333,7 +287,7 @@ paths: 200, { "origin": "matrix.org", - "auth_chain": [{"$ref": "examples/pdu.json"}], - "state": [{"$ref": "examples/pdu.json"}] + "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], + "state": [{"$ref": "examples/minimal_pdu.json"}] } ] diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 68ada9d7..1a112ad3 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -52,7 +52,11 @@ paths: responses: 200: description: |- - A template to be used to call ``/send_leave``. + A template to be used to call ``/send_leave``. Note that + events have a different version depending on the room version - check the + `room version specification`_ for precise event formats. **The response body + here describes the common event fields in more detail and may be missing other + required fields for a PDU.** schema: schema: type: object @@ -64,92 +68,62 @@ paths: the room version is assumed to be either "1" or "2". example: "2" event: - allOf: - - $ref: "definitions/unsigned_pdu.yaml" - - description: |- - An unsigned template event. + description: |- + An unsigned template event. Note that events have a different version + depending on the room version - check the `room version specification`_ + for precise event formats. + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the resident homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the resident homeserver. + example: 1234567890 + type: + type: string + description: The value ``m.room.member``. + example: "m.room.member" + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "leave"} properties: - # Note: we override a bunch of parameters to change their descriptions - sender: + membership: type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the resident homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the resident homeserver. - example: 1234567890 - type: - type: string - description: The value ``m.room.member``. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} - properties: - membership: - type: string - description: The value ``leave``. - example: "leave" - required: ['membership'] - auth_events: - type: array - description: |- - An event reference list containing the authorization events that would - allow the member to leave the room. This should normally be the - ``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules`` - events. - 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: Not used. - required: - # Every other field is already flagged as required by the $ref - - state_key + description: The value ``leave``. + example: "leave" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - state_key + - content examples: application/json: { "room_version": "2", "event": { - "$ref": "examples/unsigned_pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "content": { "membership": "leave" - }, - "auth_events": [ - ["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}], - ["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}], - ["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}] - ] + } } } 403: @@ -167,7 +141,12 @@ paths: summary: Submit a signed leave event to a resident server description: |- Submits a signed leave event to the resident server for it - to accept it into the room's graph. + to accept it into the room's graph. Note that events have + a different version depending on the room version - check + the `room version specification`_ for precise event formats. + **The request and response body here describes the common + event fields in more detail and may be missing other required + fields for a PDU.** operationId: sendLeave security: - signedRequest: [] @@ -189,79 +168,54 @@ paths: type: object required: true schema: - allOf: - - $ref: "definitions/pdu.yaml" - - type: object + type: object + properties: + sender: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + origin: + type: string + description: The name of the leaving homeserver. + example: "matrix.org" + origin_server_ts: + type: integer + format: int64 + description: A timestamp added by the leaving homeserver. + example: 1234567890 + type: + type: string + description: The value ``m.room.member``. + example: "m.room.member" + state_key: + type: string + description: The user ID of the leaving member. + example: "@someone:example.org" + content: + type: object + title: Membership Event Content + description: The content of the event. + example: {"membership": "leave"} properties: - # Note: we override a bunch of parameters to change their descriptions - sender: + membership: type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - origin: - type: string - description: The name of the leaving homeserver. - example: "matrix.org" - origin_server_ts: - type: integer - format: int64 - description: A timestamp added by the leaving homeserver. - example: 1234567890 - type: - type: string - description: The value ``m.room.member``. - example: "m.room.member" - state_key: - type: string - description: The user ID of the leaving member. - example: "@someone:example.org" - content: - type: object - title: Membership Event Content - description: The content of the event. - example: {"membership": "leave"} - properties: - membership: - type: string - description: The value ``leave``. - example: "leave" - required: ['membership'] - depth: - type: integer - description: This field must be present but is ignored; it may be 0. - example: 12 - auth_events: - type: array - description: |- - An event reference list containing the authorization events that would - allow the member to leave the room. - 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: Not used. - required: - # Every other field is already flagged as required by the $ref - - state_key + description: The value ``leave``. + example: "leave" + required: ['membership'] + depth: + type: integer + description: This field must be present but is ignored; it may be 0. + example: 12 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - state_key + - content example: { - "$ref": "examples/pdu.json", + "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", "content": { diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 355be2c6..38073e40 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -37,6 +37,9 @@ paths: The sending server must wait and retry for a 200 OK response before sending a transaction with a different ``txnId`` to the receiving server. + + Note that events have a different version depending on the room version - check + the `room version specification`_ for precise event formats. operationId: sendTransaction security: - signedRequest: [] From 5d8fa65e6e5c06573f744e8656a9a7db9ed600aa Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 10:11:39 -0700 Subject: [PATCH 4/9] De-duplicate state keys --- api/server-server/joins.yaml | 1 - api/server-server/leaving.yaml | 2 -- 2 files changed, 3 deletions(-) diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 83f8d1c5..c3539297 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -119,7 +119,6 @@ paths: - origin - origin_server_ts - type - - state_key - content examples: application/json: { diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 1a112ad3..556e0800 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -112,7 +112,6 @@ paths: - origin - origin_server_ts - type - - state_key - content examples: application/json: { @@ -212,7 +211,6 @@ paths: - origin - origin_server_ts - type - - state_key - content example: { "$ref": "examples/minimal_pdu.json", From 890fb1a01928dfa77a6ac86714c823e33460ae0a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 10:15:32 -0700 Subject: [PATCH 5/9] Fix examples for new schema Fix missed example in make_join Fix state array in response of send_join Try removing examples from send_join? Try printing more information about the error Copy/paste known working examples Try schema definitions in the response? --- api/check_examples.py | 6 ++++++ api/server-server/invites-v1.yaml | 6 ++++++ api/server-server/invites-v2.yaml | 6 ++++++ api/server-server/joins.yaml | 29 ++++++++++++++++++++++------- api/server-server/leaving.yaml | 6 ++++++ 5 files changed, 46 insertions(+), 7 deletions(-) diff --git a/api/check_examples.py b/api/check_examples.py index 0fb275b1..94f3495e 100755 --- a/api/check_examples.py +++ b/api/check_examples.py @@ -75,6 +75,12 @@ def check_response(filepath, request, code, response): filepath, request, code )) check_schema(filepath, example, schema) + except jsonschema.SchemaError as error: + for suberror in sorted(error.context, key=lambda e: e.schema_path): + print(list(suberror.schema_path), suberror.message, sep=", ") + raise ValueError("Error validating JSON schema for %r %r" % ( + request, code + ), e) except Exception as e: raise ValueError("Error validating JSON schema for %r %r" % ( request, code diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index 8daaabab..f397fc91 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -115,6 +115,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "unsigned": { "invite_room_state": [ { @@ -173,6 +176,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "unsigned": { "invite_room_state": [ { diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index 91e95d7f..d57a7ba2 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -119,6 +119,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "content": { "membership": "invite" }, @@ -167,6 +170,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "unsigned": { "invite_room_state": [ { diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index c3539297..fca273b5 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -127,6 +127,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "content": { "membership": "join" } @@ -228,12 +231,14 @@ paths: - origin - origin_server_ts - type - - state_key - content example: { "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "content": { "membership": "join" } @@ -267,19 +272,29 @@ paths: type: object title: PDU description: |- - The `PDUs <#pdus>`_ contained in the auth chain. The event format - varies depending on the room version - check the `room version specification`_ - for precise event formats. - properties: [] + The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending + on the room version - check the `room version specification`_ for precise event formats. + schema: + type: object + properties: [] example: $ref: "examples/minimal_pdu.json" state: type: array - description: The room state. + description: |- + The room state. The event format varies depending on the room version - + check the `room version specification`_ for precise event formats. items: type: object + title: PDU + description: |- + The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending + on the room version - check the `room version specification`_ for precise event formats. schema: - $ref: "definitions/pdu.yaml" + type: object + properties: [] + example: + $ref: "examples/minimal_pdu.json" required: ["auth_chain", "state", "origin"] examples: application/json: [ diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 556e0800..6c0d4959 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -120,6 +120,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "content": { "membership": "leave" } @@ -216,6 +219,9 @@ paths: "$ref": "examples/minimal_pdu.json", "type": "m.room.member", "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", "content": { "membership": "leave" } From 82bed06d3f433dc9655246931e2553efb546c5e9 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 13:19:24 -0700 Subject: [PATCH 6/9] The event *format* changes, not the version --- api/server-server/definitions/invite_event.yaml | 2 +- api/server-server/definitions/transaction.yaml | 2 +- api/server-server/event_auth.yaml | 6 +++--- api/server-server/events.yaml | 4 ++-- api/server-server/invites-v1.yaml | 4 ++-- api/server-server/invites-v2.yaml | 4 ++-- api/server-server/joins.yaml | 8 ++++---- api/server-server/leaving.yaml | 6 +++--- api/server-server/transactions.yaml | 2 +- 9 files changed, 19 insertions(+), 19 deletions(-) diff --git a/api/server-server/definitions/invite_event.yaml b/api/server-server/definitions/invite_event.yaml index 1f8b29d0..674ef2c9 100644 --- a/api/server-server/definitions/invite_event.yaml +++ b/api/server-server/definitions/invite_event.yaml @@ -14,7 +14,7 @@ type: object title: Invite Event description: |- - An invite event. Note that events have a different version depending on the + An invite event. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. allOf: - type: object diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index a77f6f8a..08f3738a 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -33,7 +33,7 @@ properties: type: array description: |- List of persistent updates to rooms. Must not include more than 50 PDUs. Note that - events have a different version depending on the room version - check the + events have a different format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object diff --git a/api/server-server/event_auth.yaml b/api/server-server/event_auth.yaml index 262ea282..0db0d401 100644 --- a/api/server-server/event_auth.yaml +++ b/api/server-server/event_auth.yaml @@ -59,7 +59,7 @@ paths: description: |- The full set of authorization events that make up the state of the room, and their authorization events, recursively. Note that - events have a different version depending on the room version - + events have a different format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object @@ -109,7 +109,7 @@ paths: type: array description: |- The auth chain (the "remote auth"). Note that events have a different - version depending on the room version - check the `room version specification`_ + format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object @@ -162,7 +162,7 @@ paths: description: |- The auth chain the receiver has, and used to determine the auth chain differences (the "local auth"). Note that events have a different - version depending on the room version - check the `room version specification`_ + format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index e7cb52cd..1f1a802d 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -60,7 +60,7 @@ paths: description: |- The full set of authorization events that make up the state of the room, and their authorization events, recursively. Note that - events have a different version depending on the room version - + events have a different format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object @@ -76,7 +76,7 @@ paths: type: array description: |- The fully resolved state of the room at the given event. Note that - events have a different version depending on the room version - + events have a different format depending on the room version - check the `room version specification`_ for precise event formats. items: type: object diff --git a/api/server-server/invites-v1.yaml b/api/server-server/invites-v1.yaml index f397fc91..2ad0f220 100644 --- a/api/server-server/invites-v1.yaml +++ b/api/server-server/invites-v1.yaml @@ -39,7 +39,7 @@ paths: which receive a v1 invite request must assume that the room version is either ``"1"`` or ``"2"``. - Note that events have a different version depending on the room version - check the + Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. **The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.** @@ -151,7 +151,7 @@ paths: 200: description: |- The event with the invited server's signature added. All other fields of the events - should remain untouched. Note that events have a different version depending on the + should remain untouched. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. schema: type: array diff --git a/api/server-server/invites-v2.yaml b/api/server-server/invites-v2.yaml index d57a7ba2..c459a848 100644 --- a/api/server-server/invites-v2.yaml +++ b/api/server-server/invites-v2.yaml @@ -43,7 +43,7 @@ paths: which receive a 400 or 404 response to this endpoint should retry using the v1 API as the server may be older, if the room version is "1" or "2". - Note that events have a different version depending on the room version - check the + Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. **The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.** @@ -154,7 +154,7 @@ paths: 200: description: |- The event with the invited server's signature added. All other fields of the events - should remain untouched. Note that events have a different version depending on the + should remain untouched. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. schema: type: object diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index fca273b5..ad033001 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -62,7 +62,7 @@ paths: 200: description: |- A template to be used for the rest of the `Joining Rooms`_ handshake. Note that - events have a different version depending on the room version - check the + events have a different format depending on the room version - check the `room version specification`_ for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** @@ -77,7 +77,7 @@ paths: example: "2" event: description: |- - An unsigned template event. Note that events have a different version + An unsigned template event. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. type: object @@ -165,7 +165,7 @@ paths: description: |- Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have - a different version depending on the room version - check + a different format depending on the room version - check the `room version specification`_ for precise event formats. **The request and response body here describes the common event fields in more detail and may be missing other required @@ -265,7 +265,7 @@ paths: auth_chain: type: array description: |- - The auth chain. Note that events have a different version depending on + The auth chain. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. items: diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 6c0d4959..95ee6880 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -53,7 +53,7 @@ paths: 200: description: |- A template to be used to call ``/send_leave``. Note that - events have a different version depending on the room version - check the + events have a different format depending on the room version - check the `room version specification`_ for precise event formats. **The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.** @@ -69,7 +69,7 @@ paths: example: "2" event: description: |- - An unsigned template event. Note that events have a different version + An unsigned template event. Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. type: object @@ -144,7 +144,7 @@ paths: description: |- Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have - a different version depending on the room version - check + a different format depending on the room version - check the `room version specification`_ for precise event formats. **The request and response body here describes the common event fields in more detail and may be missing other required diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 38073e40..9cc8be75 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -38,7 +38,7 @@ paths: The sending server must wait and retry for a 200 OK response before sending a transaction with a different ``txnId`` to the receiving server. - Note that events have a different version depending on the room version - check + Note that events have a different format depending on the room version - check the `room version specification`_ for precise event formats. operationId: sendTransaction security: From 985d02d95e9c265a446e41c2c5765349817538ba Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 13:35:38 -0700 Subject: [PATCH 7/9] Fix titles in schemas --- api/server-server/joins.yaml | 1 + api/server-server/leaving.yaml | 1 + api/server-server/third_party_invite.yaml | 1 + 3 files changed, 3 insertions(+) diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index ad033001..38586adb 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -81,6 +81,7 @@ paths: depending on the room version - check the `room version specification`_ for precise event formats. type: object + title: Event Template properties: sender: type: string diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 95ee6880..0713da6f 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -73,6 +73,7 @@ paths: depending on the room version - check the `room version specification`_ for precise event formats. type: object + title: Event Template properties: sender: type: string diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index 37c3a189..a401ae1b 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -85,6 +85,7 @@ paths: third_party_invite: type: object description: The third party invite + title: Third Party Invite properties: display_name: type: string From 1d0156ad787776966436c12785684c9211486e0a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 13:37:19 -0700 Subject: [PATCH 8/9] Fix more titles --- api/server-server/third_party_invite.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/server-server/third_party_invite.yaml b/api/server-server/third_party_invite.yaml index a401ae1b..0b7aac5b 100644 --- a/api/server-server/third_party_invite.yaml +++ b/api/server-server/third_party_invite.yaml @@ -98,6 +98,7 @@ paths: description: |- A block of content which has been signed, which servers can use to verify the event. + title: Invite Signatures properties: signatures: type: object From 222957157f5cadcaf095bc38f19dadd3e21d62ef Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 1 Feb 2019 13:56:30 -0700 Subject: [PATCH 9/9] Add missing required flags --- api/server-server/joins.yaml | 1 + api/server-server/leaving.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index 38586adb..1b5f4632 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -121,6 +121,7 @@ paths: - origin_server_ts - type - content + - sender examples: application/json: { "room_version": "2", diff --git a/api/server-server/leaving.yaml b/api/server-server/leaving.yaml index 0713da6f..c088cb5d 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving.yaml @@ -215,6 +215,7 @@ paths: - origin - origin_server_ts - type + - depth - content example: { "$ref": "examples/minimal_pdu.json",