CloudServices/Notifications/Specification

Overview

Push Notifications is a project that aims to design and create a system that allows for notifications from clients (such as web applications or services) 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

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

Requirements

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

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.

• Anonymity: Web apps MUST not know anything about user (insofar as the communication between web app and server is concerned; if the user is logged in to GMail and GMail requests to send notifications, then obviously Google knows who it is making the request to)

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

System Requirements

TODO

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.

• Simple Client Implementation: Third-party developers SHOULD be able to implement a notification client with relatively little effort.

Use Cases

User Use Cases

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

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 (ideally) 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

Web App Use Cases

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. The process from the point of view of the web app is as follows:

1. Web app creates a JSON string of the following form:

   • {"routing_key": "mailbox identifier", "type": "message type", "timestamp": "unix timestamp in seconds", "payload": "the message contents"}

2. Web app POSTs the JSON object to agent.

Implementation

Terminology

• User: Individual who receives notifications.
• Client: One of possible many devices a user wishes to receive notifications on, e.g. browser, mobile phone, microwave, etc.
• Web App: Third-party web application that actually produces the notifications. The user subscribes to notifications from this app.

Server API

The server API consists of:

Send Notification

POST https://server/notifications

Sends a notification.

The body of the request is a JSON object of the form:

{
    'user_app_key': user-app-key,
    'type': the type of notification
    'timestamp': web-app-specified time the notification was generated,
    'payload': notification message
}

The Content-Type field can optionally be set to 'application/JSON'.

Return codes:

• 201: Accepted (indicates the notification was received by the server for processing, but may or may not be processed)
• 403: Forbidden (indicates the notification was not received due to exceeding limits or some other security reason, e.g. IP blacklisted)

Detailed Flow TODO: Sequence diagram of request flow.

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?

Meeting Notes

• General notes from meetings over the course of development