ratancs / centrifuge

Simple real-time messaging in web applications.

CENTRIFUGE

Simple platform for real-time message broadcasting in web applications.

The main goal of Centrifuge is the same as in Pusher or Pubnub services. The main difference is that Centrifuge is open-source and requires installation (it is worth noting that installation is rather simple).

It is built on top of Tornado - extremely fast and mature Python's async web server.

Centrifuge uses ZeroMQ steroid sockets for internal communication and publish/subscribe operations.

For presence and history data Centrifuge utilizes Redis - advanced and super fast in memory key-value store.

To connect to Centrifuge from browser pure Websockets or SockJS library can be used.

Centrifuge comes with administrative web interface to manage project/namespace structure and monitor important messages.

Persistent data (projects, namespaces) by default stored in SQLite database. But when running Centrifuge instance processes on different machines you should use MongoDB or PostgreSQL backends instead of SQLite for structure management.

Please, read the documentation, watch screencast and look at examples for more information.

Main features

• Asynchronous backend on top of Tornado
• SockJS and pure Websockets endpoints
• Simple javascript client
• Presence and history data for channels
• Web interface for managing your projects
• Flexible channel settings through namespaces

Basic usage from browser

var centrifuge = new Centrifuge({
    url: 'http://localhost:8000/connection',  // Centrifuge SockJS connection endpoint
    token: 'TOKEN', // token based on project's secret key, project ID and user ID
    project: 'PROJECT_ID', // project ID from Centrifuge admin interface
    user: 'USER_ID', // your application user ID (can be empty for anonymous access)
});

centrifuge.on('connect', function() {

    console.log('connected');

    var subscription = centrifuge.subscribe('django', function(message) {
        // message from channel received
        console.log(message);
    });

    subscription.on('ready', function(){
        subscription.presence(function(message) {
            // information about who connected to channel at moment received
        });
        subscription.history(function(message) {
            // information about last messages sent into channel received
        });
        subscription.on('join', function(message) {
            // someone connected to channel
        });
        subscription.on('leave', function(message) {
            // someone disconnected from channel
        });
    });

});

centrifuge.on('disconnect', function(){
    console.log('disconnected');
});

centrifuge.connect();

For more information about javascript client API see documentation chapter

Architecture diagram

Admin web interface

To run tests type the following from tests directory (centrifuge must be in PYTHONPATH):

# IMPORTANT! Tests clear Redis database on every running. Be aware of this.
python -m unittest discover -p 'test_*.py'

Contributing

Pull requests are welcome! But, please, follow next principles:

• keep things as simple as possible
• pep8
• python 2.6, 2.7 and 3.3 compatible

P.S. If BSD license of Centrifuge does not allow you to use it, tell me and I'll consider to change license.