Skip to content

Latest commit

 

History

History
148 lines (116 loc) · 5.39 KB

3244-room-version-capabilities.md

File metadata and controls

148 lines (116 loc) · 5.39 KB

MSC3244: Room version capabilities

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.

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.

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 in the room settings section.

Proposal

The m.room_versions capability /_matrix/client/r0/capabilities endpoint 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. In the following hypothetical sample, 3 new versions has been introduced (7, 8 and 9) but 6 is still the default.

{
  "capabilities": {
    "m.room_versions": {
      "default": "6",
      "available": {
        "1": "stable",
        "...,
        "6": "stable",
        "7": "stable",
        "8": "stable",
        "9": "stable",
        "org.matrix.msc6789": "unstable",
      },
      "room_capabilities": {
          "knock" : {
              "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.

preferred should never point to an unstable version. When a feature is only supported by an unstable version, preferredshould 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
  • restricted for restricted join rule support MSC3083

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 (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:

POST /_matrix/client/r0/createRoom HTTP/1.1
Content-Type: application/json

{
  "preset": "....",
  "name": "....",
  "topic": "....",
  "creation_content": { ... }
  "room_version": "8"
}

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.

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

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