wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Specify that server names cannot be %-encoded
This commit is contained in:
Richard van der Hoff 2018-08-30 10:48:06 +01:00 • committed by GitHub
commit 6ba50fe2f6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 69 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

50
specification/appendices/identifier_grammar.rst
View file

@ -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. number of identifiers, as described below.
The server name represents the address at which the homeserver in question can 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] server_name = hostname [ ":" port ]
port = *DIGIT
where ``host`` is as defined by `RFC3986, section 3.2.2 port = *DIGIT
<https://tools.ietf.org/html/rfc3986#section-3.2.2>`_.
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: Examples of valid server names are:
@ -40,6 +64,20 @@ Examples of valid server names are:
* ``[1234:5678::abcd]`` (IPv6 literal) * ``[1234:5678::abcd]`` (IPv6 literal)
* ``[1234:5678::abcd]:5678`` (IPv6 literal with explicit port) * ``[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 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 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 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 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 ``.`` identifiers. Room versions consisting only of the characters ``0-9`` and ``.``

48
specification/server_server_api.rst
View file

@ -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 `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}}>`_. `{{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 Each matrix homeserver is identified by a server name consisting of a hostname
and an optional TLS port. 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:
.. code:: * 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.
server_name = hostname [ ":" tls_port] * Otherwise, if the port is present, then an IP address is discovered by
tls_port = *DIGIT 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 port is present then the server is discovered by looking up an AAAA or Homeservers may use SRV records to load balance requests between multiple TLS
A record for the hostname and connecting to the specified TLS port. If the port endpoints or to failover to another endpoint if an endpoint fails.
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 When making requests to servers, use the hostname of the target server in the
port should be used. ``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
When making requests to servers, use the DNS name of the target server in the ``matrix.example.org``, the ``Host`` header in the request should be
``Host`` header, regardless of the host given in the SRV record. For example, ``example.org``. If an explicit port was given in the server name, it should be
if making a request to ``example.org``, and the SRV record resolves to ``matrix. included in the ``Host`` header; otherwise, no port number should be given in
example.org``, the ``Host`` header in the request should be ``example.org``. The the ``Host`` header.
port number for target server should not appear in the ``Host`` header.
Server implementation Server implementation
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~