wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Swaggerify the /enabled endpoint

Browse source
This commit is contained in:
Kegan Dougal 2015-10-08 11:16:42 +01:00
parent 56ce432399
commit a9618a981b
5 changed files with 112 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

2
api/check_examples.py
View file

@ -52,7 +52,7 @@ def check_parameter(filepath, request, parameter):
jsonschema.validate(example, schema) jsonschema.validate(example, schema)
except Exception as e: except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % ( raise ValueError("Error validating JSON schema for %r %r" % (
request, code request
), e) ), e)

49
api/client-server/v1/pushrules.yaml
View file

@ -436,4 +436,51 @@ paths:
description: This request was rate-limited. description: This request was rate-limited.
schema: schema:
"$ref": "definitions/error.yaml" "$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/<profile_tag>`` 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: <body>
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

93
specification/modules/push.rst
View file

@ -110,7 +110,7 @@ Underride
In addition, each kind of rule may be either global or device-specific. Device 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 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 rules. Thusly, the full list of rule kinds, in descending priority order, is as
follows: 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. themselves are never alerted for.
Predefined Rules Predefined Rules
~~~~~~~~~~~~~~~~ ++++++++++++++++
Matrix specifies the following rule IDs for server default rules. Home Servers 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 may define rules as follows with the given IDs. If Home Servers provide rules
with these IDs, their semantics should match those given below: 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 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 notification is delivered for a matching event. This standard defines the
following actions, although if Home servers wish to support more, they are free 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 represented as a dictionary with a key equal to their name and other keys as
their parameters, e.g. ``{ "set_tweak": "sound", "value": "default" }`` 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 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: 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 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. client may choose a sensible behaviour for the tweak.
Push Rules: Conditions Conditions
~~~~~~~~~~~~~~~~~~~~~~ ++++++++++
Override, Underride and Default rules have a list of 'conditions'. All 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 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 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 using parameters named as described above. In the cases of room and sender
rules, the rule_id of the rule determines its behaviour. rules, the rule_id of the rule determines its behaviour.
{{pushrules_http_api}}
Push Rules: API Push Rules: API
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
The content of the PUT request is a JSON object with a list of actions under the Clients can retrieve, add, modify and remove push rules globally or per-device
'actions' key and either conditions (under the 'conditions' key) or the using the APIs below.
appropriate parameters for the rule (under the appropriate key name).
Examples: {{pushrules_http_api}}
To create a rule that suppresses notifications for the room with ID '!dj234r78wl45Gh4D:matrix.org':: Examples
++++++++
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 create a rule that suppresses notifications for the room with ID
``!dj234r78wl45Gh4D:matrix.org``::
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/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
'{
"actions" : ["dont_notify"]
}'
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 suppress notifications for the user ``@spambot:matrix.org``::
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/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
'{
"actions" : ["dont_notify"]
}'
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 always notify for messages that contain the work 'cake' and set a specific
sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``)::
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" "http://localhost:8008/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
'{
"pattern": "cake",
"actions" : ["notify", {"set_sound":"cakealarm.wav"}]
}'
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" To add a rule suppressing notifications for messages starting with 'cake' but
ending with 'lie', superseding the previous rule::
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/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
'{
"pattern": "cake*lie",
"actions" : ["notify"]
}'
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 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 \
Enabling and Disabling Rules '{
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "conditions": [
Rules can be enabled or disabled with a PUT operation to the 'enabled' component {"kind": "event_match", "key": "content.body", "pattern": "beer" },
beneath the rule's URI with a content of 'true' or 'false':: {"kind": "room_member_count", "is": "<=10"}
],
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" "actions" : [
"notify",
{"set_sound":"beeroclock.wav"}
]
}'
Server behaviour Server behaviour
---------------- ----------------
@ -504,8 +525,11 @@ rejected
necessarily be the notification in the request that failed: it could be that necessarily be the notification in the request that failed: it could be that
a previous notification to the same pushkey failed. 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 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 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 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 gateway before returning and instead to store failures and return
'rejected' responses next time that pushkey is used. 'rejected' responses next time that pushkey is used.
Push Gateway behaviour
----------------------
Security considerations Security considerations
----------------------- -----------------------

2
specification/targets.yaml
View file

@ -24,7 +24,7 @@ groups: # reusable blobs of files when prefixed with 'group:'
- modules/history_visibility.rst - modules/history_visibility.rst
- modules/push.rst - modules/push.rst
title_styles: ["=", "-", "~", "+", "^"] title_styles: ["=", "-", "~", "+", "^", "`"]
# The templating system doesn't know the right title style to use when generating # 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 # RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title

5
templating/matrix_templates/units.py
View file

@ -184,6 +184,11 @@ class MatrixUnits(Units):
val_type = refType # TODO: Resolve to human-readable. val_type = refType # TODO: Resolve to human-readable.
if not val_type and schemaFmt: if not val_type and schemaFmt:
val_type = 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: if val_type:
endpoint["req_params"].append({ endpoint["req_params"].append({
"key": param["name"], "key": param["name"],