Implement auto-discovery of the Client APIs (Home, Identity) endpoints

[maxidorius]

There is currently no official way in the spec to discover the client endpoint for a given Matrix domain, which would be the equivalent of the SRV record for the S2S API.

Following several conversations and exchanges [1] [2], we'll use a .well-known URL [RFC 5785].

For the domain example.org, the discovery URL will be: https://example.org/.well-known/matrix It will return a status code 200 and body as JSON object like so:

{
  "m.hs": {
    "base_urls": [
      "https://a.mxhsd.example.org",
      "https://b.mxhsd.example.org",
      "https://c.mxhsd.example.org/with/prefix/path",
      "https://d.mxhsd.example.org:12345"
    ]
  },
  "m.is": {
    "base_urls": [
      "https://a.mxisd.example.org",
      "https://b.mxisd.example.org",
      "https://c.mxisd.example.org/with/prefix/path",
      "https://d.mxisd.example.org:12345"
    ]
  },
  "im.vector.riot.integrations": {
    "ui_url": "https://dimension.example.org/riot",
    "rest_url": "https://dimension.example.org/api/v1/scalar",
    "widgets_urls": [
      "https://dimension.example.org/widgets"
    ]
  }
}

For base_urls in m.hs and m.is:

• Will not include the /_matrix/... path.
• Will be tried in order, going to the next in case of error.
• A Base URL is valid if:
  • For m.hs, /_matrix/client/versions is reachable and contains valid data
  • For m.is, /_matrix/identity/versions is reachable and contains valid data

Every other entry will be DNS namespace, like other parts of the Matrix protocol, so custom features in clients can also receive dedicated configuration, or rely on other other clients supported configuration. In this case, im.vector.riot.integrations would reference to the Riot Integration Manager and any other client that supports it.

/_matrix/identity/versions will be defined at https://kamax.io/matrix/api/identity_service/unstable.html

This implementation will be documented at https://kamax.io/matrix/api/client_server/unstable.html

[maxidorius]

This has been turned into a Google Docs proposal.

[maxidorius]

Done in #26