Overview

Mozilla Push Notifications is a project that aims to create a system that allows for notifications from clients (such as web applications or services) to be sent directly to the browsers of its users. A typical example where such a system could be useful is the eBay auctioning system. If a user makes a bid on an item, it would be convenient if that user could leave eBay and start browsing another web site, but still receive notifications if another user bids on that item, allowing them to act on the bid.

Engineers Involved

• Alex Amariutei
• Shane da Silva
• Toby Elliott
• Philipp von Weitershausen

Terminology

• Notification: A message intended to alert its recipient to some event or occurrence.
• Provider: A notification provider, or web app, is any web service that is capable of sending notifications.
• User: End-user; someone who receives notifications.

Requirements

The following section outlines the requirements of the service with respect to the user, third-party developers (a special type of user) who will have to interact with the system. It also outlines the requirements of the system itself.

User Requirements

• Transparency: Process MUST be transparent to user. For example, other than clicking "Yes" or "No" to a dialog of the web app requesting to send notifications, the user should not be aware of the underlying mechanics of the process.

• Security: From the point a message leaves the sender until it arrives at its intended recipient, all communications MUST NOT be easily readable by unauthorized persons (e.g. anyone besides the sender and the recipient). By "easily" we mean it should not be trivial to decrypt a message, but take a long enough time and resources so that such effort is not viable.

• Anonymity: Web apps MUST not know anything about user (insofar as the communication between the web app and server is concerned; if the user is logged in to GMail and signs up for notifications, then obviously Google can associate the resulting subscription with the user who created it).

• Portability: Service MUST work with any device that supports the protocol.

Developer Requirements

Often overlooked, the following requirements should be kept in mind so that third-party developers can easily incorporate the service into their applications. The goal is to make adoption incredibly easy, resulting in more people adopting it and in the end making the service more worthwhile for users who use it.

• Easy Adoption: Web apps and custom clients SHOULD be able to add notification support to their applications with relatively little effort.

Use Cases

This section outlines the use cases of the service from both the user's and web app's point of view.

Users

Register with Notifications Service

In order to make use of the service, the user must enable notifications on their client (e.g. browser). From the UI side of things, this will probably involve a simple check box. Once the user has "opted in" to using notifications, the following process takes place:

1. User selects which notifications server they want to use (most will simply use the Mozilla Notifications server, but users can roll their own if they wish).
2. Client asks user for account credentials, or points user to a link to create an account.
3. User enters their account credentials (or simply uses their Sync account)
4. Client remembers credentials for later use

If the user has already registered with the notification service, then they can add an additional client to receive notifications. See the list of related use cases below.

Related Use Cases: Add a New Client

Subscribe to Notifications

Once set up the user will the be able to subscribe to web sites which they wish to receive push notification from. The process is as follows:

1. User clicks a button or otherwise interacts with a web page such that the page requests to send notifications.
2. Client displays a confirmation box asking user if they wish to receive notifications from the web page in question.
3. Upon confirmation, a new subscription is created and can be viewed in the client's list of subscriptions.

Related Use Cases: Cancel a Subscription

Cancel a Subscription

If down the road the user feels that the subscription is not useful or is otherwise unwanted, they can cancel the subscription so that they no longer receive notifications. The process is as follows:

1. User navigates to the list of subscriptions on their client.
2. User selects the subscription(s) they wish to cancel and click a "Unsubscribe" button.

Related Use Cases: Subscribe to Notifications

Add a New Client

One of the main advantages of the service is it allows users to receive notifications on multiple clients, be it their browser, mobile phone, etc. Thus setting up another client to receive notifications is likely to be a common operation. The following are two possible methods the user can use to set up an additional client (note: the goal is to have this be virtually identical to Firefox Sync).

• Option A: Using JPAKE
  JPAKE is a mechanism for securely exchanging keys between two clients. This is the same process that is used by the Sync service when adding a new device.
• Option B: Using Credentials and Secret Key
  If the user does not have a client that is already connected, they will have to have their credentials ready along with their secret key (which is used to decrypt the messages sent to them). Provided they have this information, the following process could also be used to connect a new client:
  1. User indicates they have already registered and wish to add an additional client manually.
  2. User enters credentials along with their secret key.
  3. Client registers itself with the notification server.

Related Use Cases: Register with Notifications Service

Providers

Send a Notification

The web app is able to send a message (i.e. the notification) to a specific user using a routing key that was given to it by the user's client. The routing key can be thought of as an address that specifies the destination "mailbox" of the message. It maintains the user's anonymity while still allowing the service to communicate with the user. The process from the web app's point of view is as follows:

1. Web app creates a message it wishes to send
2. Web app sends the message to the notification server.

Implementation

Terminology

High-level overview of the lines of communication between the entities in the system.

Overview of how notifications travel from web apps to clients.

• User: Individual who receives notifications.

• Client: One of possibly many devices a user wishes to receive notifications on, e.g. a browser, mobile phone, feather duster, etc.

• Web App: Third-party web application that actually produces the notifications. The user subscribes to notifications from this app via a web page.

• Message Broker: Facilitates the transportation of messages. See RabbitMQ for more information.

• POST Office: Responsible for forwarding all notifications sent by web apps to the Message Broker.

• Client Agent: Handles the creation of exchanges and queues within the Message Broker on behalf of clients. The Client uses the Client Agent as a means to register itself and create and remove subscriptions.

• Subscription: Represents the relationship between a web app and a user who wishes to receive notifications from said web app. A subscription consists of the "link" that allows the web app to send notifications to the user.

• Routing Key/Token: A unique identifier generated by the Agent when a user subscribes to notifications from a web app. The routing key is used as a "mailbox address" to send notifications to the user.

• User Exchange: Entity within the message broker where all messages destined for a particular user are sent.

• Client Queue: Entity within the message broker where all messages destined for a particular client of a user are sent (one queue per client).

APIs

• POST Office API

• Client Agent API

• Browser JavaScript API

Security Considerations

DOS Defense

• Least Recently Used (LRU) queue approach for monitoring IP addresses issuing frequent requests
  • Configurable threshold for adding IP address to Blacklist/Penalty Box
  • Configurable time-out for IP addresses added to Blacklist/Penalty Box
• A single shared blacklist will exist within memcache
• LRU queues will be unique to each server and will penalize an IP to the shared blacklist on memcache
• All thresholds will be controlled via the configuration page

Logging Points

• What are we going to log server-side?

Administration Features

• What features will we provide for administrators of the server?