From 86ab57ec4f0a7c110cbc655c84bd55405447d5b6 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Tue, 22 Aug 2023 09:50:54 -0600
Subject: [PATCH] Specify IANA-registered service name (MSC4040) (#1624)

* Specify MSC4040

* add changelog

* Fix flow of steps 4 and 5
---
 .../newsfragments/1624.deprecation            |  1 +
 .../server_server/newsfragments/1624.feature  |  1 +
 content/server-server-api.md                  | 33 ++++++++++++++++---
 3 files changed, 31 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/server_server/newsfragments/1624.deprecation
 create mode 100644 changelogs/server_server/newsfragments/1624.feature

diff --git a/changelogs/server_server/newsfragments/1624.deprecation b/changelogs/server_server/newsfragments/1624.deprecation
new file mode 100644
index 000000000..4d8c481a0
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1624.deprecation
@@ -0,0 +1 @@
+Deprecate `matrix` SRV lookup steps during server discovery, as per [MSC4040](https://github.com/matrix-org/matrix-spec-proposals/pull/4040).
\ No newline at end of file
diff --git a/changelogs/server_server/newsfragments/1624.feature b/changelogs/server_server/newsfragments/1624.feature
new file mode 100644
index 000000000..324bf07f6
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1624.feature
@@ -0,0 +1 @@
+Add `matrix-fed` SRV lookup steps to server discovery, as per [MSC4040](https://github.com/matrix-org/matrix-spec-proposals/pull/4040).
\ No newline at end of file
diff --git a/content/server-server-api.md b/content/server-server-api.md
index d0167e01e..d658e009f 100644
--- a/content/server-server-api.md
+++ b/content/server-server-api.md
@@ -148,28 +148,45 @@ to send. The process overall is as follows:
         Requests must be made with a `Host` header of
         `<delegated_hostname>:<delegated_port>`. The target server must
         present a valid certificate for `<delegated_hostname>`.
-    3.   If `<delegated_hostname>` is not an IP literal and no
+    3.  {{< added-in v="1.8" >}} If `<delegated_hostname>` is not an IP literal and no
         `<delegated_port>` is present, an SRV record is looked up for
+        `_matrix-fed._tcp.<delegated_hostname>`. This may result in another
+        hostname (to be resolved using AAAA or A records) and port.
+        Requests should be made to the resolved IP address and port with
+        a `Host` header containing the `<delegated_hostname>`. The
+        target server must present a valid certificate for
+        `<delegated_hostname>`.
+    4.  **[Deprecated]** If `<delegated_hostname>` is not an IP literal, no
+        `<delegated_port>` is present, and a `_matrix-fed._tcp.<delegated_hostname>`
+        SRV record was not found, an SRV record is looked up for
         `_matrix._tcp.<delegated_hostname>`. This may result in another
         hostname (to be resolved using AAAA or A records) and port.
         Requests should be made to the resolved IP address and port with
         a `Host` header containing the `<delegated_hostname>`. The
         target server must present a valid certificate for
         `<delegated_hostname>`.
-    4.   If no SRV record is found, an IP address is resolved using CNAME, AAAA
+    5.   If no SRV record is found, an IP address is resolved using CNAME, AAAA
         or A records. Requests are then made to the resolve IP address
         and a port of 8448, using a `Host` header of
         `<delegated_hostname>`. The target server must present a valid
         certificate for `<delegated_hostname>`.
 
-4.  If the `/.well-known` request resulted in an error response, a server is
+4.  {{< added-in v="1.8" >}} If the `/.well-known` request resulted in an error response, a server is
+    found by resolving an SRV record for `_matrix-fed._tcp.<hostname>`. This may
+    result in a hostname (to be resolved using AAAA or A records) and
+    port. Requests are made to the resolved IP address and port, with a `Host`
+    header of `<hostname>`. The target server must present a valid certificate
+    for `<hostname>`.
+
+5.  **[Deprecated]** If the `/.well-known` request resulted in an error response,
+    and a `_matrix-fed._tcp.<hostname>` SRV record was not found, a server is
     found by resolving an SRV record for `_matrix._tcp.<hostname>`. This may
     result in a hostname (to be resolved using AAAA or A records) and
     port. Requests are made to the resolved IP address and port, with a `Host`
     header of `<hostname>`. The target server must present a valid certificate
     for `<hostname>`.
 
-5.  If the `/.well-known` request returned an error response, and the
+6.  If the `/.well-known` request returned an error response, and the
     SRV record was not found, an IP address is resolved using CNAME, AAAA and A
     records. Requests are made to the resolved IP address using port
     8448 and a `Host` header containing the `<hostname>`. The target
@@ -191,6 +208,14 @@ mandated by [RFC2782](https://www.rfc-editor.org/rfc/rfc2782.html):
 > the name MUST NOT be an alias (in the sense of RFC 1034 or RFC 2181)
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+Steps 3.4 and 5 are deprecated because they use a service name not registered by IANA.
+They may be removed in a future version of the specification. Server admins are encouraged
+to use `.well-known` over any form of SRV records.
+
+The IANA registration for port 8448 and `matrix-fed` can be found [here](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=matrix-fed).
+{{% /boxes/note %}}
+
 {{% http-api spec="server-server" api="wellknown" %}}
 
 ### Server implementation