From b819299b7efa14337f1379f2aef9830a3d7870da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 27 Feb 2024 20:07:40 +0100 Subject: [PATCH 1/8] Add server support discovery endpoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC1929. Signed-off-by: Kévin Commaille --- content/client-server-api/_index.md | 2 + data/api/client-server/support.yaml | 136 ++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 data/api/client-server/support.yaml diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0e7e8473a..57b9a04c3 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -363,6 +363,8 @@ specify parameter values. The flow for this method is as follows: {{% http-api spec="client-server" api="versions" %}} +{{% http-api spec="client-server" api="support" %}} + ## Client Authentication Most API endpoints require the user to identify themselves by presenting diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml new file mode 100644 index 000000000..95fa9be31 --- /dev/null +++ b/data/api/client-server/support.yaml @@ -0,0 +1,136 @@ +# 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. +openapi: 3.1.0 +info: + title: Matrix Client-Server Support Discovery API + version: 1.0.0 +paths: + /matrix/support: + get: + summary: Gets Matrix server admin contact and support page of the domain. + description: |- + Gets server admin contact and support page of the domain. + + Like the [well-known discovery URI](/client-server-api/#well-known-uri), + this should be accessed with the hostname of the homeserver, by making a + GET request to `https://hostname/.well-known/matrix/support`. + + Note that this endpoint is not necessarily handled by the homeserver, + but by another webserver, to be used for discovering support information + for the homeserver. + operationId: getWellknownSupport + x-addedInMatrixVersion: "1.10" + responses: + "200": + description: Server support information. + content: + application/json: + schema: + type: object + properties: + contacts: + type: array + description: |- + Ways to contact the server administrator. + + At least one of `contacts` or `support_page` is required. + If only this is set, it must contain at least one item. + items: + type: object + title: Contact + description: A way to contact the server administrator. + properties: + matrix_id: + type: string + description: |- + A Matrix User ID allowing to contact the + administrator. + + It could be an account registered on a different + homeserver so the administrator can be contacted + when the homeserver is down. + + At least one of `matrix_id` or `email_address` is + required. + email_address: + type: string + description: |- + An email address allowing to contact the + administrator. + + At least one of `matrix_id` or `email_address` is + required. + role: + type: string + enum: + - "m.role.admin" + - "m.role.security" + description: |- + An informal description of what the contact methods + are used for. + + `m.role.admin` is a catch-all user for any queries + and `m.role.security` is intended for sensitive + requests. + + Unspecified roles are permitted through the use of + [Namespaced Identifiers](/appendices/#common-namespaced-identifier-grammar). + required: + - role + example: { + "matrix_id": "@admin:example.org", + "email_address": "admin@example.org", + "role": "m.role.admin" + } + support_page: + type: string + description: |- + The URL of a page to give users help specific to the + homeserver, like extra login/registration steps. + + At least one of `contacts` or `support_page` is required. + example: "https://example.org/support.html" + examples: + response: + value: + { + "contacts": [ + { + "matrix_id": "@admin:example.org", + "email_address": "admin@example.org", + "role": "m.role.admin" + }, + { + "email_address": "security@example.org", + "role": "m.role.security" + } + ], + "support_page": "https://example.org/support.html" + } + "404": + description: No server support information available. + tags: + - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /.well-known From 4b8a285cffe1b2c990f9b3157028439f0b3708c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 27 Feb 2024 20:11:16 +0100 Subject: [PATCH 2/8] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1733.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1733.feature diff --git a/changelogs/client_server/newsfragments/1733.feature b/changelogs/client_server/newsfragments/1733.feature new file mode 100644 index 000000000..a2740ea75 --- /dev/null +++ b/changelogs/client_server/newsfragments/1733.feature @@ -0,0 +1 @@ +Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929). \ No newline at end of file From 6ca233c8fab304a74b03ce2e9fe4cec776e033c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 27 Feb 2024 20:14:50 +0100 Subject: [PATCH 3/8] Fix example indentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/support.yaml | 34 ++++++++++++++--------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index 95fa9be31..1d48d47d2 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -101,23 +101,23 @@ paths: At least one of `contacts` or `support_page` is required. example: "https://example.org/support.html" - examples: - response: - value: - { - "contacts": [ - { - "matrix_id": "@admin:example.org", - "email_address": "admin@example.org", - "role": "m.role.admin" - }, - { - "email_address": "security@example.org", - "role": "m.role.security" - } - ], - "support_page": "https://example.org/support.html" - } + examples: + response: + value: + { + "contacts": [ + { + "matrix_id": "@admin:example.org", + "email_address": "admin@example.org", + "role": "m.role.admin" + }, + { + "email_address": "security@example.org", + "role": "m.role.security" + } + ], + "support_page": "https://example.org/support.html" + } "404": description: No server support information available. tags: From a9ae4c2af8078ba544ef6ecb7346a516f2fc6970 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Mon, 4 Mar 2024 09:55:30 +0100 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Travis Ralston --- data/api/client-server/support.yaml | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index 1d48d47d2..1eef67ba1 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -18,16 +18,16 @@ info: paths: /matrix/support: get: - summary: Gets Matrix server admin contact and support page of the domain. + summary: Gets homeserver contacts and support details. description: |- Gets server admin contact and support page of the domain. Like the [well-known discovery URI](/client-server-api/#well-known-uri), - this should be accessed with the hostname of the homeserver, by making a + this should be accessed with the hostname of the homeserver by making a GET request to `https://hostname/.well-known/matrix/support`. - Note that this endpoint is not necessarily handled by the homeserver, - but by another webserver, to be used for discovering support information + Note that this endpoint is not necessarily handled by the homeserver. + It may be served by another webserver, used for discovering support information for the homeserver. operationId: getWellknownSupport x-addedInMatrixVersion: "1.10" @@ -45,7 +45,7 @@ paths: Ways to contact the server administrator. At least one of `contacts` or `support_page` is required. - If only this is set, it must contain at least one item. + If only `contacts` is set, it must contain at least one item. items: type: object title: Contact @@ -54,8 +54,7 @@ paths: matrix_id: type: string description: |- - A Matrix User ID allowing to contact the - administrator. + A Matrix User ID representing the administrator. It could be an account registered on a different homeserver so the administrator can be contacted @@ -66,8 +65,7 @@ paths: email_address: type: string description: |- - An email address allowing to contact the - administrator. + An email address to reach the administrator. At least one of `matrix_id` or `email_address` is required. @@ -80,7 +78,7 @@ paths: An informal description of what the contact methods are used for. - `m.role.admin` is a catch-all user for any queries + `m.role.admin` is a catch-all role for any queries and `m.role.security` is intended for sensitive requests. From a88d3a344308af6397c56498a1721624b5455dcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 4 Mar 2024 09:56:50 +0100 Subject: [PATCH 5/8] Fix line length MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/support.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index 1eef67ba1..8879500fc 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -27,8 +27,8 @@ paths: GET request to `https://hostname/.well-known/matrix/support`. Note that this endpoint is not necessarily handled by the homeserver. - It may be served by another webserver, used for discovering support information - for the homeserver. + It may be served by another webserver, used for discovering support + information for the homeserver. operationId: getWellknownSupport x-addedInMatrixVersion: "1.10" responses: @@ -45,7 +45,8 @@ paths: Ways to contact the server administrator. At least one of `contacts` or `support_page` is required. - If only `contacts` is set, it must contain at least one item. + If only `contacts` is set, it must contain at least one + item. items: type: object title: Contact From fc5b7f0c2abc442ed786e0b54442d08b16da94c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 4 Mar 2024 09:57:58 +0100 Subject: [PATCH 6/8] Add link to definiton of Matrix User ID MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/support.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index 8879500fc..fdc4a47b3 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -55,7 +55,8 @@ paths: matrix_id: type: string description: |- - A Matrix User ID representing the administrator. + A [Matrix User ID](/appendices/#user-identifiers) + representing the administrator. It could be an account registered on a different homeserver so the administrator can be contacted From ce44a395b983139c5700c52eb707bc42b1148394 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 4 Mar 2024 09:58:59 +0100 Subject: [PATCH 7/8] Fix copyright MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/support.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index fdc4a47b3..01ce001e2 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -1,4 +1,4 @@ -# Copyright 2018 New Vector Ltd +# Copyright 2024 Kévin Commaille # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. From 5571635d90ebb5dee12837df7cbcbdc24f24cbc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Mon, 4 Mar 2024 09:59:25 +0100 Subject: [PATCH 8/8] Remove HTTP from supported protocols MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/api/client-server/support.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml index 01ce001e2..1598d5d78 100644 --- a/data/api/client-server/support.yaml +++ b/data/api/client-server/support.yaml @@ -127,7 +127,6 @@ servers: variables: protocol: enum: - - http - https default: https hostname: