Mercurial > prosody-modules

annotate mod_web_push/README.markdown @ 3613:a5da9172362a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_web_push: Update README
author Maxime “pep” Buquet <pep@bouah.net>
date Sun, 09 Jun 2019 22:02:24 +0200
parents 2cee9fcb318b
children f74444b0e187
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:
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
35 - 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
36 - 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
37
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
38 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
39 Server.
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
40
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
41 The general flow for subscription is:
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
42 - XMPP server generate ECDH keypair, publishes public key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
43 - XMPP client generates an ECDH keypair
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
44 - XMPP client fetches server public key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
45 - 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
46 gets back an HTTP endpoint
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
47 - 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
48 and its public key
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
49
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
50 The flow for notifications is as follow:
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
51 - XMPP server receives an _important_[^1] message
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
52 - 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
53 - 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
54 - 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
55 - Push server sends notification to web browser
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
56
3612
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
57 Configuration
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
58 =============
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
59
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
60 Option Default Description
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 `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
63 `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
64
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
65 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
66 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
67 (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
68
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
69 Installation
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
70 ============
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 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
73
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
74 Configuration
2cee9fcb318b Initial version of mod_web_push. WARNING: Do not use.
Maxime “pep” Buquet <pep@bouah.net>
parents:
diff changeset
75 =============
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 Configured in-band by supporting clients.
3613
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
78
a5da9172362a mod_web_push: Update README
Maxime “pep” Buquet <pep@bouah.net>
parents: 3612
diff changeset
79 [^1]: As defined in mod_cloud_notify, or mod_csi_simple.