MSC2379: Add /versions endpoint to Appservice API #2379

Half-Shot · 2019-12-04T16:20:46Z

Half-Shot · 2019-12-04T16:27:26Z

proposals/2379-appservice-versions.md

+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


This stuff is necessary so that we do not kill all bridges everywhere if we start supporting this, but it does suck from a spec standpoint of having to include it. Perhaps we don't need to spec this and leave it as an undocumented synapse feature to be removed at some point in the future?

proposals/2379-appservice-versions.md

turt2live · 2019-12-04T17:19:03Z

proposals/2379-appservice-versions.md

+
+## Proposal
+
+The `registration` file should contain one new key: `as_version`.


Overall I'm not convinced we need this in the spec. Synapse already supports arbitrary properties on the registration file, and the registration file in the spec is not a super strict thing (like anything, it's extensible). It doesn't even have to be YAML.

Sure, but this isn't just about Synapse. This is about ensuring that bridges have a single way to tell any homeserver impl which paths they should be hitting, rather than each homeserver specifying their own way of doing this.

Right now any homeserver that wishes to implement the appservice API is not going to be following the spec anyway, because at least the matrix-org bridges do not implement the correct endpoints. Presumably there are other bridges out there too that may not have bothered to follow the spec, because synapse doesn't use it. Dendrite is also non-compliant, for ex.

Yes, we could fix the bug we have right now for Synapse onlu by ensuring that every bridge developer out there appends a synapse-only key to their registration format (or fixes their shit), but that seems a like a waste of time if we have this problem with other homeservers down the line.

Furthermore, this change also future proof the API when we inevitably change the format of the transaction format.

Half-Shot · 2019-12-04T17:54:02Z

Spoke IRL to @anoadragon453 and came to the conclusion that this should be GET /versions, because it can live outside registration which the bridge may not have control over. It also lines up nicely with our other APIs.

anoadragon453

I'm not entirely convinced we need to have the endpoint stuff in this MSC. Say an AS /versions is introduced into the spec through an MSC. You then release a new version of the AS API which has corrected paths. It's then implied that homeserver authors would need to deal with the legacy considerations that the /versions endpoint provides. If the bridge says it only supports vNext of the AS API, the homeserver should send to the new endpoints. If it doesn't or doesn't have a /versions endpoint, then the homeserver should use the legacy endpoints.

We don't need to include this transition information in the spec, it can all be done in implementation.

anoadragon453 · 2019-12-05T12:40:22Z

proposals/2379-appservice-versions.md

