prosody-modules
fe8222112cf4
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 @ 6199:fe8222112cf4

mod_conversejs: Serve base app at / This makes things slightly less awkward for the browser to figure out which URLs belong to a PWA. The app's "start URL" was previously without the '/' and therefore was not considered within the scope of the PWA. Now the canonical app URL will always have a '/'. Prosody/mod_http should take care of redirecting existing links without the trailing / to the new URL. If you have an installation at https://prosody/conversejs then it is now at https://prosody/conversejs/ (the first URL will now redirect to the second URL if you use it). The alternative would be to make the PWA scope include the parent, i.e. the whole of https://prosody/ in this case. This might get messy if other PWAs are provided by the same site or Prosody installation, however.
author Matthew Wild <mwild1@gmail.com>
date Tue, 11 Feb 2025 13:18:38 +0000
parent 6087:04d0ab97a678
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
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
4 summary: Unified Push provider
5128
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
6087
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
75 ## HTTP configuration
5156
a8df4d2447d0 mod_unified_push: README: Update docs
Matthew Wild <mwild1@gmail.com>
parents: 5139
diff changeset
76
6087
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
77 This module exposes a HTTP endpoint, by default at the path `/push` (to receive push notifications from app
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
78 servers). **If you use a reverse proxy, make sure you proxy this path too.**
04d0ab97a678 mod_unified_push: add http default path to readme for reverse proxying
Menel <menel@snikket.de>
parents: 6084
diff changeset
79 For more information on configuring HTTP services and reverse proxying in Prosody, see
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
80 [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
81
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
82 ## Example configuration
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
83
6084
3441cdf73d80 mod_unified_push: typo
Menel <menel@snikket.de>
parents: 6083
diff changeset
84 ### Recommended: load on Virtualhost(s)
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
85
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
86 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
87 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
88
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
89 ``` lua
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
90 modules_enabled = {
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
91 -- ...
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
92 "unified_push";
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
93 -- ...
5157
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
6073
045d557fc8c9 mod_unified_push: fix Compability sextion and improve Layout
Menel <menel@snikket.de>
parents: 5157
diff changeset
97 #### Component method
5157
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
98
9032143bad08 mod_unified_push: Update docs to recommend loading on normal hosts
Matthew Wild <mwild1@gmail.com>
parents: 5156
diff changeset
99 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
100 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
101
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
102 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
103 'notify.example.com'.
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
104
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
105 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
106 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
107 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
108
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
109 ``` lua
5138
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
110 Component "notify.example.com" "unified_push"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
111 unified_push_secret = "<secret string here>"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
112 http_host = "example.com"
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
113 ```
4511e90d1d08 mod_unified_push: README: Documentation updates (example, etc.)
Matthew Wild <mwild1@gmail.com>
parents: 5128
diff changeset
114
5128
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
115 ## Compatibility
7cc0f68b8715 mod_unified_push: Experimenal Unified Push provider
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
116
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
117 Prosody-Version Status
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
118 ----------------- ----------------------
6083
631415831007 mod_unified_push: update testing time and Chapter size
Menel <menel@snikket.de>
parents: 6080
diff changeset
119 trunk Works as of 24-12-08
6080
9ab0d1c75c26 mod_unified_push: Normalize Markdown
Kim Alvefur <zash@zash.se>
parents: 6073
diff changeset
120 0.12 Works