annotate mod_muc_cloud_notify/README.markdown @ 5545:fcef6263acdb

mod_http_oauth2: Use code spans for some config options in README To make them more recognisable as code things.
author Kim Alvefur <zash@zash.se>
date Sun, 11 Jun 2023 14:02:47 +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.