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.

Tracking bug is no bug filed yet.

Engineers Involved

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

User Requirements

• Transparency: Process MUST be transparent to user, only involving clicking "Yes" or "No" to a dialog of the web app requesting to send notifications

• 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 into GMail and wants to receive notifications, then obviously Google knows who they are)

• Portable: 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 make use of the software. 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.

• Low-barrier to Entry: Web apps SHOULD be able to add notification support to their applications with relatively little effort.

System Requirements

TODO

Desired User Flow

1. User visits web site
2. Web site requests to send notifications to the user
   1. User says no: flow is halted and no further requests take place.
   2. User says yes:
      1. TODO

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

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