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

@@ -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: {
               }

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
 ~~~~~~~~~~~~~~~