Mercurial > prosody-modules

annotate mod_unified_push/README.md @ 5154:48ca519cd66a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_unified_push: Improved error handling and reporting
author Matthew Wild <mwild1@gmail.com>
date Sat, 14 Jan 2023 16:16:47 +0000
parents 449e4ca4de32
children a8df4d2447d0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - Stage-Alpha
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: "Unified Push provider"
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5 ---
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 This module implements a [Unified Push](https://unifiedpush.org/) Provider
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8 that uses XMPP to talk to a Push Distributor (e.g. [Conversations](http://codeberg.org/iNPUTmice/Conversations)).
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
10 It allows push notifications to be delivered to apps on your device over XMPP.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
11 This means notifications can be delivered quickly and efficiently (apps don't
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
12 need to repeatedly poll for new notifications).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
13
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
14 For a list of compatible apps, see the [UnifiedPush apps list](https://unifiedpush.org/users/apps/).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
15
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
16 A server-independent external component is also available - see [the 'up'
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
17 project](https://codeberg.org/inputmice/up). That project also contains a
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
18 description of the protocol between the XMPP server and the client.
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 This module and the protocol it implements is at an experimental prototype
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 stage.
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 Note that this module is **not related** to XEP-0357 push notifications for
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 XMPP. It does not send push notifications to disconnected XMPP clients. For
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25 that, see [mod_cloud_notify](https://modules.prosody.im/mod_cloud_notify).
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27 ## Configuration
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 | Name | Description | Default |
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 |-------------------------------|--------------------------------------------------------|-----------------------|
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 | unified_push_secret | A random secret string (32+ bytes), used for auth | |
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32 | unified_push_registration_ttl | Maximum lifetime of a push registration (seconds) | `86400` (1 day) |
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34 A random push secret can be generated with the command
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 `openssl rand -base64 32`. Changing the secret will invalidate all existing
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 push registrations.
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
38 This module exposes a HTTP endpoint (to receive push notifications from app
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
39 servers). For more information on configuring HTTP services in Prosody, see
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
40 [Prosody HTTP documentation](https://prosody.im/doc/http).
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
41
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
42 ### Example configuration
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
43
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
44 This example creates a push notification component called
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
45 'notify.example.com'.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
46
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
47 The 'http_host' line instructs Prosody to expose this module's HTTP services
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
48 on the 'example.com' host, which avoids needing to create/update DNS records
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
49 and HTTPS certificates if example.com is already set up.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
50
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
51 ``` {.lua}
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
52 Component "notify.example.com" "unified_push"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
53 unified_push_secret = "<secret string here>"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
54 http_host = "example.com"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
55 ```
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
56
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 ## Compatibility
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58
5139
449e4ca4de32 mod_unified_push: Remove dependency on trunk util.jwt (0.12 compat)
Matthew Wild <mwild1@gmail.com>
parents: 5138
diff changeset
59 | trunk | Works |
449e4ca4de32 mod_unified_push: Remove dependency on trunk util.jwt (0.12 compat)
Matthew Wild <mwild1@gmail.com>
parents: 5138
diff changeset
60 | 0.12 | Should work |