Mercurial > prosody-modules

annotate mod_web_push/README.markdown @ 3661:88d414c916ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_upload: Back out 3fb0add97cdb - depends on yet uncommon lfs version
author Kim Alvefur <zash@zash.se>
date Fri, 30 Aug 2019 18:34:55 +0200
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.