Simple yet powerful infra-structure for handling of WebSocket connections.

Objectives

The server itself should be based on a common infra-structure like the one present in frameworks like node.js that should abstract the socket connection layer (select layer) on an event driven basis. The infra-structure itself should be non-blocking and asynchronous for performance and scalability.

The API layer should be provided by a simple WSGI application implemented using the Appier Framework to keep things simple and fast.

For persistence the pushi infra-structure uses the MongoDB database infra-structure to avoid any unwanted complexities and provide fast performance.

Inspiration

Pushi was heavily inspired by the Pusher service, and aims at providing a free alternative to it (for cost reducing).

Channels

The channel is the base object for communication and there are four types of channels so that each one has its own objectives.

Public Channels

Channels that may be subscribed by any connection without any sort of validation.

Private Channels

Authenticated channels for which the access is constrained to only server side validated connections. The validation is performed using a REST-JSON based API.

Presence Channels

Channels that provide extra information on the situation on the channel, for instance allow the identification of a set of connection using a single user_id tag. Using this approach it's possible to know when a new user connects to a channel and when one disconnects (no more connections with the same user_id are present). These channels are considered private and so are subject to validation from the server side.

Personal Channels

This channels provide the capability to aggregate a series of (personal) subscriptions into a single channel (for simplicity). This way it's easy to aggregate a stream of notifications that arise from a group of channels. This channel must be used together with the publish subscribe model. A channel of this type should be named personal-<user_id>.

Peer Channels

Targeted at chat environment allows for the creation of automatic channels for the various elements (users) that are subscribed to a peer channel. The activation of the automatic peer channel configuration is archived using the peer flag in the channel_data structure upon the subscription of such channel. This channel type should not be created directly but instead should be created through presence channels.

The management of these kind of channels implies that the peer advertisement flag is set for a channel shared among the peers, from that moment the peer is visible to all the other peers upon subscription of that shared channel. These kind of channels should be used together with the presence channels.

The naming of these kind of channels will always follow the structure peer-base_channel:user_1&user_2&user_3.

Persistence

It's possible to use pushi to store messages in the server side in a publish/subscriber way so that a user_id may subscribe for a certain channel even when it's offline.

Subscribe

To be able to subscribe for a channel use the apps/<app_id>/subscribe route with the user_id and the event parameters indicating both the id and the name of the event that should be subscribed.

Unsubscribe

To revert the subscribe operation one should call the apps/<app_id>/unsubscribe route with the same user_id and the event parameters.

Usage

When a user connects to the channel that it has subscribed the last messages are returned as part of the channel_data structure.

Running

To be able to run the pushi infra-structure under a normal non encrypted connection and bind to the complete set of network interfaces in the host the following command:

APP_HOST=0.0.0.0 \
APP_PORT=8080 \
SERVER_HOST=0.0.0.0 \
SERVER_PORT=80 \
python pushi/src/pushi/base/state.py < /dev/null &> ~/pushi.log &

To be able to run in using SSL encryption additional commands must be used, please note that the SSL port used by the app is not the default one:

APP_SERVER=netius \
APP_HOST=0.0.0.0 \
APP_PORT=9090 \
APP_SSL=1 \
APP_SSL_KEY=/path/to/file.key \
APP_SSL_CER=/path/to/file.cer \
SERVER_HOST=0.0.0.0 \
SERVER_PORT=443 \
SERVER_SSL=1 \
SERVER_SSL_KEY=/path/to/file.key \
SERVER_SSL_CER=/path/to/file.cer \
python pushi/src/pushi/base/state.py < /dev/null &> ~/pushi.log &

Quick Start

Client Side

var pushi = new Pushi("YOU_APP_KEY");
pushi.bind("message", function(event, data) {
    jQuery("body").append("<div>" + data + "</div>");
});

Server Side

import pushi

proxy = pushi.Pushi(
    app_id = "YOU_APP_ID",
    app_key = "YOU_APP_KEY",
    app_secret = "YOU_APP_SECRET"
)
proxy.trigger_event(
    channel = "global",
    data = "hello world",
    event = "message"
)

Examples

A set of runnable examples is available to demonstrate the most common operations, all of them require a running Pushi server and the pushi client (pip install pushi).

Web Push

A browser based example demonstrating Web Push notifications is available under src/pushi/app/static/examples/web-push. It includes the browser client (index.html) and the service worker (sw.js) used to display the notifications.

To test it, configure an app with VAPID credentials (use the Generate VAPID operation on the app), fill the APP_KEY, APP_ID and APP_SECRET values in index.html and start the server with a single command:

APP_HOST=0.0.0.0 APP_PORT=8080 SERVER_HOST=0.0.0.0 SERVER_PORT=9090 python -m pushi.base

Then open the example from the Pushi server (to avoid CORS issues):

http://localhost:8080/static/examples/web-push/index.html

Subscribe from the browser and then trigger a notification from the server side using the examples/base/notify.py script:

python examples/base/notify.py

Email (SMTP)

The examples/smtp/subscribe.py script subscribes an email address to a channel so that an email is sent whenever an event is triggered on it (requires SMTP to be configured on the server):

python examples/smtp/subscribe.py user@example.com

License

Pushi System is currently licensed under the Apache License, Version 2.0.

Build Automation