From 2783820f98b02f01dd2d55aca1e05fc3e78a617d Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Thu, 3 May 2018 12:23:24 +0100 Subject: [PATCH 01/44] 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/44] 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/44] 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/44] 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 077cd04a6d42b852f0dd8e29ad26ffda843e48ef Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Wed, 20 Jun 2018 16:01:06 +0100 Subject: [PATCH 05/44] /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 06/44] 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 07/44] 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 08/44] 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 09/44] 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 10/44] 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 11/44] 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 12/44] 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 13/44] 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 14/44] 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 15/44] +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 16/44] 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 7d94aaace8a799927673d53fa49b5f28c7d83acd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 14:59:41 -0600 Subject: [PATCH 17/44] Explicitly declare that the kick/ban reason will be on the membership event Fixes https://github.com/matrix-org/matrix-doc/issues/798 --- api/client-server/banning.yaml | 3 ++- api/client-server/kicking.yaml | 8 +++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/api/client-server/banning.yaml b/api/client-server/banning.yaml index 3877f0e9..4030f46b 100644 --- a/api/client-server/banning.yaml +++ b/api/client-server/banning.yaml @@ -61,7 +61,8 @@ paths: description: The fully qualified user ID of the user being banned. reason: type: string - description: The reason the user has been banned. + description: The reason the user has been banned. This will be supplied as the + ``reason`` on the target's updated `m.room.member`_ event. required: ["user_id"] responses: 200: diff --git a/api/client-server/kicking.yaml b/api/client-server/kicking.yaml index ef43c0ee..bacc806e 100644 --- a/api/client-server/kicking.yaml +++ b/api/client-server/kicking.yaml @@ -34,6 +34,10 @@ paths: Kick a user from the room. The caller must have the required power level in order to perform this operation. + + Kicking a user adjusts the target member's membership state to be ``leave`` with an + optional ``reason``. Like with other membership changes, a user can directly adjust + the target member's state by making a request to ``/rooms//state/m.room.member/``. operationId: kick security: - accessToken: [] @@ -59,7 +63,9 @@ paths: description: The fully qualified user ID of the user being kicked. reason: type: string - description: The reason the user has been kicked. + description: |- + The reason the user has been kicked. This will be supplied as the + ``reason`` on the target's updated `m.room.member`_ event. required: ["user_id"] responses: 200: From 5b6ad6f39d5792c987b4bee60989b8a2b026f9b3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 15:19:33 -0600 Subject: [PATCH 18/44] 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..a16b96ae 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -39,6 +39,8 @@ Unreleased changes (`#1245 `_). - Describe ``StateEvent`` for ``/createRoom`` (`#1329 `_). + - Describe how the ``reason`` is handled for kicks/bans + (`#1362 `_). - Changes to the API which will be backwards-compatible for clients: From d279fdafa6e649f4dd8ea2dd4a89e559c633a3f3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 15:49:16 -0600 Subject: [PATCH 19/44] 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 20/44] 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 21/44] 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 4ca54404fa4ae3b2ae58c34688204883e4c94903 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 16:15:29 -0600 Subject: [PATCH 22/44] Document the CORS/preflight headers Fixes https://github.com/matrix-org/matrix-doc/issues/1006 --- specification/client_server_api.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index dec3a4f4..f7a7d509 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -164,6 +164,26 @@ recommended. {{versions_cs_http_api}} +Web Browser Clients +------------------- + +It is realistic to expect that some clients will be written to be run within a +web browser or similar environment. In these cases, the homeserver should respond +to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers. + +When a client approaches the server with a pre-flight (``OPTIONS``) request, the +server should respond with the CORS headers for that route. If the route does not +exist, the server should return an ``M_NOT_FOUND`` error with a 404 status code. + +The standard CORS headers to be returned by servers on all requests are: + +.. code:: + + Access-Control-Allow-Origin: * + Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS + Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization + + Client Authentication --------------------- From b8c8d859268874cd548aff3be9fe58eed50a15a6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 16:18:04 -0600 Subject: [PATCH 23/44] 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..e4e7552f 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 CORS/preflight headers + (`#1365 `_). - 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 24/44] 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 25/44] 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 1f12637d3f8973301e0ec6b7ebdfb167603b7d49 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 12:23:51 -0600 Subject: [PATCH 26/44] Getting presence requires authentication --- api/client-server/presence.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index ba202c2d..ab32f983 100644 --- a/api/client-server/presence.yaml +++ b/api/client-server/presence.yaml @@ -83,6 +83,8 @@ paths: description: |- Get the given user's presence state. operationId: getPresence + security: + - accessToken: [] parameters: - in: path type: string From b61fe201718ca121c62a8edde9093bb2c0611bf7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 13:02:32 -0600 Subject: [PATCH 27/44] 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..eb0387c1 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 `_). + - Mark ``GET /presence/{userId}/status`` as requiring authentication + (`#1371 `_). - Describe ``StateEvent`` for ``/createRoom`` (`#1329 `_). From 981d1004bc9d7a82e09ca413eee87a64d80d59f1 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 3 May 2018 23:18:47 +0900 Subject: [PATCH 28/44] 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 0779d81e52556c28bed61b82c602fd154a8f184d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 14:30:39 -0600 Subject: [PATCH 29/44] Clarify which requests should have CORS headers Spoilers: all of them. --- specification/client_server_api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index f7a7d509..33ee8b1a 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -169,7 +169,8 @@ Web Browser Clients It is realistic to expect that some clients will be written to be run within a web browser or similar environment. In these cases, the homeserver should respond -to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers. +to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on +all requests. When a client approaches the server with a pre-flight (``OPTIONS``) request, the server should respond with the CORS headers for that route. If the route does not From 05c85fd840b3feda4916596365387e1e75cb1e8b Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 14:37:21 -0600 Subject: [PATCH 30/44] Spec the 403 on GET /presence/{userId}/status --- api/client-server/presence.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index ab32f983..46134430 100644 --- a/api/client-server/presence.yaml +++ b/api/client-server/presence.yaml @@ -123,6 +123,15 @@ paths: description: |- There is no presence state for this user. This user may not exist or isn't exposing presence information to you. + 403: + description: You are not allowed to see this user's presence status. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to see their presence" + } + schema: + "$ref": "definitions/error.yaml" tags: - Presence "/presence/list/{userId}": From 9e796192e45aad16019f29d892cf875db7eeb7c5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 15:31:23 -0600 Subject: [PATCH 31/44] 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 32/44] 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 33/44] 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 34/44] 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 35/44] 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 36/44] 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 37/44] 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 38/44] 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 39/44] 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 40/44] 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 41/44] 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. From 423d5593f5a48e8bd0b7dfea0d37278b957d7a56 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 9 Jul 2018 15:40:03 -0600 Subject: [PATCH 42/44] Generify how OPTIONS and CORS are handled --- specification/client_server_api.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 33ee8b1a..8dde4302 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -173,10 +173,8 @@ to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers o all requests. When a client approaches the server with a pre-flight (``OPTIONS``) request, the -server should respond with the CORS headers for that route. If the route does not -exist, the server should return an ``M_NOT_FOUND`` error with a 404 status code. - -The standard CORS headers to be returned by servers on all requests are: +server should respond with the CORS headers for that route. The recommended CORS +headers to be returned by servers on all requests are: .. code:: From 55e4e90ab1155c5b4d4031fe5108c7b5ea63ac53 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 10 Jul 2018 12:52:11 -0600 Subject: [PATCH 43/44] Document message formats as-is This is likely to later be replaced by mixins, however this is being documented now so clients aren't left in the dark. Fixes https://github.com/matrix-org/matrix-doc/issues/917 --- event-schemas/examples/m.room.message#m.emote | 4 +++- event-schemas/examples/m.room.message#m.text | 4 +++- event-schemas/schema/m.room.message#m.emote | 10 ++++++++++ event-schemas/schema/m.room.message#m.text | 10 ++++++++++ 4 files changed, 26 insertions(+), 2 deletions(-) diff --git a/event-schemas/examples/m.room.message#m.emote b/event-schemas/examples/m.room.message#m.emote index 4280928e..79292ddf 100644 --- a/event-schemas/examples/m.room.message#m.emote +++ b/event-schemas/examples/m.room.message#m.emote @@ -2,7 +2,9 @@ "age": 242352, "content": { "body": "thinks this is an example emote", - "msgtype": "m.emote" + "msgtype": "m.emote", + "format": "org.matrix.custom.html", + "formatted_body": "thinks this is an example emote" }, "origin_server_ts": 1431961217939, "event_id": "$WLGTSEFSEF:localhost", diff --git a/event-schemas/examples/m.room.message#m.text b/event-schemas/examples/m.room.message#m.text index e00c7aa5..48a97db8 100644 --- a/event-schemas/examples/m.room.message#m.text +++ b/event-schemas/examples/m.room.message#m.text @@ -2,7 +2,9 @@ "age": 242352, "content": { "body": "This is an example text message", - "msgtype": "m.text" + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "formatted_body": "This is an example text message" }, "origin_server_ts": 1431961217939, "event_id": "$WLGTSEFSEF:localhost", diff --git a/event-schemas/schema/m.room.message#m.emote b/event-schemas/schema/m.room.message#m.emote index 88860cb2..f67a184b 100644 --- a/event-schemas/schema/m.room.message#m.emote +++ b/event-schemas/schema/m.room.message#m.emote @@ -12,6 +12,16 @@ properties: enum: - m.emote type: string + format: + description: |- + The format used in the ``formatted_body``. Currently only + ``org.matrix.custom.html`` is supported. + type: string + formatted_body: + description: |- + The formatted version of the ``body``. This is required if ``format`` + is specified. + type: string required: - msgtype - body diff --git a/event-schemas/schema/m.room.message#m.text b/event-schemas/schema/m.room.message#m.text index 2720172d..b481bcea 100644 --- a/event-schemas/schema/m.room.message#m.text +++ b/event-schemas/schema/m.room.message#m.text @@ -12,6 +12,16 @@ properties: enum: - m.text type: string + format: + description: |- + The format used in the ``formatted_body``. Currently only + ``org.matrix.custom.html`` is supported. + type: string + formatted_body: + description: |- + The formatted version of the ``body``. This is required if ``format`` + is specified. + type: string required: - msgtype - body From c999b7c2e21b61a8f5d217054555d6a317a76cf0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 10 Jul 2018 13:00:37 -0600 Subject: [PATCH 44/44] Add newsfragment --- changelogs/client_server/newsfragments/1397.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1397.feature diff --git a/changelogs/client_server/newsfragments/1397.feature b/changelogs/client_server/newsfragments/1397.feature new file mode 100644 index 00000000..e4bd248a --- /dev/null +++ b/changelogs/client_server/newsfragments/1397.feature @@ -0,0 +1 @@ +Document message formats on ``m.text`` and ``m.emote`` messages