diff --git a/api/check_examples.py b/api/check_examples.py index f08b2dc1..0622bfeb 100755 --- a/api/check_examples.py +++ b/api/check_examples.py @@ -52,7 +52,7 @@ def check_parameter(filepath, request, parameter): jsonschema.validate(example, schema) except Exception as e: raise ValueError("Error validating JSON schema for %r %r" % ( - request, code + request ), e) diff --git a/api/client-server/v1/pushrules.yaml b/api/client-server/v1/pushrules.yaml index c9dd777e..eef0b2c7 100644 --- a/api/client-server/v1/pushrules.yaml +++ b/api/client-server/v1/pushrules.yaml @@ -436,4 +436,51 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" - + "/pushrules/{scope}/{kind}/{ruleId}/enabled": + put: + summary: "Enable or disable a push rule." + description: |- + This endpoint allows clients to enable or disable the specified push rule. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: scope + required: true + x-example: "global" + description: |- + Either ``global`` or ``device/`` to specify global + rules or device rules for the given ``profile_tag``. + - in: path + type: string + name: kind + required: true + x-example: room + enum: ["override", "underride", "sender", "room", "content"] + description: | + The kind of rule + - in: path + type: string + name: ruleId + required: true + x-example: "#spam:example.com" + description: | + The identifier for the rule. + - in: body + name: + description: | + Whether the push rule is enabled or not. + required: true + schema: + type: boolean + example: |- + true + responses: + 200: + description: The push rule was enabled or disabled. + examples: + application/json: |- + {} + schema: + type: object # empty json object diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 6411f3df..ab3f0bf0 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -110,7 +110,7 @@ Underride In addition, each kind of rule may be either global or device-specific. Device specific rules only affect delivery of notifications via pushers with a matching -profile_tag. All device-specific rules are higher priority than all global +``profile_tag``. All device-specific rules are higher priority than all global rules. Thusly, the full list of rule kinds, in descending priority order, is as follows: @@ -145,7 +145,7 @@ If no rules match an event, the Home Server should not notify for the message themselves are never alerted for. Predefined Rules -~~~~~~~~~~~~~~~~ +++++++++++++++++ Matrix specifies the following rule IDs for server default rules. Home Servers may define rules as follows with the given IDs. If Home Servers provide rules with these IDs, their semantics should match those given below: @@ -247,8 +247,8 @@ with these IDs, their semantics should match those given below: ], } -Push Rules: Actions: -~~~~~~~~~~~~~~~~~~~~ +Actions ++++++++ All rules have an associated list of 'actions'. An action affects if and how a notification is delivered for a matching event. This standard defines the following actions, although if Home servers wish to support more, they are free @@ -273,8 +273,8 @@ Actions that have no parameters are represented as a string. Otherwise, they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. ``{ "set_tweak": "sound", "value": "default" }`` -Push Rules: Actions: Tweaks -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Tweaks +^^^^^^ The ``set_tweak`` key action is used to add an entry to the 'tweaks' dictionary that is sent in the notification poke. The following tweaks are defined: @@ -295,8 +295,8 @@ notification light on a mobile device. If a kind of tweak that a client understands is not specified in an action, the client may choose a sensible behaviour for the tweak. -Push Rules: Conditions -~~~~~~~~~~~~~~~~~~~~~~ +Conditions +++++++++++ Override, Underride and Default rules have a list of 'conditions'. All conditions must hold true for an event in order for a rule to be applied to an event. A rule with no conditions always matches. Matrix specifies the following @@ -332,44 +332,65 @@ but instead have predefined conditions, the behaviour of which can be configured using parameters named as described above. In the cases of room and sender rules, the rule_id of the rule determines its behaviour. -{{pushrules_http_api}} - Push Rules: API ~~~~~~~~~~~~~~~ -The content of the PUT request is a JSON object with a list of actions under the -'actions' key and either conditions (under the 'conditions' key) or the -appropriate parameters for the rule (under the appropriate key name). - -Examples: - -To create a rule that suppresses notifications for the room with ID '!dj234r78wl45Gh4D:matrix.org':: - - curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" - -To suppress notifications for the user '@spambot:matrix.org':: - - curl -X PUT -H "Content-Type: application/json" -d '{ "actions" : ["dont_notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" - -To always notify for messages that contain the work 'cake' and set a specific sound (with a rule_id of 'SSByZWFsbHkgbGlrZSBjYWtl'):: - - curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake", "actions" : ["notify", {"set_sound":"cakealarm.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" - -To add a rule suppressing notifications for messages starting with 'cake' but ending with 'lie', superseeding the previous rule:: - - curl -X PUT -H "Content-Type: application/json" -d '{ "pattern": "cake*lie", "actions" : ["notify"] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" +Clients can retrieve, add, modify and remove push rules globally or per-device +using the APIs below. -To add a custom sound for notifications messages containing the word 'beer' in any rooms with 10 members or fewer (with greater importance than the room, sender and content rules):: - - curl -X PUT -H "Content-Type: application/json" -d '{ "conditions": [{"kind": "event_match", "key": "content.body", "pattern": "beer" }, {"kind": "room_member_count", "is": "<=10"}], "actions" : ["notify", {"set_sound":"beeroclock.wav"}] }' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456 - - -Enabling and Disabling Rules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Rules can be enabled or disabled with a PUT operation to the 'enabled' component -beneath the rule's URI with a content of 'true' or 'false':: +{{pushrules_http_api}} - curl -X PUT -H "Content-Type: application/json" -d 'false' "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org/enabled?access_token=123456" +Examples +++++++++ + +To create a rule that suppresses notifications for the room with ID +``!dj234r78wl45Gh4D:matrix.org``:: + + curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \ + '{ + "actions" : ["dont_notify"] + }' + +To suppress notifications for the user ``@spambot:matrix.org``:: + + curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \ + '{ + "actions" : ["dont_notify"] + }' + +To always notify for messages that contain the work 'cake' and set a specific +sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``):: + + curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \ + '{ + "pattern": "cake", + "actions" : ["notify", {"set_sound":"cakealarm.wav"}] + }' + +To add a rule suppressing notifications for messages starting with 'cake' but +ending with 'lie', superseding the previous rule:: + + curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \ + '{ + "pattern": "cake*lie", + "actions" : ["notify"] + }' + +To add a custom sound for notifications messages containing the word 'beer' in +any rooms with 10 members or fewer (with greater importance than the room, +sender and content rules):: + + curl -X PUT -H "Content-Type: application/json" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \ + '{ + "conditions": [ + {"kind": "event_match", "key": "content.body", "pattern": "beer" }, + {"kind": "room_member_count", "is": "<=10"} + ], + "actions" : [ + "notify", + {"set_sound":"beeroclock.wav"} + ] + }' Server behaviour ---------------- @@ -504,8 +525,11 @@ rejected necessarily be the notification in the request that failed: it could be that a previous notification to the same pushkey failed. -Push: Recommendations for APNS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Push Gateway behaviour +---------------------- + +Recommendations for APNS +~~~~~~~~~~~~~~~~~~~~~~~~ For sending APNS notifications, the exact format is flexible and up to the client app and its push gateway to agree on (since APNS requires that the sender have a private key owned by the app developer, each app must have its own push @@ -518,9 +542,6 @@ gateway). However, Matrix strongly recommends: gateway before returning and instead to store failures and return 'rejected' responses next time that pushkey is used. -Push Gateway behaviour ----------------------- - Security considerations ----------------------- diff --git a/specification/targets.yaml b/specification/targets.yaml index 8106b7cf..5786ea6b 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -24,7 +24,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/history_visibility.rst - modules/push.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 diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 24e92f5a..c3be2b60 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -184,6 +184,11 @@ class MatrixUnits(Units): val_type = refType # TODO: Resolve to human-readable. if not val_type and schemaFmt: val_type = schemaFmt + # handle top-level strings/bools + if not val_type and Units.prop(param, "schema/type") == "string": + val_type = "string" + if not val_type and Units.prop(param, "schema/type") == "boolean": + val_type = "boolean" if val_type: endpoint["req_params"].append({ "key": param["name"],