From 2783820f98b02f01dd2d55aca1e05fc3e78a617d Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 3 May 2018 12:23:24 +0100 Subject: [PATCH 01/39] Initial draft of GET media/limits --- api/client-server/content-repo.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 03a25fd9..6e3ba273 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -269,3 +269,30 @@ paths: "$ref": "definitions/error.yaml" tags: - Media + "/limits": + get: + summary: Get limits on what can be uploaded to the content repository. + Clients SHOULD use this as a guide when uploading content. + All values are intentionally left optional, the client MUST assume + that any field not given is not limited. + + **NOTE:** Reverse proxies may apply their own limits. + operationId: getLimits + produces: ["application/json"] + security: + - accessToken: [] + responses: + 200: + description: The limits exposed by the matrix server. + schema: + type: object + properties: + size: + type: number + description: "The maximum size a upload can be in bytes." + examples: + application/json: { + "size": 50000000 + } + tags: + - Media From c9abf36097f1f4a3a2086c6629e9ab8112c035d2 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 3 May 2018 16:58:22 +0100 Subject: [PATCH 02/39] size > upload_size --- api/client-server/content-repo.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 6e3ba273..cfcb00dd 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -287,12 +287,12 @@ paths: schema: type: object properties: - size: + upload_size: type: number description: "The maximum size a upload can be in bytes." examples: application/json: { - "size": 50000000 + "upload_size": 50000000 } tags: - Media From de6fe1b76e325380eef7110364c0e11ac2d014d2 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 3 May 2018 18:00:50 +0100 Subject: [PATCH 03/39] Add note about auth --- api/client-server/content-repo.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index cfcb00dd..97a7d8f9 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -277,6 +277,9 @@ paths: that any field not given is not limited. **NOTE:** Reverse proxies may apply their own limits. + + If auth is not supplied, this endpoint gives the global limit of the server. + Otherwise it should give the limits applied to the authenticated user. operationId: getLimits produces: ["application/json"] security: From ffc8ee298adfc90a2b21801636927cbcff78b969 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 8 May 2018 11:50:34 +0100 Subject: [PATCH 04/39] a upload > an upload --- api/client-server/content-repo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 97a7d8f9..cf7b5f25 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -292,7 +292,7 @@ paths: properties: upload_size: type: number - description: "The maximum size a upload can be in bytes." + description: "The maximum size an upload can be in bytes." examples: application/json: { "upload_size": 50000000 From 42fba1a87ec5886a2cba9ee60359347ca2647234 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 3 Jun 2018 12:08:19 +0900 Subject: [PATCH 05/39] Add 'default' to formally enforce the description A quick follow up on #1265. Signed-off-by: Alexey Rusakov --- api/client-server/content-repo.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index f76b2fb9..943fee3c 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -100,6 +100,7 @@ paths: name: allow_remote x-example: false required: false + default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to @@ -154,6 +155,7 @@ paths: name: allow_remote x-example: false required: false + default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to @@ -221,6 +223,7 @@ paths: name: allow_remote x-example: false required: false + default: true description: | Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to From 077cd04a6d42b852f0dd8e29ad26ffda843e48ef Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 20 Jun 2018 16:01:06 +0100 Subject: [PATCH 06/39] /limits => /config --- api/client-server/content-repo.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index cf7b5f25..3c200344 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -269,9 +269,9 @@ paths: "$ref": "definitions/error.yaml" tags: - Media - "/limits": + "/config": get: - summary: Get limits on what can be uploaded to the content repository. + summary: Get the config for the media repository. Clients SHOULD use this as a guide when uploading content. All values are intentionally left optional, the client MUST assume that any field not given is not limited. From 6b9640bcb499e95cb87ca6784b2b68e5bdf73d7a Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 20 Jun 2018 17:06:17 +0100 Subject: [PATCH 07/39] upload_size => m.upload.size --- api/client-server/content-repo.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 3c200344..b86b6596 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -290,12 +290,12 @@ paths: schema: type: object properties: - upload_size: + m.upload.size: type: number description: "The maximum size an upload can be in bytes." examples: application/json: { - "upload_size": 50000000 + "m.upload.size": 50000000 } tags: - Media From 6d0a56d190cddab7b0e710f6e1c43b04392088e0 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 22 Jun 2018 09:38:53 +0100 Subject: [PATCH 08/39] Suggestions by Travis tend to be sensible ones --- api/client-server/content-repo.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index b86b6596..4a61ccec 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -286,7 +286,7 @@ paths: - accessToken: [] responses: 200: - description: The limits exposed by the matrix server. + description: The public content repository configuration for the matrix server. schema: type: object properties: @@ -295,7 +295,7 @@ paths: description: "The maximum size an upload can be in bytes." examples: application/json: { - "m.upload.size": 50000000 - } + "m.upload.size": 50000000 + } tags: - Media From 20200264e1ba2a31aa45b5ed67f38f1403577546 Mon Sep 17 00:00:00 2001 From: Remi Rampin Date: Sat, 23 Jun 2018 11:11:38 -0400 Subject: [PATCH 09/39] Consolidate backwards-compatible client changes --- changelogs/client_server.rst | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index feabecab..f375fc97 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -15,6 +15,22 @@ Unreleased changes - Sticker messages: - Add sticker message event definition. (`#1158 `_). + - Add 'token' parameter to /keys/query endpoint + (`#1104 `_). + - Add the room visibility options for the room directory + (`#1141 `_). + - Add spec for ignoring users + (`#1142 `_). + - Add the ``/register/available`` endpoint for username availability + (`#1151 `_). + - Add ``allow_remote`` to the content repo to avoid routing loops + (`#1265 `_). + - Add report content API + (`#1264 `_). + - Document ``/logout/all`` endpoint + (`#1263 `_). + - Document `highlights` field in /search response + (`#1274 `_). - Spec clarifications: @@ -40,25 +56,6 @@ Unreleased changes - Describe ``StateEvent`` for ``/createRoom`` (`#1329 `_). -- Changes to the API which will be backwards-compatible for clients: - - - Add 'token' parameter to /keys/query endpoint - (`#1104 `_). - - Add the room visibility options for the room directory - (`#1141 `_). - - Add spec for ignoring users - (`#1142 `_). - - Add the ``/register/available`` endpoint for username availability - (`#1151 `_). - - Add ``allow_remote`` to the content repo to avoid routing loops - (`#1265 `_). - - Add report content API - (`#1264 `_). - - Document ``/logout/all`` endpoint - (`#1263 `_). - - Document `highlights` field in /search response - (`#1274 `_). - r0.3.0 ====== From ddc152347bfa6c472ffc30d508b0a2fdbd3e8cb6 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 27 Jun 2018 20:14:29 +0100 Subject: [PATCH 10/39] Extending words and rate limiting --- api/client-server/content-repo.yaml | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 4a61ccec..57585ce8 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -271,16 +271,17 @@ paths: - Media "/config": get: - summary: Get the config for the media repository. + summary: Get the configuration for the media repository. Clients SHOULD use this as a guide when uploading content. All values are intentionally left optional, the client MUST assume that any field not given is not limited. - **NOTE:** Reverse proxies may apply their own limits. + **NOTE:** Reverse proxies may apply their own configuration. + - If auth is not supplied, this endpoint gives the global limit of the server. - Otherwise it should give the limits applied to the authenticated user. - operationId: getLimits + If an accessToken is supplied, the configuration applied to the authenticated user. + Otherwise it should give the configuration applied globally to the server. + operationId: getConfig produces: ["application/json"] security: - accessToken: [] @@ -297,5 +298,10 @@ paths: application/json: { "m.upload.size": 50000000 } + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + tags: - Media From 80935eadcf87f6dd8e1a3669e5519844e77e34fb Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 28 Jun 2018 00:14:42 +0100 Subject: [PATCH 11/39] Update content-repo.yaml --- api/client-server/content-repo.yaml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 57585ce8..c8096138 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -273,13 +273,13 @@ paths: get: summary: Get the configuration for the media repository. Clients SHOULD use this as a guide when uploading content. - All values are intentionally left optional, the client MUST assume - that any field not given is not limited. + All values are intentionally left optional. Clients SHOULD follow + the advise given in the field description when the field is not avaliable. **NOTE:** Reverse proxies may apply their own configuration. - If an accessToken is supplied, the configuration applied to the authenticated user. + If an accessToken is supplied, the configuration applied to the authenticated user is returned. Otherwise it should give the configuration applied globally to the server. operationId: getConfig produces: ["application/json"] @@ -293,7 +293,9 @@ paths: properties: m.upload.size: type: number - description: "The maximum size an upload can be in bytes." + description: |- + The maximum size an upload can be in bytes. If not listed or null, + the upload limit should be treated as unknown. examples: application/json: { "m.upload.size": 50000000 From eeaf4385d73f221e896917432ec6ed336bbabeaf Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 28 Jun 2018 09:04:01 +0100 Subject: [PATCH 12/39] Speling is my weakniss --- api/client-server/content-repo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index c8096138..be003a2b 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -274,7 +274,7 @@ paths: summary: Get the configuration for the media repository. Clients SHOULD use this as a guide when uploading content. All values are intentionally left optional. Clients SHOULD follow - the advise given in the field description when the field is not avaliable. + the advice given in the field description when the field is not available. **NOTE:** Reverse proxies may apply their own configuration. From 091b2a677190c1a120dd31c2ef4e4c0bec6469e6 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 28 Jun 2018 16:42:36 +0100 Subject: [PATCH 13/39] Hard limit on requiring accessToken. Rephrased some sections --- api/client-server/content-repo.yaml | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index be003a2b..b48068f2 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -272,15 +272,13 @@ paths: "/config": get: summary: Get the configuration for the media repository. - Clients SHOULD use this as a guide when uploading content. + Clients SHOULD use this as a guide when using media endpoints. All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available. - **NOTE:** Reverse proxies may apply their own configuration. - - - If an accessToken is supplied, the configuration applied to the authenticated user is returned. - Otherwise it should give the configuration applied globally to the server. + **NOTE:** The /config endpoint is a guide. Other middleware such as + reverse proxies may apply their own configuration not described on this + endpoint. operationId: getConfig produces: ["application/json"] security: @@ -294,8 +292,9 @@ paths: m.upload.size: type: number description: |- - The maximum size an upload can be in bytes. If not listed or null, - the upload limit should be treated as unknown. + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. examples: application/json: { "m.upload.size": 50000000 From 1820df02d9faebf042bb3cf81e24d2036e844f74 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 28 Jun 2018 17:07:44 +0100 Subject: [PATCH 14/39] media => content repository --- api/client-server/content-repo.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index b48068f2..582d0695 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -271,8 +271,8 @@ paths: - Media "/config": get: - summary: Get the configuration for the media repository. - Clients SHOULD use this as a guide when using media endpoints. + summary: Get the configuration for the content repository. + Clients SHOULD use this as a guide when using content endpoints. All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available. From 21e957edfba242107eb871a960fc1af334b8ce49 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 28 Jun 2018 17:23:57 +0100 Subject: [PATCH 15/39] Better note for /config --- api/client-server/content-repo.yaml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 582d0695..8ccc7684 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -276,9 +276,11 @@ paths: All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available. - **NOTE:** The /config endpoint is a guide. Other middleware such as - reverse proxies may apply their own configuration not described on this - endpoint. + **NOTE:** Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. Clients should handle such + situations gracefully. operationId: getConfig produces: ["application/json"] security: From 41c18bed0f954e43e65993b7487a573bf65152f0 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 28 Jun 2018 17:53:57 +0100 Subject: [PATCH 16/39] +repository --- api/client-server/content-repo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 8ccc7684..e2549c65 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -272,7 +272,7 @@ paths: "/config": get: summary: Get the configuration for the content repository. - Clients SHOULD use this as a guide when using content endpoints. + Clients SHOULD use this as a guide when using content repository endpoints. All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available. From a1309d636c8af90ef04499c392ce836fb07d614f Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 29 Jun 2018 09:58:07 +0100 Subject: [PATCH 17/39] Remove "Clients should handle gracefully" sentence --- api/client-server/content-repo.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index e2549c65..0f4ef2da 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -279,8 +279,7 @@ paths: **NOTE:** Both clients and server administrators should be aware that proxies between the client and the server may affect the apparent behaviour of content repository APIs, for example, proxies may enforce a lower upload size limit - than is advertised by the server on this endpoint. Clients should handle such - situations gracefully. + than is advertised by the server on this endpoint. operationId: getConfig produces: ["application/json"] security: From 5803c9cace238c6ce72bb52c0800e064ec5d6d48 Mon Sep 17 00:00:00 2001 From: Ben Parsons Date: Tue, 3 Jul 2018 15:49:40 +0100 Subject: [PATCH 18/39] don't run proposals.py step if in TravisCI environment --- scripts/generate-matrix-org-assets | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/scripts/generate-matrix-org-assets b/scripts/generate-matrix-org-assets index ed08f81d..cbebbb64 100755 --- a/scripts/generate-matrix-org-assets +++ b/scripts/generate-matrix-org-assets @@ -8,8 +8,11 @@ cd `dirname $0`/.. mkdir -p assets -# generate specification/proposals.rst -./scripts/proposals.py +if [ "$TRAVIS" != "true" ] +then + # generate specification/proposals.rst + ./scripts/proposals.py +fi # generate the spec docs ./scripts/gendoc.py -d assets/spec From 85e1962f9ceabd64d0a72d20eb651fe50172670c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 12:07:31 -0600 Subject: [PATCH 19/39] Use filepath.To/FromSlash instead of manually replacing slashes see https://github.com/matrix-org/matrix-doc/pull/1356#discussion_r199897557 --- scripts/continuserv/main.go | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/scripts/continuserv/main.go b/scripts/continuserv/main.go index fe4e5cc9..3797b9d7 100644 --- a/scripts/continuserv/main.go +++ b/scripts/continuserv/main.go @@ -98,8 +98,10 @@ func makeWalker(base string, w *fsnotify.Watcher) filepath.WalkFunc { log.Fatalf("Failed to get relative path of %s: %v", path, err) } + // Normalize slashes + rel = filepath.ToSlash(rel) + // skip a few things that we know don't form part of the spec - rel = strings.Replace(rel, "\\", "/", -1) // normalize slashes (thanks to windows) if rel == "api/node_modules" || rel == "scripts/gen" || rel == "scripts/tmp" { @@ -127,7 +129,7 @@ func filter(e fsnotify.Event) bool { } // Forcefully ignore directories we don't care about (Windows, at least, tries to notify about some directories) - filePath := strings.Replace(e.Name, "\\", "/", -1) // normalize slashes (thanks to windows) + filePath := filepath.ToSlash(e.Name) // normalize slashes if strings.Contains(filePath, "/scripts/tmp") || strings.Contains(filePath, "/scripts/gen") || strings.Contains(filePath, "/api/node_modules") { @@ -156,11 +158,7 @@ func serve(w http.ResponseWriter, req *http.Request) { if file[0] == '/' { file = file[1:] } - b, ok = m.bytes[file] - - if !ok { - b, ok = m.bytes[strings.Replace(file, "/", "\\", -1)] // Attempt a Windows lookup - } + b, ok = m.bytes[filepath.FromSlash(file)] // de-normalize slashes if ok && file == "api-docs.json" { w.Header().Set("Access-Control-Allow-Origin", "*") From aac7b848f77e4aeb5f72f7858ea4027f01d2b3c0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 13:10:28 -0600 Subject: [PATCH 20/39] Add uhoreg and myself as trusted speculator people --- scripts/speculator/main.go | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/speculator/main.go b/scripts/speculator/main.go index 0380a3cd..5e122503 100644 --- a/scripts/speculator/main.go +++ b/scripts/speculator/main.go @@ -713,6 +713,8 @@ func main() { "ara4n": true, "leonerd": true, "rxl881": true, + "uhoreg": true, + "turt2live": true, } if err := initCache(); err != nil { log.Fatal(err) From 2409c849686cf7028dd35d5c12cfb6fb67ed5565 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 13:41:49 -0600 Subject: [PATCH 21/39] Document the GET version of /login Fixes https://github.com/matrix-org/matrix-doc/issues/677 --- api/client-server/login.yaml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index a6e21a38..c0db2299 100644 --- a/api/client-server/login.yaml +++ b/api/client-server/login.yaml @@ -28,6 +28,42 @@ securityDefinitions: $ref: definitions/security.yaml paths: "/login": + get: + summary: Get the supported login types to authenticate users + description: |- + Gets the homeserver's supported login types to authenticate users. Clients + should pick one of these and supply it as the ``type`` when logging in. + operationId: getLoginFlows + responses: + 200: + description: The login types the homeserver supports + examples: + application/json: { + "flows": [ + {"type": "m.login.password"} + ] + } + schema: + type: object + properties: + flows: + type: array + description: The homeserver's supported login types + items: + type: object + title: LoginFlow + properties: + type: + description: |- + The login type. This is supplied as the ``type`` when + logging in. + type: string + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + tags: + - Session management post: summary: Authenticates the user. description: |- From 17c9cde0ec06e2f85b4e08615041890c4c223218 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 13:46:57 -0600 Subject: [PATCH 22/39] Add to changelog --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index feabecab..44d41f4e 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -15,6 +15,8 @@ Unreleased changes - Sticker messages: - Add sticker message event definition. (`#1158 `_). + - Document the GET version of ``/login`` + (`#1361 `_). - Spec clarifications: From d279fdafa6e649f4dd8ea2dd4a89e559c633a3f3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 15:49:16 -0600 Subject: [PATCH 23/39] Document the server_name query parameter on /join/{roomIdOrAlias} Fixes https://github.com/matrix-org/matrix-doc/issues/904 --- api/client-server/joining.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index da4e4337..bd3e6885 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -143,6 +143,16 @@ paths: description: The room identifier or alias to join. required: true x-example: "#monkeys:matrix.org" + - in: query + type: array + items: + type: string + explode: true + name: server_name + description: |- + The servers to attempt to join the room through. One of the servers + must be participating in the room. + x-example: ["matrix.org", "elsewhere.ca"] - in: body name: third_party_signed schema: From cbbdcbcf01cd5c9d18bb0ca0aa80257dad8fccfe Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 15:50:01 -0600 Subject: [PATCH 24/39] Show arrays in the query string as "[type]" rather than "array" Otherwise the question "array of what?" is raised. --- scripts/templating/matrix_templates/units.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index d8cfe1e3..dac183d1 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -502,6 +502,11 @@ class MatrixUnits(Units): # assign value expected for this param val_type = param.get("type") # integer/string + if val_type == "array": + items = param.get("items") + if items: + val_type = "[%s]" % items.get("type") + if param.get("enum"): val_type = "enum" desc += ( From 625913d797cda10d9916934351e598161adaced0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 15:53:43 -0600 Subject: [PATCH 25/39] Add to changelog --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index feabecab..01670c74 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -15,6 +15,8 @@ Unreleased changes - Sticker messages: - Add sticker message event definition. (`#1158 `_). + - Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}`` + (`#1364 `_). - Spec clarifications: From a6b0125da62e9c911ff15b8cbcf267499f95ee99 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 16:19:31 -0600 Subject: [PATCH 26/39] Our swagger doesn't support explode yet --- api/client-server/joining.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index bd3e6885..471c5038 100644 --- a/api/client-server/joining.yaml +++ b/api/client-server/joining.yaml @@ -147,7 +147,6 @@ paths: type: array items: type: string - explode: true name: server_name description: |- The servers to attempt to join the room through. One of the servers From 2fc292646147b236a3740184a589f457206b3db5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 11:33:51 -0600 Subject: [PATCH 27/39] Clearly say that the server/server API is unstable and subject to change --- specification/server_server_api.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 3738ea05..f2b3204a 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -16,6 +16,10 @@ Federation API ============== +.. WARNING:: + This API is unstable and will change without warning or discussion while + we work towards a r0 release (scheduled for August 2018). + Matrix homeservers use the Federation APIs (also known as server-server APIs) to communicate with each other. Homeservers use these APIs to push messages to each other in real-time, to From 981d1004bc9d7a82e09ca413eee87a64d80d59f1 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 3 May 2018 23:18:47 +0900 Subject: [PATCH 28/39] Add a missing $ref --- api/client-server/message_pagination.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 71406653..941e61fb 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -107,6 +107,7 @@ paths: items: type: object title: RoomEvent + "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml" examples: application/json: { "start": "t47429-4392820_219380_26003_2265", From 9e796192e45aad16019f29d892cf875db7eeb7c5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 15:31:23 -0600 Subject: [PATCH 29/39] Document that clients must leave before forgetting rooms Fixes https://github.com/matrix-org/matrix-doc/issues/1011 --- api/client-server/leaving.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/leaving.yaml b/api/client-server/leaving.yaml index 36351fd4..e8e58397 100644 --- a/api/client-server/leaving.yaml +++ b/api/client-server/leaving.yaml @@ -78,8 +78,8 @@ paths: for this room. If all users on a homeserver forget a room, the room is eligible for deletion from that homeserver. - If the user is currently joined to the room, they will implicitly leave - the room as part of this API call. + If the user is currently joined to the room, they must leave the room + before calling this API. operationId: forgetRoom security: - accessToken: [] From a19bbc80897fe0b4e184263200203b4b2e2c707c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 15:32:53 -0600 Subject: [PATCH 30/39] Add to changelog --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 44d41f4e..697b02c1 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -41,6 +41,8 @@ Unreleased changes (`#1245 `_). - Describe ``StateEvent`` for ``/createRoom`` (`#1329 `_). + - Clarify that clients must leave rooms before forgetting them + (`#1378 `_). - Changes to the API which will be backwards-compatible for clients: From 95e8f1bddebc927fff3bf2b03ea795a79312b2ed Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 19:21:03 -0600 Subject: [PATCH 31/39] Add to changelog --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 44d41f4e..34e42d0b 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -39,6 +39,8 @@ Unreleased changes (`#1152 `_). - Mark ``GET /rooms/{roomId}/members`` as requiring authentication (`#1245 `_). + - Define what a ``RoomEvent`` is on ``/rooms/{roomId}/messages`` + (`#1380 `_). - Describe ``StateEvent`` for ``/createRoom`` (`#1329 `_). From 436b4106980663b595570f5878033765195be6b2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 20:02:30 -0600 Subject: [PATCH 32/39] Document the error code when someone tries to forget a room they are in --- api/client-server/leaving.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/api/client-server/leaving.yaml b/api/client-server/leaving.yaml index e8e58397..57a148c6 100644 --- a/api/client-server/leaving.yaml +++ b/api/client-server/leaving.yaml @@ -99,6 +99,15 @@ paths: } schema: type: object + 400: + description: The user has not left the room + examples: + application/json: { + "errcode": "M_UNKNOWN", + "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" + } + schema: + "$ref": "definitions/error.yaml" 429: description: This request was rate-limited. schema: From dfdc5f9bef899c356695c9cc0c5b7f9e8c45b2d5 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 3 May 2018 23:19:55 +0900 Subject: [PATCH 33/39] search.yaml: Rename some titles to avoid confusion between request and response schemas Signed-off-by: Alexey Rusakov --- api/client-server/search.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index e5f6a872..f7c96180 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -74,7 +74,7 @@ paths: properties: room_events: type: object - title: "Room Events" + title: Room Events Criteria description: Mapping of category name to search criteria. properties: search_term: @@ -103,7 +103,7 @@ paths: The order in which to search for results. By default, this is ``"rank"``. event_context: - title: "Event Context" + title: "Include Event Context" type: object description: |- Configures whether any context for the events @@ -169,13 +169,13 @@ paths: properties: search_categories: type: object - title: Categories + title: Result Categories description: Describes which categories to search in and their criteria. properties: room_events: type: object - title: Room Event Results + title: Result Room Events description: Mapping of category name to search criteria. properties: count: From 0867ab2365e403241343d45bc06c966d73442ea3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 20:14:19 -0600 Subject: [PATCH 34/39] Add to changelog --- changelogs/client_server.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 44d41f4e..f732a6d8 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -41,6 +41,8 @@ Unreleased changes (`#1245 `_). - Describe ``StateEvent`` for ``/createRoom`` (`#1329 `_). + - Clarify the request and result types on ``/search`` + (`#1381 `_). - Changes to the API which will be backwards-compatible for clients: From 16860ddd22b8364ea501bbcf0034c5ae189b3bf3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 5 Jul 2018 10:46:53 -0600 Subject: [PATCH 35/39] De-quote --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index f7c96180..687140b3 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -103,7 +103,7 @@ paths: The order in which to search for results. By default, this is ``"rank"``. event_context: - title: "Include Event Context" + title: Include Event Context type: object description: |- Configures whether any context for the events From f9a0a49e96a98eb0d96b2ef424868858235ab007 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 5 Jul 2018 20:22:59 +0100 Subject: [PATCH 36/39] Add a bunch more people to the speculator trusted list --- scripts/speculator/main.go | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/scripts/speculator/main.go b/scripts/speculator/main.go index 5e122503..12ec2aec 100644 --- a/scripts/speculator/main.go +++ b/scripts/speculator/main.go @@ -701,8 +701,8 @@ func ignoreExitCodeOne(err error) error { func main() { flag.Parse() - // It would be great to read this from github, but there's no convenient way to do so. - // Most of these memberships are "private", so would require some kind of auth. + // It would be great to read this from github + // cf https://github.com/matrix-org/matrix-doc/issues/1384 allowedMembers = map[string]bool{ "dbkr": true, "erikjohnston": true, @@ -715,6 +715,11 @@ func main() { "rxl881": true, "uhoreg": true, "turt2live": true, + "Half-Shot": true, + "anoadragon453": true, + "mujx": true, + "benparsons": true, + "KitsuneRal": true, } if err := initCache(); err != nil { log.Fatal(err) From d5ce87e9567a38c9fbaafa2cbbfd90304794053b Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 6 Jul 2018 10:27:03 +0100 Subject: [PATCH 37/39] Split summary up into description and summary --- api/client-server/content-repo.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 0f4ef2da..3340808c 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -272,14 +272,14 @@ paths: "/config": get: summary: Get the configuration for the content repository. - Clients SHOULD use this as a guide when using content repository endpoints. - All values are intentionally left optional. Clients SHOULD follow - the advice given in the field description when the field is not available. + description: Clients SHOULD use this as a guide when using content repository endpoints. + All values are intentionally left optional. Clients SHOULD follow + the advice given in the field description when the field is not available. - **NOTE:** Both clients and server administrators should be aware that proxies - between the client and the server may affect the apparent behaviour of content - repository APIs, for example, proxies may enforce a lower upload size limit - than is advertised by the server on this endpoint. + **NOTE:** Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. operationId: getConfig produces: ["application/json"] security: From 2e6cc8045cc3f0942b9c23caab1edd25f52e4915 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 6 Jul 2018 10:29:05 +0100 Subject: [PATCH 38/39] Better indent of description --- api/client-server/content-repo.yaml | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 3340808c..1f1d6abc 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -272,14 +272,15 @@ paths: "/config": get: summary: Get the configuration for the content repository. - description: Clients SHOULD use this as a guide when using content repository endpoints. - All values are intentionally left optional. Clients SHOULD follow - the advice given in the field description when the field is not available. + description: |- + Clients SHOULD use this as a guide when using content repository endpoints. + All values are intentionally left optional. Clients SHOULD follow + the advice given in the field description when the field is not available. - **NOTE:** Both clients and server administrators should be aware that proxies - between the client and the server may affect the apparent behaviour of content - repository APIs, for example, proxies may enforce a lower upload size limit - than is advertised by the server on this endpoint. + **NOTE:** Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. operationId: getConfig produces: ["application/json"] security: From 77f4ac54aaddee927812a6c3e10d844d8df00ef7 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 6 Jul 2018 10:36:17 +0100 Subject: [PATCH 39/39] Wordy intro sentence for description --- api/client-server/content-repo.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 1f1d6abc..d88961b7 100644 --- a/api/client-server/content-repo.yaml +++ b/api/client-server/content-repo.yaml @@ -273,6 +273,8 @@ paths: get: summary: Get the configuration for the content repository. description: |- + This endpoint allows clients to retrieve the configuration of the content + repository, such as upload limitations. Clients SHOULD use this as a guide when using content repository endpoints. All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available.