annotate mod_cloud_notify/business_rules.markdown @ 5262:e73f364b5624

mod_http_oauth2: Rename oauth client credential related functions To make it more explicit what "secret" these deal with.
author Kim Alvefur <zash@zash.se>
date Tue, 21 Mar 2023 21:36:54 +0100
parents 6ab46ff685d0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
1 XEP-0357 Business rules implementation in prosody
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
2 =================================================
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
3
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
4 Daniel proposed some business rules for push notifications [^1]
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
5 This document describes the various implementation details involved in
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
6 implementing these rules in prosody.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
7
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
8 Point 3 of Daniel's mail is implemented by setting two attributes
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
9 on the session table when a client enables push for a session:
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
10
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
11 - push_identifier: this is push_jid .. "<" .. (push_node or "")
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
12 (this value is used as key of the user_push_services table)
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
13 - push_settings: this is a reference to the user_push_services[push_identifier]
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
14
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
15
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
16 Point 4 of Daniel's mail contains the actual business rules
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
17 -----------------------------------------------------------
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
18
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
19 **a)**
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
20 CSI is honoured in this scenario because messages hold back by csi don't even
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
21 reach the smacks module. mod_smacks has 3 events:
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
22
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
23 - smacks-ack-delayed: This event is triggered when the client doesn't respond to
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
24 a smacks <r> in a configurable amount of time (default: 60 seconds).
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
25 Mod_cloud_notify reacts on this event and sends out push notifications
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
26 to the push service registered for this session in point 3 (see above) for all
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
27 stanzas in the smacks queue (the queue is given in the event).
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
28
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
29 - smacks-hibernation-start: This event is triggered when the smacks session
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
30 is put in hibernation state. The event contains the smacks queue, too.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
31 Mod_cloud_notify uses this event to send push notifications for all
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
32 stanzas not already pushed and installs a "stanzas/out"-filter to
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
33 react on new stanzas coming in while the session is hibernated.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
34 The push endpoint of the hibernated session is then also notified
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
35 for every new stanza.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
36 - smacks-hibernation-end: This event is triggered, when the smacks hibernation
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
37 is stopped (the smacks session is resumed) and used by Mod_cloud_notify
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
38 to remove the "stanzas/out"-filter.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
39
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
40 **b)**
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
41 Mod_mam already provides an event named "archive-message-added" which is
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
42 triggered every time a stanza is saved into the mam store.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
43 Mod_cloud_notify uses this event to send out push notifications to all
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
44 push services registered for the user the stanza is for, but *only*
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
45 to those push services not having an active (or smacks hibernated) session.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
46 Only those stanzas are considered that contain the "for_user" event attribute
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
47 of mod_mam as the user part of the jid.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
48 This is done to ensure that mam archiving rules are honoured.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
49
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
50 **c)**
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
51 The "message/offline/handle"-hook is used to send out push notifications to all
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
52 registered push services belonging to the user the offline stanza is for.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
53 This was already implemented in the first version of mod_cloud_notify.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
54
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
55
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
56 Some statements to related technologies/XEPs/modules
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
57 ----------------------------------------------------
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
58
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
59 - carbons: These are handled as usual and don't interfere with these business rules
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
60 at all. Smacks events are generated for carbon copies if needed and mod_cloud_notify
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
61 uses them to wake up the device in question if needed, as normal stanzas would do, too.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
62
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
63 - csi: Csi is honoured also, because every stanza hold back by mod_pump or other csi
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
64 modules is never seen by the smacks module, thus not added to its queue and not
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
65 forwarded to mod_cloud_notify by the smacks events.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
66 Mod_cloud_notify does only notify devices having no active or smacks hibernated session
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
67 of new mam stored stanzas, so stanzas filtered by csi don't get to mod_cloud_notify
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
68 this way neither.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
69
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
70 - other technologies: There shouldn't be any issues with other technologies imho.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
71
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
diff changeset
72 [^1]: https://mail.jabber.org/pipermail/standards/2016-February/030925.html