Push

Note
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 following MDN document

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 (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.

Third party ServerAutopushFirefoxWeb Application JSThird party ServerAutopushFirefoxWeb Application JSsubscribe(scope)subscribe(scope) using web socketURLCreate pub/privKey Encryption pairPersist URL, pubKey, privKey indexed using an id derived from scopeURL + pubKeyURL + pubKeyEncrypt payload using pubKeySend encrypted payload using URLSend encrypted payload using web socketDecrypt payload using privKeyDisplay Notification

Firefox Desktop

Flow diagram for source code

The source code for push is available under dom/push in mozilla-central.

The following flow diagram describes how different modules interact with each other to provide the push API to consumers.

Local Storage

Server

Browser Code

Public API

imports

Implemented by

Yes

NO

subscribe,getSubscription

subscribe,getSubscription

subscribe,getSubscription

Storage

Network

uses

Send, Receive

Read,Write

Third party Web app

PushManager.webidl

Main Thread?

Push.sys.mjs

PushManager.cpp

PushComponents.sys.mjs

PushService.sys.mjs

PushDB.sys.mjs

PushWebSocket.sys.mjs

FxAccountsPush.sys.mjs

Autopush

IndexedDB

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.

beginWSSetup

wsOnStart Success

handleHelloReply

Receive + notify observers

wsOnStop

sendPing Fails

wsOnStart fails

invalid server hello

Shut Down

Waiting for WebSocket to start

Waiting for server hello

Ready

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

  2. 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:

SubscriptionstringchannelIDKey, Derived from scopestringpushEndpointUnique endpoint for this subscriptionstringscopeUsually the origin, unique value for internal consumersObjectp256dhPublicKeyObject representing the public keyObjectp256dhPrivateKeyObject representing the private key

Firefox for Android

See also:

Flow diagram for source code

The source code for push is available under the following paths in mozilla-central:

The following flow diagram describes how different modules interact with each other to provide the push API to consumers.

Local Storage

Server

Browser Code

Public API

imports

Implemented by

Yes

NO

subscribe,getSubscription

subscribe,getSubscription

PushSubscribe,PushGetSubscription

onSubscribe,onGetSubscription

subscribe,getSubscription

start

onNewToken

onNewToken

subscribe,getSubscription

subscribe,get_subscription

Storage

Network

bridge interface

Read,Write

Third party Web app

PushManager.webidl

Main Thread?

Push.sys.mjs

PushManager.cpp

GeckoViewPush.sys.mjs

WebPushController.java

WebPushEngineIntegration.kt

AutoPushFeature.kt

AbstractFirebasePushService.kt

Firebase Cloud Messaging

push/src/lib.rs

internal/push_manager.rs

internal/storage/db.rs

internal/communications.rs

Autopush

SQLite