From 6f3b42a457c7fc7973fb07847840143ffc7164e3 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 28 Aug 2018 23:56:20 +0100 Subject: [PATCH 1/8] Server names cannot be %-encoded They aren't URLs; it was a thinko to refer to the URL spec for this. --- .../appendices/identifier_grammar.rst | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index fc89f031..d068b768 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -23,13 +23,38 @@ 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 = host [ ":" port ] -where ``host`` is as defined by `RFC3986, section 3.2.2 -`_. + port = *DIGIT + + host = 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 `_. + +DNS names for use with Matrix should follow the conventional restrictions for +internet hostnames: they should consist of a series of labels separated by +dots, where each label consists of the alphanumeric characters or +hyphens. Examples of valid server names are: @@ -40,6 +65,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 `_, + 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 +90,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 ``.`` From 7f9524f8016f4cdfb35c0434cd45619859326f87 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 00:07:36 +0100 Subject: [PATCH 2/8] =?UTF-8?q?s/--/=E2=80=94/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specification/appendices/identifier_grammar.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index d068b768..e686f0c6 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -43,7 +43,7 @@ following grammar:: dns-char = DIGIT / ALPHA / "-" / "." --- in other words, the server name is the hostname, followed by an optional +— 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. From 8679a642b49d865c628ef6f598f374f273e6e8b1 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 00:19:05 +0100 Subject: [PATCH 3/8] clarity --- specification/appendices/identifier_grammar.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index e686f0c6..92db2fec 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -48,13 +48,12 @@ 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 +range 0 to 255, separated by ``.``. IPv6 literals must be as specified by `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 -dots, where each label consists of the alphanumeric characters or -hyphens. +``.``, where each label consists of the alphanumeric characters or hyphens. Examples of valid server names are: From 120bb8dc8eb3261f71dfc0b27e4b42c76003f808 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:24:24 +0100 Subject: [PATCH 4/8] s/host/hostname/ --- specification/appendices/identifier_grammar.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/appendices/identifier_grammar.rst b/specification/appendices/identifier_grammar.rst index 92db2fec..1a46ae1a 100644 --- a/specification/appendices/identifier_grammar.rst +++ b/specification/appendices/identifier_grammar.rst @@ -26,11 +26,11 @@ The server name represents the address at which the homeserver in question can be reached by other homeservers. All valid server names are included by the following grammar:: - server_name = host [ ":" port ] + server_name = hostname [ ":" port ] port = *DIGIT - host = IPv4address / "[" IPv6address "]" / dns-name + hostname = IPv4address / "[" IPv6address "]" / dns-name IPv4address = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT From 08fba5de51b09e3abecf6247218146fa917f9576 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:25:38 +0100 Subject: [PATCH 5/8] Link to grammar rather than duplicating. --- specification/server_server_api.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 439b35f9..910dab1d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -78,14 +78,7 @@ 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 - -.. ** +and an optional port, as described by the `grammar <../appendices.html#server-name>`_. 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 From 78d81188468ba80e2a6d75566a70472d35a81089 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 09:36:50 +0100 Subject: [PATCH 6/8] Further server_name clarification --- specification/server_server_api.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 910dab1d..d9edfcb3 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -80,18 +80,22 @@ Resolving Server Names Each matrix homeserver is identified by a server name consisting of a hostname and an optional port, as described by the `grammar <../appendices.html#server-name>`_. -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. +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. -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. From d493c82e82c49c8f252cb06554a51f7ef136be11 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 10:04:02 +0100 Subject: [PATCH 7/8] even more clarification --- specification/server_server_api.rst | 44 ++++++++++++++++------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index d9edfcb3..8cce792b 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -71,36 +71,40 @@ This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. -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 port, as described by the `grammar <../appendices.html#server-name>`_. +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. +* 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. +* 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. +* 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. + 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 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. +When making requests to servers, use the hostname of the target server in the +``Host`` header, regardless of the 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``. The port number for target server should **not** appear in the +``Host`` header. Server implementation ~~~~~~~~~~~~~~~~~~~~~~ From 196159be9116f2d82626296bd7eef44ee845f473 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 29 Aug 2018 22:15:38 +0100 Subject: [PATCH 8/8] We should include the Host header if the port was explicit. --- specification/server_server_api.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 8cce792b..7239c12d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -100,11 +100,12 @@ address and port using the following process: 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 the any hostname given in the SRV record. For +``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``. The port number for target server should **not** appear in the -``Host`` header. +``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 ~~~~~~~~~~~~~~~~~~~~~~