Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC2379: Add /versions endpoint to Appservice API #2379

Open
wants to merge 8 commits into
base: old_master
Choose a base branch
from
Open

MSC2379: Add /versions endpoint to Appservice API #2379

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
74dd80f
Add proposal
Half-Shot Dec 4, 2019
09296ee
Rename MSC
Half-Shot Dec 4, 2019
4fbe134
Fix formatting
Half-Shot Dec 4, 2019
4ce981b
s/txnId/roomAlias
Half-Shot Dec 4, 2019
7acdaa4
Switch to /versions
Half-Shot Dec 5, 2019
e139d4f
Spell out full path
Half-Shot Dec 5, 2019
08d0261
Allow homeservers to ignore /versions less bridges
Half-Shot Dec 5, 2019
0438fca
Remove information about legacy endpoints
Half-Shot Dec 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions proposals/2379-appservice-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# MSC 2379: Add /versions endpoint to Appservice API.

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

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, 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.
Copy link
Member

@anoadragon453 anoadragon453 Dec 5, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Potential issues

None

## Alternatives

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

None