Merge pull request #1588 from matrix-org/rav/fix_server_name

Specify that server names cannot be %-encoded

specification/appendices/identifier_grammar.rst

@@ -23,13 +23,37 @@ A homeserver is uniquely identified by its server name. This value is used in a
 number of identifiers, as described below.
 
 The server name represents the address at which the homeserver in question can
-be reached by other homeservers. The complete grammar is::
+be reached by other homeservers. All valid server names are included by the
+following grammar::
 
-    server_name = host [ ":" port]
-    port = *DIGIT
+    server_name = hostname [ ":" port ]
 
-where ``host`` is as defined by `RFC3986, section 3.2.2
-<https://tools.ietf.org/html/rfc3986#section-3.2.2>`_.
+    port        = *DIGIT
+
+    hostname    = IPv4address / "[" IPv6address "]" / dns-name
+
+    IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT
+
+    IPv6address = 2*45IPv6char
+
+    IPv6char    = DIGIT / %x41-46 / %x61-66 / ":" / "."
+                      ; 0-9, A-F, a-f, :, .
+
+    dns-name    = *255dns-char
+
+    dns-char    = DIGIT / ALPHA / "-" / "."
+
+— in other words, the server name is the hostname, followed by an optional
+numeric port specifier. The hostname may be a dotted-quad IPv4 address literal,
+an IPv6 address literal surrounded with square brackets, or a DNS name.
+
+IPv4 literals must be a sequence of four decimal numbers in the
+range 0 to 255, separated by ``.``. IPv6 literals must be as specified by
+`RFC3513, section 2.2 <https://tools.ietf.org/html/rfc3513#section-2.2>`_.
+
+DNS names for use with Matrix should follow the conventional restrictions for
+internet hostnames: they should consist of a series of labels separated by
+``.``, where each label consists of the alphanumeric characters or hyphens.
 
 Examples of valid server names are:
 
@@ -40,6 +64,20 @@ Examples of valid server names are:
 * ``[1234:5678::abcd]`` (IPv6 literal)
 * ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port)
 
+.. Note::
+
+   This grammar is based on the standard for internet host names, as specified
+   by `RFC1123, section 2.1 <https://tools.ietf.org/html/rfc1123#page-13>`_,
+   with an extension for IPv6 literals.
+
+Server names must be treated case-sensitively: in other words,
+``@user:matrix.org`` is a different person from ``@user:MATRIX.ORG``.
+
+Some recommendations for a choice of server name follow:
+
+* The length of the complete server name should not exceed 230 characters.
+* Server names should not use upper-case characters.
+
 
 Room Versions
 ~~~~~~~~~~~~~
@@ -51,7 +89,7 @@ not understanding the new rules.
 
 A room version is defined as a string of characters which MUST NOT exceed 32
 codepoints in length. Room versions MUST NOT be empty and SHOULD contain only
-the characters ``a-z``, ``0-9``, ``.``, and ``-``. 
+the characters ``a-z``, ``0-9``, ``.``, and ``-``.
 
 Room versions are not intended to be parsed and should be treated as opaque
 identifiers. Room versions consisting only of the characters ``0-9`` and ``.``

specification/server_server_api.rst

@@ -71,39 +71,41 @@ This version of the specification is generated from
 `matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
 `{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
 
-Server Discovery
+Server discovery
 ----------------
 
-Resolving Server Names
+Resolving server names
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Each matrix homeserver is identified by a server name consisting of a hostname
-and an optional TLS port.
-
-.. code::
-
-    server_name = hostname [ ":" tls_port]
-    tls_port = *DIGIT
-
-.. **
-
-If the port is present then the server is discovered by looking up an AAAA or
-A record for the hostname and connecting to the specified TLS port. If the port
-is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV
-record for the hostname. If this record does not exist then the server is
-discovered by looking up an AAAA or A record on the hostname and taking the
-default fallback port number of 8448.
-Homeservers may use SRV records to load balance requests between multiple TLS
-endpoints or to failover to another endpoint if an endpoint fails.
-
-If the DNS name is a literal IP address, the port specified or the fallback
-port should be used.
-
-When making requests to servers, use the DNS name of the target server in the
-``Host`` header, regardless of the host given in the SRV record. For example,
-if making a request to ``example.org``, and the SRV record resolves to ``matrix.
-example.org``, the ``Host`` header in the request should be ``example.org``. The
-port number for target server should not appear in the ``Host`` header.
+and an optional port, as described by the `grammar
+<../appendices.html#server-name>`_.  Server names should be resolved to an IP
+address and port using the following process:
+
+* If the hostname is an IP literal, then that IP address should be used,
+  together with the given port number, or 8448 if no port is given.
+
+* Otherwise, if the port is present, then an IP address is discovered by
+  looking up an AAAA or A record for the hostname, and the specified port is
+  used.
+
+* If the hostname is not an IP literal and no port is given, the server is
+  discovered by first looking up a ``_matrix._tcp`` SRV record for the
+  hostname, which may give a hostname (to be looked up using AAAA or A queries)
+  and port.  If the SRV record does not exist, then the server is discovered by
+  looking up an AAAA or A record on the hostname and taking the default
+  fallback port number of 8448.
+
+  Homeservers may use SRV records to load balance requests between multiple TLS
+  endpoints or to failover to another endpoint if an endpoint fails.
+
+When making requests to servers, use the hostname of the target server in the
+``Host`` header, regardless of any hostname given in the SRV record. For
+example, if the server name is ``example.org``, and the SRV record resolves to
+``matrix.example.org``, the ``Host`` header in the request should be
+``example.org``.  If an explicit port was given in the server name, it should be
+included in the ``Host`` header; otherwise, no port number should be given in
+the ``Host`` header.
 
 Server implementation
 ~~~~~~~~~~~~~~~~~~~~~~