Matrix 1.1 checklist

[turt2live]

Matrix 1.1 is coming up and consists of major changes to how the protocol operates from a versioning perspective. From a Synapse perspective, the ordered details are:

1. Support r0.6.1 as normal (Advertise support for r0.6.1 #11064)
2. Add/duplicate listeners for all /r0 endpoints to also listen on /v3
   • Add support for /_matrix/client/v3 APIs #11318
   • Add support for /_matrix/media/v3 APIs #11371
   • Register the login redirect endpoint for v3 #11451
3. Add or stabilize support for the feature list below.
4. Advertise v1.1 in /_matrix/client/versions (after the spec has been released)

The community has also expressed interest in having a config flag to test what the transition would look like in their clients for when servers start advertising the Matrix version. I think this can be accomplished by adding an unstable flag to /versions of org.matrix.msc2844 from the original MSC - no server implementations (to my knowledge) used the flag for anything during the MSC period, so we can and should use it for something like this. Its presence would denote whether Step 3 above is complete.

---

There's not currently anything that is expected to be added to v1.1 beyond this point, so the following curated features become stable or added:

• Key backup
• Knocking
• Social Login (/login/sso/redirect/:idp)
• Cross signing
• Secret Storage
• device_id in login fallback (MSC2604)
• 404 M_NOT_FOUND errors on push rule endpoints (MSC2663)
• reason and score are optional on the /report API
• Guests can get access to the members of a room (MSC2689)
• device_id on /account/whoami
• Room version 7 (for knocking)
• Add /_matrix/identity/versions API (if you use version checking against identity services)

Do note that Spaces are not included in this 1.1 release at present. The MSCs which have landed are still stable enough to use stable identifiers, however the functionality is not presently included in a released version of the spec. This should be fine as there's no API endpoints to worry about for versioning purposes, though servers may need to be aware of the m.space room type.

---

For clarity: the versioning of the protocol is now handled by 1 "global version". This version, expected to be 1.1 in the next release, covers all of the API documents, room versions, and appendices. Previously, the API documents were individually versioned and the room versions were specified but their stability was not versioned. The appendices previously were not versioned either. All of those things are now versioned as one single unit.

To accommodate this change, the client-server API has been reverted back to per-endpoint versioning in line with the other APIs. This is largely because there isn't an "r0" we can rely on anymore for the endpoint versioning. Instead, we've made all the endpoints currently listed as r0 since r0.6.1 become v3 to avoid conflicts with the very old and very legacy v1 and v2_alpha definitions found in Synapse (or which are familiar to those from the early days of the protocol).

New endpoints after Matrix 1.1 are anticipated to start at v1 as it should be clear by then that they aren't part of Matrix 1.1 or earlier.

Synapse is still encouraged to expose and maintain the r0 APIs for some time until sufficient adoption of the new versioning scheme.

[richvdh]

I've unticked "Add/duplicate listeners for all /r0 endpoints" because I think /_matrix/media/v3 remains to be done.

[DMRobertson]

I've unticked "Add/duplicate listeners for all /r0 endpoints" because I think /_matrix/media/v3 remains to be done.

Thanks, that was a mistake on my part.

[aaronraimist]

I forgot about /media/v3

[clokep]

We also need to update the reverse proxy documentation to pass through the v3 URLs.

[aaronraimist]

I don't think it needs an update. The existing reverse proxy documentation doesn't include API versions. It should pass through any version since the examples are shown like location ~* ^(\/_matrix|\/_synapse\/client) { or reverse_proxy /_matrix/*

[clokep]

I don't think it needs an update. The existing reverse proxy documentation doesn't include API versions. It should pass through any version since the examples are shown like location ~* ^(\/_matrix|\/_synapse\/client) { or reverse_proxy /_matrix/*

I was thinking of the worker documentation specifically: https://github.com/matrix-org/synapse/blob/master/docs/workers.md#available-worker-applications