Merge branch 'master' into travis/spec-reason

api/client-server/content-repo.yaml

@@ -100,6 +100,7 @@ paths:
           name: allow_remote
           x-example: false
           required: false
+          default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
             remote. This is to prevent routing loops where the server contacts itself. Defaults to 
@@ -154,6 +155,7 @@ paths:
           name: allow_remote
           x-example: false
           required: false
+          default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
             remote. This is to prevent routing loops where the server contacts itself. Defaults to 
@@ -221,6 +223,7 @@ paths:
           name: allow_remote
           x-example: false
           required: false
+          default: true
           description: |
             Indicates to the server that it should not attempt to fetch the media if it is deemed
             remote. This is to prevent routing loops where the server contacts itself. Defaults to 
@@ -296,3 +299,44 @@ paths:
             "$ref": "definitions/error.yaml"
       tags:
         - Media
+  "/config":
+    get:
+      summary: Get the configuration for the content repository.
+      description: |-
+        This endpoint allows clients to retrieve the configuration of the content
+        repository, such as upload limitations.
+        Clients SHOULD use this as a guide when using content repository endpoints.
+        All values are intentionally left optional. Clients SHOULD follow
+        the advice given in the field description when the field is not available.
+
+        **NOTE:** Both clients and server administrators should be aware that proxies
+        between the client and the server may affect the apparent behaviour of content
+        repository APIs, for example, proxies may enforce a lower upload size limit
+        than is advertised by the server on this endpoint.
+      operationId: getConfig
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The public content repository configuration for the matrix server.
+          schema:
+            type: object
+            properties:
+              m.upload.size:
+                type: number
+                description: |- 
+                  The maximum size an upload can be in bytes.
+                  Clients SHOULD use this as a guide when uploading content.
+                  If not listed or null, the size limit should be treated as unknown.
+          examples:
+            application/json: {
+               "m.upload.size": 50000000
+            }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+
+      tags:
+        - Media

api/client-server/joining.yaml

@@ -143,6 +143,15 @@ paths:
           description: The room identifier or alias to join.
           required: true
           x-example: "#monkeys:matrix.org"
+        - in: query
+          type: array
+          items:
+            type: string
+          name: server_name
+          description: |-
+            The servers to attempt to join the room through. One of the servers
+            must be participating in the room.
+          x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
           name: third_party_signed
           schema:

api/client-server/leaving.yaml

@@ -78,8 +78,8 @@ paths:
         for this room. If all users on a homeserver forget a room, the room is
         eligible for deletion from that homeserver.
 
-        If the user is currently joined to the room, they will implicitly leave
+        If the user is currently joined to the room, they must leave the room
-        the room as part of this API call.
+        before calling this API.
       operationId: forgetRoom
       security:
         - accessToken: []
@@ -99,6 +99,15 @@ paths:
               }
           schema:
             type: object
+        400:
+          description: The user has not left the room
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN",
+              "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
+            }
+          schema:
+            "$ref": "definitions/error.yaml"
         429:
           description: This request was rate-limited.
           schema:

api/client-server/login.yaml

@@ -28,6 +28,42 @@ securityDefinitions:
   $ref: definitions/security.yaml
 paths:
   "/login":
+    get:
+      summary: Get the supported login types to authenticate users
+      description: |-
+        Gets the homeserver's supported login types to authenticate users. Clients
+        should pick one of these and supply it as the ``type`` when logging in.
+      operationId: getLoginFlows
+      responses:
+        200:
+          description: The login types the homeserver supports
+          examples:
+            application/json: {
+              "flows": [
+                {"type": "m.login.password"}
+              ]
+            }
+          schema:
+            type: object
+            properties:
+              flows:
+                type: array
+                description: The homeserver's supported login types
+                items:
+                  type: object
+                  title: LoginFlow
+                  properties:
+                    type:
+                      description: |-
+                        The login type. This is supplied as the ``type`` when
+                        logging in.
+                      type: string
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Session management
     post:
       summary: Authenticates the user.
       description: |-

