Software /
code /
prosody-modules
Annotate
mod_cloud_notify/README.markdown @ 5519:83ebfc367169
mod_http_oauth2: Return Authentication Time per OpenID Core Section 2
Mandatory To Implement, either MUST include or OPTIONAL depending on
things we don't look at, so might as well include it all the time.
Since we do not persist authentication state with cookies or such, the
authentication time will always be some point between the user being
sent to the authorization endpoint and the time they are sent back to
the client application.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Mon, 05 Jun 2023 22:32:44 +0200 |
parent | 5216:1d9dbe84b6e8 |
rev | line source |
---|---|
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
1 --- |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
2 labels: |
2249
d3e697c141e4
mod_cloud_notify/README: Let's call it Beta
Kim Alvefur <zash@zash.se>
parents:
2248
diff
changeset
|
3 - 'Stage-Beta' |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
4 summary: 'XEP-0357: Cloud push notifications' |
2199
2582d09d2ec4
mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents:
2198
diff
changeset
|
5 --- |
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
6 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
7 Introduction |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
8 ============ |
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
9 |
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
10 This module enables support for sending "push notifications" to clients that |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
11 need it, typically those running on certain mobile devices. |
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
12 |
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
13 As well as this module, your client must support push notifications (the apps |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
14 that need it generally do, of course) and the app developer's push gateway |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
15 must be reachable from your Prosody server (this happens over a normal XMPP |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
16 server-to-server 's2s' connection). |
3089
5b5c6ba527fc
mod_cloud_notify: last cleanup
tmolitor <thilo@eightysoft.de>
parents:
3088
diff
changeset
|
17 |
1803
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
18 Details |
4d73a1a6ba68
Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
1785
diff
changeset
|
19 ======= |
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
20 |
5058
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
21 Some platforms, notably Apple's iOS and many versions of Android, impose |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
22 limits that prevent applications from running or accessing the network in the |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
23 background. This makes it difficult or impossible for an XMPP application to |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
24 remain reliably connected to a server to receive messages. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
25 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
26 In order for messaging and other apps to receive notifications, the OS vendors |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
27 run proprietary servers that their OS maintains a permanent connection to in |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
28 the background. Then they provide APIs to application developers that allow |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
29 sending notifications to specific devices via those servers. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
30 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
31 When you connect to your server with an app that requires push notifications, |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
32 it will use this module to set up a "push registration". When you receive |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
33 a message but your device is not connected to the server, this module will |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
34 generate a notification and send it to the push gateway operated by your |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
35 application's developers). Their gateway will then connect to your device's |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
36 OS vendor and ask them to forward the notification to your device. When your |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
37 device receives the notification, it will display it or wake up the app so it |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
38 can connect to XMPP and receive any pending messages. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
39 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
40 This protocol is described for developers in [XEP-0357: Push Notifications]. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
41 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
42 For this module to work reliably, you must have [mod_smacks], [mod_mam] and |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
43 [mod_carbons] also enabled on your server. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
44 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
45 Some clients, notably Siskin and Snikket iOS need some additional extensions |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
46 that are not currently defined in a standard XEP. To support these clients, |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
47 see [mod_cloud_notify_extensions]. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
48 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
49 Configuration |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
50 ============= |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
51 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
52 Option Default Description |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
53 ------------------------------------ ----------------- ------------------------------------------------------------------------------------------------------------------- |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
54 `push_notification_important_body` `New Message!` The body text to use when the stanza is important (see above), no message body is sent if this is empty |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
55 `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
56 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached) |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
57 `push_max_hibernation_timeout` `259200` (72h) Number of seconds to extend the smacks timeout if no push was triggered yet (default: 72 hours) |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
58 `push_notification_with_body` (\*) `false` Whether or not to send the real message body to remote pubsub node. Without end-to-end encryption, enabling this may expose your message contents to your client developers and OS vendor. Not recommended. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
59 `push_notification_with_sender` (\*) `false` Whether or not to send the real message sender to remote pubsub node. Enabling this may expose your contacts to your client developers and OS vendor. Not recommended. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
60 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
61 (\*) There are privacy implications for enabling these options. |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
62 |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
63 Internal design notes |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
64 ===================== |
39c2824c2880
mod_cloud_notify: README overhaul
Matthew Wild <mwild1@gmail.com>
parents:
5056
diff
changeset
|
65 |
2609
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2395
diff
changeset
|
66 App servers are notified about offline messages, messages stored by [mod_mam] |
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2395
diff
changeset
|
67 or messages waiting in the smacks queue. |
3088
6eaa1aa4f8ae
mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents:
3087
diff
changeset
|
68 The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. |
6eaa1aa4f8ae
mod_cloud_notify: more cleanup
tmolitor <thilo@eightysoft.de>
parents:
3087
diff
changeset
|
69 |
2395
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
70 To cooperate with [mod_smacks] this module consumes some events: |
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
71 `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. |
2395
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
72 These events allow this module to send out notifications for messages received |
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
73 while the session is hibernated by [mod_smacks] or even when smacks |
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
74 acknowledgements for messages are delayed by a certain amount of seconds |
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
75 configurable with the [mod_smacks] setting `smacks_max_ack_delay`. |
2395
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
76 |
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
77 The `smacks_max_ack_delay` setting allows to send out notifications to clients |
2395
2e641ab995b3
mod_cloud_notify: added code to respond to the new event "smacks-ack-delayed" issued by mod_smacks when acks are delayed for a certain amount of time. This allows to send out notification requests before the read timeout or connection close event really happens, thus allowing conversations to be smoother.
tmolitor <thilo@eightysoft.de>
parents:
2250
diff
changeset
|
78 which aren't already in smacks hibernation state (because the read timeout or |
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
79 connection close didn't already happen) but also aren't responding to acknowledgement |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
80 request in a timely manner. This setting thus allows conversations to be smoother |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
81 under such circumstances. |
1783
b31fe2d22310
mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
82 |
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
83 The new event `cloud-notify-ping` can be used by any module to send out a cloud |
2609
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2395
diff
changeset
|
84 notification to either all registered endpoints for the given user or only the endpoints |
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2395
diff
changeset
|
85 given in the event data. |
6ab46ff685d0
mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents:
2395
diff
changeset
|
86 |
2976
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
87 The config setting `push_notification_important_body` can be used to specify an alternative |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
88 body text to send to the remote pubsub node if the stanza is encrypted or has a body. |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
89 This way the real contents of the message aren't revealed to the push appserver but it |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
90 can still see that the push is important. |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
91 This is used by Chatsecure on iOS to send out high priority pushes in those cases for example. |
df86ce6bb0b4
Implement dummy body message to indicate high priority push
tmolitor <thilo@eightysoft.de>
parents:
2611
diff
changeset
|
92 |
2248
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2199
diff
changeset
|
93 Compatibility |
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2199
diff
changeset
|
94 ============= |
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2199
diff
changeset
|
95 |
5216
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5058
diff
changeset
|
96 **Note:** This module should be used with Lua 5.2 and higher. Using it with |
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5058
diff
changeset
|
97 Lua 5.1 may cause push notifications to not be sent to some clients. |
1d9dbe84b6e8
mod_cloud_notify: Add note about Lua version requirements to README
Matthew Wild <mwild1@gmail.com>
parents:
5058
diff
changeset
|
98 |
3944
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
99 ------ ----------------------------------------------------------------------------- |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
100 trunk Works |
4968
487f1eb829cf
mod_cloud_notify: Compat for prosody 0.12
tmolitor <thilo@eightysoft.de>
parents:
3944
diff
changeset
|
101 0.12 Works |
3944
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
102 0.11 Works |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
103 0.10 Works |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
104 0.9 Support dropped, use last supported version [675726ab06d3](//hg.prosody.im/prosody-modules/raw-file/675726ab06d3/mod_cloud_notify/mod_cloud_notify.lua) |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
105 ------ ----------------------------------------------------------------------------- |
7630d4ade7cd
mod_cloud_notify: fix link and table layout in readme
tmolitor <thilo@eightysoft.de>
parents:
3943
diff
changeset
|
106 |
2248
3ecf65dabb6e
mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents:
2199
diff
changeset
|
107 |
3086
3e91eb1bdd84
mod_cloud_notify: Some readme cleanup
tmolitor <thilo@eightysoft.de>
parents:
3079
diff
changeset
|
108 [^1]: The service which is expected to forward notifications to something like Google Cloud Messaging or Apple Notification Service |
3090
1d0925d008b2
mod_cloud_notify: fix link to business rules description
tmolitor <thilo@eightysoft.de>
parents:
3089
diff
changeset
|
109 [^2]: [business_rules.markdown](//hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown) |