+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`.


Suggested change

refuse to load appservices that do not include this `key`.

refuse to load appservices that do not include this endpoint.

?

anoadragon453 · 2019-12-05T12:41:06Z

proposals/2379-appservice-versions.md

+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.


Suggested change

of the spec, this mode could be removed.

of the spec, this legacy behaviour could be removed.

Half-Shot · 2019-12-05T13:10:33Z

I'm not entirely convinced we need to have the endpoint stuff in this MSC. Say an AS /versions is introduced into the spec through an MSC. You then release a new version of the AS API which has corrected paths. It's then implied that homeserver authors would need to deal with the legacy considerations that the /versions endpoint provides.

Sure. I'm also not convinced we needed this information in the MSC, but wanted it there for context. I guess we can leave this as an easter egg in synapse.

If the bridge says it only supports vNext of the AS API, the homeserver should send to the new endpoints. If it doesn't or doesn't have a /versions endpoint, then the homeserver should use the legacy endpoints.

That's the plan, yep.

We don't need to include this transition information in the spec, it can all be done in implementation.

Sure thing.

anoadragon453

Thanks, I think this will also be much less contentious.

anoadragon453 · 2019-12-05T13:17:02Z

proposals/2379-appservice-versions.md

+but lacks a `unstable_features` key, and is hosted by the appservice rather than the homeserver.
+
+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.


Last thing I think I'd put in is a "Legacy Considerations" section that states if an appservice hasn't implemented /versions, a homeserver can choose to either assume it supports all AS API versions up until the one where this /versions endpoint was introduced, or just deny connecting to it at all.

...but that's what I just deleted 😢

I wanted the stuff about specifying new endpoints deleted, but this bit we should keep.

Add proposal

74dd80f

Half-Shot changed the title ~~MSC XXXX: Add supported appservice version to registration information~~ MSC 2379: Add supported appservice version to registration information Dec 4, 2019

Rename MSC

09296ee

Half-Shot added proposal A matrix spec change proposal proposal-in-review labels Dec 4, 2019

Fix formatting

4fbe134

Half-Shot mentioned this pull request Dec 4, 2019

Use v1 endpoints for appservices matrix-org/synapse#6460

Closed

s/txnId/roomAlias

4ce981b

Half-Shot commented Dec 4, 2019

View reviewed changes

turt2live self-requested a review December 4, 2019 17:13

turt2live requested changes Dec 4, 2019

View reviewed changes

Switch to /versions

7acdaa4

Half-Shot force-pushed the hs/msc-as-versions2 branch from cb6d03f to 7acdaa4 Compare December 5, 2019 11:13

Half-Shot changed the title ~~MSC 2379: Add supported appservice version to registration information~~ MSC 2379: Add /versions endpoint to Appservice API Dec 5, 2019

Half-Shot added 2 commits December 5, 2019 11:14

Spell out full path

e139d4f

Allow homeservers to ignore /versions less bridges

08d0261

anoadragon453 requested changes Dec 5, 2019

View reviewed changes

Remove information about legacy endpoints

0438fca

anoadragon453 requested changes Dec 5, 2019

View reviewed changes

turt2live changed the title ~~MSC 2379: Add /versions endpoint to Appservice API~~ MSC2379: Add /versions endpoint to Appservice API Dec 5, 2019

turt2live added the kind:maintenance MSC which clarifies/updates existing spec label Apr 20, 2020

richvdh mentioned this pull request Jul 9, 2020

Ensure all appservice endpoints are prefixed with /_matrix/app/v1 matrix-org/sytest#758

Open

turt2live added the needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. label Jun 8, 2021

turt2live force-pushed the old_master branch from e895827 to dca99ee Compare August 30, 2021 22:34

turt2live removed the proposal-in-review label May 5, 2022

clokep mentioned this pull request Jun 24, 2024

How should an appservice opt-out of providing an endpoint? matrix-org/matrix-spec#1859

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MSC2379: Add /versions endpoint to Appservice API #2379

MSC2379: Add /versions endpoint to Appservice API #2379

Half-Shot commented Dec 4, 2019 •

edited

Loading

Half-Shot Dec 4, 2019

turt2live Dec 4, 2019

Half-Shot Dec 4, 2019

Half-Shot commented Dec 4, 2019

anoadragon453 left a comment

anoadragon453 Dec 5, 2019

anoadragon453 Dec 5, 2019

Half-Shot commented Dec 5, 2019

anoadragon453 left a comment

anoadragon453 Dec 5, 2019 •

edited

Loading

Half-Shot Dec 5, 2019

anoadragon453 Dec 6, 2019


		## Proposal

		The `registration` file should contain one new key: `as_version`.

	refuse to load appservices that do not include this `key`.
	refuse to load appservices that do not include this endpoint.

	of the spec, this mode could be removed.
	of the spec, this legacy behaviour could be removed.

MSC2379: Add /versions endpoint to Appservice API #2379

Are you sure you want to change the base?

MSC2379: Add /versions endpoint to Appservice API #2379

Conversation

Half-Shot commented Dec 4, 2019 • edited Loading

Half-Shot Dec 4, 2019

Choose a reason for hiding this comment

turt2live Dec 4, 2019

Choose a reason for hiding this comment

Half-Shot Dec 4, 2019

Choose a reason for hiding this comment

Half-Shot commented Dec 4, 2019

anoadragon453 left a comment

Choose a reason for hiding this comment

anoadragon453 Dec 5, 2019

Choose a reason for hiding this comment

anoadragon453 Dec 5, 2019

Choose a reason for hiding this comment

Half-Shot commented Dec 5, 2019

anoadragon453 left a comment

Choose a reason for hiding this comment

anoadragon453 Dec 5, 2019 • edited Loading

Choose a reason for hiding this comment

Half-Shot Dec 5, 2019

Choose a reason for hiding this comment

anoadragon453 Dec 6, 2019

Choose a reason for hiding this comment

Half-Shot commented Dec 4, 2019 •

edited

Loading

anoadragon453 Dec 5, 2019 •

edited

Loading