prosody-modules: mod_unified_push/README.md annotate

annotate mod_unified_push/README.md @ 5354:39d59d857bfb

mod_http_oauth2: Use new mod_cron API for periodic cleanup Less frequent but this isn't that important after all since, as the comment states, expired codes are not usable anyway. They're also not that large so memory usage probably doesn't matter.

author	Kim Alvefur <zash@zash.se>
date	Sat, 22 Apr 2023 11:59:52 +0200
parents	9032143bad08
children

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 \|

Mercurial > prosody-modules

annotate mod_unified_push/README.md @ 5354:39d59d857bfb