author | Matthew Wild <mwild1@gmail.com> |
Tue, 16 Apr 2024 12:41:52 +0100 | |
changeset 5888 | 49b0873932ca |
parent 5161 | 9032143bad08 |
permissions | -rw-r--r-- |
5132
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 |
|
5142
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
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:
5132
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:
5132
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:
5132
diff
changeset
|
13 |
|
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
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:
5132
diff
changeset
|
15 |
|
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
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:
5132
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:
5132
diff
changeset
|
18 |
description of the protocol between the XMPP server and the client. |
5132
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 |
|
5160
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
29 |
| Name | Description | Default | |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
30 |
|-------------------------------|---------------------------------------------------------|---------------------------------------------| |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
31 |
| unified_push_acl | A list of domains or users permitted to use the service | current host, or parent host if a component | |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
32 |
| unified_push_backend | Backend to use: "paseto", "storage" or "jwt" | "paseto" (trunk), "storage" (0.12) | |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
33 |
| unified_push_registration_ttl | Maximum lifetime of a push registration (seconds) | `86400` (1 day) | |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
34 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
35 |
### Backends |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
36 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
37 |
The module needs to track registrations, and be able to associate tokens with |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
38 |
users. There are multiple ways to do this, but not every method is supported |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
39 |
on every Prosody version. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
40 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
41 |
By default the module will automatically select the best backend that is |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
42 |
supported on the current Prosody version you are using. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
43 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
44 |
#### storage backend |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
45 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
46 |
This is the default backend on Prosody 0.12 and earlier. It stores tokens and |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
47 |
their associated data in Prosody's configured data store. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
48 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
49 |
Supported by all Prosody versions. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
50 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
51 |
#### paseto backend |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
52 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
53 |
This is a stateless (i.e. no storage required) backend that uses encrypted |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
54 |
[PASETO tokens](https://paseto.io/) to store registration info. It is the |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
55 |
default backend on Prosody trunk, as PASETO support is not available in |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
56 |
Prosody 0.12 and earlier. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
57 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
58 |
#### jwt backend |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
59 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
60 |
This is a stateless backend that uses [JWT tokens](https://jwt.io/) to store |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
61 |
registration info. It is supported in Prosody 0.12 and higher. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
62 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
63 |
**Note:** The JWT tokens are **not encrypted**, which means the JID |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
64 |
associated with a registration is visible to apps and services that send you |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
65 |
push notifications. This can have privacy implications. If in doubt, do not |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
66 |
use this backend. |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
67 |
|
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
68 |
This backend requires you to set a secure random string in the config file, |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
69 |
using the `unified_push_secret` option. |
5132
7cc0f68b8715
mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
70 |
|
7cc0f68b8715
mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
71 |
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
|
72 |
`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
|
73 |
push registrations. |
7cc0f68b8715
mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
74 |
|
5160
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
75 |
### HTTP configuration |
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
76 |
|
5142
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
77 |
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:
5132
diff
changeset
|
78 |
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:
5132
diff
changeset
|
79 |
[Prosody HTTP documentation](https://prosody.im/doc/http). |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
80 |
|
5161
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
81 |
#### Example configuration |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
82 |
|
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
83 |
##### Normal method |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
84 |
|
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
85 |
Just add just add `"unified_push"` to your `modules_enabled` option. |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
86 |
This is the easiest and **recommended** configuration. |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
87 |
|
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
88 |
``` {.lua} |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
89 |
modules_enabled = { |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
90 |
--- |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
91 |
"unified_push"; |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
92 |
--- |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
93 |
} |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
94 |
``` |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
95 |
|
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
96 |
##### Component method |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
97 |
|
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
98 |
This is an example of how to configure the module as an internal component, |
9032143bad08
mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents:
5160
diff
changeset
|
99 |
e.g. on a subdomain or other non-user domain. |
5142
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
100 |
|
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
101 |
This example creates a push notification component called |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
102 |
'notify.example.com'. |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
103 |
|
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
104 |
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:
5132
diff
changeset
|
105 |
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:
5132
diff
changeset
|
106 |
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:
5132
diff
changeset
|
107 |
|
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
108 |
``` {.lua} |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
109 |
Component "notify.example.com" "unified_push" |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
110 |
unified_push_secret = "<secret string here>" |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
111 |
http_host = "example.com" |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
112 |
``` |
4511e90d1d08
mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents:
5132
diff
changeset
|
113 |
|
5132
7cc0f68b8715
mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
114 |
## Compatibility |
7cc0f68b8715
mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff
changeset
|
115 |
|
5143
449e4ca4de32
mod_unified_push: Remove dependency on trunk util.jwt (0.12 compat)
Matthew Wild <mwild1@gmail.com>
parents:
5142
diff
changeset
|
116 |
| trunk | Works | |
5160
a8df4d2447d0
mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents:
5143
diff
changeset
|
117 |
| 0.12 | Works | |