From d318ff95f3e835687df9d3411cf52613475516a3 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 14 Jan 2019 11:55:27 +0000 Subject: [PATCH 1/6] MSC1802: Standardised federation response formats --- ...standardised-federation-response-format.md | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 proposals/1802-standardised-federation-response-format.md diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md new file mode 100644 index 00000000..736cbbd3 --- /dev/null +++ b/proposals/1802-standardised-federation-response-format.md @@ -0,0 +1,55 @@ +# Standardised federation response formats + +Some responses formats in the federation API specifications use the form `[200, +res]` in which `res` is the JSON object containing the actual response for the +affected endpoints. This was due to a mishap while building synapse's federation +features, and has been left as is because fixing it would induce backward +incompatibility. With r0 approaching, and already including features with +backward compatibility issues (e.g. +[MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711)), this is likely +the right timing to address this issue. + +## Proposal + +Change the responses with a 200 status code for the following federation +endpoints: + +* `PUT /_matrix/federation/v1/send/{txnId}` +* `PUT /_matrix/federation/v1/send_join/{roomId}/{eventId}` +* `PUT /_matrix/federation/v1/invite/{roomId}/{eventId}` +* `PUT /_matrix/federation/v1/send_leave/{roomId}/{eventId}` + +From a response using this format: + +``` +[ + 200, + res +] +``` + +To a response using this format: + +``` +res +``` + +Where `res` is the JSON object containing the response to a request directed at +one of the affected endpoints. + +## Potential issues + +As it's already been mentioned in the proposal's introduction, this would induce +backward compatibility issues. However, proposals that have already been merged +at the time this one is being written already induce similar issues. + +As a mitigation solution, we could have a transition period during which both +response formats would be accepted on the affected endpoints. This would give +people time to update their homeservers to a version supporting the new one +without breaking federation entirely. + +## Conclusion + +Such a change would make the federation API specifications more standardised, +but would induce backward incompatible changes. However, with r0 coming up soon, +this is likely the best timing to address this issue. From 749b1777fa549ba1e6c156d26dfb43b5eb88127f Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 14 Jan 2019 16:17:40 +0000 Subject: [PATCH 2/6] Propose a backward-compatible option instead of an incompatible one --- ...standardised-federation-response-format.md | 44 ++++++++----------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md index 736cbbd3..f4cefc8f 100644 --- a/proposals/1802-standardised-federation-response-format.md +++ b/proposals/1802-standardised-federation-response-format.md @@ -4,22 +4,21 @@ Some responses formats in the federation API specifications use the form `[200, res]` in which `res` is the JSON object containing the actual response for the affected endpoints. This was due to a mishap while building synapse's federation features, and has been left as is because fixing it would induce backward -incompatibility. With r0 approaching, and already including features with -backward compatibility issues (e.g. -[MSC1711](https://github.com/matrix-org/matrix-doc/pull/1711)), this is likely -the right timing to address this issue. +incompatibility. + +This proposal proposes a backward compatible alternative ## Proposal -Change the responses with a 200 status code for the following federation -endpoints: +Add a new version of the following endpoints under the prefix +`/_matrix/federation/v2`: -* `PUT /_matrix/federation/v1/send/{txnId}` -* `PUT /_matrix/federation/v1/send_join/{roomId}/{eventId}` -* `PUT /_matrix/federation/v1/invite/{roomId}/{eventId}` -* `PUT /_matrix/federation/v1/send_leave/{roomId}/{eventId}` +* `PUT /_matrix/federation/v2/send/{txnId}` +* `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}` +* `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}` -From a response using this format: +Which are the exact same endpoints as their equivalents under the `v1` prefix, +except for the response format, which changes from: ``` [ @@ -28,7 +27,7 @@ From a response using this format: ] ``` -To a response using this format: +To: ``` res @@ -37,19 +36,12 @@ res Where `res` is the JSON object containing the response to a request directed at one of the affected endpoints. -## Potential issues - -As it's already been mentioned in the proposal's introduction, this would induce -backward compatibility issues. However, proposals that have already been merged -at the time this one is being written already induce similar issues. - -As a mitigation solution, we could have a transition period during which both -response formats would be accepted on the affected endpoints. This would give -people time to update their homeservers to a version supporting the new one -without breaking federation entirely. +This proposal doesn't address the `PUT +/_matrix/federation/v1/invite/{roomId}/{eventId}` endpoint since +[MSC1794](https://github.com/matrix-org/matrix-doc/pull/1794) already takes care +of it. -## Conclusion +## Alternative solutions -Such a change would make the federation API specifications more standardised, -but would induce backward incompatible changes. However, with r0 coming up soon, -this is likely the best timing to address this issue. +An alternative solution would be to make the change in the `v1` fedration API, +but would break backward compatibility, thus would be harder to manage. From 661d69858edde5d543a0eaa1503f0383b2ea2b92 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 29 Apr 2019 10:24:46 +0100 Subject: [PATCH 3/6] Add fallback --- proposals/1802-standardised-federation-response-format.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md index f4cefc8f..da18c254 100644 --- a/proposals/1802-standardised-federation-response-format.md +++ b/proposals/1802-standardised-federation-response-format.md @@ -41,6 +41,10 @@ This proposal doesn't address the `PUT [MSC1794](https://github.com/matrix-org/matrix-doc/pull/1794) already takes care of it. +If a call to any of the `v2` endpoints described in this proposal results in an +unrecognised request exception, then the sending server should retry the request +with the `v1` API. + ## Alternative solutions An alternative solution would be to make the change in the `v1` fedration API, From e71b3ac754963910ef76e39e29178ad3e40aab9f Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 1 May 2019 16:53:29 +0100 Subject: [PATCH 4/6] Add details to what an unrecognised request is --- proposals/1802-standardised-federation-response-format.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md index da18c254..bd8b1189 100644 --- a/proposals/1802-standardised-federation-response-format.md +++ b/proposals/1802-standardised-federation-response-format.md @@ -42,8 +42,8 @@ This proposal doesn't address the `PUT of it. If a call to any of the `v2` endpoints described in this proposal results in an -unrecognised request exception, then the sending server should retry the request -with the `v1` API. +unrecognised request exception (i.e. in a response with a 400 or a 404 status +code), then the sending server should retry the request with the `v1` API. ## Alternative solutions From fc262300070aedbc8a948fc20518eeaa07c6f8e7 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 5 Sep 2019 14:41:53 +0100 Subject: [PATCH 5/6] Update proposals/1802-standardised-federation-response-format.md Co-Authored-By: Matthew Hodgson --- proposals/1802-standardised-federation-response-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md index bd8b1189..abb39361 100644 --- a/proposals/1802-standardised-federation-response-format.md +++ b/proposals/1802-standardised-federation-response-format.md @@ -47,5 +47,5 @@ code), then the sending server should retry the request with the `v1` API. ## Alternative solutions -An alternative solution would be to make the change in the `v1` fedration API, +An alternative solution would be to make the change in the `v1` federation API, but would break backward compatibility, thus would be harder to manage. From cb2b71c0be27346e8cd8c431b57031c692446ee7 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 5 Sep 2019 14:54:31 +0100 Subject: [PATCH 6/6] Remove /send + rename --- proposals/1802-standardised-federation-response-format.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/1802-standardised-federation-response-format.md b/proposals/1802-standardised-federation-response-format.md index bd8b1189..e874524e 100644 --- a/proposals/1802-standardised-federation-response-format.md +++ b/proposals/1802-standardised-federation-response-format.md @@ -1,4 +1,4 @@ -# Standardised federation response formats +# Remove the '200' value from some federation responses Some responses formats in the federation API specifications use the form `[200, res]` in which `res` is the JSON object containing the actual response for the @@ -13,7 +13,6 @@ This proposal proposes a backward compatible alternative Add a new version of the following endpoints under the prefix `/_matrix/federation/v2`: -* `PUT /_matrix/federation/v2/send/{txnId}` * `PUT /_matrix/federation/v2/send_join/{roomId}/{eventId}` * `PUT /_matrix/federation/v2/send_leave/{roomId}/{eventId}`