From 4ca54404fa4ae3b2ae58c34688204883e4c94903 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 3 Jul 2018 16:15:29 -0600 Subject: [PATCH 1/9] 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 2/9] 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 1f12637d3f8973301e0ec6b7ebdfb167603b7d49 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 12:23:51 -0600 Subject: [PATCH 3/9] 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 4/9] 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 0779d81e52556c28bed61b82c602fd154a8f184d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 4 Jul 2018 14:30:39 -0600 Subject: [PATCH 5/9] 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 6/9] 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 423d5593f5a48e8bd0b7dfea0d37278b957d7a56 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 9 Jul 2018 15:40:03 -0600 Subject: [PATCH 7/9] 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 8/9] 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 9/9] 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