Mercurial > prosody-modules

annotate mod_web_push/README.markdown @ 3772:22f02716819f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_s2s_keepalive: Isolate source host of pings The incoming_s2s table is not restricted to the current virtualhost so this prevents opening more connections than what's needed. Also prevents useless double sending of one whitespace per local host.
author Kim Alvefur <zash@zash.se>
date Mon, 23 Dec 2019 01:18:02 +0100
parents f74444b0e187
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3612
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
1 ---
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
2 labels:
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
3 - 'Stage-Alpha'
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
4 summary: 'XEP-XXXX: Web Push'
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
5 ---
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
6
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
7 Introduction
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
8 ============
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
9
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
10 ::: {.alert .alert-danger}
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
11 **This module is terribly untested and will only work with Firefox as it's
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
12 missing payload encryption. Other vendors require it all the time. Public and
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
13 private keys are also statically set in it.**
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
14 :::
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
15
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
16 This is an implementation of the server bits of [XEP-XXXX: Web Push].
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
17
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
18 It allows web clients to register a "push server" which is notified about new
3612
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
19 messages while the user is offline, disconnected or the session is hibernated
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
20 by [mod_smacks].
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
21
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
22 Push servers are provided by browser vendors.
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
23
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
24 This module is heavily based on [mod_cloud_notify].
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
25
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
26 Details
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
27 =======
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
28
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
29 [Push API](https://w3c.github.io/push-api/) is a specification by the W3C that
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
30 is essentially the same principle as Mobile OS vendors' Push notification
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
31 systems. It is implemented by most browsers vendors except Safari on iOS
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
32 (mobile).
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
33
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
34 For more information, see:
3614
f74444b0e187 mod_web_push: README: Fix list formatting
Maxime “pep” Buquet <pep@bouah.net>
parents: 3613
diff changeset
35
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
36 - https://developer.mozilla.org/en-US/docs/Web/API/Push_API
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
37 - https://developers.google.com/web/ilt/pwa/introduction-to-push-notifications
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
38
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
39 Compared to [XEP-0357: Push Notifications], Web Push doesn't need an App
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
40 Server.
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
41
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
42 The general flow for subscription is:
3614
f74444b0e187 mod_web_push: README: Fix list formatting
Maxime “pep” Buquet <pep@bouah.net>
parents: 3613
diff changeset
43
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
44 - XMPP server generate ECDH keypair, publishes public key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
45 - XMPP client generates an ECDH keypair
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
46 - XMPP client fetches server public key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
47 - XMPP client subscribes to browser Push server using the Web Push API, and
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
48 gets back an HTTP endpoint
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
49 - XMPP client enables Push notifications telling the server the HTTP endpoint,
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
50 and its public key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
51
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
52 The flow for notifications is as follow:
3614
f74444b0e187 mod_web_push: README: Fix list formatting
Maxime “pep” Buquet <pep@bouah.net>
parents: 3613
diff changeset
53
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
54 - XMPP server receives an _important_[^1] message
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
55 - XMPP server generates something something JWT + signature with ECDH key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
56 - XMPP server can optionally include payload encrypted for the client
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
57 - XMPP server initiates HTTP POST request to the Push server
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
58 - Push server sends notification to web browser
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
59
3612
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
60 Configuration
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
61 =============
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
62
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
63 Option Default Description
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
64 ------------------------------------ ----------------- -------------------------------------------------------------------------------------------------------------------
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
65 `push_notification_important_body` `New Message!` The body text to use when the stanza is important (see above), no message body is sent if this is empty
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
66 `push_max_devices` `5` The number of allowed devices per user (the oldest devices are automatically removed if this threshold is reached)
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
67
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
68 There are privacy implications for enabling these options because
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
69 plaintext content and metadata will be shared with centralized servers
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
70 (the pubsub node) run by arbitrary app developers.
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
71
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
72 Installation
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
73 ============
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
74
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
75 Same as any other module.
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
76
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
77 Configuration
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
78 =============
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
79
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
80 Configured in-band by supporting clients.
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
81
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
82 [^1]: As defined in mod_cloud_notify, or mod_csi_simple.