<commit_before>Push Notifications
==================

Pushers
-------
To receive any notification pokes at all, it is necessary to configure a
'pusher' on the Home Server that you wish to receive notifications from. There
is a single API endpoint for this::

	POST $PREFIX/pushers/set

This takes a JSON object with the following keys:

pushkey
  This is a unique identifier for this pusher. The value you should use for this
  is the routing or destination address information for the notification, for
  example, the APNS token for APNS or the Registration ID for GCM. If your
  notification client has no such concept, use any unique identifier.
kind
  The kind of pusher to configure. 'http' makes a pusher that sends HTTP pokes.
  null deletes the pusher.
profile_tag
  This is a string that determines what set of device rules will be matched when
  evaluating push rules for this pusher. It is an arbitrary string. Multiple
  devices maybe use the same profile_tag. It is advised that when an app's
  data is copied or restored to a different device, this value remain the same.
  Client apps should offer ways to change the profile_tag, optionally copying
  rules from the old profile tag.
app_id
  appId is a reverse-DNS style identifier for the application. It is recommended
  that this end with the platform, such that different platform versions get
  different app identifiers. Max length, 64 chars.
app_display_name
  A string that will allow the user to identify what application owns this
  pusher.
device_display_name
  A string that will allow the user to identify what device owns this pusher.
lang
  The preferred language for receiving notifications (eg, 'en' or 'en-US')
data
  A dictionary of information for the pusher implementation itself. For HTTP
  pushers, this must contain a 'url' key which is a string of the URL that
  should be used to send notifications.

If the pusher was created successfully, an empty JSON dictionary is returned.


Push Rules
----------
Home Servers have an interface to configure what events trigger notifications.
This behaviour is configured through 'Push Rules'. Push Rules come in a variety
of different kinds and each kind of rule has an associated priority. The
different kinds of rule, in descending order of priority, are:

Override Rules
  The highest priority rules are user-configured overrides.
Content Rules
  These configure behaviour for (unencrypted) messages that match certain
  patterns. Content rules take one parameter, 'pattern', that gives the pattern
  to match against. This is treated in the same way as pattern for event_match
  conditions, below.
Room Rules
  These change the behaviour of all messages to a given room. The rule_id of a
  room rule is always the ID of the room that it affects.
Sender
  These rules configure notification behaviour for messages from a specific,
  named Matrix user ID. The rule_id of Sender rules is always the Matrix user
  ID of the user whose messages theyt apply to.
Underride
  These are identical to override rules, but have a lower priority than content,
  room and sender rules.

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
rules. Thusly, the full list of rule kinds, in descending priority order, is as
follows:

 * Device-specific Override
 * Device-specific Content
 * Device-specific Room
 * Device-specific Sender
 * Device-specific Underride
 * Global Override
 * Global Content
 * Global Room
 * Global Sender
 * Global Underride

For some kinds of rule, rules of the same kind also have an ordering with
respect to one another. The kinds that do not are room and sender rules where
the rules are mutually exclusive by definition and therefore an ordering would
be redundant. Actions for the highest priority rule and only that rule apply
(for example, a set_tweak action in a lower priority rule will not apply if a
higher priority rule matches, even if that rule does not specify any tweaks).

Rules also have an identifier, rule_id, which is a string.  The rule_id is
unique within the kind of rule and scope: rule_ids need not be unique between
rules of the same kind on different devices.

A home server may also have server default rules of each kind and in each scope.
Server default rules are lower priority than user-defined rules in eacgh scope.
Server defined rules do not have a rule_id except when it is necessary to derive
the function of the rule (ie. in room and sender rules).

Push Rules: Actions:
--------------------
All rules have an associated list of 'actions'. An action affects if and how a
notification is delievered for a matching event. This standard defines the
following actions, although if Home servers wish to support more, they are free
to do so:

notify
  This causes each matching event to generate a notification.
dont_notify<commit_msg>How to tell server default rules from other rules.<commit_after>Push Notifications
==================

