Push notifications for the web
Failed to load latest commit information.
docs use graphviz instead of PIL Apr 24, 2012
etc fill out queuey install instructions (thanks jrconlin) May 2, 2012
push return the queue as a URL Apr 23, 2012
.gitignore get some sphinx docs Apr 24, 2012
.travis.yml use push-test.ini for tests on travis Apr 23, 2012
MANIFEST.in start the push server Nov 22, 2011
README.rst fill out queuey install instructions (thanks jrconlin) May 2, 2012
client.py mark messages as read through the notification stream Apr 18, 2012
dev-reqs.txt make it easier to build docs for rtfd.org Apr 24, 2012
monitor.py close the websockets when we're done Apr 20, 2012
router.py clean up unused files Apr 14, 2012
setup.cfg test coverage for websockets Apr 20, 2012
setup.py remove CHANGES.txt from setup.py Apr 24, 2012
websocket_client.py give me a python websocket client Apr 14, 2012
websockets.py test coverage for websockets Apr 20, 2012



Getting Started

  1. Make your virtualenv.

  2. Install the python packages:

    pip install -r dev-reqs.txt
  3. Install Queuey from https://github.com/mozilla-services/queuey.

    • add push to the application_keys section in queuey/etc/queuey-dev.ini:

      queuey = f25bfb8fe200475c8a0532a9cbe7651e
      push = f25bfb8fe200475c8a0532a9cbe7651e*
    • Start Cassandra and Queuey.

  4. Create the database:

    cat etc/schema.sql | sqlite3 -echo etc/push.db
  5. Start all the things:

    circusd etc/circus-test.ini
  6. Watch it go:

    python client.py http://localhost:5011

The API server runs on http://localhost:5001 in dev mode and http://localhost:5011 in test mode.

Running the Server

There's a lot of moving pieces involved in the notifications service. These can all be controlled through circusd etc/circus-dev.ini. Here's what's running:

paster serve etc/push-dev.ini
The main HTTP API server.
python websockets.py etc/push-dev.ini
The websocket server.
python router.py etc/push-dev.ini
The pubsub broker between the HTTP server and the websocket server.
python monitor.py etc/push-dev.ini
A daemon that monitors the status of the websocket server.


export PUSH_TEST_CONFIG=./etc/push-test.ini

If the tests appear to be stuck, you're experiencing the joy of asynchronous zeromq sockets. Kill it!

Public API

POST /queue/<queue>/

Add a new message to the queue.

* title: Primary text of the notification.
* body: Secondary text of the notification.
* actionUrl: URL to be opened if the user clicks on the notification.
* replaceId: A string which identifies a group of like messages. If the
  user is offline, only the last message with the same replaceId will be
  sent when the user comes back online.

Accepted content types:
* Content-Type: application/x-www-form-urlencoded
* Content-Type: application/json

Client API

POST /token/

>>> 200 OK {"token": <token>}

Create a new token. This token should be stored on the client for future
POST /queue/


>>> 200 OK {"queue": http://example.com/queue/<queue>/}

Create a new queue.
* <token> should be a value created by POSTing to /token/.
* <domain> is the domain the queue belongs to.
PUT /queue/<queue>/
X-Auth-Token: <token>


Update the <timestamp> of the queue. Used to coordinate with other clients
on which messages have been read. The <token> used to create the queue must
be given for authentication.
GET /queue/<queue>/
X-Auth-Token: <token>

>>> 200 OK {"messages": [<message>...]}

Get messages from the queue. The <token> used to create the queue must be
given for authentication.

The format of a message:

Optional query parameters:

limit: The maximum number of messages to show.
since: If given, only return messages sent later than `since`.