Merge 339ea6be12 into ca9c376076

* Clarify Well-Known URIs

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

* Fix section link

---------

Signed-off-by: HarHarLinks <2803622+HarHarLinks@users.noreply.github.com>

changelogs/client_server/newsfragments/2109.clarification

@@ -0,0 +1 @@
+Spaces are subject to the same access mechanisms as rooms.

changelogs/client_server/newsfragments/2140.clarification

@@ -0,0 +1 @@
+Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

changelogs/server_server/newsfragments/2140.clarification

@@ -0,0 +1 @@
+Clarify that Well-Known URIs are available on the server name's hostname. Contributed by @HarHarLinks.

content/client-server-api/_index.md

@@ -371,15 +371,23 @@ valid data was obtained, but no server is available to serve the client.
 No further guess should be attempted and the user should make a
 conscientious decision what to do next.
 
-### Well-known URI
+### Well-known URIs
+
+Matrix facilitates automatic discovery for the Client-Server API base URL and more via the
+[RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615) "Well-Known URI" method.
+This method uses JSON files at a predetermined location on the root path `/.well-known/` to
+specify parameter values.
 
 {{% boxes/note %}}
+Diverging from the rest of the endpoints in the Client-Server spec, these files can not be provided
+on the base URL that the Client-Server API is reachable on, as it is yet to be discovered.
+Instead, they can be reached via HTTPS on the [server name](/appendices/#server-name)'s hostname as domain.
+
 Servers hosting the `.well-known` JSON file SHOULD offer CORS headers,
 as per the [CORS](#web-browser-clients) section in this specification.
 {{% /boxes/note %}}
 
-The `.well-known` method uses a JSON file at a predetermined location to
+The flow for auto-discovery is as follows:
-specify parameter values. The flow for this method is as follows:
 
 1.  Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the
     Matrix ID at the first colon.
@@ -415,10 +423,17 @@ specify parameter values. The flow for this method is as follows:
 
 {{% http-api spec="client-server" api="wellknown" %}}
 
-{{% http-api spec="client-server" api="versions" %}}
-
 {{% http-api spec="client-server" api="support" %}}
 
+### API Versions
+
+Upon connecting, the Matrix client and server need to negotiate which version of the specification
+they commonly support, as the API evolves over time. The server advertises its supported versions
+and optionally unstable features to the client, which can then go on to make requests to the
+endpoints it supports.
+
+{{% http-api spec="client-server" api="versions" %}}
+
 ## Client Authentication
 
 Most API endpoints require the user to identify themselves by presenting

content/client-server-api/modules/spaces.md

@@ -2,8 +2,8 @@
 
 {{% added-in v="1.2" %}}
 
-Often used to group rooms of similar subject matter (such as a public "Official
+Often used to group rooms of similar subject matter (such as an "Official
-matrix.org rooms" space or personal "Work stuff" space), spaces are a way to
+matrix.org rooms" space or a "Work stuff" space), spaces are a way to
 organise rooms while being represented as rooms themselves.
 
 A space is defined by the [`m.space` room type](#types), making it known as a
@@ -19,10 +19,10 @@ go a step further and explicitly ignore notification counts on space-rooms.
 
 Membership of a space is defined and controlled by the existing mechanisms which
 govern a room: [`m.room.member`](#mroommember), [`m.room.history_visibility`](#mroomhistory_visibility),
-and [`m.room.join_rules`](#mroomjoin_rules). Public spaces are encouraged to have
+and [`m.room.join_rules`](#mroomjoin_rules). Canonical aliases and invites, including
-a similar setup to public rooms: `world_readable` history visibility, published
+third-party invites, still work just as they do in normal rooms as well. Furthermore,
-canonical alias, and suitably public `join_rule`. Invites, including third-party
+spaces can also be published in the [room directory](#room-directory) to make them
-invites, still work just as they do in normal rooms as well.
+discoverable.
 
 All other aspects of regular rooms are additionally carried over, such as the
 ability to set arbitrary state events, hold room account data, etc. Spaces are
@@ -87,10 +87,9 @@ the state of `#space:example.org` would consist of:
 }
 ```
 
-No state events in the child rooms themselves would be required (though they
+No state events in the child rooms themselves would be required (though they can also
-can also be present). This allows for users
+be present). This allows for users to define spaces without needing explicit permission
-to define personal/private spaces to organise their own rooms without needing explicit
+from the room moderators/admins.
-permission from the room moderators/admins.
 
 Child rooms can be removed from a space by omitting the `via` key of `content` on the
 relevant state event, such as through redaction or otherwise clearing the `content`.

content/server-server-api.md

@@ -119,7 +119,8 @@ to send. The process overall is as follows:
     server must present a valid certificate for the hostname.
 
 3.  If the hostname is not an IP literal, a regular HTTPS request is
-    made to `https://<hostname>/.well-known/matrix/server`, expecting
+    made to `https://<hostname>/.well-known/matrix/server` (according to 
+    [RFC 8615](https://datatracker.ietf.org/doc/html/rfc8615)), expecting
     the schema defined later in this section. 30x redirects should be
     followed, however redirection loops should be avoided. Responses
     (successful or otherwise) to the `/.well-known` endpoint should be

data/api/client-server/support.yaml

@@ -22,9 +22,12 @@ paths:
       description: |-
         Gets server admin contact and support page of the domain.
 
-        Like the [well-known discovery URI](/client-server-api/#well-known-uri),
+        {{% boxes/note %}}
-        this should be accessed with the hostname of the homeserver by making a
+        Like the [well-known discovery URI](/client-server-api/#well-known-uris),
+        this endpoint should be accessed with the hostname of the homeserver's
+        [server name](/appendices/#server-name) by making a
         GET request to `https://hostname/.well-known/matrix/support`.
+        {{% /boxes/note %}}
 
         Note that this endpoint is not necessarily handled by the homeserver.
         It may be served by another webserver, used for discovering support

data/api/client-server/wellknown.yaml

@@ -26,6 +26,12 @@ paths:
         suitably namespaced for each application and reduces the risk of
         clashes.
 
+        {{% boxes/note %}}
+        This endpoint should be accessed with the hostname of the homeserver's
+        [server name](/appendices/#server-name) by making a
+        GET request to `https://hostname/.well-known/matrix/client`.
+        {{% /boxes/note %}}
+
         Note that this endpoint is not necessarily handled by the homeserver,
         but by another webserver, to be used for discovering the homeserver URL.
       operationId: getWellknown

data/api/server-server/wellknown.yaml

@@ -24,6 +24,12 @@ paths:
         Gets information about the delegated server for server-server communication
         between Matrix homeservers. Servers should follow 30x redirects, carefully
         avoiding redirect loops, and use normal X.509 certificate validation.
+
+        {{% boxes/note %}}
+        This endpoint should be accessed with the hostname of the homeserver's
+        [server name](/appendices/#server-name) by making a
+        GET request to `https://hostname/.well-known/matrix/server`.
+        {{% /boxes/note %}}
       operationId: getWellKnown
       responses:
         "200":