Merge ca801d1751 into 252de984cc

* Spec for MSC4230: Flag for animated images

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add x-addedInMatrixVersion property

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/2328.feature

@@ -0,0 +1 @@
+Add the `is_animated` flag to the `info` object of the `m.image` msgtype and the `m.sticker` event, as per [MSC4230](https://github.com/matrix-org/matrix-spec-proposals/pull/423O).

changelogs/client_server/newsfragments/2329.clarification

@@ -0,0 +1 @@
+Add link to JSON signing algorithm in server-server auth section for clarity. Contributed by @thetayloredman.

changelogs/server_server/newsfragments/2326.clarification

@@ -0,0 +1 @@
+Clarify the s2s profile query behaviour and responses.

content/server-server-api.md

@@ -277,12 +277,12 @@ queried from multiple servers to mitigate against DNS spoofing.
 
 Every HTTP request made by a homeserver is authenticated using public
 key digital signatures. The request method, target and body are signed
-by wrapping them in a JSON object and signing it using the JSON signing
+by wrapping them in a JSON object and signing it using the [JSON signing
-algorithm. The resulting signatures are added as an Authorization header
+algorithm](/appendices#signing-json). The resulting signatures are added
-with an auth scheme of `X-Matrix`. Note that the target field should
+as an Authorization header with an auth scheme of `X-Matrix`. Note that
-include the full path starting with `/_matrix/...`, including the `?`
+the target field should include the full path starting with `/_matrix/...`,
-and any query parameters if present, but should not include the leading
+including the `?` and any query parameters if present, but should not
-`https:`, nor the destination server's hostname.
+include the leading `https:`, nor the destination server's hostname.
 
 Step 1 sign JSON:
 

data/api/server-server/query.yaml

@@ -111,22 +111,26 @@ paths:
       summary: Query for profile information about a given user
       description: |-
         Performs a query to get profile information, such as a display name or avatar,
-        for a given user. Homeservers should only query profiles for users that belong
+        for a given user. Homeservers MUST only query profiles for users that belong
         to the target server (identified by the [server name](/appendices/#server-name)
         in the user ID).
 
-        Servers may wish to cache the response to this query to avoid requesting the
+        Responding servers MAY
-        information too often.
+          - allow users to set arbitrary key/value pairs in their profile in addition to the
+            specified pairs
+          - deny profile look-up over federation by responding with 403 and an error code of
+            `M_FORBIDDEN`
+          - omit certain key/value pairs in the response
 
-        Servers MAY deny profile look-up over federation by responding with 403 and an
+        Requesting servers MAY wish to cache the response to this query to avoid requesting the
-        error code of `M_FORBIDDEN`.
+        information too often.
       operationId: queryProfile
       security:
         - signedRequest: []
       parameters:
         - in: query
           name: user_id
-          description: The user ID to query. Must be a user local to the receiving homeserver.
+          description: The user ID to query. MUST be a user local to the receiving homeserver.
           required: true
           example: "@someone:example.org"
           schema:
@@ -134,24 +138,24 @@ paths:
         - in: query
           name: field
           description: |-
-            The field to query. If specified, the server will only return the given field
+            The field of the profile to query. If specified, the server MUST only return the
-            in the response. If not specified, the server will return the full profile for
+            given field in the response. If not specified, the server MUST return the full,
-            the user.
+            public, profile for the user.
+
+            Defined values are `displayname`, `avatar_url` and `m.tz`. In addition to these
+            servers MAY allow users to set additional key/value pairs.
           schema:
             type: string
-            enum:
-              - displayname
-              - avatar_url
       responses:
         "200":
           description: |-
             The profile for the user. If a `field` is specified in the request, only the
-            matching field should be included in the response. If no `field` was specified,
+            matching field MUST included in the response. If no `field` was specified,
-            the response should include the fields of the user's profile that can be made
+            the response MUST include the fields of the user's profile that can be made
             public, such as the display name and avatar.
 
             If the user does not have a particular field set on their profile, the server
-            should exclude it from the response body or give it the value `null`.
+            MUST either exclude it from the response body or give it the value `null`.
           content:
             application/json:
               schema:
@@ -160,20 +164,20 @@ paths:
                   displayname:
                     type: string
                     description: |-
-                      The display name of the user. May be omitted if the user does not have a
+                      The display name of the user. MUST either be omitted or set to `null` if
-                      display name set.
+                      the user does not have a display name set.
                     example: John Doe
                   avatar_url:
                     type: string
                     description: |-
-                      The avatar URL for the user's avatar. May be omitted if the user does not
+                      The avatar URL for the user's avatar. MUST either be omitted or set to
-                      have an avatar set.
+                      `null` if the user does not have an avatar set.
-                    example: mxc://matrix.org/MyC00lAvatar
+                    example: mxc://example.org/MyC00lAvatar
               examples:
                 response:
                   value: {
                     "displayname": "John Doe",
-                    "avatar_url": "mxc://matrix.org/MyC00lAvatar"
+                    "avatar_url": "mxc://example.org/MyC00lAvatar"
                   }
         "403":
           x-addedInMatrixVersion: "1.12"
@@ -190,7 +194,7 @@ paths:
                     "error": "Profile lookup over federation is disabled on this homeserver"
                   }
         "404":
-          description: The user does not exist or does not have a profile.
+          description: The user does not exist, does not have a profile or the queried field does not exist.
           content:
             application/json:
               schema:

data/event-schemas/examples/m.room.message$m.image.yaml

@@ -7,7 +7,8 @@
         "h": 398,
         "w": 394,
         "mimetype": "image/jpeg",
-        "size": 31037
+        "size": 31037,
+        "is_animated": false
     },
     "url": "mxc://example.org/JWEIFJgwEIhweiWJE",
     "msgtype": "m.image"

data/event-schemas/examples/m.sticker.yaml

@@ -9,7 +9,8 @@
         "mimetype": "image/png",
         "h": 200,
         "w": 140,
-        "size": 73602
+        "size": 73602,
+        "is_animated": true
       },
       "h": 200,
       "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP",

data/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -34,5 +34,19 @@ properties:
     allOf:
       - $ref: thumbnail_info.yaml
     description: Metadata about the image referred to in `thumbnail_url`.
+  is_animated:
+    x-addedInMatrixVersion: "1.18"
+    description: |-
+      If this flag is `true`, the original image SHOULD be assumed to be
+      animated. If this flag is `false`, the original image SHOULD be assumed to
+      NOT be animated.
+
+      If a sending client is unable to determine whether an image is animated,
+      it SHOULD leave the flag unset.
+
+      Receiving clients MAY use this flag to optimize whether to download the
+      original image rather than a thumbnail if it is animated, but they SHOULD
+      NOT trust this flag.
+    type: boolean
 title: ImageInfo
 type: object