Merge pull request #1359 from uhoreg/well-known

.well-known discovery

api/client-server/definitions/wellknown/homeserver.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+title: Homeserver Information
+description: |-
+  Used by clients to discover homeserver information.
+type: object
+properties:
+  base_url:
+    type: string
+    description: The base URL for the homeserver for client-server connections.
+    example: https://matrix.example.com
+required:
+  - base_url

api/client-server/definitions/wellknown/identity_server.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+title: Identity Server Information
+description: |-
+  Used by clients to discover identity server information.
+type: object
+properties:
+  base_url:
+    type: string
+    description: The base URL for the identity server for client-server connections.
+    example: https://identity.example.com
+required:
+  - base_url

api/client-server/wellknown.yaml

@@ -0,0 +1,66 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Server Discovery API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+basePath: /.well-known
+produces:
+  - application/json
+paths:
+  "/matrix/client":
+    get:
+      summary: Gets Matrix server discovery information about the domain.
+      description: |-
+        Gets discovery information about the domain. The file may include
+        additional keys, which MUST follow the Java package naming convention,
+        e.g. ``com.example.myapp.property``. This ensures property names are
+        suitably namespaced for each application and reduces the risk of
+        clashes.
+
+        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
+      responses:
+        200:
+          description: Server discovery information.
+          examples:
+            application/json: {
+                "m.homeserver": {
+                  "base_url": "https://matrix.example.com"
+                },
+                "m.identity_server": {
+                  "base_url": "https://identity.example.com"
+                }
+              }
+          schema:
+            type: object
+            properties:
+              m.homeserver:
+                description: Information about the homeserver to connect to.
+                "$ref": "definitions/wellknown/homeserver.yaml"
+              m.identity_server:
+                description: Optional. Information about the identity server to connect to.
+                "$ref": "definitions/wellknown/identity_server.yaml"
+            additionalProperties:
+              description: Application-dependent keys using Java package naming convention.
+            required:
+              - m.homeserver
+        404:
+          description: No server discovery information available.
+      tags:
+        - Server administration

changelogs/client_server/newsfragments/1359.feature

@@ -0,0 +1 @@
+Add ``.well-known`` server discovery method

specification/client_server_api.rst

@@ -189,6 +189,82 @@ headers to be returned by servers on all requests are:
   Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
   Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
 
+Server Discovery
+----------------
+
+In order to allow users to connect to a Matrix server without needing to
+explicitly specify the homeserver's URL or other parameters, clients SHOULD use
+an auto-discovery mechanism to determine the server's URL based on a user's
+Matrix ID. Auto-discovery should only be done at login time.
+
+In this section, the following terms are used with specific meanings:
+
+``PROMPT``
+  Retrieve the specific piece of information from the user in a way which
+  fits within the existing client user experience, if the client is inclined to
+  do so. Failure can take place instead if no good user experience for this is
+  possible at this point.
+
+``IGNORE``
+  Stop the current auto-discovery mechanism. If no more auto-discovery
+  mechanisms are available, then the client may use other methods of
+  determining the required parameters, such as prompting the user, or using
+  default values.
+
+``FAIL_PROMPT``
+  Inform the user that auto-discovery failed due to invalid/empty data and
+  ``PROMPT`` for the parameter.
+
+``FAIL_ERROR``
+  Inform the user that auto-discovery did not return any usable URLs. Do not
+  continue further with the current login process. At this point, valid data
+  was obtained, but no homeserver 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
+~~~~~~~~~~~~~~
+
+The ``.well-known`` method uses a JSON file at a predetermined location to
+specify parameter values. The flow for this method is as follows:
+
+1. Extract the server name from the user's Matrix ID by splitting the Matrix ID
+   at the first colon.
+2. Extract the hostname from the server name.
+3. Make a GET request to ``https://hostname/.well-known/matrix/client``.
+
+   a. If the returned status code is 404, then ``IGNORE``.
+   b. If the returned status code is not 200, or the response body is empty,
+      then ``FAIL_PROMPT``.
+   c. Parse the response body as a JSON object
+
+      i. If the content cannot be parsed, then ``FAIL_PROMPT``.
+
+   d. Extract the ``base_url`` value from the ``m.homeserver`` property. This
+      value is to be used as the base URL of the homeserver.
+
+      i. If this value is not provided, then ``FAIL_PROMPT``.
+
+   e. Validate the homeserver base URL:
+
+      i. Parse it as a URL. If it is not a URL, then ``FAIL_ERROR``.
+      ii. Clients SHOULD validate that the URL points to a valid homeserver
+          before accepting it by connecting to the |/_matrix/client/versions|_
+          endpoint, ensuring that it does not return an error, and parsing and
+          validating that the data conforms with the expected response
+          format. If any step in the validation fails, then
+          ``FAIL_ERROR``. Validation is done as a simple check against
+          configuration errors, in order to ensure that the discovered address
+          points to a valid homeserver.
+
+   f. If the ``m.identity_server`` property is present, extract the
+      ``base_url`` value for use as the base URL of the identity server.
+      Validation for this URL is done as in the step above, but using
+      ``/_matrix/identity/api/v1`` as the endpoint to connect to. If the
+      ``m.identity_server`` property is present, but does not have a
+      ``base_url`` value, then ``FAIL_ERROR``.
+
+{{wellknown_cs_http_api}}
 
 Client Authentication
 ---------------------
@@ -1596,5 +1672,8 @@ have to wait in milliseconds before they can try again.
 .. |/user/<user_id>/account_data/<type>| replace:: ``/user/<user_id>/account_data/<type>``
 .. _/user/<user_id>/account_data/<type>: #put-matrix-client-%CLIENT_MAJOR_VERSION%-user-userid-account-data-type
 
+.. |/_matrix/client/versions| replace:: ``/_matrix/client/versions``
+.. _/_matrix/client/versions: #get-matrix-client-versions
+
 .. _`Unpadded Base64`:  ../appendices.html#unpadded-base64
 .. _`3PID Types`:  ../appendices.html#pid-types