Pushers
-------
To receive any notification pokes at all, it is necessary to configure a
'pusher' on the Home Server that you wish to receive notifications from. There
is a single API endpoint for this::

	POST $PREFIX/pushers/set

This takes a JSON object with the following keys:

pushkey
  This is a unique identifier for this pusher. The value you should use for this
  is the routing or destination address information for the notification, for
  example, the APNS token for APNS or the Registration ID for GCM. If your
  notification client has no such concept, use any unique identifier.
kind
  The kind of pusher to configure. 'http' makes a pusher that sends HTTP pokes.
  null deletes the pusher.
profile_tag
  This is a string that determines what set of device rules will be matched when
  evaluating push rules for this pusher. It is an arbitrary string. Multiple
  devices maybe use the same profile_tag. It is advised that when an app's
  data is copied or restored to a different device, this value remain the same.
  Client apps should offer ways to change the profile_tag, optionally copying
  rules from the old profile tag.
app_id
  appId is a reverse-DNS style identifier for the application. It is recommended
  that this end with the platform, such that different platform versions get
  different app identifiers. Max length, 64 chars.
app_display_name
  A string that will allow the user to identify what application owns this
  pusher.
device_display_name
  A string that will allow the user to identify what device owns this pusher.
lang
  The preferred language for receiving notifications (eg, 'en' or 'en-US')
data
  A dictionary of information for the pusher implementation itself. For HTTP
  pushers, this must contain a 'url' key which is a string of the URL that
  should be used to send notifications.

If the pusher was created successfully, an empty JSON dictionary is returned.


Push Rules
----------
Home Servers have an interface to configure what events trigger notifications.
This behaviour is configured through 'Push Rules'. Push Rules come in a variety
of different kinds and each kind of rule has an associated priority. The
different kinds of rule, in descending order of priority, are:

Override Rules
  The highest priority rules are user-configured overrides.
Content Rules
  These configure behaviour for (unencrypted) messages that match certain
  patterns. Content rules take one parameter, 'pattern', that gives the pattern
  to match against. This is treated in the same way as pattern for event_match
  conditions, below.
Room Rules
  These change the behaviour of all messages to a given room. The rule_id of a
  room rule is always the ID of the room that it affects.
Sender
  These rules configure notification behaviour for messages from a specific,
  named Matrix user ID. The rule_id of Sender rules is always the Matrix user
  ID of the user whose messages theyt apply to.
Underride
  These are identical to override rules, but have a lower priority than content,
  room and sender rules.

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
rules. Thusly, the full list of rule kinds, in descending priority order, is as
follows:

 * Device-specific Override
 * Device-specific Content
 * Device-specific Room
 * Device-specific Sender
 * Device-specific Underride
 * Global Override
 * Global Content
 * Global Room
 * Global Sender
 * Global Underride

For some kinds of rule, rules of the same kind also have an ordering with
respect to one another. The kinds that do not are room and sender rules where
the rules are mutually exclusive by definition and therefore an ordering would
be redundant. Actions for the highest priority rule and only that rule apply
(for example, a set_tweak action in a lower priority rule will not apply if a
higher priority rule matches, even if that rule does not specify any tweaks).

Rules also have an identifier, rule_id, which is a string.  The rule_id is
unique within the kind of rule and scope: rule_ids need not be unique between
rules of the same kind on different devices.

A home server may also have server default rules of each kind and in each scope.
Server default rules are lower priority than user-defined rules in eacgh scope.
Server defined rules do not have a rule_id except when it is necessary to derive
the function of the rule (ie. in room and sender rules). Server default rules
have an attribute, "default" set to true.

Push Rules: Actions:
--------------------
All rules have an associated list of 'actions'. An action affects if and how a
notification is delievered for a matching event. This standard defines the
following actions, although if Home servers wish to support more, they are free
to do so:

notify
  This causes each matching event to generate a notification.
dont_notify
{'fraction_non_alphanumeric': 0.03871287128712871, 'fraction_numerical': 0.00039603960396039607, 'mean_word_length': 4.053026513256628, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '314359', 'n_tokens_mistral': 2428, 'n_tokens_neox': 2369, 'n_words': 1581}