From 99b1ae1df647b75ef429a0e4ed939567138657bc Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Fri, 11 Feb 2022 20:12:09 +0000 Subject: [PATCH 1/3] create federation versions MSC --- proposals/xxxx-federation-versions.md | 76 +++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 proposals/xxxx-federation-versions.md diff --git a/proposals/xxxx-federation-versions.md b/proposals/xxxx-federation-versions.md new file mode 100644 index 000000000..5f5a16338 --- /dev/null +++ b/proposals/xxxx-federation-versions.md @@ -0,0 +1,76 @@ +# MSCXXXX: Federation Versions + +This MSC aims to add a `/versions` endpoint to federation, similar to `/client/versions`. + +# Background + +Today, Matrix has a unversioned `/versions` endpoint on the client-server specification that +responds with an object containing an array of global matrix versions the server supports. + +This endpoint, together with global versioning, provides the source of truth for client-server +compatibility, where clients can detect pre-emptively if a server supports certain endpoints, and/or +provide or tune the user experience according to those versions provided, or provide a friendly +error explaining the server is too old/new for that particular client. + +# Proposal + +This proposal aims to add a similar API to the federation side; + +`GET /_matrix/federation/versions` + +Which returns a JSON object, which will contain at least one key, `versions`, with an array of +supported matrix versions, in the same format as `/client/versions`. + +## Rationale + +Today, there exists no server-server versioning, this has historically not been a problem, as +server-server communications were relatively stable, and did not change in backwards-incompatible +ways. + +However, this may change in the future, and this MSC can enable servers to specify version(s) of +federation behaviour they support. + +As such, future MSCs can rely on the fact that their intended behaviour does not need explicit +backwards compatibility detection cases, and could reliably assume the other server (can) know this +server supports its endpoint(s) with this version check. + +A wider philosophy surrounding federation endpoint deprecation is out of scope for this MSC, as the +author believes it is up to the SCT to weigh the costs and benefits of deprecating those endpoints, +with the risks of possible federation fragmentation attached to them. + +There is currently no expectation that `/client/` endpoints are mounted or listening to +federation-reachable endpoint, so this proposal wishes to address the uncomfortable situation where +a server may have to "probe" another server for its `/client/` endpoint, and fetch versions from +there. + +Furthermore, it could be useful that the set of supported matrix +versions are disjointed between the client-version `/versions` and a server-server `/versions` +endpoint, as federation endpoints may have a longer "lifetime" than client-server ones might. + +## Forwards compatibility + +Considering that this MSC was written after the general introduction of global versioning, it is +possible that a small strata of servers will not implement this endpoint, yet other servers may wish +to probe version-specific federation behavior with this endpoint. + +Thus, if a server queries this endpoint, and it does not receive an expected response, it should +also query `/federation/v1/version` to cross-check general availability of the federation endpoints. + +If this last call succeeds, the sending server should behave as if the receiving server supports all +versions from v1.1 up until the last version before the version that includes this MSC. + +## Caching + +Considering that matrix servers are designed (and often expected to) stay up for prolonged periods +of time, and may wish to send and receive much federation traffic in this period, caching could be +introduced for this endpoint. + +The cache for `/federation/versions` is valid for 24 hours, this value is chosen as to not re-request +this endpoint unnecessarily, yet allow for (relatively) quick transitions for matrix versions in +this time. + +# Unstable endpoint + +For the time in this proposal, this endpoint should be mounted on; + +`/_matrix/federation/unstable/org.matrix.mscXXXX/versions` \ No newline at end of file From e38ea67a2ace665199899b7ed4845b705ab688b0 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Fri, 11 Feb 2022 20:13:46 +0000 Subject: [PATCH 2/3] rename all the things --- ...xxx-federation-versions.md => 3723-federation-versions.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{xxxx-federation-versions.md => 3723-federation-versions.md} (97%) diff --git a/proposals/xxxx-federation-versions.md b/proposals/3723-federation-versions.md similarity index 97% rename from proposals/xxxx-federation-versions.md rename to proposals/3723-federation-versions.md index 5f5a16338..9303d82e6 100644 --- a/proposals/xxxx-federation-versions.md +++ b/proposals/3723-federation-versions.md @@ -1,4 +1,4 @@ -# MSCXXXX: Federation Versions +# MSC3723: Federation Versions This MSC aims to add a `/versions` endpoint to federation, similar to `/client/versions`. @@ -73,4 +73,4 @@ this time. For the time in this proposal, this endpoint should be mounted on; -`/_matrix/federation/unstable/org.matrix.mscXXXX/versions` \ No newline at end of file +`/_matrix/federation/unstable/org.matrix.msc3723/versions` \ No newline at end of file From 2c31a0ea9dc081084d885bda00c01429ee197836 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Sat, 12 Feb 2022 10:21:02 +0000 Subject: [PATCH 3/3] add `unstable_features` --- proposals/3723-federation-versions.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/3723-federation-versions.md b/proposals/3723-federation-versions.md index 9303d82e6..36b7a962c 100644 --- a/proposals/3723-federation-versions.md +++ b/proposals/3723-federation-versions.md @@ -21,6 +21,9 @@ This proposal aims to add a similar API to the federation side; Which returns a JSON object, which will contain at least one key, `versions`, with an array of supported matrix versions, in the same format as `/client/versions`. +This JSON object can also include a `unstable_features` object, with a mapping of feature names to +booleans, in a manner similar to `/client/versions`. + ## Rationale Today, there exists no server-server versioning, this has historically not been a problem, as