MSC3244: Room version capabilities #3244
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,125 @@ | ||||||||||||
| # MSC3244: Room version capabilities | ||||||||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||||||||
|
|
||||||||||||
| Room version updates can bring new functionalities, for example v7 is introducing `knocking`. | ||||||||||||
|
|
||||||||||||
| There is a delay before a room version becomes the default version (when supported by enough home servers). | ||||||||||||
| And when creating rooms clients should not ask for a specific version (or else they will stick to this | ||||||||||||
| specific version unless they are updated). | ||||||||||||
|
|
||||||||||||
| So currently clients can't know before creating the room if a feature they need will be supported by the created room. | ||||||||||||
|
|
||||||||||||
| The goal of this MSC is to give the client a way to have more information on the supported features of room | ||||||||||||
| versions available on a given server, to give more feedback to users during room creation as well as | ||||||||||||
| in the room settings section. | ||||||||||||
|
|
||||||||||||
| ## Proposal | ||||||||||||
|
|
||||||||||||
| The __m.room_versions capability__ [`/_matrix/client/r0/capabilities`]([https://matrix.org/docs/spec/client_server/r0.6.1#m-room-versions-capability]) | ||||||||||||
| endpoint could be decorated to provide more information on room version capabilities. | ||||||||||||
|
Comment on lines
+25
to
+26
There was a problem hiding this comment. Malformed link/text here.
Suggested change
|
||||||||||||
|
|
||||||||||||
| Actual capabilities response: | ||||||||||||
|
There was a problem hiding this comment. I think you mean 'Current'.
Suggested change
|
||||||||||||
| ```` | ||||||||||||
|
|
||||||||||||
| { | ||||||||||||
| "capabilities": { | ||||||||||||
| "m.room_versions": { | ||||||||||||
| "default": "6", | ||||||||||||
| "available": { | ||||||||||||
| "1": "stable", | ||||||||||||
| "2": "stable", | ||||||||||||
| "3": "stable", | ||||||||||||
| "4": "stable", | ||||||||||||
| "5": "stable", | ||||||||||||
| "6": "stable",, | ||||||||||||
| "org.matrix.msc2176": "unstable", | ||||||||||||
|
There was a problem hiding this comment. is it deliberate that these unstable room versions are removed in the below example? There was a problem hiding this comment. kind of, the below example is the future compared to that one, but it was also to reduce noise There was a problem hiding this comment. okay, then need to add a line to make it clear that between the two examples, the unstable versions were stabilised. |
||||||||||||
| "org.matrix.msc3083": "unstable" | ||||||||||||
| } | ||||||||||||
| }, | ||||||||||||
| "m.change_password": {...} | ||||||||||||
| } | ||||||||||||
| } | ||||||||||||
| ```` | ||||||||||||
|
|
||||||||||||
|
|
||||||||||||
| Proposed modification | ||||||||||||
|
|
||||||||||||
| ```` | ||||||||||||
| { | ||||||||||||
| "capabilities": { | ||||||||||||
| "m.room_versions": { | ||||||||||||
| "default": "6", | ||||||||||||
| "available": { | ||||||||||||
| "1": "stable", | ||||||||||||
| "..., | ||||||||||||
| "6": "stable", | ||||||||||||
| "7": "stable", | ||||||||||||
| "8": "stable", | ||||||||||||
| "9": "stable" | ||||||||||||
| }, | ||||||||||||
| "room_capabilities": { | ||||||||||||
|
There was a problem hiding this comment. s/room_capabilities/capabilities/ ? |
||||||||||||
| "knocking" : { | ||||||||||||
|
There was a problem hiding this comment. should we not namespace these to m.knocking or whatever? if only for symmetry with all our other identifiers? There was a problem hiding this comment. will check and use same name There was a problem hiding this comment. updaded to There was a problem hiding this comment. I also agree that these attributes should be namespaced as There was a problem hiding this comment. the top level att are namespaced (m.room_versions, m.change_password) but not the content attributes (default/available/room_capabilities) |
||||||||||||
| "preferred": "7", | ||||||||||||
| "support" : ["7"] | ||||||||||||
| }, | ||||||||||||
| "restricted" : { | ||||||||||||
| "preferred": "9", | ||||||||||||
| "support" : ["8", "9"] | ||||||||||||
| } | ||||||||||||
| } | ||||||||||||
| } | ||||||||||||
| } | ||||||||||||
| } | ||||||||||||
| ```` | ||||||||||||
|
|
||||||||||||
| A new object is added under `room_capabilities`, each key is the name of a capability. | ||||||||||||
| This object provides the list of room versions supporting this capability as well as the preferred version to use. | ||||||||||||
|
|
||||||||||||
|
|
||||||||||||
| As part of this MSC, two capabilities are defined: | ||||||||||||
| - `knocking` for knocking join rule support (msc2403)[https://github.com/matrix-org/matrix-doc/pull/2403] | ||||||||||||
| - `restricted` for restricted join rule support (msc3083)[https://github.com/matrix-org/matrix-doc/pull/3083] | ||||||||||||
|
|
||||||||||||
| ## Client recommendations: | ||||||||||||
|
|
||||||||||||
| When presenting room settings, clients should use capabilities in order to display the correct UI. | ||||||||||||
|
|
||||||||||||
| For example if the room support knocking, the client should add this option in the join rule chooser | ||||||||||||
| (and if not only show `Invite Only` and `Public` for example). | ||||||||||||
|
|
||||||||||||
| When creating a room, the client could check if the needed feature is supported by the server before creating. | ||||||||||||
|
|
||||||||||||
| If the feature is not supported, the client could inform the user that this type of room can't be created | ||||||||||||
| as well as an information message explaining how to contact the home server admin. | ||||||||||||
|
|
||||||||||||
| If the feature is supported by the default room version, then just continue as usual. | ||||||||||||
|
|
||||||||||||
| If the feature is supported but by a stable room version that is not the default one, the client should | ||||||||||||
| then request to use the preferred version (`preferred`) that supports the feature, in the create room call: | ||||||||||||
|
Comment on lines
+119
to
+120
There was a problem hiding this comment. This seems to imply that unstable room versions can be included in the response. This isn't 100% clear from the examples. There was a problem hiding this comment. IMO |
||||||||||||
|
|
||||||||||||
| ```` | ||||||||||||
| POST /_matrix/client/r0/createRoom HTTP/1.1 | ||||||||||||
| Content-Type: application/json | ||||||||||||
|
|
||||||||||||
| { | ||||||||||||
| "preset": "....", | ||||||||||||
| "name": "....", | ||||||||||||
| "topic": "....", | ||||||||||||
| "creation_content": { ... } | ||||||||||||
| "room_version": "8" | ||||||||||||
| } | ||||||||||||
| ```` | ||||||||||||
|
|
||||||||||||
| If multiple capabilities are needed (e.g mscXX1 and mscXX2), and they have different `preferred` versions, clients can | ||||||||||||
BillCarsonFr marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||
| then pick one of the stable version that appears in both `support` arrays. | ||||||||||||
|
There was a problem hiding this comment. A downside of this is that you can end up on an older room version since there's no ordering, e.g.
From here you could choose 8 or 9, but which to use? Maybe it doesn't really matter. 🤷 There was a problem hiding this comment. can we say that support is ordered? There was a problem hiding this comment. I'm not sure where that information would come from though. The server doesn't really have an ordered list of room versions it prefers. |
||||||||||||
|
|
||||||||||||
| It is not recommended to use an unstable room version even if it's the only one supporting a given feature. | ||||||||||||
| It should be reserved for development. | ||||||||||||
|
|
||||||||||||
|
|
||||||||||||
| ## Unstable prefix | ||||||||||||
|
|
||||||||||||
| The following mapping will be used for identifiers in this MSC during development: | ||||||||||||
|
|
||||||||||||
|
|
||||||||||||
| Proposed final identifier | Purpose | Development identifier | ||||||||||||
| ------------------------------- | ------- | ---- | ||||||||||||
| `room_capabilities` | event type | `org.matrix.msc3244.room_capabilities` | ||||||||||||
|
There was a problem hiding this comment. PoC implementations: Uses |
||||||||||||
|
|
||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I might be missing something, but I don't see why this data needs to come from the server. Standard room version capabilities don't vary across servers, so the supported features can just be hardcoded into clients. Only the list of supported room versions will vary, but that data is already available from the endpoint.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yea... I'm not seeing what this is trying to accomplish. Room versions are meant to be frozen sets of functionality, particularly at the spec level, and not mutated over time. If someone were to create a
com.example.my_room_versionthey'd almost certainly have to figure out a nested versioning scheme because once used the room version can't change behaviour.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Currently cients never require a specific room version, and created room are using the default version at the time of creation.
If clients start hard coding room version, they will need to be continuously updated to be up to date. E.g if the default room version is updated (for security reason), the clients will force lower room version
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the idea isn't whether or not the client specifies the room version, but that the clients would encode the information in them for what features a room version supports.
The argument against this is that the servers have to know this already (e.g. Synapse's implementation), so instead of hard-coding it into each client the server could pass the information to the client.
Maybe that's over-designed though and the proper thing is to codify a similar list in the clients?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The issue with having a list in the clients is that it can get outdated. If I'm running an old client, and the server says that the default room version is "10", but the client doesn't know what room version "10" is, then it doesn't know if a room created with the default version will support knocking, or if it should specify that it wants room version "7".
Arguably, clients shouldn't be doing anything with room versions that they don't understand, but since most of the room version changes are server-side things, clients have been mostly fine just assuming that everything is (almost) the same.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The server can't really be sure it's suggesting the right values though? If a client is developed with v8 in mind, it's not going to really know if v10 will also serve its purpose, and the server definitely won't know how the client expects to function.
Room versions are non-linear, so in a hypothetical (and possibly likely down the line) scenario we could have v8 for knocking, v9 for enforced encryption, v10 for newfangled knocking+restricted cooperation, and v11 which mixes it all together. In this case, the client will want a feature called "knocking" but doesn't know that v10/11 are actually some completely new approach it has never heard of. It'd be irresponsible of the server to suggest this as a preferred version, but also it's not immediately clear what we'd do given it's keyed by feature name. Further, the server suggesting v11 could impact the user experience of the client even if the client did know about v10 (but not 11): it may very well not want to have encryption baked into the room, but the server will have suggested an unknown room version for new-knocking.
Overall, I do seriously wonder if this can be solved with process rather than tech. If we sped up the room version cutting process, would it alleviate the concerns of this MSC? Can we find a non-technical answer to communicating what is in a given room version and drive uptake?