From 8ad82ce3c0783cacb29f0730546f738acaacd92a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 5 Apr 2019 16:24:51 -0600 Subject: [PATCH] Add permalink routing through ?via parameters on matrix.to URIs Spec for [MSC1704](https://github.com/matrix-org/matrix-doc/pull/1704) Reference implementations: * Original: https://github.com/matrix-org/matrix-react-sdk/pull/2250 * Modern recommendations: https://github.com/matrix-org/matrix-react-sdk/blob/2ca281f6b7b735bc96945370584c5cb1b5f7e1f1/src/matrix-to.js#L29-L70 The only deviation from the original MSC is the recommendation for which servers to pick. The original MSC failed to consider server ACLs and IP addresses correctly, and during implementation it was realized that both of these cases should be handled. The core principles of the original MSC are left unaltered. --- .../appendices/identifier_grammar.rst | 61 +++++++++++++++++-- 1 file changed, 55 insertions(+), 6 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 729246d0..ea805955 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -311,13 +311,16 @@ in the room's history (a permalink). A matrix.to URI has the following format, based upon the specification defined in RFC 3986: - https://matrix.to/#// + https://matrix.to/#//? 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. The matrix.to URI, when referenced, must always start with ``https://matrix.to/#/`` followed by the identifier. +The ```` 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 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 @@ -331,7 +334,7 @@ Examples of matrix.to URIs are: * Room alias: ``https://matrix.to/#/%23somewhere%3Aexample.org`` * Room: ``https://matrix.to/#/!somewhere%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`` * Group: ``https://matrix.to/#/%2Bexample%3Aexample.org`` @@ -345,7 +348,53 @@ Examples of matrix.to URIs are: appearing due to some `room versions `_. These slashes should normally be encoded when producing matrix.to URIs, however. -.. Note:: - 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 `_. +Routing +<<<<<<< + +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 `_. + +A room (or room permalink) which isn't using a room alias should supply at least one +server using ``via`` in the ````, 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.