Mercurial > prosody-modules

annotate mod_cloud_notify/business_rules.markdown @ 4651:8231774f5bfd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_cloud_notify_encrypted: Ensure body substring remains valid UTF-8 The `body:sub()` call risks splitting the string in the middle of a multi-byte UTF-8 sequence. This should have been caught by util.stanza validation, but that would have caused some havoc, at the very least causing the notification to not be sent. There have been no reports of this happening. Likely because this module isn't widely deployed among users with languages that use many longer UTF-8 sequences. The util.encodings.utf8.valid() function is O(n) where only the last sequence really needs to be checked, but it's in C and expected to be fast.
author Kim Alvefur <zash@zash.se>
date Sun, 22 Aug 2021 13:22:59 +0200
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