Matrix Decentralised HTTP Linking: About
Decentralised linking from the Web (HTTP contexts) to a matrix user or room.
Or, “Let’s decentralise matrix.to!”
- Overview and rationale: matrix-decentralised-http-linking-about (this document)
- The (proposed) specification: matrix-decentralised-http-linking-spec
- Discussion (matrix room):
Matrix is supposed to be a decentralised protocol [MATRIX]. While much of it is, an important part isn’t. Matrix uses
matrix.to [SPEC-TO] as a centralised mechanism for linking and invitation to matrix resources from HTTP contexts.
We can do better than centralised.
This is a proposal to fix an important part of that problem.
Why Decentralise This?
Let’s call the service that
matrix.to provides, a reception service. Somewhat like a reception desk at a conference, it receives visitors arriving in matrix from outside, introduces them to the inside, and directs them to the room or person they are looking for.
A “default” centralised reception service (
matrix.to) is an anti-pattern.
A dependency on a central resource, controlled by a single entity, is a single-point-of-failure and a single-point-of-control for a big chunk of the whole matrix system.
Although the “core” protocol of matrix is decentralised, and can in principle be used independent of “matrix.to”, in practice the use of “matrix.to” is currently part of the system, both in theory [SPEC-TO] and in practice. It is no good arguing that the “core” protocol is decentralised if the system as a whole isn’t. A system is judged as a whole.
From a corporate stand-point, that’s Business As Usual. The corporate world is accustomed to the idea of a service provider that controls the service.
From a social “Public Goods” stand-point, that’s a defect. A protocol with a significant dependency on a single resource provided by a single provider is not decentralised.
The dependency on
matrix.to is an obstacle to presenting matrix as a decentralised protocol.
Avoid a single point of failure. Avoid a single point of control. Although not everyone’s priority, to some, this is essential.
Decentralised Linking and DNS
Techniques for linking to matrix resources:
matrix:URI scheme [SPEC-URI] — truly decentralised naming scheme.
- The current
- A decentralised HTTP-based reception service.
matrix: URI scheme
matrix: URI scheme provides a way to link to matrix resources, such as
matrix:user/user1:example.net. This is a dedicated naming scheme for matrix, and support for it is gradually being added in more contexts: matrix clients, generic web browsers, and other places.
Much as we would like to see
matrix: URI scheme links supported everywhere, in web browsers and other user interfaces, however, for the foreseeable future we can only expect it will be supported in limited contexts. So this doesn’t solve the use cases in the current HTTP world.
Wide-spread linking to matrix from HTTP contexts (such as Web sites) therefore requires that we support HTTP linking.
matrix.to design uses HTTP URLs like
https://matrix.to/#/%40user1%3Aexample.net for a user id
@user1:example.net, and a similar pattern for room aliases etc.
matrix.to links are used in two ways: (1) the user follows the link as a generic HTTP URL, visiting the DNS domain
matrix.to running a web service [M.TO-SITE]; and (2) if the user’s client software is aware of matrix, it may recognise a
matrix.to URL as a special syntax [M.TO-SYNTAX] and parse it and invoke local matrix functionality, without visiting the DNS domain
The spec [SPEC-TO] states this scheme is intended to be used as a special syntax, as in usage (2) above. It notes, “This is not meant to be interpreted as an available web service” (original emphasis) and “Clients should not rely on matrix.to URIs falling back to a web server if accessed and instead should perform some sort of action within the client.” This part of the spec seems to lack an acknowledgement that its other use as a concrete domain and service (1) is essential and wide-spread in non-matrix-aware contexts such as web browsers.
The software behind the
matrix.to service [M.TO-CODE] can be run on other domains: then we say it is “self-hosted”. People using a matrix client that is under their (or their administrator’s) own control can get their client to produce links to their self-hosted domain, and of course anyone can manually produce such links. Someone following such a link will arrive at the web page of the self-hosted reception service. In this way the creator of the link decides which reception service the recipient(s) will visit.
Those setting up a self-hosted reception service could even make their own matrix clients recognise such links internally. However they cannot make other people’s clients recognise such links, because there is no agreed protocol to recognise them. A seamless experience of using such links within matrix clients therefore is only possible in a closed setting such as a private federation in an organisation that controls all its clients. Outside such a constrained environment, “self-hosted matrix.to” cannot provide a seamless linking experience in matrix clients. The proposed specification solves the issue of allowing arbitrary matrix clients to recognise links.
Matrix uses DNS-based naming for resources such as users and room-aliases (see [Scope]). DNS itself provides a natural way to route a request directly to the intended target resource. There is no need for a middle-man, no need to route the user first through a separate (central) domain before arriving at the intended domain.
As spelled out more precisely in the specification, some forms of identifier such as
!room-id:domain contain a DNS domain that is not authoritative. These are out of scope — this specification does not provide any new way to deal with these kinds of identifier.
There has been some confusion about the role of the DNS domain in matrix resource identifiers, especially in the
#room:domain identifier known as a room alias. In a room alias, the alias itself falls under DNS authority, while the room itself does not. In this regard, alias is a poor name for the relationship. The relationship rather is a pointer to the room.
Until now, users sharing a link to a matrix room have shared either a room-id (
!room-id) or a room-alias (
#room-alias:server-name-domain) and in many cases they, or their client software, have not cared to think much about distinguishing one form from the other.
(TODO: MORE about this...)
In Essence: Decentralised matrix.to
In essence, the proposed specification says: let each matrix server advertise its own reception service for its own resources, and recommend that clients and other tools should produce links that refer to the target server’s own reception service.
A matrix server’s own reception service provides a function broadly similar to a self-hosted ‘matrix-to’ service.
When a Matrix client displays a “link to this room” or “link to this matrix user” for the user to copy and share, the client first checks the well-known advertisement of the server-name of this room’s main alias, and constructs a URL pointing to that server’s *reception service* if it advertises one. (If not, it falls back to old behaviour: it constructs a URL pointing to another reception service it knows about such as
matrix.to.) User shares the resulting link.
When a person follows such a link in a general HTTP (Web) context, they visit the web page served by the reception service. If user has visited before and asked the reception service to remember their choice of client for opening the link, that works invisibly just like
matrix.to; else it will provide its own suggestions of clients that the user may like to use, and its own UI which may reflect the style and context (e.g. language) of the target.
When a person follows such a link in a context that understands decentralised matrix links, such as in a matrix-aware app, the app may resolve the link in its own way without necessarily contacting the reception service or showing the user anything. The spec defines the mechanism for this, as it already did for
The following changes are needed to existing software and systems, in order to implement the proposed specification.
Matrix.to should be made to redirect a DNS-MXID to the target resource’s own reception service:
- if it isn’t already redirecting to a matrix URI
- if it isn’t already redirecting to a chosen client
The aim is that the user will see the interface and clients and options defined by the target resource rather than the “global default” interface and clients and options offered by
A secondary aim is that the user will see that the
matrix.to link was a ‘legacy’ style of link, and will see the ‘new’ style of link, in case they care about forwarding the link elsewhere and/or updating the source of the link.
Where a matrix client provides the user with an HTTP link to a matrix resource (DNS-MXID), and the link is available for the user to copy or share (rather than only to follow), the client should discover the target resource’s own reception service and provide a link to that if available. (If such reception service is not advertised, client may use its own choice of reception service.)
Integrate support into matrix-docker-ansible-deploy.
- option to install a reception service (initially, perhaps, a self-hosted copy of the
- configure the well-known advertisement for it;
- configure self-deployed components and clients to prefer it, where any additional configuration is needed.
Operator of a French matrix server configures its link end-point with French language in its URL (e.g. “domaine.fr/matrix-à/”) and it prioritises suggestions for French-language client software.
Q: “It’s uglier than matrix.to links: now the links all start with different domains, depending on the target.”
A: Yes! Welcome to decentralisation! But note how ugliness is in the eye of the beholder. matrix.to links were beautiful only for members of the matrix.to happy-users club. The people who are unhappy or unable to use matrix.to currently have a much worse experience: these people can create links to their own self-hosted matrix.to, but matrix clients won’t recognise those links as such.
Q: “People see different landing pages depending on which matrix server the resource lives on. It breaks consistency of the Matrix on-boarding Experience.”
A: Yes! Welcome to decentralisation! That’s good, intentional, useful. Bear in mind that while the visible landing page is currently important for on-boarding, in the longer term it is a temporary inconvenience and should more and more often redirect automatically according to the user’s preference.
Q: “Every time I visit another server’s reception service, will I have to select my preferred client again?”
A: Once a client with matrix-URI support is installed and matrix-URI scheme recognised within the browser, the reception service redirects to that client without intervention for a seamless experience. For other cases... (TODO: Is there any other technique to address this, either within or outside the web browser?)
Research: Standards like Webfinger
Another aspect I wish to explore is sharing best practices with other protocols. ActivityPub/Fediverse linking is a prominent one. AFAIK they have the same problem/challenge: in general Web contexts, people often link to users or messages by posting an address of their fediverse client UI (in the matrix world, that's like linking to riot.im/app/...). Can these be automatically recognised by fediverse-aware software? Well, sometimes. They're in a better position than matrix is. They use Webfinger, as described in mastodon's docs. AFAIK usage is not yet consistent across the fediverse; I'd like to study that more.
Possibly relevant also:
Terminology | References | TODO
See in the spec: matrix-decentralised-http-linking-spec
For engaging with discussion and development of the topic, please prefer the room linked here, rather than the blog comments facility:
- Discussion (matrix room):
- email me:
- matrix me:
Donations gratefully accepted