From a6a25c967a622f0f7894c88ab34661f8829faa96 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 1 Feb 2022 16:18:20 +0000 Subject: [PATCH 1/4] Clarify the behavour of `event_match` in push rules --- content/client-server-api/modules/push.md | 76 +++++++++++++++++-- .../definitions/push_condition.yaml | 4 +- 2 files changed, 72 insertions(+), 8 deletions(-) diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 70c61ea5ce2..e843fd3515a 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -217,11 +217,77 @@ defined: `event_match` This is a glob pattern match on a field of the event. Parameters: -- `key`: The dot-separated field of the event to match, e.g. - `content.body` -- `pattern`: The glob-style pattern to match against. Patterns with no - special glob characters should be treated as having asterisks - prepended and appended when testing the condition. +- `key`: The dot-separated path of the property of the event to match, e.g. + `content.body`. + +- `pattern`: The glob-style pattern to match against. + +The match is performed case-insensitively, and must match the entire value of +the event field given by `key` (though see below regarding `content.body`). The +exact meaning of "case insensitive" is defined by the implementation of the +homeserver. + +Within `pattern`: + + * The character `*` matches zero or more characters. + * `?` matches exactly one character. + +If the property specified by `key` is completely absent from the event, then +the condition will not match, even if `pattern` is `*`. + +For example, if `key` is `content.membership`, and `pattern` is `jo?*`, then +the following event will match: + +```json +{ + "content": { + "membership": "join", + }, + "event_id": "$143273582443PhrSn:example.org", + "room_id": "!636q39766251:example.com", + "sender": "@example:example.org", + "state_key": "@alice:example.org", + "type": "m.room.member" +} +``` + +Other `membership` values which will match are: + + * `JOIN` + * `joinnn` + * `join ` (note trailing space) + * `joy` (`*` may match zero characters) + +The following `membership` values will NOT match: + * ` join` (note leading space) + * `jo` (`?` must match a character) + +As a special case, if `key` is `content.body`, then `pattern` must instead +match any substring of the value of the property which starts and ends at a +word boundary. A word boundary is defined as the start or end of the value, or +any character not in the sets `[A-Z]`, `[a-z]`, `[0-9]` or `_`. + +For example, if `key` is `content.body` and `pattern` is `ex*ple`, the +following event will match: + +```json +{ + "content": { + "body": "An example event.", + }, + "event_id": "$143273976499sgjks:example.org", + "room_id": "!636q39766251:example.com", + "sender": "@example:example.org", + "type": "m.room.message" +} +``` + +Other `body` values which will match are: + + * `exple` (the pattern can match at the start and end of the body.) + * `An exciting triple-whammy` (the pattern can span multiple words, and `-` + acts as a word separator.) + `contains_display_name` This matches unencrypted messages where `content.body` contains the diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 64d975ff21b..044f8627fdb 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -35,9 +35,7 @@ properties: type: string description: |- Required for `event_match` conditions. The glob-style pattern to - match against. Patterns with no special glob characters should be - treated as having asterisks prepended and appended when testing the - condition. + match against. is: type: string description: |- From 6784629c449c7222e05f44954d1a6ad86b287a45 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 1 Feb 2022 16:19:12 +0000 Subject: [PATCH 2/4] newsfile --- changelogs/client_server/3690.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/3690.clarification diff --git a/changelogs/client_server/3690.clarification b/changelogs/client_server/3690.clarification new file mode 100644 index 00000000000..acdd558d81f --- /dev/null +++ b/changelogs/client_server/3690.clarification @@ -0,0 +1 @@ +Clarify the behaviour of `event_match` in push rule conditions. From 1ba5a9d26e7a1f62d45e000aabcf10d428d3f98e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 1 Feb 2022 16:39:12 +0000 Subject: [PATCH 3/4] clarifications --- content/client-server-api/modules/push.md | 58 ++++++++++++++--------- 1 file changed, 35 insertions(+), 23 deletions(-) diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index e843fd3515a..f93a61c75bf 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -211,10 +211,19 @@ other keys as their parameters, e.g. `override` and `underride` rules MAY have a list of 'conditions'. All conditions must hold true for an event in order for the rule to match. A -rule with no conditions always matches. The following conditions are -defined: +rule with no conditions always matches. + +Unrecognised conditions MUST NOT match any events, effectively making +the push rule disabled. + +`room`, `sender` and `content` rules do not have conditions in the same +way, but instead have predefined conditions. In the cases of `room` and +`sender` rules, the `rule_id` of the rule determines its behaviour. + +The following conditions are defined: + +**`event_match`** -`event_match` This is a glob pattern match on a field of the event. Parameters: - `key`: The dot-separated path of the property of the event to match, e.g. @@ -232,9 +241,11 @@ Within `pattern`: * The character `*` matches zero or more characters. * `?` matches exactly one character. -If the property specified by `key` is completely absent from the event, then -the condition will not match, even if `pattern` is `*`. +If the property specified by `key` is completely absent from the event, or does +not have a string value, then the condition will not match, even if `pattern` +is `*`. +{{% boxes/note %}} For example, if `key` is `content.membership`, and `pattern` is `jo?*`, then the following event will match: @@ -253,20 +264,23 @@ the following event will match: Other `membership` values which will match are: - * `JOIN` - * `joinnn` - * `join ` (note trailing space) - * `joy` (`*` may match zero characters) + * `"JOIN"` + * `"joinnn"` + * `"join "` (note trailing space) + * `"joy"` (`*` may match zero characters) The following `membership` values will NOT match: - * ` join` (note leading space) - * `jo` (`?` must match a character) + * `" join"` (note leading space) + * `"jo"` (`?` must match a character) + * `null` (not a string) +{{% /boxes/note %}} As a special case, if `key` is `content.body`, then `pattern` must instead match any substring of the value of the property which starts and ends at a word boundary. A word boundary is defined as the start or end of the value, or any character not in the sets `[A-Z]`, `[a-z]`, `[0-9]` or `_`. +{{% boxes/note %}} For example, if `key` is `content.body` and `pattern` is `ex*ple`, the following event will match: @@ -284,18 +298,22 @@ following event will match: Other `body` values which will match are: - * `exple` (the pattern can match at the start and end of the body.) - * `An exciting triple-whammy` (the pattern can span multiple words, and `-` + * `"exple"` (the pattern can match at the start and end of the body.) + * `"An exciting triple-whammy"` (the pattern can span multiple words, and `-` acts as a word separator.) +{{% /boxes/note %}} + -`contains_display_name` +**`contains_display_name`** + This matches unencrypted messages where `content.body` contains the owner's display name in that room. This is a separate rule because display names may change and as such it would be hard to maintain a rule that matched the user's display name. This condition has no parameters. -`room_member_count` +**`room_member_count`** + This matches the current number of members in the room. Parameters: - `is`: A decimal integer optionally prefixed by one of, `==`, `<`, @@ -303,7 +321,8 @@ This matches the current number of members in the room. Parameters: count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to `==`. -`sender_notification_permission` +**`sender_notification_permission`** + This takes into account the current power levels in the room, ensuring the sender of the event has high enough power to trigger the notification. @@ -317,13 +336,6 @@ Parameters: to look up the power level required to send a notification type from the `notifications` object in the power level event content. -Unrecognised conditions MUST NOT match any events, effectively making -the push rule disabled. - -`room`, `sender` and `content` rules do not have conditions in the same -way, but instead have predefined conditions. In the cases of `room` and -`sender` rules, the `rule_id` of the rule determines its behaviour. - ##### Predefined Rules Homeservers can specify "server-default rules" which operate at a lower From 84d2198494fa3d7253fd4b5090a5875fec8911e8 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 15 Feb 2022 15:06:50 +0000 Subject: [PATCH 4/4] address review comments --- content/client-server-api/modules/push.md | 29 +++++++++++++---------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index f93a61c75bf..bd7be800e1b 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -246,32 +246,29 @@ not have a string value, then the condition will not match, even if `pattern` is `*`. {{% boxes/note %}} -For example, if `key` is `content.membership`, and `pattern` is `jo?*`, then +For example, if `key` is `content.topic`, and `pattern` is `lunc?*`, then the following event will match: ```json { "content": { - "membership": "join", + "topic": "Lunch plans", }, "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", - "state_key": "@alice:example.org", - "type": "m.room.member" + "state_key": "", + "type": "m.room.topic" } ``` -Other `membership` values which will match are: +Other `topic` values which will match are: - * `"JOIN"` - * `"joinnn"` - * `"join "` (note trailing space) - * `"joy"` (`*` may match zero characters) + * `"LUNCH"` (case-insensitive; `*` may match zero characters) The following `membership` values will NOT match: - * `" join"` (note leading space) - * `"jo"` (`?` must match a character) + * `" lunch"` (note leading space) + * `"lunc"` (`?` must match a character) * `null` (not a string) {{% /boxes/note %}} @@ -304,6 +301,14 @@ Other `body` values which will match are: {{% /boxes/note %}} +{{% boxes/warning %}} +Note that there is no implicit condition for `state_key`. In other words, push +rules which should match only state events must include an explicit condition +for `state_key`. + +For an example of this, see the default rule +[`.m.rule.tombstone`](#mruletombstone) below. +{{% /boxes/warning %}} **`contains_display_name`** @@ -481,7 +486,7 @@ Definition: } ``` -**`.m.rule.tombstone`** +**`.m.rule.tombstone`** Matches any state event whose type is `m.room.tombstone`. This is intended to notify users of a room when it is upgraded, similar to what