annotate mod_cloud_notify/README.markdown @ 2668:f8fc79b3051a

mod_pep_plus: Import from Prosody trunk ae3c5abb3336
author Matthew Wild <mwild1@gmail.com>
date Tue, 04 Apr 2017 15:09:04 +0100
parents 4d81d7219db0
children df86ce6bb0b4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
2250
f5cc6328b20f mod_cloud_notify/README: Reflow text
Kim Alvefur <zash@zash.se>
parents: 2249
diff changeset
10 This is an implementation of the server bits of [XEP-0357: Push Notifications].
f5cc6328b20f mod_cloud_notify/README: Reflow text
Kim Alvefur <zash@zash.se>
parents: 2249
diff changeset
11 It allows clients to register an "app server" which is notified about new
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
12 messages while the user is offline, disconnected or the session is hibernated
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
13 by [mod_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
14 Implementation of the "app server" is not included[^1].
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
15
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
16 Details
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
17 =======
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
diff changeset
19 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
20 or messages waiting in the smacks queue.
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
diff changeset
21 The business rules outlined [here] are all honored[^2].
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
22
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
23 To cooperate with [mod_smacks] this module consumes some events:
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
24 "smacks-ack-delayed", "smacks-hibernation-start" and "smacks-hibernation-end".
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
25 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
26 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
27 acknowledgements for messages are delayed by a certain amount of seconds
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
28 configurable with the [mod_smacks] setting "smacks_max_ack_delay".
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
29
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
30 The "smacks_max_ack_delay" setting allows to send out notifications to clients
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
31 which aren't already in smacks hibernation state (because the read timeout or
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
32 connection close didn't happen already) but also aren't responding to acknowledgement
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
33 request in a timely manner, thus allowing conversations to be smoother under such
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
34 circumstances.
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
35
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
diff changeset
36 The new event "cloud-notify-ping" can be used by any module to send out a cloud
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
diff changeset
37 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
38 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
39
2198
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
40 Configuration
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
41 =============
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
42
2199
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
43 Option Default Description
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
44 --------------------------------- --------- ------------------------------------------------------------------
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
45 `push_notification_with_body` `false` Whether or not to send the message body to remote pubsub node.
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
46 `push_notification_with_sender` `false` Whether or not to send the message sender to remote pubsub node.
2198
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
47
2199
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
48 There are privacy implications for enabling these options because
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
49 plaintext content and metadata will be shared with centralized servers
2582d09d2ec4 mod_cloud_notify/README: Fixup markdown
Kim Alvefur <zash@zash.se>
parents: 2198
diff changeset
50 (the pubsub node) run by arbitrary app developers.
2198
eb53a830864c mod_cloud_notify: default false for sending body and sender
Chris Ballinger <chrisballinger@gmail.com>
parents: 2141
diff changeset
51
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
52 Installation
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
53 ============
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55 Same as any other module.
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
56
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
57 Configuration
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents: 1785
diff changeset
58 =============
1783
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 Configured in-band by supporting clients.
b31fe2d22310 mod_cloud_notify: XEP-0357: Push - the server bits ("app server" not included)
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61
2248
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
62 Compatibility
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
63 =============
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
64
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
65 Should work with 0.9+.
3ecf65dabb6e mod_cloud_notify/README: Add compatibility section
Kim Alvefur <zash@zash.se>
parents: 2199
diff changeset
66
1853
c25a0ac8b511 mod_cloud_notify/README: Sentence was missing the ending
Kim Alvefur <zash@zash.se>
parents: 1852
diff changeset
67 [^1]: The service which is expected to forward notifications to
c25a0ac8b511 mod_cloud_notify/README: Sentence was missing the ending
Kim Alvefur <zash@zash.se>
parents: 1852
diff changeset
68 something like Google Cloud Messaging or Apple Notification Service
2609
6ab46ff685d0 mod_cloud_notify: Respect Daniel's business rules and remove endpoints on error
tmolitor <thilo@eightysoft.de>
parents: 2395
diff changeset
69 [here]: https://mail.jabber.org/pipermail/standards/2016-February/030925.html
2611
4d81d7219db0 mod_cloud_notify: Correct link to implementation details
tmolitor <thilo@eightysoft.de>
parents: 2609
diff changeset
70 [^2]: //hg.prosody.im/prosody-modules/file/tip/mod_cloud_notify/business_rules.markdown