|
|
@ -311,13 +311,16 @@ in the room's history (a permalink).
|
|
|
|
A matrix.to URI has the following format, based upon the specification defined
|
|
|
|
A matrix.to URI has the following format, based upon the specification defined
|
|
|
|
in RFC 3986:
|
|
|
|
in RFC 3986:
|
|
|
|
|
|
|
|
|
|
|
|
https://matrix.to/#/<identifier>/<extra parameter>
|
|
|
|
https://matrix.to/#/<identifier>/<extra parameter>?<additional arguments>
|
|
|
|
|
|
|
|
|
|
|
|
The identifier may be a room ID, room alias, user ID, or group ID. The extra
|
|
|
|
The identifier may be a room ID, room alias, user ID, or group ID. The extra
|
|
|
|
parameter is only used in the case of permalinks where an event ID is referenced.
|
|
|
|
parameter is only used in the case of permalinks where an event ID is referenced.
|
|
|
|
The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/``
|
|
|
|
The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/``
|
|
|
|
followed by the identifier.
|
|
|
|
followed by the identifier.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The ``<additional arguments>`` and the preceeding question mark are optional and
|
|
|
|
|
|
|
|
only apply in certain circumstances, documented below.
|
|
|
|
|
|
|
|
|
|
|
|
Clients should not rely on matrix.to URIs falling back to a web server if accessed
|
|
|
|
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. For example, if
|
|
|
|
and instead should perform some sort of action within the client. For example, if
|
|
|
|
the user were to click on a matrix.to URI for a room alias, the client may open
|
|
|
|
the user were to click on a matrix.to URI for a room alias, the client may open
|
|
|
@ -331,7 +334,7 @@ Examples of matrix.to URIs are:
|
|
|
|
* Room alias: ``https://matrix.to/#/%23somewhere%3Aexample.org``
|
|
|
|
* Room alias: ``https://matrix.to/#/%23somewhere%3Aexample.org``
|
|
|
|
* Room: ``https://matrix.to/#/!somewhere%3Aexample.org``
|
|
|
|
* Room: ``https://matrix.to/#/!somewhere%3Aexample.org``
|
|
|
|
* Permalink by room: ``https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org``
|
|
|
|
* Permalink by room: ``https://matrix.to/#/!somewhere%3Aexample.org/%24event%3Aexample.org``
|
|
|
|
* Permalink by room alias: ``https://matrix.to/#/#somewhere:example.org/%24event%3Aexample.org``
|
|
|
|
* Permalink by room alias: ``https://matrix.to/#/%23somewhere:example.org/%24event%3Aexample.org``
|
|
|
|
* User: ``https://matrix.to/#/%40alice%3Aexample.org``
|
|
|
|
* User: ``https://matrix.to/#/%40alice%3Aexample.org``
|
|
|
|
* Group: ``https://matrix.to/#/%2Bexample%3Aexample.org``
|
|
|
|
* Group: ``https://matrix.to/#/%2Bexample%3Aexample.org``
|
|
|
|
|
|
|
|
|
|
|
@ -345,7 +348,53 @@ Examples of matrix.to URIs are:
|
|
|
|
appearing due to some `room versions <index.html#room-versions>`_. These slashes
|
|
|
|
appearing due to some `room versions <index.html#room-versions>`_. These slashes
|
|
|
|
should normally be encoded when producing matrix.to URIs, however.
|
|
|
|
should normally be encoded when producing matrix.to URIs, however.
|
|
|
|
|
|
|
|
|
|
|
|
.. Note::
|
|
|
|
Routing
|
|
|
|
Room ID permalinks are unroutable as there is no reliable domain to send requests
|
|
|
|
<<<<<<<
|
|
|
|
to upon receipt of the permalink. Clients should do their best route Room IDs to
|
|
|
|
|
|
|
|
where they need to go, however they should also be aware of `issue #1579 <https://github.com/matrix-org/matrix-doc/issues/1579>`_.
|
|
|
|
Room IDs are not routable on their own as there is no reliable domain to send requests
|
|
|
|
|
|
|
|
to. This is partially mitigated with the addition of a ``via`` argument on a matrix.to
|
|
|
|
|
|
|
|
URI, however the problem of routability is still present. Clients should do their best
|
|
|
|
|
|
|
|
to route Room IDs to where they need to go, however they should also be aware of
|
|
|
|
|
|
|
|
`issue #1579 <https://github.com/matrix-org/matrix-doc/issues/1579>`_.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A room (or room permalink) which isn't using a room alias should supply at least one
|
|
|
|
|
|
|
|
server using ``via`` in the ``<additional arguments>``, like so:
|
|
|
|
|
|
|
|
``https://matrix.to/!somewhere%3Aexample.org?via=example.org&via=alt.example.org``. The
|
|
|
|
|
|
|
|
parameter can be supplied multiple times to specify multiple servers to try.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The values of ``via`` are intended to be passed along as the ``server_name`` parameters
|
|
|
|
|
|
|
|
on the Client Server ``/join`` API.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
When generating room links and permalinks, the application should pick servers which
|
|
|
|
|
|
|
|
have a high probability of being in the room in the distant future. How these servers
|
|
|
|
|
|
|
|
are picked is left as an implementation detail, however the current recommendation is
|
|
|
|
|
|
|
|
to pick 3 unique servers based on the following criteria:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* The first server should be the server of the highest power level user in the room,
|
|
|
|
|
|
|
|
provided they are at least power level 50. If no user meets this criteria, pick the
|
|
|
|
|
|
|
|
most popular server in the room (most joined users). The rationale for not picking
|
|
|
|
|
|
|
|
users with power levels under 50 is that they are unlikely to be around into the
|
|
|
|
|
|
|
|
distant future while higher ranking users (and therefore servers) are less likely
|
|
|
|
|
|
|
|
to give up their power and move somewhere else. Most rooms in the public federation
|
|
|
|
|
|
|
|
have a power level 100 user and have not deviated from the default structure where
|
|
|
|
|
|
|
|
power level 50 users have moderator-style privileges.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* The second server should be the next highest server by population, or the first
|
|
|
|
|
|
|
|
highest by population if the first server was based on a user's power level. The
|
|
|
|
|
|
|
|
rationale for picking popular servers is that the server is unlikely to be removed
|
|
|
|
|
|
|
|
as the room naturally grows in membership due to that server joining users. The
|
|
|
|
|
|
|
|
server could be refused participation in the future due to server ACLs or similar,
|
|
|
|
|
|
|
|
however the chance of that happening to a server which is organically joining the
|
|
|
|
|
|
|
|
room is unlikely.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* The third server should be the next highest server by population.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* Servers which are blocked due to server ACLs should never be chosen.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* Servers which are IP addresses should never be chosen. Servers which use a domain
|
|
|
|
|
|
|
|
name are less likely to be unroutable in the future whereas IP addresses cannot be
|
|
|
|
|
|
|
|
pointed to a different location and therefore higher risk options.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
* All 3 servers should be unique from each other. If the room does not have enough users
|
|
|
|
|
|
|
|
to supply 3 servers, the application should only specify the servers it can. For example,
|
|
|
|
|
|
|
|
a room with only 2 users in it would result in maximum 2 ``via`` parameters.
|
|
|
|