From 8a1a02a11bc63a93c5e43a594bebd813a27cefe2 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 15 Feb 2016 16:28:43 +0000 Subject: [PATCH 1/6] Update the predefined push rules in the spec --- specification/modules/push.rst | 230 ++++++++++++++++++++++++++++----- 1 file changed, 197 insertions(+), 33 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 133b838a..d0c3968c 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -202,14 +202,70 @@ than "user-defined rules". The ``rule_id`` for all server-default rules MUST start with a dot (".") to identify them as "server-default". The following server-default rules are specified: + +Default Override Rules +^^^^^^^^^^^^^^^^^^^^^^ + +``m.rule.master`` + Matches all events, this can be enabled to turn off all push notifications + other than those generated by override rules set by the user. By default this + rule is disabled. + + Definition + +.. code:: json + + { + "rule_id": ".m.rule.master, + "default": true, + "enabled": false, + "conditions": [], + "actions": [ + "dont_notify" + ] + } + +``.m.rule.suppress_notices`` + Matches messages with a ``msgtype`` of ``notice``. This should be an + ``override`` rule so that it takes priority over ``content`` / ``sender`` / + ``room`` rules. + + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.suppress_notices", + "default": true, + "enabled": true, + "conditions': [ + { + "kind": "event_match", + "key": "content.msgtype", + "pattern": "m.notice", + } + ], + "actions": [ + "dont_notify", + ] + } + + +Default Content Rules +^^^^^^^^^^^^^^^^^^^^^ + ``.m.rule.contains_user_name`` Matches any message whose content is unencrypted and contains the local part of the user's Matrix ID, separated by word boundaries. - Definition (as a ``content`` rule):: + Definition (as a ``content`` rule): + +.. code:: json { - "rule_id": ".m.rule.contains_user_name" + "rule_id": ".m.rule.contains_user_name", + "default": true, + "enabled": true, "pattern": "[the local part of the user's Matrix ID]", "actions": [ "notify", @@ -217,17 +273,56 @@ server-default rules are specified: "set_tweak": "sound", "value": "default" } - ], + ] } +Default Underride Rules +^^^^^^^^^^^^^^^^^^^^^^^ + +``.m.rule.call`` + Matches any incoming VOIP call. + + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.call", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ] + }, + + ``.m.rule.contains_display_name`` Matches any message whose content is unencrypted and contains the user's current display name in the room in which it was sent. - Definition (this rule can only be an ``override`` or ``underride`` rule):: + Definition: + +.. code:: json { - "rule_id": ".m.rule.contains_display_name" + "rule_id": ".m.rule.contains_display_name", + "default": true, + "enabled": true, "conditions": [ { "kind": "contains_display_name" @@ -238,21 +333,28 @@ server-default rules are specified: { "set_tweak": "sound", "value": "default" + }, + { + "set_tweak": "highlight" } - ], + ] } ``.m.rule.room_one_to_one`` Matches any message sent in a room with exactly two members. - Definition (this rule can only be an ``override`` or ``underride`` rule):: + Definition: + +.. code:: json { - "rule_id": ".m.rule.room_two_members" + "rule_id": ".m.rule.room_two_members", + "default": true, + "enabled": true, "conditions": [ { - "is": "2", "kind": "room_member_count" + "is": "2", } ], "actions": [ @@ -260,46 +362,108 @@ server-default rules are specified: { "set_tweak": "sound", "value": "default" + }, + { + "set_tweak": "highlight", + "value": false } ], } -``.m.rule.suppress_notices`` - Matches messages with a ``msgtype`` of ``notice``. This should be an - ``override`` rule so that it takes priority over ``content`` / ``sender`` / - ``room`` rules. +``.m.rule.invite_for_me`` + Matches any invites to a new room for this user. - Definition:: + Definition: + +.. code:: json { - 'rule_id': '.m.rule.suppress_notices', - 'conditions': [ + "rule_id": ".m.rule.invite_for_me", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, { - 'kind': 'event_match', - 'key': 'content.msgtype', - 'pattern': 'm.notice', + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" } ], - 'actions': [ - 'dont-notify', + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } ] } - -``.m.rule.fallback`` - Matches any message. Used to define the behaviour of messages that match no - other rules. If homeservers define this it should be the lowest priority - ``underride`` rule. - Definition:: +``.m.rule.member_event`` + Matches membership change events. - { - "rule_id": ".m.rule.fallback" - "conditions": [], - "actions": [ - "notify" + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.member_event", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } ], - } + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ] + } +``.m.rule.message`` + Matches all chat messages. + + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.member_event", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ] + } Conditions From b16af5ef6454db3cf32eb28641947fe9787fb30c Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 15 Feb 2016 16:41:47 +0000 Subject: [PATCH 2/6] Fix JSON, add headers --- specification/modules/push.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index d0c3968c..11ce8154 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -207,6 +207,7 @@ Default Override Rules ^^^^^^^^^^^^^^^^^^^^^^ ``m.rule.master`` +````````````````` Matches all events, this can be enabled to turn off all push notifications other than those generated by override rules set by the user. By default this rule is disabled. @@ -216,7 +217,7 @@ Default Override Rules .. code:: json { - "rule_id": ".m.rule.master, + "rule_id": ".m.rule.master", "default": true, "enabled": false, "conditions": [], @@ -226,6 +227,7 @@ Default Override Rules } ``.m.rule.suppress_notices`` +```````````````````````````` Matches messages with a ``msgtype`` of ``notice``. This should be an ``override`` rule so that it takes priority over ``content`` / ``sender`` / ``room`` rules. @@ -238,7 +240,7 @@ Default Override Rules "rule_id": ".m.rule.suppress_notices", "default": true, "enabled": true, - "conditions': [ + "conditions": [ { "kind": "event_match", "key": "content.msgtype", @@ -255,6 +257,7 @@ Default Content Rules ^^^^^^^^^^^^^^^^^^^^^ ``.m.rule.contains_user_name`` +`````````````````````````````` Matches any message whose content is unencrypted and contains the local part of the user's Matrix ID, separated by word boundaries. @@ -280,6 +283,7 @@ Default Underride Rules ^^^^^^^^^^^^^^^^^^^^^^^ ``.m.rule.call`` +```````````````` Matches any incoming VOIP call. Definition: @@ -312,6 +316,7 @@ Default Underride Rules ``.m.rule.contains_display_name`` +````````````````````````````````` Matches any message whose content is unencrypted and contains the user's current display name in the room in which it was sent. @@ -341,6 +346,7 @@ Default Underride Rules } ``.m.rule.room_one_to_one`` +``````````````````````````` Matches any message sent in a room with exactly two members. Definition: @@ -367,10 +373,11 @@ Default Underride Rules "set_tweak": "highlight", "value": false } - ], + ] } ``.m.rule.invite_for_me`` +````````````````````````` Matches any invites to a new room for this user. Definition: @@ -412,6 +419,7 @@ Default Underride Rules } ``.m.rule.member_event`` +```````````````````````` Matches membership change events. Definition: @@ -439,6 +447,7 @@ Default Underride Rules } ``.m.rule.message`` +``````````````````` Matches all chat messages. Definition: From afe7638e302bbd45a5e1fa2ff11c2162216ce3d6 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 15 Feb 2016 16:50:15 +0000 Subject: [PATCH 3/6] Add a new title level to appease gendoc --- specification/targets.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/targets.yaml b/specification/targets.yaml index 98ca9322..4b08d6ef 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -42,7 +42,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/event_context.rst -title_styles: ["=", "-", "~", "+", "^", "`", "@"] +title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"] # The templating system doesn't know the right title style to use when generating # RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title From 5d85e3a505f81d2c7ece4e7398deca8f2361d3a1 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 15 Feb 2016 16:53:08 +0000 Subject: [PATCH 4/6] Remove indents --- specification/modules/push.rst | 48 +++++++++++++++++----------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 11ce8154..f3690159 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -208,11 +208,11 @@ Default Override Rules ``m.rule.master`` ````````````````` - Matches all events, this can be enabled to turn off all push notifications - other than those generated by override rules set by the user. By default this - rule is disabled. +Matches all events, this can be enabled to turn off all push notifications +other than those generated by override rules set by the user. By default this +rule is disabled. - Definition +Definition .. code:: json @@ -228,11 +228,11 @@ Default Override Rules ``.m.rule.suppress_notices`` ```````````````````````````` - Matches messages with a ``msgtype`` of ``notice``. This should be an - ``override`` rule so that it takes priority over ``content`` / ``sender`` / - ``room`` rules. +Matches messages with a ``msgtype`` of ``notice``. This should be an +``override`` rule so that it takes priority over ``content`` / ``sender`` / +``room`` rules. - Definition: +Definition: .. code:: json @@ -258,10 +258,10 @@ Default Content Rules ``.m.rule.contains_user_name`` `````````````````````````````` - Matches any message whose content is unencrypted and contains the local part - of the user's Matrix ID, separated by word boundaries. +Matches any message whose content is unencrypted and contains the local part +of the user's Matrix ID, separated by word boundaries. - Definition (as a ``content`` rule): +Definition (as a ``content`` rule): .. code:: json @@ -284,9 +284,9 @@ Default Underride Rules ``.m.rule.call`` ```````````````` - Matches any incoming VOIP call. +Matches any incoming VOIP call. - Definition: +Definition: .. code:: json @@ -317,10 +317,10 @@ Default Underride Rules ``.m.rule.contains_display_name`` ````````````````````````````````` - Matches any message whose content is unencrypted and contains the user's - current display name in the room in which it was sent. +Matches any message whose content is unencrypted and contains the user's +current display name in the room in which it was sent. - Definition: +Definition: .. code:: json @@ -347,9 +347,9 @@ Default Underride Rules ``.m.rule.room_one_to_one`` ``````````````````````````` - Matches any message sent in a room with exactly two members. +Matches any message sent in a room with exactly two members. - Definition: +Definition: .. code:: json @@ -378,9 +378,9 @@ Default Underride Rules ``.m.rule.invite_for_me`` ````````````````````````` - Matches any invites to a new room for this user. +Matches any invites to a new room for this user. - Definition: +Definition: .. code:: json @@ -420,9 +420,9 @@ Default Underride Rules ``.m.rule.member_event`` ```````````````````````` - Matches membership change events. +Matches membership change events. - Definition: +Definition: .. code:: json @@ -448,9 +448,9 @@ Default Underride Rules ``.m.rule.message`` ``````````````````` - Matches all chat messages. +Matches all chat messages. - Definition: +Definition: .. code:: json From 8a050aebc0e085455ff99aad663d39e1efecddae Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Mon, 15 Feb 2016 17:17:58 +0000 Subject: [PATCH 5/6] Add a note to the docs for before and after to make it clear that they cannot be used with the predefined rules --- api/client-server/pushrules.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index 07bd6bdb..2aba7bd9 100644 --- a/api/client-server/pushrules.yaml +++ b/api/client-server/pushrules.yaml @@ -380,7 +380,8 @@ paths: x-example: someRuleId description: |- Use 'before' with a ``rule_id`` as its value to make the new rule the - next-most important rule with respect to the given rule. + next-most important rule with respect to the given user defined rule. + It is not possible to add a rule relative to a predefined server rule. - in: query type: string name: after @@ -388,7 +389,8 @@ paths: x-example: anotherRuleId description: |- This makes the new rule the next-less important rule relative to the - given rule. + given user defined rule. It is not possible to add a rule relative + to a predefined server rule. - in: body name: pushrule description: |- From 740f7759324d8d6b7dcab1fc14f0c10b7408519f Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 18 Feb 2016 18:36:08 +0000 Subject: [PATCH 6/6] Fix a couple of typos, remove .m.rule.member_event --- specification/modules/push.rst | 38 +++++----------------------------- 1 file changed, 5 insertions(+), 33 deletions(-) diff --git a/specification/modules/push.rst b/specification/modules/push.rst index f3690159..363d1a66 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -354,13 +354,13 @@ Definition: .. code:: json { - "rule_id": ".m.rule.room_two_members", + "rule_id": ".m.rule.room_one_to_one", "default": true, "enabled": true, "conditions": [ { - "kind": "room_member_count" - "is": "2", + "kind": "room_member_count", + "is": "2" } ], "actions": [ @@ -402,7 +402,7 @@ Definition: { "key": "state_key", "kind": "event_match", - "pattern": "@alice:example.com" + "pattern": "[the user's Matrix ID]" } ], "actions": [ @@ -418,34 +418,6 @@ Definition: ] } -``.m.rule.member_event`` -```````````````````````` -Matches membership change events. - -Definition: - -.. code:: json - - { - "rule_id": ".m.rule.member_event", - "default": true, - "enabled": true, - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - } - ], - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ] - } - ``.m.rule.message`` ``````````````````` Matches all chat messages. @@ -455,7 +427,7 @@ Definition: .. code:: json { - "rule_id": ".m.rule.member_event", + "rule_id": ".m.rule.message", "default": true, "enabled": true, "conditions": [