annotate mod_muc_cloud_notify/README.markdown @ 4537:53ee391ca689

mod_smacks: Fix traceback due to session being destroyed in send() Sending something can cause the OS to notice that the connection is dead and then the connection can be dead at this point. More likely if opportunistic_writes is enabled.
author Kim Alvefur <zash@zash.se>
date Thu, 01 Apr 2021 11:35:26 +0200
parents 6317a5d8ce2d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3319
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
1 ---
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
2 labels:
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
3 - 'Stage-Alpha'
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
4 summary: 'XEP-XXX: Cloud push notifications for MUC'
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
5 ---
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
6
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
7 # Introduction
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
8
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
9 This is an experimental fork of [mod_cloud_notify](https://modules.prosody.im/mod_cloud_notify.html)
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
10 which allows a [XEP-0357 Push Notifications App Servers](https://xmpp.org/extensions/xep-0357.html#general-architecture)
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
11 to be registered against a MUC domain (normally they're only registered against
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
12 your own chat server's domain).
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
13
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
14 The goal here is to also enable push notifications also for MUCs.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
15
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
16 In contrast to mod_cloud_notify, this module does NOT integrate with
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
17 mod_smacks, because a MUC can't access a remote user's XEP-0198 queue.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
18
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
19 Configuration
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
20 =============
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
21
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
22 Option Default Description
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
23 ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
24 `push_notification_with_body` `false` Whether or not to send the message body to remote pubsub node.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
25 `push_notification_with_sender` `false` Whether or not to send the message sender to remote pubsub node.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
26 `push_max_errors` `16` How much persistent push errors are tolerated before notifications for the identifier in question are disabled
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
27 `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
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
28 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
29
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
30 There are privacy implications for enabling these options because
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
31 plaintext content and metadata will be shared with centralized servers
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
32 (the pubsub node) run by arbitrary app developers.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
33
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
34 ## To test this module:
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
35
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
36 The [Converse](http://conversejs.org/) client has support for registering push
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
37 "app servers" against a MUC.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
38
3330
426447d8f82e Mention auto_register_muc_nickname setting from Converse
JC Brand <jc@opkode.com>
parents: 3319
diff changeset
39 You specify app servers with the [push_app_servers](https://conversejs.org/docs/html/configuration.html#push-app-servers)
3319
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
40 config setting.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
41
3375
6317a5d8ce2d mod_muc_cloud_notify: README updates
JC Brand <jc@opkode.com>
parents: 3330
diff changeset
42 And then you need to set [enable_muc_push](https://conversejs.org/docs/html/configuration.html#enable-muc-push)
3319
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
43 to `true` so that these app servers are also registered against MUC domains.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
44
3330
426447d8f82e Mention auto_register_muc_nickname setting from Converse
JC Brand <jc@opkode.com>
parents: 3319
diff changeset
45 Additionally you need to set [auto_register_muc_nickname](https://conversejs.org/docs/html/configuration.html#auto-register-muc-nickname)
426447d8f82e Mention auto_register_muc_nickname setting from Converse
JC Brand <jc@opkode.com>
parents: 3319
diff changeset
46 to true.
426447d8f82e Mention auto_register_muc_nickname setting from Converse
JC Brand <jc@opkode.com>
parents: 3319
diff changeset
47
3375
6317a5d8ce2d mod_muc_cloud_notify: README updates
JC Brand <jc@opkode.com>
parents: 3330
diff changeset
48 Then, when you enter a MUC, Converse will try to automatically register your nickname
6317a5d8ce2d mod_muc_cloud_notify: README updates
JC Brand <jc@opkode.com>
parents: 3330
diff changeset
49 on that MUC.
3319
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
50
3375
6317a5d8ce2d mod_muc_cloud_notify: README updates
JC Brand <jc@opkode.com>
parents: 3330
diff changeset
51 Note: Converse currently doesn't let you register separate app servers for
3319
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
52 a MUC domain. The same app servers are registered for the MUC domain and your
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
53 own domain.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
54
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
55 ## To be done:
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
56
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
57 We currently don't handle "ghost connections", users who are currently offline
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
58 but the XMPP server is not yet aware of this and shows considers them online in
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
59 the MUC.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
60
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
61 Prosody already checks for error bounces from undelivered groupchat messages
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
62 and then kicks the particular user from the room.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
63
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
64 So these ghost connection users eventually get kicked from the room.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
65
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
66 We now need a module that fires an event when a groupchat messages can't be
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
67 delivered to an occupant. The module can look up the undelivered message in MAM
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
68 and include it in the event.
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
69
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
70 In mod_muc_cloud_notify we can then listen for this event and send out a push
408f92149774 mod_muc_cloud_notify: New module
JC Brand <jc@opkode.com>
parents:
diff changeset
71 notification.