prosody-modules
449e4ca4de32
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 @ 5139:449e4ca4de32

mod_unified_push: Remove dependency on trunk util.jwt (0.12 compat) This should allow the module to work on 0.12, while preserving expiry checking (which was not built in to 0.12's util.jwt).
author Matthew Wild <mwild1@gmail.com>
date Tue, 10 Jan 2023 16:34:21 +0000
parent 5138:4511e90d1d08
child 5156: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 |