Merge remote-tracking branch 'matrix-org/master' into travis/preset-guests

api/client-server/banning.yaml

@@ -61,7 +61,8 @@ paths:
                 description: The fully qualified user ID of the user being banned.
               reason:
                 type: string
-                description: The reason the user has been banned.
+                description: The reason the user has been banned. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
         200:

api/client-server/content-repo.yaml

@@ -299,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/kicking.yaml

@@ -34,6 +34,10 @@ paths:
         Kick a user from the room.
 
         The caller must have the required power level in order to perform this operation.
+        
+        Kicking a user adjusts the target member's membership state to be ``leave`` with an
+        optional ``reason``. Like with other membership changes, a user can directly adjust
+        the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
       operationId: kick
       security:
         - accessToken: []
@@ -59,7 +63,9 @@ paths:
                 description: The fully qualified user ID of the user being kicked.
               reason:
                 type: string
-                description: The reason the user has been kicked.
+                description: |-
+                  The reason the user has been kicked. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
         200:

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
-        the room as part of this API call.
+        If the user is currently joined to the room, they must leave the room
+        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/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/presence.yaml

@@ -83,6 +83,8 @@ paths:
       description: |-
         Get the given user's presence state.
       operationId: getPresence
+      security:
+        - accessToken: []
       parameters:
         - in: path
           type: string
@@ -121,6 +123,15 @@ paths:
           description: |-
             There is no presence state for this user. This user may not exist or
             isn't exposing presence information to you.
+        403:
+          description: You are not allowed to see this user's presence status.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You are not allowed to see their presence"
+            }
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - Presence
   "/presence/list/{userId}":

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,10 +15,30 @@ 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>`_).
   - Document guest access in ``/createRoom`` presets
     (`#1379 <https://github.com/matrix-org/matrix-doc/pull/1379>`_).
+  - Document the CORS/preflight headers
+    (`#1365 <https://github.com/matrix-org/matrix-doc/pull/1365>`_).
 
 - Spec clarifications:
 
@@ -41,27 +61,18 @@ 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>`_).
+  - Mark ``GET /presence/{userId}/status`` as requiring authentication
+    (`#1371 <https://github.com/matrix-org/matrix-doc/pull/1371>`_).
   - Describe ``StateEvent`` for ``/createRoom``
     (`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
-
-- Changes to the API which will be backwards-compatible for clients:
-
-  - 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>`_).
+  - 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
+    (`#1378 <https://github.com/matrix-org/matrix-doc/pull/1378>`_).
+  - Clarify the request and result types on ``/search``
+    (`#1381 <https://github.com/matrix-org/matrix-doc/pull/1381>`_).
 
 r0.3.0
 ======

changelogs/client_server/newsfragments/1397.feature

@@ -0,0 +1 @@
+Document message formats on ``m.text`` and ``m.emote`` messages

event-schemas/examples/m.room.message#m.emote

@@ -2,7 +2,9 @@
   "age": 242352,
   "content": {
     "body": "thinks this is an example emote",
-    "msgtype": "m.emote"
+    "msgtype": "m.emote",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "thinks <b>this</b> is an example emote"
   },
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",

event-schemas/examples/m.room.message#m.text

@@ -2,7 +2,9 @@
   "age": 242352,
   "content": {
     "body": "This is an example text message",
-    "msgtype": "m.text"
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "<b>This is an example text message</b>"
   },
   "origin_server_ts": 1431961217939,
   "event_id": "$WLGTSEFSEF:localhost",

event-schemas/schema/m.room.message#m.emote

@@ -12,6 +12,16 @@ properties:
         enum:
           - m.emote
         type: string
+      format:
+        description: |-
+          The format used in the ``formatted_body``. Currently only
+          ``org.matrix.custom.html`` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the ``body``. This is required if ``format``
+          is specified.
+        type: string
     required:
       - msgtype
       - body

event-schemas/schema/m.room.message#m.text

@@ -12,6 +12,16 @@ properties:
         enum:
           - m.text
         type: string
+      format:
+        description: |-
+          The format used in the ``formatted_body``. Currently only
+          ``org.matrix.custom.html`` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the ``body``. This is required if ``format``
+          is specified.
+        type: string
     required:
       - msgtype
       - body

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.
-	// Most of these memberships are "private", so would require some kind of auth.
+	// It would be great to read this from github
+	// cf https://github.com/matrix-org/matrix-doc/issues/1384
 	allowedMembers = map[string]bool{
 		"dbkr":          true,
 		"erikjohnston":  true,
@@ -715,6 +715,11 @@ func main() {
 		"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/client_server_api.rst

@@ -164,6 +164,25 @@ recommended.
 
 {{versions_cs_http_api}}
 
+Web Browser Clients
+-------------------
+
+It is realistic to expect that some clients will be written to be run within a
+web browser or similar environment. In these cases, the homeserver should respond
+to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on
+all requests.
+
+When a client approaches the server with a pre-flight (``OPTIONS``) request, the
+server should respond with the CORS headers for that route. The recommended CORS
+headers to be returned by servers on all requests are:
+
+.. code::
+
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+  Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
+
+
 Client Authentication
 ---------------------
 

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