Merge pull request #1955 from matrix-org/travis/spec/1704

Add permalink routing through ?via parameters on matrix.to URIs

proposals/1704-matrix.to-permalinks.md

@@ -33,4 +33,7 @@ is to pick up to 3 unique servers where the first one is that of the user with t
 highest power level in the room, provided that power level is 50 or higher. The other
 2 servers should be the most popular servers in the room based on the number of joined
 users. This same heuristic should apply to the first server if no user meets the power
-level requirements.
+level requirements. Servers blocked by server ACLs should not be picked because they
+are unlikely to continue being residents of the room. Similarly, IP addresses should
+not be picked because they cannot be redirected to another location like domain names
+can, making them a higher risk option.

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/#/<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
 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 ``<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
 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 <index.html#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 <https://github.com/matrix-org/matrix-doc/issues/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 <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.