Add a mechanism for redirecting clients after login

Implements https://github.com/matrix-org/matrix-doc/pull/1730

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

@@ -0,0 +1,39 @@
+# Copyright 2019 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: Discovery Information
+description: |-
+  Used by clients to determine the homeserver, identity server, and other
+  optional components they should be interacting with.
+type: object
+properties:
+  "m.homeserver":
+    $ref: "homeserver.yaml"
+  "m.identity_server":
+    $ref: "identity_server.yaml"
+additionalProperties:
+  type: object
+  description: Application-dependent keys using Java package naming convention.
+required:
+  - m.homeserver
+example: {
+  "m.homeserver": {
+    "base_url": "https://matrix.example.com"
+  },
+  "m.identity_server": {
+    "base_url": "https://identity.example.com"
+  },
+  "org.example.custom.property": {
+    "app_url": "https://custom.app.example.org"
+  }
+}

api/client-server/login.yaml

@@ -139,7 +139,15 @@ paths:
             application/json: {
                 "user_id": "@cheeky_monkey:matrix.org",
                 "access_token": "abc123",
-                "device_id": "GHTYAJCE"
+                "device_id": "GHTYAJCE",
+                "well_known": {
+                  "m.homeserver": {
+                    "base_url": "https://example.org"
+                  },
+                  "m.identity_server": {
+                    "base_url": "https://id.example.org"
+                  }
+                }
               }
           schema:
             type: object
@@ -166,6 +174,14 @@ paths:
                 description: |-
                   ID of the logged-in device. Will be the same as the
                   corresponding parameter in the request, if one was specified.
+              well_known:
+                type: object
+                description: |-
+                  Optional client configuration provided by the server. If present,
+                  clients SHOULD ise the provided object to reconfigure themselves,
+                  optionally validating the URLs within. This object takes the same
+                  form as the one returned from .well-known autodiscovery.
+                "$ref": "definitions/wellknown/full.yaml"
         400:
           description: |-
             Part of the request was invalid. For example, the login type may not be recognised.

api/client-server/wellknown.yaml

@@ -38,28 +38,9 @@ paths:
       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
+            "$ref": "definitions/wellknown/full.yaml"
         404:
           description: No server discovery information available.
       tags: