mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-17 17:04:10 +01:00
Compare commits
6 commits
2c186d2a72
...
24b69293c3
| Author | SHA1 | Date | |
|---|---|---|---|
|
24b69293c3 | ||
|
|
f6d5009959 | ||
|
|
9c313b099f | ||
|
|
7b5935e5cb | ||
|
|
e3db17eb8e | ||
|
|
271ae6a0e8 |
1
changelogs/client_server/newsfragments/2186.removal
Normal file
1
changelogs/client_server/newsfragments/2186.removal
Normal file
|
|
@ -0,0 +1 @@
|
|||
Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).
|
||||
1
changelogs/client_server/newsfragments/2187.feature
Normal file
1
changelogs/client_server/newsfragments/2187.feature
Normal file
|
|
@ -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).
|
||||
1
changelogs/internal/newsfragments/2190.clarification
Normal file
1
changelogs/internal/newsfragments/2190.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Clarify that clients should replace events with the most recent replacement by origin_server_ts.
|
||||
|
|
@ -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),
|
||||
|
|
|
|||
|
|
@ -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),
|
||||
[`.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 %}}
|
||||
{{% boxes/note %}}
|
||||
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.
|
||||
{{% /boxes/rationale %}}
|
||||
the event. When the `m.mentions` field was introduced, those push rules were
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`**
|
||||
|
|
|
|||
|
|
@ -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": [
|
||||
|
|
|
|||
|
|
@ -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
|
||||
`timeline` (or all state up to the start of the
|
||||
the `since` parameter, and 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:
|
||||
|
|
|
|||
|
|
@ -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": [
|
||||
|
|
|
|||
Loading…
Reference in a new issue