Merge 7b5935e5cb into f6d5009959

Signed-off-by: Andy Balaam <andy.balaam@matrix.org>

changelogs/client_server/newsfragments/2186.removal

@@ -0,0 +1 @@
+Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).

changelogs/client_server/newsfragments/2187.feature

@@ -0,0 +1 @@
+Add the `use_state_after` query parameter and `state_after` response property to `GET /sync`, as per [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/issues/4222).

changelogs/internal/newsfragments/2190.clarification

@@ -0,0 +1 @@
+Clarify that clients should replace events with the most recent replacement by origin_server_ts.

content/client-server-api/modules/event_replacements.md

@@ -195,7 +195,7 @@ given event (for example, if an event is edited multiple times). These should
 be [aggregated](#aggregations-of-child-events) by the homeserver.
 
 The aggregation format of `m.replace` relationships gives the **most recent**
-replacement event, formatted [as normal](#room-event-format).
+valid replacement event, formatted [as normal](#room-event-format).
 
 The most recent event is determined by comparing `origin_server_ts`; if two or
 more replacement events have identical `origin_server_ts`, the event with the
@@ -268,6 +268,11 @@ Client authors are reminded to take note of the requirements for [Validity of
 replacement events](#validity-of-replacement-events), and to ignore any
 invalid replacement events that are received.
 
+Clients should render the content of the **most recent** valid replacement event. The
+most recent event is determined by comparing `origin_server_ts`; if two or more
+replacement events have identical `origin_server_ts`, the event with the
+lexicographically largest `event_id` is treated as more recent.
+
 ##### Permalinks
 
 When creating [links](/appendices/#uris) to events (also known as permalinks),

content/client-server-api/modules/mentions.md

@@ -3,6 +3,9 @@
 
 {{% changed-in v="1.7" %}}
 
+{{% changed-in v="1.16" %}}: the legacy push rules that looked for mentions in
+the `body` of the event were removed.
+
 This module allows users to "mention" other users and rooms within a room event.
 This is primarily used as an indicator that the recipient should receive a notification
 about the event.
@@ -38,19 +41,18 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
 must be decrypted first. See [receiving notifications](#receiving-notifications).
 {{% /boxes/warning %}}
 
-Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
+{{% boxes/note %}}
-[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
-[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to  match if the `body` of
-the event contains the user's display name or ID. To avoid unintentional notifications,
-**it is recommended that clients include a `m.mentions` property on each event**.
-(If there are no mentions to include it can be an empty object.)
-
-{{% boxes/rationale %}}
 In previous versions of the specification, mentioning users was done by
 including the user's display name or the localpart of their Matrix ID and room
 mentions were done by including the string "@room" in the plaintext `body` of
-the event. This was prone to confusing and buggy behaviour.
+the event. When the `m.mentions` field was introduced, those push rules were
-{{% /boxes/rationale %}}
+disabled if the `m.mentions` field was present.
+
+To avoid unintentional notifications with clients and servers that still use
+those push rules, **it is recommended that clients still include a `m.mentions`
+property on each event**. (If there are no mentions to include it can be an
+empty object.)
+{{% /boxes/note %}}
 
 #### Client behaviour
 

content/client-server-api/modules/push.md

@@ -382,6 +382,9 @@ The following `alt_aliases` values will NOT match:
 
 **`contains_display_name`**
 
+{{% changed-in v="1.16" %}}: this condition is deprecated and **should not be
+used in new push rules**.
+
 This matches messages where `content.body` contains the owner's display name in
 that room. This is a separate condition because display names may change and as such
 it would be hard to maintain a rule that matched the user's display name. This
@@ -413,6 +416,9 @@ Parameters:
 
 #### Predefined Rules
 
+{{% changed-in v="1.16" %}}: the legacy default push rules that looked for
+mentions in the `body` of the event were removed.
+
 Homeservers can specify "server-default rules". They operate at a lower
 priority than "user-defined rules", except for the `.m.rule.master` rule
 which has always a higher priority than any other rule. The `rule_id`
@@ -557,41 +563,6 @@ Definition:
 }
 ```
 
-<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message whose content contains the user's current display name
-in the room in which it was sent.
-
-Definition:
-
-```json
-{
-    "rule_id": ".m.rule.contains_display_name",
-    "default": true,
-    "enabled": true,
-    "conditions": [
-        {
-            "kind": "contains_display_name"
-        }
-    ],
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "sound",
-            "value": "default"
-        },
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 <a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
 
 {{% added-in v="1.7" %}}
@@ -626,44 +597,6 @@ Definition:
 }
 ```
 
-<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message from a sender with the proper power level whose content
-contains the text `@room`, signifying the whole room should be notified of
-the event.
-
-Definition:
-
-```json
-{
-    "rule_id": ".m.rule.roomnotif",
-    "default": true,
-    "enabled": true,
-    "conditions": [
-        {
-            "kind": "event_match",
-            "key": "content.body",
-            "pattern": "@room"
-        },
-        {
-            "kind": "sender_notification_permission",
-            "key": "room"
-        }
-    ],
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 **<a id="mruletombstone"></a>`.m.rule.tombstone`**
 
 Matches any state event whose type is `m.room.tombstone`. This is
@@ -776,39 +709,6 @@ Definition:
 }
 ```
 
-##### Default Content Rules
-
-<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
-
-{{% changed-in v="1.7" %}}
-
-As of `v1.7`, this rule is deprecated and **should only be enabled if the event
-does not have an [`m.mentions` property](#definition-mmentions)**.
-
-Matches any message whose content contains the local part of the user's
-Matrix ID, separated by word boundaries.
-
-Definition (as a `content` rule):
-
-```json
-{
-    "rule_id": ".m.rule.contains_user_name",
-    "default": true,
-    "enabled": true,
-    "pattern": "[the local part of the user's Matrix ID]",
-    "actions": [
-        "notify",
-        {
-            "set_tweak": "sound",
-            "value": "default"
-        },
-        {
-            "set_tweak": "highlight"
-        }
-    ]
-}
-```
-
 ##### Default Underride Rules
 
 **`.m.rule.call`**

data/api/client-server/definitions/push_ruleset.yaml

@@ -34,24 +34,6 @@ properties:
     type: array
 type: object
 example: {
-  "content": [
-    {
-      "actions": [
-        "notify",
-        {
-          "set_tweak": "sound",
-          "value": "default"
-        },
-        {
-          "set_tweak": "highlight"
-        }
-      ],
-      "default": true,
-      "enabled": true,
-      "pattern": "alice",
-      "rule_id": ".m.rule.contains_user_name"
-    }
-  ],
   "override": [
     {
       "actions": [],
@@ -113,12 +95,14 @@ example: {
       ],
       "conditions": [
         {
-          "kind": "contains_display_name"
+            "kind": "event_property_contains",
+            "key": "content.m\\.mentions.user_ids",
+            "value": "@alice:example.com"
         }
       ],
       "default": true,
       "enabled": true,
-      "rule_id": ".m.rule.contains_display_name"
+      "rule_id": ".m.rule.is_user_mention"
     },
     {
       "actions": [

data/api/client-server/sync.yaml

@@ -117,6 +117,31 @@ paths:
           example: 30000
           schema:
             type: integer
+        - in: query
+          name: use_state_after
+          x-addedInMatrixVersion: "1.16"
+          description: |-
+            Controls whether to receive state changes between the previous sync
+            and the **start** of the timeline, or between the previous sync and
+            the **end** of the timeline.
+
+            If this is set to `true`, servers MUST respond with the state
+            between the previous sync and the **end** of the timeline in
+            `state_after` and MUST omit `state`.
+
+            If `false`, servers MUST respond with the state between the previous
+            sync and the **start** of the timeline in `state` and MUST omit
+            `state_after`.
+
+            Even if this is set to `true`, clients MUST update their local state
+            with events in `state` and `timeline` if `state_after` is missing in
+            the response, for compatibility with servers that don't support this
+            parameter.
+
+            By default, this is `false`.
+          example: false
+          schema:
+            type: boolean
       responses:
         "200":
           description: The initial snapshot or delta for the client to use to update their
@@ -197,16 +222,50 @@ paths:
                                 type: object
                                 description: |-
                                   Updates to the state, between the time indicated by
-                                  the `since` parameter, and the start of the
+                                  the `since` parameter, and the **start** of the
-                                  `timeline` (or all state up to the start of the
+                                  `timeline` (or all state up to the **start** of the
                                   `timeline`, if `since` is not given, or
                                   `full_state` is true).
 
-                                  N.B. state updates for `m.room.member` events will
+                                  {{% boxes/note %}}
+                                  State updates for `m.room.member` events will
                                   be incomplete if `lazy_load_members` is enabled in
                                   the `/sync` filter, and only return the member events
                                   required to display the senders of the timeline events
                                   in this response.
+                                  {{% /boxes/note %}}
+
+                                  MUST be omitted if `use_state_after` was set to `true`
+                                  in the request.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              state_after:
+                                title: State
+                                type: object
+                                x-addedInMatrixVersion: "1.16"
+                                description: |-
+                                  Updates to the state, between the time indicated by
+                                  the `since` parameter, and the **end** of the
+                                  `timeline` (or all state up to the **end** of the
+                                  `timeline`, if `since` is not given, or
+                                  `full_state` is true).
+
+                                  {{% boxes/note %}}
+                                  State updates for `m.room.member` events will
+                                  be incomplete if `lazy_load_members` is enabled in
+                                  the `/sync` filter, and only return the member events
+                                  required to display the senders of the timeline events
+                                  in this response.
+                                  {{% /boxes/note %}}
+
+                                  If this field is set, even if it is empty, clients MUST
+                                  only update their local state with events in this list,
+                                  and MUST NOT update their local state with events in
+                                  `timeline`. If this field is not set, clients MUST update
+                                  their local state with events in `state` and `timeline`.
+
+                                  **Required** if `use_state_after` was set to `true` in the
+                                  request, even if it is empty.
                                 allOf:
                                   - $ref: definitions/state_event_batch.yaml
                               timeline:
@@ -353,7 +412,28 @@ paths:
                               state:
                                 title: State
                                 type: object
-                                description: The state updates for the room up to the start of the timeline.
+                                description: |-
+                                  The state updates for the room up to the **start** of the timeline.
+
+                                  MUST be omitted if `use_state_after` was set to `true` in the
+                                  request.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              state_after:
+                                title: State
+                                type: object
+                                x-addedInMatrixVersion: "1.16"
+                                description: |-
+                                  The state updates for the room up to the **end** of the timeline.
+
+                                  If this field is set, even if it is empty, clients MUST only
+                                  update their local state with events in this list, and MUST NOT
+                                  update their local state with events in `timeline`. If this field
+                                  is not set, clients MUST update their local state with events in
+                                  `state` and `timeline`.
+
+                                  **Required** if `use_state_after` was set to `true` in the
+                                  request, even if it is empty.
                                 allOf:
                                   - $ref: definitions/state_event_batch.yaml
                               timeline:

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

@@ -3,24 +3,6 @@
   "type": "m.push_rules",
   "content": {
     "global": {
-      "content": [
-        {
-          "actions": [
-            "notify",
-            {
-              "set_tweak": "sound",
-              "value": "default"
-            },
-            {
-              "set_tweak": "highlight"
-            }
-          ],
-          "default": true,
-          "enabled": true,
-          "pattern": "alice",
-          "rule_id": ".m.rule.contains_user_name"
-        }
-      ],
       "override": [
         {
           "actions": [],
@@ -82,12 +64,14 @@
           ],
           "conditions": [
             {
-              "kind": "contains_display_name"
+                "kind": "event_property_contains",
+                "key": "content.m\\.mentions.user_ids",
+                "value": "@alice:example.com"
             }
           ],
           "default": true,
           "enabled": true,
-          "rule_id": ".m.rule.contains_display_name"
+          "rule_id": ".m.rule.is_user_mention"
         },
         {
           "actions": [