From e3dc62e448468a6e5df47d0051df7cc65558b9f4 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Sun, 29 Oct 2023 12:06:11 +0000 Subject: [PATCH 1/5] Add placeholder proposal --- proposals/xxx-pagination-token-headers.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 proposals/xxx-pagination-token-headers.md diff --git a/proposals/xxx-pagination-token-headers.md b/proposals/xxx-pagination-token-headers.md new file mode 100644 index 00000000000..58d31fded5a --- /dev/null +++ b/proposals/xxx-pagination-token-headers.md @@ -0,0 +1,3 @@ +# MSCXXX: Pagination Token Headers + +Coming soon... From 514f5b5c950f3405187815ae58ba81b889428525 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Sun, 29 Oct 2023 12:07:37 +0000 Subject: [PATCH 2/5] Rename --- proposals/4071-pagination-token-headers.md | 3 +++ proposals/xxx-pagination-token-headers.md | 3 --- 2 files changed, 3 insertions(+), 3 deletions(-) create mode 100644 proposals/4071-pagination-token-headers.md delete mode 100644 proposals/xxx-pagination-token-headers.md diff --git a/proposals/4071-pagination-token-headers.md b/proposals/4071-pagination-token-headers.md new file mode 100644 index 00000000000..9e7cd69631f --- /dev/null +++ b/proposals/4071-pagination-token-headers.md @@ -0,0 +1,3 @@ +# MSC4071: Pagination Token Headers + +Coming soon... diff --git a/proposals/xxx-pagination-token-headers.md b/proposals/xxx-pagination-token-headers.md deleted file mode 100644 index 58d31fded5a..00000000000 --- a/proposals/xxx-pagination-token-headers.md +++ /dev/null @@ -1,3 +0,0 @@ -# MSCXXX: Pagination Token Headers - -Coming soon... From 4efe021330fb48718f9084d6dcbde24cf69bc0c5 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Sun, 29 Oct 2023 19:54:54 +0000 Subject: [PATCH 3/5] Write up initial proposal --- proposals/4071-pagination-token-headers.md | 55 +++++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/proposals/4071-pagination-token-headers.md b/proposals/4071-pagination-token-headers.md index 9e7cd69631f..add4e0f634a 100644 --- a/proposals/4071-pagination-token-headers.md +++ b/proposals/4071-pagination-token-headers.md @@ -1,3 +1,56 @@ # MSC4071: Pagination Token Headers -Coming soon... +Many (Matrix) desktop apps are today written using webviews (electron, tauri, etc), these enforce +the use of CORS for requests to Matrix APIs. This adds an additional ~20-50ms (best case) to API +calls and usually isn't noticeable. But in Matrix the sync (and to a lesser extend messages) +endpoints are so often requested that this can have an impact (increased latency, wasted CPU, wasted +bandwidth) on both server and client. + +This MSC proposes an opt-in workaround that enables clients to specify the pagination token in a +header rather than query string thus avoiding a new CORS request each time the token changes. This +is absolutely a hack, and if accepted must only be used to work around this specific problem. + +## Proposal + +Super simple - clients may pass pagination tokens as a header instead of query parameters using the +format `X-Matrix-Pagination-$PARAM`, the following table lists the available headers by endpoint: + +|Endpoint (link to current spec)|Query Parameter|Header Alternative| +|-|-|-| +|[`sync`](https://spec.matrix.org/v1.8/client-server-api/#get_matrixclientv3sync)|`since`|`X-Matrix-Pagination-Since`| +|[`messages`](https://spec.matrix.org/v1.8/client-server-api/#get_matrixclientv3roomsroomidmessages)|`from`|`X-Matrix-Pagination-From`| +|[`messages`](https://spec.matrix.org/v1.8/client-server-api/#get_matrixclientv3roomsroomidmessages)|`to`|`X-Matrix-Pagination-To`| + +Servers must treat the values exactly the same as the query string versions. + +If a client makes a request specifying both header and query string servers should reject the request +with a 400 response and `M_INVALID_PARAM` error code. + +## Potential issues + +As noted above, this is a hack to work around CORS restrictions. Unfortunately CORS isn't going to +change any time soon (if ever). Whether the advantages outweigh the "ugliness" of this hack is up +for discussion here. + +## Alternatives + +A POST request with a body containing the parameters would also suffice as a solution. Like this +proposal this would also be a hacky workaround. + +## Security considerations + +In the context of Matrix clients CORS provides no security and homeservers are expected to accept +all CORS preflight requests, so this change has no security impact. + +## Unstable prefix + +No unstable prefix required, but servers should indicate unstable support for this within the +`unstable_features` key of the versions endpoint as so: + +```json +{ + "unstable_versions": { + "com.beeper.msc4071": true + } +} +``` From 2f55b2634315b531bdbcc19f40aa3fc3f6a26275 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Wed, 1 Nov 2023 10:15:39 +0000 Subject: [PATCH 4/5] Expand alternatives section --- proposals/4071-pagination-token-headers.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/proposals/4071-pagination-token-headers.md b/proposals/4071-pagination-token-headers.md index add4e0f634a..e1c3b6ed754 100644 --- a/proposals/4071-pagination-token-headers.md +++ b/proposals/4071-pagination-token-headers.md @@ -10,6 +10,10 @@ This MSC proposes an opt-in workaround that enables clients to specify the pagin header rather than query string thus avoiding a new CORS request each time the token changes. This is absolutely a hack, and if accepted must only be used to work around this specific problem. +Note that there are a bunch of less hacky [alternatives](#alternatives) but none of them are simple +and quick to implement such as this. This is very much a patch to alleviate the immediate issue while +better solutions can be worked out. + ## Proposal Super simple - clients may pass pagination tokens as a header instead of query parameters using the @@ -37,6 +41,12 @@ for discussion here. A POST request with a body containing the parameters would also suffice as a solution. Like this proposal this would also be a hacky workaround. +[matrix-spec#223](https://github.com/matrix-org/matrix-spec/issues/223) discusses some other alternative +workarouds for the issue. + +[MSC2108](https://github.com/matrix-org/matrix-spec-proposals/pull/2108) proposes using SSE as an +alternative. This would indeed work, but it's a significant change to implement and deploy everywhere. + ## Security considerations In the context of Matrix clients CORS provides no security and homeservers are expected to accept From 1ee27bf3d1822b6da36107ab42d382286c178988 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Wed, 1 Nov 2023 10:17:30 +0000 Subject: [PATCH 5/5] Spelling! --- proposals/4071-pagination-token-headers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4071-pagination-token-headers.md b/proposals/4071-pagination-token-headers.md index e1c3b6ed754..27b5fe9edcb 100644 --- a/proposals/4071-pagination-token-headers.md +++ b/proposals/4071-pagination-token-headers.md @@ -42,7 +42,7 @@ A POST request with a body containing the parameters would also suffice as a sol proposal this would also be a hacky workaround. [matrix-spec#223](https://github.com/matrix-org/matrix-spec/issues/223) discusses some other alternative -workarouds for the issue. +workarounds for the issue. [MSC2108](https://github.com/matrix-org/matrix-spec-proposals/pull/2108) proposes using SSE as an alternative. This would indeed work, but it's a significant change to implement and deploy everywhere.