From 74dd80f4a6ab3d48520ed3b590b279f2cfb32543 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Wed, 4 Dec 2019 16:18:24 +0000 Subject: [PATCH 1/8] Add proposal --- proposals/0000-appservice-versions.md | 44 +++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 proposals/0000-appservice-versions.md diff --git a/proposals/0000-appservice-versions.md b/proposals/0000-appservice-versions.md new file mode 100644 index 0000000000..031a15d5f9 --- /dev/null +++ b/proposals/0000-appservice-versions.md @@ -0,0 +1,44 @@ +# MSC XXXX: Add supported appservice version to registration information. + +The [AS registration format](https://matrix.org/docs/spec/application_service/r0.1.2#registration) does +not have a way to specify what version of the spec that bridges support. This means that if the path +of any of the appservice endpoints were to change in the spec, homeservers would not be able to +intelligently discover the paths that a bridge supports. + +## Proposal + +The `registration` file should contain one new key: `as_version`. + +The value of the key should be set to the AS API version (`rX.X.X`) that the bridge supports. This +key SHOULD be specified by all bridges. When set, the homeserver MUST send requests to the endpoints +specified by that version of the AS spec. + +Homeservers may optionally support an omitted value, which will make it support the legacy paths used +by Synapse `<=1.6.X`. + +The legacy paths omit the /_matrix/app/{version} prefix entirely for: + - `/_matrix/app/{version}/transactions/{txnId}`` becomes `/transactions/{txnId}` + - `/_matrix/app/{version}/users/{userId}`` becomes `/users/{userId}` + - `/_matrix/app/{version}/rooms/{txnId}`` becomes `/rooms/{roomAlias}` + +Additionally, the `{version}` for the Third party network routes is always set to `unstable`. + +It should be reiterated that support for this is up to the homeserver implemetor. Homeservers may +refuse to load appservices that do not include this `key`. + +## Potential issues + +Keeping a 'legacy' mode around in the spec sucks, because it's horribly non-compliant to the version system. +However, most of the ecosystem has been modeled over Synapse behaviours which means this spec change would break +support for bridges if implemented by Synapse. This option remains the most pragmatic option. In a future version +of the spec, this mode could be removed. + +## Alternatives + +A /versions endpoint could be defined for the bridge to host, but this feels overcomplicated when the +registration format could also work. + + +## Security considerations + +None From 09296ee6b28e74fc8a87d83199d52a1625e20620 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Wed, 4 Dec 2019 16:21:09 +0000 Subject: [PATCH 2/8] Rename MSC --- ...{0000-appservice-versions.md => 2379-appservice-versions.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{0000-appservice-versions.md => 2379-appservice-versions.md} (96%) diff --git a/proposals/0000-appservice-versions.md b/proposals/2379-appservice-versions.md similarity index 96% rename from proposals/0000-appservice-versions.md rename to proposals/2379-appservice-versions.md index 031a15d5f9..cbe39dfe28 100644 --- a/proposals/0000-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -1,4 +1,4 @@ -# MSC XXXX: Add supported appservice version to registration information. +# MSC 2379: Add supported appservice version to registration information. The [AS registration format](https://matrix.org/docs/spec/application_service/r0.1.2#registration) does not have a way to specify what version of the spec that bridges support. This means that if the path From 4fbe1341da463399b6374908a4175a70337633e4 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Wed, 4 Dec 2019 16:21:56 +0000 Subject: [PATCH 3/8] Fix formatting --- proposals/2379-appservice-versions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2379-appservice-versions.md b/proposals/2379-appservice-versions.md index cbe39dfe28..c857f1360c 100644 --- a/proposals/2379-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -17,9 +17,10 @@ Homeservers may optionally support an omitted value, which will make it support by Synapse `<=1.6.X`. The legacy paths omit the /_matrix/app/{version} prefix entirely for: - - `/_matrix/app/{version}/transactions/{txnId}`` becomes `/transactions/{txnId}` - - `/_matrix/app/{version}/users/{userId}`` becomes `/users/{userId}` - - `/_matrix/app/{version}/rooms/{txnId}`` becomes `/rooms/{roomAlias}` + + - `/_matrix/app/{version}/transactions/{txnId}` becomes `/transactions/{txnId}` + - `/_matrix/app/{version}/users/{userId}` becomes `/users/{userId}` + - `/_matrix/app/{version}/rooms/{txnId}` becomes `/rooms/{roomAlias}` Additionally, the `{version}` for the Third party network routes is always set to `unstable`. From 4ce981b0cc67c7083a39ad54e59a99dc555d7047 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Wed, 4 Dec 2019 16:24:44 +0000 Subject: [PATCH 4/8] s/txnId/roomAlias --- proposals/2379-appservice-versions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2379-appservice-versions.md b/proposals/2379-appservice-versions.md index c857f1360c..7644fad386 100644 --- a/proposals/2379-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -20,7 +20,7 @@ The legacy paths omit the /_matrix/app/{version} prefix entirely for: - `/_matrix/app/{version}/transactions/{txnId}` becomes `/transactions/{txnId}` - `/_matrix/app/{version}/users/{userId}` becomes `/users/{userId}` - - `/_matrix/app/{version}/rooms/{txnId}` becomes `/rooms/{roomAlias}` + - `/_matrix/app/{version}/rooms/{roomAlias}` becomes `/rooms/{roomAlias}` Additionally, the `{version}` for the Third party network routes is always set to `unstable`. From 7acdaa4a9f47b87dd6322603b4fc17f16f011110 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Thu, 5 Dec 2019 11:12:57 +0000 Subject: [PATCH 5/8] Switch to /versions --- proposals/2379-appservice-versions.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/proposals/2379-appservice-versions.md b/proposals/2379-appservice-versions.md index 7644fad386..8bdf5b8564 100644 --- a/proposals/2379-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -1,19 +1,19 @@ -# MSC 2379: Add supported appservice version to registration information. +# MSC 2379: Add /versions endpoint to Appservice API. -The [AS registration format](https://matrix.org/docs/spec/application_service/r0.1.2#registration) does -not have a way to specify what version of the spec that bridges support. This means that if the path +Bridges do not have a way to specify what version of the spec they support. This means that if the path of any of the appservice endpoints were to change in the spec, homeservers would not be able to intelligently discover the paths that a bridge supports. ## Proposal -The `registration` file should contain one new key: `as_version`. +A new endpoint is required, which is `/versions`. This is nearly identical to the +[C-S API](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-versions) endpoint +but lacks a `unstable_features` key. -The value of the key should be set to the AS API version (`rX.X.X`) that the bridge supports. This -key SHOULD be specified by all bridges. When set, the homeserver MUST send requests to the endpoints -specified by that version of the AS spec. +All bridges SHOULD implement this endpoint and specify which version(s) of the `AS` API they support. +The homeserver MUST send requests to the endpoints specified by that version of the AS spec. -Homeservers may optionally support an omitted value, which will make it support the legacy paths used +Homeservers may optionally support a 404 response to this endpoint, which will make it use the legacy paths used by Synapse `<=1.6.X`. The legacy paths omit the /_matrix/app/{version} prefix entirely for: @@ -36,9 +36,10 @@ of the spec, this mode could be removed. ## Alternatives -A /versions endpoint could be defined for the bridge to host, but this feels overcomplicated when the -registration format could also work. - +This proposal previously used the `registration` file as a way to specify the supported version, but +this was dropped as it was hard for the bridge to be authoritive over what version it supports. Typically +the registration format is generated once by the bridge and then handled by the homeserver. If a bridge were +to update and require a new version of the AS API, the registration data would need to be updated/regenerated. ## Security considerations From e139d4f816e536489779928a89a51cd086d8f20e Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Thu, 5 Dec 2019 11:14:13 +0000 Subject: [PATCH 6/8] Spell out full path --- proposals/2379-appservice-versions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2379-appservice-versions.md b/proposals/2379-appservice-versions.md index 8bdf5b8564..1451a0cea2 100644 --- a/proposals/2379-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -6,9 +6,9 @@ intelligently discover the paths that a bridge supports. ## Proposal -A new endpoint is required, which is `/versions`. This is nearly identical to the +A new endpoint is required, which is `/_matrix/app/versions`. This is nearly identical to the [C-S API](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-versions) endpoint -but lacks a `unstable_features` key. +but lacks a `unstable_features` key, and is hosted by the appservice rather than the homeserver. All bridges SHOULD implement this endpoint and specify which version(s) of the `AS` API they support. The homeserver MUST send requests to the endpoints specified by that version of the AS spec. From 08d02616c83e4baedd7f6171c97574702eb5b0da Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Thu, 5 Dec 2019 11:15:02 +0000 Subject: [PATCH 7/8] Allow homeservers to ignore /versions less bridges --- proposals/2379-appservice-versions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2379-appservice-versions.md b/proposals/2379-appservice-versions.md index 1451a0cea2..7f1a1775c8 100644 --- a/proposals/2379-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -14,7 +14,8 @@ All bridges SHOULD implement this endpoint and specify which version(s) of the ` The homeserver MUST send requests to the endpoints specified by that version of the AS spec. Homeservers may optionally support a 404 response to this endpoint, which will make it use the legacy paths used -by Synapse `<=1.6.X`. +by Synapse `<=1.6.X`. Alternatively, the homeserver may choose not to communicate with a bridge that lacks a /versions +endpoint. The legacy paths omit the /_matrix/app/{version} prefix entirely for: From 0438fcaade7bbd2aa93e3eec1cd2e8108730de30 Mon Sep 17 00:00:00 2001 From: Half-Shot Date: Thu, 5 Dec 2019 13:11:23 +0000 Subject: [PATCH 8/8] Remove information about legacy endpoints --- proposals/2379-appservice-versions.md | 22 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) diff --git a/proposals/2379-appservice-versions.md b/proposals/2379-appservice-versions.md index 7f1a1775c8..be5313a2c3 100644 --- a/proposals/2379-appservice-versions.md +++ b/proposals/2379-appservice-versions.md @@ -10,30 +10,12 @@ A new endpoint is required, which is `/_matrix/app/versions`. This is nearly ide [C-S API](https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-versions) endpoint but lacks a `unstable_features` key, and is hosted by the appservice rather than the homeserver. -All bridges SHOULD implement this endpoint and specify which version(s) of the `AS` API they support. +All bridges MUST implement this endpoint and specify which version(s) of the `AS` API they support. The homeserver MUST send requests to the endpoints specified by that version of the AS spec. -Homeservers may optionally support a 404 response to this endpoint, which will make it use the legacy paths used -by Synapse `<=1.6.X`. Alternatively, the homeserver may choose not to communicate with a bridge that lacks a /versions -endpoint. - -The legacy paths omit the /_matrix/app/{version} prefix entirely for: - - - `/_matrix/app/{version}/transactions/{txnId}` becomes `/transactions/{txnId}` - - `/_matrix/app/{version}/users/{userId}` becomes `/users/{userId}` - - `/_matrix/app/{version}/rooms/{roomAlias}` becomes `/rooms/{roomAlias}` - -Additionally, the `{version}` for the Third party network routes is always set to `unstable`. - -It should be reiterated that support for this is up to the homeserver implemetor. Homeservers may -refuse to load appservices that do not include this `key`. - ## Potential issues -Keeping a 'legacy' mode around in the spec sucks, because it's horribly non-compliant to the version system. -However, most of the ecosystem has been modeled over Synapse behaviours which means this spec change would break -support for bridges if implemented by Synapse. This option remains the most pragmatic option. In a future version -of the spec, this mode could be removed. +None ## Alternatives