From 7ec3cc4343a30c41176c50bb208d57fc698663a5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:21:21 -0600 Subject: [PATCH 1/4] General improvements to the push rules module This commit does a few things: * Add 3 undocumented push rules to the spec for encrypted events and at-room notifications. * Require unrecognized conditions to not match, ensuring that future conditions do not cause clients to accidentally notify users. * Clarify that push rules should be enabled when created. * Document a new condition required for at-room notifications. Fixes https://github.com/matrix-org/matrix-doc/issues/1163 Fixes https://github.com/matrix-org/matrix-doc/issues/1034 Fixes https://github.com/matrix-org/matrix-doc/issues/676 Fixes https://github.com/matrix-org/matrix-doc/issues/1033 Relates to https://github.com/matrix-org/matrix-doc/issues/1101 --- api/client-server/pushrules.yaml | 4 +- specification/modules/push.rst | 118 ++++++++++++++++++++++++++++++- 2 files changed, 119 insertions(+), 3 deletions(-) diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index ceb9954b..e23c9189 100644 --- a/api/client-server/pushrules.yaml +++ b/api/client-server/pushrules.yaml @@ -343,6 +343,8 @@ paths: This endpoint allows the creation, modification and deletion of pushers for this user ID. The behaviour of this endpoint varies depending on the values in the JSON body. + + When creating push rules, they MUST be enabled by default. operationId: setPushRule security: - accessToken: [] @@ -424,7 +426,7 @@ paths: required: ["actions"] responses: 200: - description: The pusher was set. + description: The push rule was created/updated. examples: application/json: { } diff --git a/specification/modules/push.rst b/specification/modules/push.rst index e9ee8c90..94683436 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -124,7 +124,7 @@ There are different "kinds" of push rules and each rule has an associated priority. Every push rule MUST have a ``kind`` and ``rule_id``. The ``rule_id`` is a unique string within the kind of rule and its' scope: ``rule_ids`` do not need to be unique between rules of the same kind on different devices. Rules may -have extra keys depending on the value of ``kind``.The different kinds of rule +have extra keys depending on the value of ``kind``. The different kinds of rule in descending order of priority are: Override Rules ``override`` @@ -369,6 +369,41 @@ Definition: } +``.m.rule.roomnotif`` +````````````````````````````````` +Matches any message whose content is unencrypted and contains the +text ``@room``, signifying the whole room should be notified of +the event. + +Definition: + +.. code:: 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", + "value": true + } + ] + } + + Default Content Rules ^^^^^^^^^^^^^^^^^^^^^ @@ -428,7 +463,38 @@ Definition: "value": false } ] - }, + } + +``.m.rule.encrypted_room_one_to_one`` +``````````````````````````` +Matches any encrypted event sent in a room with exactly two members. + +Definition: + +.. code:: json + + { + "rule_id": ".m.rule.encrypted_room_one_to_one", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + } + ], + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ] + } ``.m.rule.room_one_to_one`` ``````````````````````````` @@ -446,6 +512,11 @@ Definition: { "kind": "room_member_count", "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.encrypted" } ], "actions": [ @@ -489,6 +560,34 @@ Definition: ] } +``.m.rule.encrypted`` +``````````````````` +Matches all encrypted events. + +Definition: + +.. code:: json + + { + "rule_id": ".m.rule.encrypted", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.encrypted" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ] + } + Conditions ++++++++++ @@ -523,6 +622,21 @@ rule determines its behaviour. The following conditions are defined: count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to ``==``. +``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. + + Parameters: + + * ``key``: The notification power level to require the sender to have. Refer to + the `m.room.power_levels`_ event schema for information about what the defaults + are and how to interpret the event. The ``key`` is used to look up a specific + 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. + Push Rules: API ~~~~~~~~~~~~~~~ From ab0be0457199e65d115ed3eb6fd46ba94f591d1a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:24:53 -0600 Subject: [PATCH 2/4] Fix titles --- specification/modules/push.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 94683436..408eabe6 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -370,7 +370,7 @@ Definition: ``.m.rule.roomnotif`` -````````````````````````````````` +````````````````````` Matches any message whose content is unencrypted and contains the text ``@room``, signifying the whole room should be notified of the event. @@ -466,7 +466,7 @@ Definition: } ``.m.rule.encrypted_room_one_to_one`` -``````````````````````````` +````````````````````````````````````` Matches any encrypted event sent in a room with exactly two members. Definition: @@ -561,7 +561,7 @@ Definition: } ``.m.rule.encrypted`` -``````````````````` +````````````````````` Matches all encrypted events. Definition: From bce324818b8e1a41e1ee313f6944ca3e03d27d40 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 22 Aug 2018 15:26:27 -0600 Subject: [PATCH 3/4] Changelog --- changelogs/client_server/newsfragments/1551.clarification | 1 + changelogs/client_server/newsfragments/1551.feature | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1551.clarification create mode 100644 changelogs/client_server/newsfragments/1551.feature diff --git a/changelogs/client_server/newsfragments/1551.clarification b/changelogs/client_server/newsfragments/1551.clarification new file mode 100644 index 00000000..06eac4da --- /dev/null +++ b/changelogs/client_server/newsfragments/1551.clarification @@ -0,0 +1 @@ +Clarify that new push rules should be enabled by default, and that unrecognised conditions should not match. diff --git a/changelogs/client_server/newsfragments/1551.feature b/changelogs/client_server/newsfragments/1551.feature new file mode 100644 index 00000000..dfce0f0a --- /dev/null +++ b/changelogs/client_server/newsfragments/1551.feature @@ -0,0 +1 @@ +Add new push rules for encrypted events and ``@room`` notifications. From bac0392a2d98662b19f32f2955daca145e42a499 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 27 Aug 2018 17:28:08 -0600 Subject: [PATCH 4/4] General clarity for push rule defaults and where to get information Include moving a roaming condition that was under the wrong rule. --- specification/modules/push.rst | 29 ++++++++++++++++++----------- 1 file changed, 18 insertions(+), 11 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 408eabe6..1972fa17 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -468,6 +468,10 @@ Definition: ``.m.rule.encrypted_room_one_to_one`` ````````````````````````````````````` Matches any encrypted event sent in a room with exactly two members. +Unlike other push rules, this rule cannot be matched against the content +of the event by nature of it being encrypted. This causes the rule to +be an "all or nothing" match where it either matches *all* events that +are encrypted (in 1:1 rooms) or none. Definition: @@ -492,6 +496,11 @@ Definition: { "set_tweak": "highlight", "value": false + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.encrypted" } ] } @@ -512,11 +521,6 @@ Definition: { "kind": "room_member_count", "is": "2" - }, - { - "kind": "event_match", - "key": "type", - "pattern": "m.room.encrypted" } ], "actions": [ @@ -562,7 +566,10 @@ Definition: ``.m.rule.encrypted`` ````````````````````` -Matches all encrypted events. +Matches all encrypted events. Unlike other push rules, this rule cannot +be matched against the content of the event by nature of it being encrypted. +This causes the rule to be an "all or nothing" match where it either +matches *all* events that are encrypted (in 1:1 rooms) or none. Definition: @@ -628,11 +635,11 @@ rule determines its behaviour. The following conditions are defined: Parameters: - * ``key``: The notification power level to require the sender to have. Refer to - the `m.room.power_levels`_ event schema for information about what the defaults - are and how to interpret the event. The ``key`` is used to look up a specific - notification type from the ``notifications`` object in the power level event - content. + * ``key``: A string that determines the power level the sender must have to trigger + notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_ + event schema for information about what the defaults are and how to interpret the event. + The ``key`` is used 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.