prosody-modules
d3a72777f149
mod_unified_push/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_unified_push/README.md @ 5928:d3a72777f149

mod_vcard_muc: fix field type for XEP-0486 field
author Jonas Schäfer <jonas@wielicki.name>
date Sat, 11 May 2024 10:02:00 +0200
parent 5157:9032143bad08
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
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
29 | Name | Description | Default |
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
30 |-------------------------------|---------------------------------------------------------|---------------------------------------------|
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
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: 5139
diff changeset
34
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
35 ### Backends
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
36
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
diff changeset
39 on every Prosody version.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
40
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
diff changeset
43
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
44 #### storage backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
45
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
diff changeset
48
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
49 Supported by all Prosody versions.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
50
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
51 #### paseto backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
52
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
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: 5139
diff changeset
56 Prosody 0.12 and earlier.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
57
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
58 #### jwt backend
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
59
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
diff changeset
62
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
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: 5139
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: 5139
diff changeset
66 use this backend.
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
67
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
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: 5139
diff changeset
69 using the `unified_push_secret` option.
5128
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
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
75 ### HTTP configuration
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
76
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
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: 5128
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: 5128
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: 5128
diff changeset
80
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
81 #### Example configuration
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
82
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
83 ##### Normal method
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
84
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
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: 5156
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: 5156
diff changeset
87
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
88 ``` {.lua}
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
89 modules_enabled = {
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
90 ---
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
91 "unified_push";
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
92 ---
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
93 }
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
94 ```
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
95
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
96 ##### Component method
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
97
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
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: 5156
diff changeset
99 e.g. on a subdomain or other non-user domain.
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
100
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
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: 5128
diff changeset
102 'notify.example.com'.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
103
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
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: 5128
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: 5128
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: 5128
diff changeset
107
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
108 ``` {.lua}
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
109 Component "notify.example.com" "unified_push"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
110 unified_push_secret = "<secret string here>"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
111 http_host = "example.com"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
112 ```
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
113
5128
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
5139
449e4ca4de32 mod_unified_push: Remove dependency on trunk util.jwt (0.12 compat)
Matthew Wild <mwild1@gmail.com>
parents: 5138
diff changeset
116 | trunk | Works |
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
117 | 0.12 | Works |