1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
# Push
<div class="note">
<div class="admonition-title">Note</div>
This document describes how Firefox implements the Web Push standard internally, and is intended for developers working directly on Push. If you are looking for how to consume push, please refer to the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Push_API" target="_blank">following MDN document</a>
</div>
## High level push architecture
The following sequence diagram describes the high level push architecture as observed by web application. The diagram describes the interactions between a Web application's client code running in the browser, Firefox, [Autopush](https://autopush.readthedocs.io/en/latest/) (Firefox's push server that delivers push notifications) and a third party server that sends the push notifications to Autopush
The dotted lines are done by the consumer of push.
```{mermaid}
sequenceDiagram
participant TP as Web Application JS
participant F as Firefox
participant A as Autopush
participant TPS as Third party Server
TP->>F: subscribe(scope)
activate TP
activate F
F->>A: subscribe(scope) using web socket
activate A
A->>F: URL
deactivate A
F->>F: Create pub/privKey Encryption pair
F->>F: Persist URL, pubKey, privKey indexed using an id derived from scope
F->>TP: URL + pubKey
deactivate F
TP-->>TPS: URL + pubKey
deactivate TP
TPS-->>TPS: Encrypt payload using pubKey
TPS-->>A: Send encrypted payload using URL
activate A
A->>F: Send encrypted payload using web socket
deactivate A
activate F
F->>F: Decrypt payload using privKey
F->>F: Display Notification
deactivate F
```
## Firefox Desktop
### Flow diagram for source code
The source code for push is available under [`dom/push`](https://searchfox.org/mozilla-central/source/dom/push) in mozilla-central.
The following flow diagram describes how different modules interact with each other to provide the push API to consumers.
```{mermaid}
flowchart TD
subgraph Public API
W[Third party Web app]-->|imports| P[PushManager.webidl]
end
subgraph Browser Code
P-->|Implemented by| MM
MM{Main Thread?}-->|Yes| B[Push.sys.mjs]
MM -->|NO| A[PushManager.cpp]
B-->|subscribe,getSubscription| D[PushComponents.sys.mjs]
A-->|subscribe,getSubscription| D
D-->|subscribe,getSubscription| M[PushService.sys.mjs]
M-->|Storage| S[PushDB.sys.mjs]
M-->|Network| N[PushWebSocket.sys.mjs]
F[FxAccountsPush.sys.mjs] -->|uses| D
end
subgraph Server
N-. Send, Receive.-> O[Autopush]
end
subgraph Local Storage
S-->|Read,Write| PP[(IndexedDB)]
end
```
### The Push Web Socket
Push in Firefox Desktop communicates with Autopush using a web socket connection.
The web socket connection is created as the browser initializes and is managed by the following state diagram.
```{mermaid}
stateDiagram-v2
state "Shut Down" as SD
state "Waiting for WebSocket to start" as W1
state "Waiting for server hello" as W2
state "Ready" as R
[*] --> SD
SD --> W1: beginWSSetup
W1 --> W2: wsOnStart Success
W2 --> R: handleHelloReply
R --> R: send (subscribe)
R --> R: Receive + notify observers
R --> SD: wsOnStop
R --> SD: sendPing Fails
W1 --> SD: wsOnStart fails
W2 --> SD: invalid server hello
R --> [*]
```
Once the Push web socket is on the `Ready` state, it is ready to send new subscriptions to Autopush, and receive push notifications from those subscriptions.
Push uses an observer pattern to notify observers of any incoming push notifications. See the [high level architecture](#high-level-push-architecture) section.
### Push Storage
Push uses IndexedDB to store subscriptions for the following reasons:
1. In case the consumer attempts to re-subscribe, storage is used as a cache to serve the URL and the public key
1. In order to persist the private key, so that it can be used to decrypt any incoming push notifications
The following is what gets persisted:
```{mermaid}
erDiagram
Subscription {
string channelID "Key, Derived from scope"
string pushEndpoint "Unique endpoint for this subscription"
string scope "Usually the origin, unique value for internal consumers"
Object p256dhPublicKey "Object representing the public key"
Object p256dhPrivateKey "Object representing the private key"
}
```
## Firefox for Android
See also:
* [Rust Push Component](https://mozilla.github.io/application-services/book/rust-docs/push/index.html)
* [Push Service Bridge HTTP Interface](https://autopush.readthedocs.io/en/latest/http.html#push-service-bridge-http-interface)
* [Android Components: Push](https://github.com/mozilla/gecko-dev/blob/master/mobile/android/android-components/components/feature/push/README.md)
### Flow diagram for source code
The source code for push is available under the following paths in mozilla-central:
* [`dom/push/`](https://searchfox.org/mozilla-central/source/dom/push/)
* [`mobile/shared/components/geckoview/GeckoViewPush.sys.mjs`](mobile/shared/components/geckoview/GeckoViewPush.sys.mjs)
* [`mobile/android/geckoview/src/main/java/org/mozilla/geckoview/WebPush*.java`](https://searchfox.org/mozilla-central/source/mobile/android/geckoview/src/main/java/org/mozilla/geckoview/)
* Under `mobile/android/android-components/components`:
* [`feature/push/src/main/java/mozilla/components/feature/push/`](https://searchfox.org/mozilla-central/source/mobile/android/android-components/components/feature/push/src/main/java/mozilla/components/feature/push/)
* [`browser/engine-gecko/src/main/java/mozilla/components/browser/engine/gecko/webpush/`](https://searchfox.org/mozilla-central/source/mobile/android/android-components/components/browser/engine-gecko/src/main/java/mozilla/components/browser/engine/gecko/webpush/)
* [`concept/engine/src/main/java/mozilla/components/concept/engine/webpush`](https://searchfox.org/mozilla-central/source/mobile/android/android-components/components/concept/engine/src/main/java/mozilla/components/concept/engine/webpush/)
* [Rust Push Component](https://github.com/mozilla/application-services/tree/main/components/push)
The following flow diagram describes how different modules interact with each other to provide the push API to consumers.
```{mermaid}
flowchart TD
subgraph Public API
W[Third party Web app]-->|imports| P[PushManager.webidl]
end
subgraph Browser Code
P-->|Implemented by| MM
MM{Main Thread?}-->|Yes| B[Push.sys.mjs]
MM -->|NO| A[PushManager.cpp]
B-->|subscribe,getSubscription| D[GeckoViewPush.sys.mjs]
A-->|subscribe,getSubscription| D
D-->|PushSubscribe,PushGetSubscription| WPC[WebPushController.java]
WPC-->|onSubscribe,onGetSubscription| WPEI[WebPushEngineIntegration.kt]
WPEI-->|subscribe,getSubscription| APF[AutoPushFeature.kt]
APF-->|start| PS[AbstractFirebasePushService.kt]
FCM[Firebase Cloud Messaging]-->|onNewToken| PS
PS-->|onNewToken| APF
APF-->|subscribe,getSubscription| PRS[push/src/lib.rs]
PRS-->|subscribe,get_subscription| PM[internal/push_manager.rs]
PM-->|Storage| S[internal/storage/db.rs]
PM-->|Network| N[internal/communications.rs]
end
subgraph Server
N-. bridge interface.-> O[Autopush]
end
subgraph Local Storage
S-->|Read,Write| SQL[(SQLite)]
end
```
|
