From a2a1694c35e830cc7271cdd2e6cb242e62f037a4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 15 May 2020 14:10:06 -0600 Subject: [PATCH] Spec v2 send_join and send_leave endpoints MSC: https://github.com/matrix-org/matrix-doc/pull/1802 Fixes https://github.com/matrix-org/matrix-doc/issues/2541 This also adds the v2 invite endpoint to the ACL protected list as that appears to be an omission. --- .../{joins.yaml => joins-v1.yaml} | 7 +- api/server-server/joins-v2.yaml | 176 ++++++++++++++++++ .../{leaving.yaml => leaving-v1.yaml} | 7 +- api/server-server/leaving-v2.yaml | 140 ++++++++++++++ .../server_server/newsfragments/2547.new | 1 + specification/server_server_api.rst | 11 +- 6 files changed, 338 insertions(+), 4 deletions(-) rename api/server-server/{joins.yaml => joins-v1.yaml} (98%) create mode 100644 api/server-server/joins-v2.yaml rename api/server-server/{leaving.yaml => leaving-v1.yaml} (97%) create mode 100644 api/server-server/leaving-v2.yaml create mode 100644 changelogs/server_server/newsfragments/2547.new diff --git a/api/server-server/joins.yaml b/api/server-server/joins-v1.yaml similarity index 98% rename from api/server-server/joins.yaml rename to api/server-server/joins-v1.yaml index 1b5f4632..8defda20 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins-v1.yaml @@ -1,4 +1,5 @@ # Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -165,6 +166,10 @@ paths: put: summary: Submit a signed join event to a resident server description: |- + .. Note:: + Servers should instead prefer to use the v2 ``/send_join`` + endpoint. + 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 format depending on the room version - check @@ -172,7 +177,7 @@ paths: **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 + operationId: sendJoinV1 security: - signedRequest: [] parameters: diff --git a/api/server-server/joins-v2.yaml b/api/server-server/joins-v2.yaml new file mode 100644 index 00000000..585ab4b8 --- /dev/null +++ b/api/server-server/joins-v2.yaml @@ -0,0 +1,176 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# 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 Join Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + # Note: there is no v2 of make_join (yet) + "/send_join/{roomId}/{eventId}": + put: + summary: Submit a signed join event to a resident server + description: |- + .. Note:: + This API is nearly identical to the v1 API with the + exception of the response format being fixed. + + This endpoint is preferred over the v1 API as it provides + a more standarised response format. Senders which receive + a 400, 404, or other status code which indicates this endpoint + is not available should retry using the v1 API instead. + + 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 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 + fields for a PDU.** + operationId: sendJoinV2 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be joined. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the join event. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + 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: + membership: + type: string + description: The value ``join``. + example: "join" + required: ['membership'] + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - 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" + } + } + responses: + 200: + description: |- + The full state for the room, having accepted the join event. + schema: + type: object + title: Room State + description: The state for the room. + properties: + origin: + type: string + description: The resident server's DNS name. + auth_chain: + type: array + description: |- + 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: + type: object + title: PDU + description: |- + 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. 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: + type: object + properties: [] + example: + $ref: "examples/minimal_pdu.json" + required: ["auth_chain", "state", "origin"] + examples: + application/json: { + "origin": "matrix.org", + "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-v1.yaml similarity index 97% rename from api/server-server/leaving.yaml rename to api/server-server/leaving-v1.yaml index e0882fe8..cd07406e 100644 --- a/api/server-server/leaving.yaml +++ b/api/server-server/leaving-v1.yaml @@ -1,4 +1,5 @@ # Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -142,6 +143,10 @@ paths: put: summary: Submit a signed leave event to a resident server description: |- + .. Note:: + Servers should instead prefer to use the v2 ``/send_leave`` + endpoint. + 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 format depending on the room version - check @@ -149,7 +154,7 @@ paths: **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 + operationId: sendLeaveV1 security: - signedRequest: [] parameters: diff --git a/api/server-server/leaving-v2.yaml b/api/server-server/leaving-v2.yaml new file mode 100644 index 00000000..ed16773e --- /dev/null +++ b/api/server-server/leaving-v2.yaml @@ -0,0 +1,140 @@ +# Copyright 2018 New Vector Ltd +# Copyright 2020 The Matrix.org Foundation C.I.C. +# +# 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 Leave Room API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v2 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + # Note: there is no v2 of make_leave (yet) + "/send_leave/{roomId}/{eventId}": + put: + summary: Submit a signed leave event to a resident server + description: |- + .. Note:: + This API is nearly identical to the v1 API with the + exception of the response format being fixed. + + This endpoint is preferred over the v1 API as it provides + a more standarised response format. Senders which receive + a 400, 404, or other status code which indicates this endpoint + is not available should retry using the v1 API instead. + + 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 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 + fields for a PDU.** + operationId: sendLeaveV2 + security: + - signedRequest: [] + parameters: + - in: path + name: roomId + type: string + description: The room ID that is about to be left. + required: true + x-example: "!abc123:matrix.org" + - in: path + name: eventId + type: string + description: The event ID for the leave event. + required: true + x-example: "$abc123:example.org" + - in: body + name: body + type: object + required: true + schema: + 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: + 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 + required: + - state_key + - sender + - origin + - origin_server_ts + - type + - depth + - 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": "leave" + } + } + responses: + 200: + description: |- + An empty response to indicate the event was accepted into the graph by + the receiving homeserver. + schema: + type: object + title: Empty Object + description: An empty object. + examples: + application/json: {} diff --git a/changelogs/server_server/newsfragments/2547.new b/changelogs/server_server/newsfragments/2547.new new file mode 100644 index 00000000..c558fb5b --- /dev/null +++ b/changelogs/server_server/newsfragments/2547.new @@ -0,0 +1 @@ +Add new v2 ``/send_join`` and ``/send_leave`` endpoints per `MSC1802 `_. diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 655a8cfc..b0a2bc1a 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -780,7 +780,9 @@ and responds to the joining server with the full set of state for the newly-joined room. The resident server must also send the event to other servers participating in the room. -{{joins_ss_http_api}} +{{joins_v1_ss_http_api}} + +{{joins_v2_ss_http_api}} .. TODO-spec - (paul) I don't really understand why the full auth_chain events are given @@ -817,7 +819,9 @@ signs the event and replaces the ``event_id`` with it's own. This is then sent t the resident server via ``/send_leave``. The resident server will then send the event to other servers in the room. -{{leaving_ss_http_api}} +{{leaving_v1_ss_http_api}} + +{{leaving_v2_ss_http_api}} Third-party invites ------------------- @@ -1071,8 +1075,11 @@ The following endpoint prefixes MUST be protected: * ``/_matrix/federation/v1/make_join`` * ``/_matrix/federation/v1/make_leave`` * ``/_matrix/federation/v1/send_join`` +* ``/_matrix/federation/v2/send_join`` * ``/_matrix/federation/v1/send_leave`` +* ``/_matrix/federation/v2/send_leave`` * ``/_matrix/federation/v1/invite`` +* ``/_matrix/federation/v2/invite`` * ``/_matrix/federation/v1/state`` * ``/_matrix/federation/v1/state_ids`` * ``/_matrix/federation/v1/backfill``