api/client-server/message_pagination.yaml

@@ -107,6 +107,7 @@ paths:
                 items:
                   type: object
                   title: RoomEvent
+                  "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
           examples:
             application/json: {
                 "start": "t47429-4392820_219380_26003_2265",

api/client-server/search.yaml

@@ -74,7 +74,7 @@ paths:
                 properties:
                   room_events:
                     type: object
-                    title: "Room Events"
+                    title: Room Events Criteria
                     description: Mapping of category name to search criteria.
                     properties:
                       search_term:
@@ -103,7 +103,7 @@ paths:
                           The order in which to search for results.
                           By default, this is ``"rank"``.
                       event_context:
-                        title: "Event Context"
+                        title: Include Event Context
                         type: object
                         description: |-
                           Configures whether any context for the events
@@ -169,13 +169,13 @@ paths:
             properties:
               search_categories:
                 type: object
-                title: Categories
+                title: Result Categories
                 description: Describes which categories to search in and
                   their criteria.
                 properties:
                   room_events:
                     type: object
-                    title: Room Event Results
+                    title: Result Room Events
                     description: Mapping of category name to search criteria.
                     properties:
                       count:

changelogs/client_server.rst

@@ -15,6 +15,26 @@ Unreleased changes
   - Sticker messages:
     - Add sticker message event definition.
     (`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
+  - Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}``
+    (`#1364 <https://github.com/matrix-org/matrix-doc/pull/1364>`_).
+  - Add 'token' parameter to /keys/query endpoint
+    (`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
+  - Add the room visibility options for the room directory
+    (`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
+  - Add spec for ignoring users
+    (`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
+  - Add the ``/register/available`` endpoint for username availability
+    (`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
+  - Add ``allow_remote`` to the content repo to avoid routing loops
+    (`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
+  - Add report content API
+    (`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
+  - Document ``/logout/all`` endpoint
+    (`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
+  - Document `highlights` field in /search response
+    (`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
+  - Document the GET version of ``/login``
+    (`#1361 <https://github.com/matrix-org/matrix-doc/pull/1361>`_).
 
 - Spec clarifications:
 
@@ -37,29 +57,16 @@ Unreleased changes
     (`#1152 <https://github.com/matrix-org/matrix-doc/pull/1152>`_).
   - Mark ``GET /rooms/{roomId}/members`` as requiring authentication
     (`#1245 <https://github.com/matrix-org/matrix-doc/pull/1244>`_).
+  - Define what a ``RoomEvent`` is on ``/rooms/{roomId}/messages``
+    (`#1380 <https://github.com/matrix-org/matrix-doc/pull/1380>`_).
   - Describe ``StateEvent`` for ``/createRoom``
     (`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
   - Describe how the ``reason`` is handled for kicks/bans
     (`#1362 <https://github.com/matrix-org/matrix-doc/pull/1362>`_).
-
+  - Clarify that clients must leave rooms before forgetting them
-- Changes to the API which will be backwards-compatible for clients:
+    (`#1378 <https://github.com/matrix-org/matrix-doc/pull/1378>`_).
-
+  - Clarify the request and result types on ``/search``
-  - Add 'token' parameter to /keys/query endpoint
+    (`#1381 <https://github.com/matrix-org/matrix-doc/pull/1381>`_).
-    (`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
-  - Add the room visibility options for the room directory
-    (`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
-  - Add spec for ignoring users
-    (`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
-  - Add the ``/register/available`` endpoint for username availability
-    (`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
-  - Add ``allow_remote`` to the content repo to avoid routing loops
-    (`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
-  - Add report content API
-    (`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
-  - Document ``/logout/all`` endpoint
-    (`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
-  - Document `highlights` field in /search response
-    (`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
 
 r0.3.0
 ======

scripts/continuserv/main.go

@@ -98,8 +98,10 @@ func makeWalker(base string, w *fsnotify.Watcher) filepath.WalkFunc {
 			log.Fatalf("Failed to get relative path of %s: %v", path, err)
 		}
 
+		// Normalize slashes
+		rel = filepath.ToSlash(rel)
+
 		// skip a few things that we know don't form part of the spec
-		rel = strings.Replace(rel, "\\", "/", -1) // normalize slashes (thanks to windows)
 		if rel == "api/node_modules" ||
 			rel == "scripts/gen" ||
 			rel == "scripts/tmp" {
@@ -127,7 +129,7 @@ func filter(e fsnotify.Event) bool {
 	}
 
 	// Forcefully ignore directories we don't care about (Windows, at least, tries to notify about some directories)
-	filePath := strings.Replace(e.Name, "\\", "/", -1) // normalize slashes (thanks to windows)
+	filePath := filepath.ToSlash(e.Name) // normalize slashes
 	if strings.Contains(filePath, "/scripts/tmp") ||
 		strings.Contains(filePath, "/scripts/gen") ||
 		strings.Contains(filePath, "/api/node_modules") {
@@ -156,11 +158,7 @@ func serve(w http.ResponseWriter, req *http.Request) {
 	if file[0] == '/' {
 		file = file[1:]
 	}
-	b, ok = m.bytes[file]
+	b, ok = m.bytes[filepath.FromSlash(file)] // de-normalize slashes
-
-	if !ok {
-		b, ok = m.bytes[strings.Replace(file, "/", "\\", -1)] // Attempt a Windows lookup
-	}
 
 	if ok && file == "api-docs.json" {
 		w.Header().Set("Access-Control-Allow-Origin", "*")

scripts/generate-matrix-org-assets

@@ -8,8 +8,11 @@ cd `dirname $0`/..
 
 mkdir -p assets
 
+if [ "$TRAVIS" != "true" ]
+then
     # generate specification/proposals.rst
     ./scripts/proposals.py
+fi
 
 # generate the spec docs
 ./scripts/gendoc.py -d assets/spec

scripts/speculator/main.go

@@ -701,8 +701,8 @@ func ignoreExitCodeOne(err error) error {
 
 func main() {
 	flag.Parse()
-	// It would be great to read this from github, but there's no convenient way to do so.
+	// It would be great to read this from github
-	// Most of these memberships are "private", so would require some kind of auth.
+	// cf https://github.com/matrix-org/matrix-doc/issues/1384
 	allowedMembers = map[string]bool{
 		"dbkr":          true,
 		"erikjohnston":  true,
@@ -713,6 +713,13 @@ func main() {
 		"ara4n":         true,
 		"leonerd":       true,
 		"rxl881":        true,
+		"uhoreg":        true,
+		"turt2live":     true,
+		"Half-Shot":     true,
+		"anoadragon453": true,
+		"mujx":          true,
+		"benparsons":    true,
+		"KitsuneRal":    true,
 	}
 	if err := initCache(); err != nil {
 		log.Fatal(err)

scripts/templating/matrix_templates/units.py

@@ -502,6 +502,11 @@ class MatrixUnits(Units):
                 # assign value expected for this param
                 val_type = param.get("type")  # integer/string
 
+                if val_type == "array":
+                    items = param.get("items")
+                    if items:
+                        val_type = "[%s]" % items.get("type")
+
                 if param.get("enum"):
                     val_type = "enum"
                     desc += (

specification/server_server_api.rst

@@ -16,6 +16,10 @@
 Federation API
 ==============
 
+.. WARNING::
+  This API is unstable and will change without warning or discussion while
+  we work towards a r0 release (scheduled for August 2018).
+
 Matrix homeservers use the Federation APIs (also known as server-server APIs)
 to communicate with each other. Homeservers use these APIs to push messages to
 each other in real-time, to