From 1373d49b19fe4eb94fa16f13ff21e531874d9956 Mon Sep 17 00:00:00 2001 From: Valere Date: Tue, 15 Jun 2021 16:43:04 +0200 Subject: [PATCH 1/8] Room version capabilities --- proposals/323X-room-version-capabilities.md | 143 ++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 proposals/323X-room-version-capabilities.md diff --git a/proposals/323X-room-version-capabilities.md b/proposals/323X-room-version-capabilities.md new file mode 100644 index 00000000000..6dfe4ea8066 --- /dev/null +++ b/proposals/323X-room-version-capabilities.md @@ -0,0 +1,143 @@ +# MSCXXXX: Room version capabilities + +Room version updates can bring new functionalities, for example v7 is introducing `knocking`. + +There is a delay before a room version became 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 informations on the supported features of room +versions available on a given server, to give more feedbacks 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]) +enpoint could be decorated to provide more information on room version capabilities. + +Actual capabilities response: +```` +{ + "capabilities": { + "m.room_versions": { + "default": "6", + "available": { + "1": "stable", + "2": "stable", + "3": "stable", + "4": "stable", + "5": "stable", + "6": "stable",, + "org.matrix.msc2176": "unstable", + "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": { + "msc2403" : { + "best": "7", + "support" : ["7"] + }, + "msc3083" : { + "best": "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 version supporting this capability as well as the preferred version to use. + + +As part of this MSC, two capabilities are defined: +- msc2403 a.k.a knocking join rule support +- msc3083 a.k.a restricted join rule support + +## 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, 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 homeserver 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 (`best`) that supports the feature, in the create room call: + +```` +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, then the client should peek on of the common stable version +in `support`even if not defined as `best` + +It is not recommanded to use an unstable room version even if it's the only one supporting a given feature. +It should be reserved for development. + + +## Potential issues + + +## Alternatives + +```` + "room_capabilities": { + "7" : ["msc2403"], + "8" : ["msc2403", "msc3083"] + } +```` + +A new field is added under `room_capabilities`, and for each available room version a list of `string` +capabilities is provided. +The room versions are ordered, if a capabilities is supported by several unstable room version, the latest is the prefered one. + +## Security considerations + + +## 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.mscXXX.room_capabilities` From 4d45a605b890665e08346321e4e3b1017ee31d58 Mon Sep 17 00:00:00 2001 From: Valere Date: Tue, 15 Jun 2021 16:44:17 +0200 Subject: [PATCH 2/8] updated MSC number --- ...sion-capabilities.md => 3244-room-version-capabilities.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{323X-room-version-capabilities.md => 3244-room-version-capabilities.md} (97%) diff --git a/proposals/323X-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md similarity index 97% rename from proposals/323X-room-version-capabilities.md rename to proposals/3244-room-version-capabilities.md index 6dfe4ea8066..6090325a689 100644 --- a/proposals/323X-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -1,4 +1,4 @@ -# MSCXXXX: Room version capabilities +# MSC3244: Room version capabilities Room version updates can bring new functionalities, for example v7 is introducing `knocking`. @@ -140,4 +140,4 @@ The following mapping will be used for identifiers in this MSC during developmen Proposed final identifier | Purpose | Development identifier ------------------------------- | ------- | ---- -`room_capabilities` | event type | `org.matrix.mscXXX.room_capabilities` +`room_capabilities` | event type | `org.matrix.msc3244.room_capabilities` From 7cb51c4120118d0c7d6ee72140211665b6295887 Mon Sep 17 00:00:00 2001 From: Valere Date: Tue, 15 Jun 2021 16:47:34 +0200 Subject: [PATCH 3/8] spelling --- proposals/3244-room-version-capabilities.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/proposals/3244-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md index 6090325a689..5dd872a94e3 100644 --- a/proposals/3244-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -2,7 +2,7 @@ Room version updates can bring new functionalities, for example v7 is introducing `knocking`. -There is a delay before a room version became the default version (when supported by enough home servers). +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). @@ -15,7 +15,7 @@ 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]) -enpoint could be decorated to provide more information on room version capabilities. +endpoint could be decorated to provide more information on room version capabilities. Actual capabilities response: ```` @@ -70,7 +70,7 @@ Proposed modification ```` A new object is added under `room_capabilities`, each key is the name of a capability. -This object provides the list of room version supporting this capability as well as the preferred version to use. +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: @@ -84,10 +84,10 @@ When presenting room settings, clients should use capabilities in order to displ 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, client could check if the needed feature is supported by the server before creating. +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 homeserver admin. +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. @@ -110,7 +110,7 @@ Content-Type: application/json If multiple capabilities are needed, then the client should peek on of the common stable version in `support`even if not defined as `best` -It is not recommanded to use an unstable room version even if it's the only one supporting a given feature. +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. @@ -127,8 +127,9 @@ It should be reserved for development. ```` A new field is added under `room_capabilities`, and for each available room version a list of `string` -capabilities is provided. -The room versions are ordered, if a capabilities is supported by several unstable room version, the latest is the prefered one. +capabilities are provided. +The room versions are ordered, if a capability is supported by several unstable room versions, +the latest is the prefered one. ## Security considerations @@ -141,3 +142,4 @@ The following mapping will be used for identifiers in this MSC during developmen Proposed final identifier | Purpose | Development identifier ------------------------------- | ------- | ---- `room_capabilities` | event type | `org.matrix.msc3244.room_capabilities` + From bf2c58d69dee79ad6a6738c1654106ef0269112c Mon Sep 17 00:00:00 2001 From: Valere Date: Tue, 15 Jun 2021 17:39:47 +0200 Subject: [PATCH 4/8] clarify when multiple features are required --- proposals/3244-room-version-capabilities.md | 24 ++------------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/proposals/3244-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md index 5dd872a94e3..8027b79aa50 100644 --- a/proposals/3244-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -107,33 +107,13 @@ Content-Type: application/json } ```` -If multiple capabilities are needed, then the client should peek on of the common stable version -in `support`even if not defined as `best` +If multiple capabilities are needed (e.g mscXX1 and mscXX2), and they have different `best`versions, clients can +then pick one of the stable version that appears in both `support` array. 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. -## Potential issues - - -## Alternatives - -```` - "room_capabilities": { - "7" : ["msc2403"], - "8" : ["msc2403", "msc3083"] - } -```` - -A new field is added under `room_capabilities`, and for each available room version a list of `string` -capabilities are provided. -The room versions are ordered, if a capability is supported by several unstable room versions, -the latest is the prefered one. - -## Security considerations - - ## Unstable prefix The following mapping will be used for identifiers in this MSC during development: From 7fdc96db28b0147f23572fec01753bdcb93422e9 Mon Sep 17 00:00:00 2001 From: Valere Date: Wed, 16 Jun 2021 09:11:01 +0200 Subject: [PATCH 5/8] changes from uhoreg review --- proposals/3244-room-version-capabilities.md | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/proposals/3244-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md index 8027b79aa50..c0eff8042c3 100644 --- a/proposals/3244-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -8,8 +8,8 @@ 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 informations on the supported features of room -versions available on a given server, to give more feedbacks to users during room creation as well as +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 @@ -55,12 +55,12 @@ Proposed modification "9": "stable" }, "room_capabilities": { - "msc2403" : { - "best": "7", + "knocking" : { + "preferred": "7", "support" : ["7"] }, - "msc3083" : { - "best": "9", + "restricted" : { + "preferred": "9", "support" : ["8", "9"] } } @@ -74,8 +74,8 @@ This object provides the list of room versions supporting this capability as wel As part of this MSC, two capabilities are defined: -- msc2403 a.k.a knocking join rule support -- msc3083 a.k.a restricted join rule support +- `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: @@ -92,7 +92,7 @@ as well as an information message explaining how to contact the home server admi 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 (`best`) that supports the feature, in the create room call: +then request to use the preferred version (`preferred`) that supports the feature, in the create room call: ```` POST /_matrix/client/r0/createRoom HTTP/1.1 @@ -107,8 +107,8 @@ Content-Type: application/json } ```` -If multiple capabilities are needed (e.g mscXX1 and mscXX2), and they have different `best`versions, clients can -then pick one of the stable version that appears in both `support` array. +If multiple capabilities are needed (e.g mscXX1 and mscXX2), and they have different `preferred` versions, clients can +then pick one of the stable version that appears in both `support` arrays. 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. From 15a1c2e3d2d977819a7d9d1949d141e24a4b441f Mon Sep 17 00:00:00 2001 From: Valere Date: Mon, 21 Jun 2021 10:15:50 +0200 Subject: [PATCH 6/8] Clarify goal of this MSC --- proposals/3244-room-version-capabilities.md | 41 ++++++++++++++------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/proposals/3244-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md index c0eff8042c3..74f2f3a5331 100644 --- a/proposals/3244-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -1,12 +1,20 @@ # MSC3244: Room version capabilities -Room version updates can bring new functionalities, for example v7 is introducing `knocking`. +When a new room version is introduced there is a delay before it becames the default +version. This delay is related to support of this new room version across the federation. +If a Home Server were to switch the new version as default to early, it will lock out all other users +that are on Home Servers that do not understand this version. -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). +But however the new room version might add an interesting feature that some client on some Home +Servers might want to use earlier. One solution might be for the client to explicitly request a +version when creating a room but it's a bad practice to force a room version. -So currently clients can't know before creating the room if a feature they need will be supported by the created room. +If the client is forcing a room version, and server side a new version is added (that support the needed +feature) the client will still use the old one until it's updated. + +As an example v7 is introducing `knock` but it's not default yet, it would be nice for client to +start using it until it is supported by the default version and to also use the latest stable version that +supports this feature in the future. 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 @@ -29,7 +37,7 @@ Actual capabilities response: "3": "stable", "4": "stable", "5": "stable", - "6": "stable",, + "6": "stable", "org.matrix.msc2176": "unstable", "org.matrix.msc3083": "unstable" } @@ -39,7 +47,8 @@ Actual capabilities response: } ```` -Proposed modification +Proposed modification. +In the following hypothetical sample, 3 new versions has been introduced (7, 8 and 9) but 6 is still the default. ```` { @@ -52,10 +61,11 @@ Proposed modification "6": "stable", "7": "stable", "8": "stable", - "9": "stable" + "9": "stable", + "org.matrix.msc6789": "unstable", }, "room_capabilities": { - "knocking" : { + "knock" : { "preferred": "7", "support" : ["7"] }, @@ -74,11 +84,15 @@ This object provides the list of room versions supporting this capability as wel 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] +- `knock` 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: +__Notice__: In real world usage most of the time clients should not specify a room version when creating +a room, and should let the Home Server select the correct one (via their knowledgeable server admin). +This is an advanced mechanism to start using feature early. + 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 @@ -107,11 +121,10 @@ Content-Type: application/json } ```` -If multiple capabilities are needed (e.g mscXX1 and mscXX2), and they have different `preferred` versions, clients can -then pick one of the stable version that appears in both `support` arrays. +In the hypothetical scenario where multiple capabilities would be needed (e.g mscXX1 and mscXX2), and have different `preferred` versions, clients can then pick one of the stable version that appears in both `support` arrays. -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. +Notice that, 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. This MSC is only about default version not about unstable. ## Unstable prefix From bdd164c8a3dc3b0472e947f5bb2f70a394cb13b3 Mon Sep 17 00:00:00 2001 From: Valere Date: Tue, 29 Jun 2021 17:03:43 +0200 Subject: [PATCH 7/8] Update proposals/3244-room-version-capabilities.md Co-authored-by: Patrick Cloke --- proposals/3244-room-version-capabilities.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/proposals/3244-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md index 74f2f3a5331..8f34c31f66f 100644 --- a/proposals/3244-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -84,8 +84,8 @@ This object provides the list of room versions supporting this capability as wel As part of this MSC, two capabilities are defined: -- `knock` 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] +- `knock` 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: @@ -135,4 +135,3 @@ The following mapping will be used for identifiers in this MSC during developmen Proposed final identifier | Purpose | Development identifier ------------------------------- | ------- | ---- `room_capabilities` | event type | `org.matrix.msc3244.room_capabilities` - From 8cd99ccd2a0e55c2b2cde49c2a9bcae2c29b0aa5 Mon Sep 17 00:00:00 2001 From: Valere Date: Mon, 19 Jul 2021 17:35:38 +0200 Subject: [PATCH 8/8] review - clarify that preferred uses only stable versions --- proposals/3244-room-version-capabilities.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/proposals/3244-room-version-capabilities.md b/proposals/3244-room-version-capabilities.md index 8f34c31f66f..1ac351c21d4 100644 --- a/proposals/3244-room-version-capabilities.md +++ b/proposals/3244-room-version-capabilities.md @@ -82,6 +82,17 @@ In the following hypothetical sample, 3 new versions has been introduced (7, 8 a 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. +`preferred` should never point to an unstable version. When a feature is only supported by an unstable version, `preferred`should be set to null, and the unstable versions would be listed in `support`. + +```` +"restricted": { + "preferred": null, + "support": [ + "org.matrix.msc3083" + ] +} +```` + As part of this MSC, two capabilities are defined: - `knock` for knocking join rule support [MSC2403](https://github.com/matrix-org/matrix-doc/pull/2403)