XEP-0357 Business rules implementation in prosody
=================================================

Daniel proposed some business rules for push notifications [^1]
This document describes the various implementation details involved in
implementing these rules in prosody.

Point 3 of Daniel's mail is implemented by setting two attributes
on the session table when a client enables push for a session:

- push_identifier: this is push_jid .. "<" .. (push_node or "")
  (this value is used as key of the user_push_services table)
- push_settings: this is a reference to the user_push_services[push_identifier]


Point 4 of Daniel's mail contains the actual business rules
-----------------------------------------------------------

**a)**  
CSI is honoured in this scenario because messages hold back by csi don't even
reach the smacks module. mod_smacks has 3 events:

- smacks-ack-delayed: This event is triggered when the client doesn't respond to
   a smacks <r> in a configurable amount of time (default: 60 seconds).
   Mod_cloud_notify reacts on this event and sends out push notifications
   to the push service registered for this session in point 3 (see above) for all
   stanzas in the smacks queue (the queue is given in the event).

- smacks-hibernation-start: This event is triggered when the smacks session
  is put in hibernation state. The event contains the smacks queue, too.
  Mod_cloud_notify uses this event to send push notifications for all
  stanzas not already pushed and installs a "stanzas/out"-filter to
  react on new stanzas coming in while the session is hibernated.
  The push endpoint of the hibernated session is then also notified
  for every new stanza.
- smacks-hibernation-end: This event is triggered, when the smacks hibernation
  is stopped (the smacks session is resumed) and used by Mod_cloud_notify
  to remove the "stanzas/out"-filter.

**b)**  
Mod_mam already provides an event named "archive-message-added" which is
triggered every time a stanza is saved into the mam store.
Mod_cloud_notify uses this event to send out push notifications to all
push services registered for the user the stanza is for, but *only*
to those push services not having an active (or smacks hibernated) session.
Only those stanzas are considered that contain the "for_user" event attribute
of mod_mam as the user part of the jid.
This is done to ensure that mam archiving rules are honoured.

**c)**  
The "message/offline/handle"-hook is used to send out push notifications to all
registered push services belonging to the user the offline stanza is for.
This was already implemented in the first version of mod_cloud_notify.


Some statements to related technologies/XEPs/modules
----------------------------------------------------

- carbons: These are handled as usual and don't interfere with these business rules
  at all. Smacks events are generated for carbon copies if needed and mod_cloud_notify
  uses them to wake up the device in question if needed, as normal stanzas would do, too.

- csi: Csi is honoured also, because every stanza hold back by mod_pump or other csi
  modules is never seen by the smacks module, thus not added to its queue and not
  forwarded to mod_cloud_notify by the smacks events.
  Mod_cloud_notify does only notify devices having no active or smacks hibernated session
  of new mam stored stanzas, so stanzas filtered by csi don't get to mod_cloud_notify
  this way neither.

- other technologies: There shouldn't be any issues with other technologies imho.

[^1]: https://mail.jabber.org/pipermail/standards/2016-February/030925.html