Skip to main content

SockJS python server for the Cyclone Web Server

Project description

SockJS-cyclone
==============

.. image:: https://badge.fury.io/py/sockjs-cyclone.png
:target: https://pypi.python.org/pypi/sockjs-cyclone

.. image:: https://secure.travis-ci.org/flaviogrossi/sockjs-cyclone.png?branch=master
:target: http://travis-ci.org/#!/flaviogrossi/sockjs-cyclone

.. image:: https://pypip.in/d/sockjs-cyclone/badge.png
:target: https://crate.io/packages/sockjs-cyclone/

SockJS-cyclone is a pure Python server implementation for the
`SockJS client library <https://github.com/sockjs/sockjs-client>`_
running on the `Cyclone <http://cyclone.io>`_ web server.

SockJS-cyclone is released under the `MIT license
<https://github.com/flaviogrossi/sockjs-cyclone/tree/master/LICENSE>`_.

What is SockJS?
---------------

`SockJS <http://sockjs.org>`_ is a browser JavaScript library that provides a
WebSocket-like object. SockJS gives you a coherent, cross-browser, JavaScript
API which creates a low latency, full duplex, cross-domain communication
channel between the browser and the web server, which consistently works across
old browsers, misconfigured or old proxies and firewalls, etc. by automatically
using other transports as a fallback mechanism.

SockJS main features:

- simple APIs, as close to the WebSocket API as possible;
- scaling and load balancing techniques;
- very fast connection establishment;
- pure JavaScript library on the client-side, no flash needed;
- very extensive code testing available for both the server and client sides.

SockJS-cyclone fully supports the SockJS protocol version 0.3.3.

What is Cyclone?
----------------

`Cyclone <http://cyclone.io>`_ is a very fast and scalable web server framework
that implements the Tornado API as a Twisted protocol.

How does it look like?
----------------------

Here is a small example for an echo server:

.. code-block:: python

from twisted.internet import reactor
import cyclone
import sockjs.cyclone

class EchoConnection(sockjs.cyclone.SockJSConnection):
def messageReceived(self, message):
self.sendMessage(message)

if __name__ == "__main__":
EchoRouter = sockjs.cyclone.SockJSRouter(EchoConnection, '/echo')
app = cyclone.web.Application(EchoRouter.urls)
reactor.listenTCP(8888, app)
reactor.run()

and an excerpt for the client:

.. code-block:: javascript

var sock = new SockJS('http://mydomain.com/echo');
sock.onopen = function() {
console.log('open');
};
sock.onmessage = function(e) {
console.log('message', e.data);
};
sock.onclose = function() {
console.log('close');
};
sock.send('hello!');

Complete examples `here <https://github.com/flaviogrossi/sockjs-cyclone/tree/master/examples>`_.

Multiplexing
------------

SockJS-Cyclone supports multiplexing (multiple distinct channels over a single
shared connection):

.. code-block:: python

from twisted.internet import reactor
import cyclone
from sockjs.cyclone.conn import SockJSConnection, MultiplexConnection
from sockjs.cyclone.router import SockJSRouter

class AnnConnection(SockJSConnection):
def messageReceived(self, message):
self.sendMessage('Ann received ' + message)

class BobConnection(SockJSConnection):
def messageReceived(self, message):
self.sendMessage('Bob received ' + message)

class CarlConnection(SockJSConnection):
def messageReceived(self, message):
self.sendMessage('Carl received ' + message)

if __name__ == "__main__":
multiplexConnection = MultiplexConnection.create(ann=AnnConnection,
bob=BobConnection,
carl=CarlConnection)

echoRouter = SockJSRouter(multiplexConnection, '/echo')

app = cyclone.web.Application(echoRouter.urls)
reactor.listenTCP(8888, app)
reactor.run()

See the `websocket-multiplex <https://github.com/sockjs/websocket-multiplex>`_
library for the client support, and the complete example `here
<https://github.com/flaviogrossi/sockjs-cyclone/tree/master/examples/multiplex>`_.


Installation
============

Install from pypi with:

::

pip install sockjs-cyclone

or from the latest sources with:

::

git clone https://github.com/flaviogrossi/sockjs-cyclone.git
cd sockjs-cyclone
python setup.py install


SockJS-cyclone API
==================

The main interaction with SockJS-cyclone happens via the two classes
``SockJSRouter`` and ``SockJSConnection``.

SockJSConnection
----------------

The ``SockJSConnection`` class represent a connection with a client and
contains the logic of your application. Its main methods are:

- ``connectionMade(request)``: called when the connection with the client is
established;
- ``messageReceived(message)``: called when a new message is received from the
client;
- ``sendMessage(message)``: call when you want to send a new message to the
client;
- ``close()``: close the connection;
- ``connectionLost()``: called when the connection with the client is lost or
explicitly closed.

SockJSRouter
------------

The ``SockJSRouter`` class routes the requests to the various connections
according to the url prefix. Its main methods are:

- ``__init__(connection, prefix, user_settings)``: bounds the given connection
to the given url prefix;
- ``urls``: read only property to be used to initialize the cyclone application
with all the needed sockjs urls.


Deployment
==========

SockJS servers are usually deployed in production behind reverse proxies and/or
load balancers. The most used options are currently `Nginx <http://nginx.org>`_
and `HAProxy <http://haproxy.1wt.eu>`_.

Nginx
-----

Two major options are needed to fully support proxying requests to a
SockJS-Cyclone server: setting the HTTP protocol version to 1.1 and `passing
upgrade headers to the server <http://nginx.org/en/docs/http/websocket.html>`_.
The relevant portion of the required configuration is:

::

server {
listen 80;
server_name localhost;

location / {
proxy_pass http://<sockjs_server>:<port>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
}

}

For websocket support, nginx version 1.3.13 or above is needed.

A working ``nginx.conf`` example can be found `here <https://github.com/flaviogrossi/sockjs-cyclone/tree/master/examples/deployment>`_.

HAProxy
-------

A complete example for HAProxy deployment and load balancing can be found on
``SockJS-Node`` `Readme <https://github.com/sockjs/sockjs-node#deployment-and-load-balancing>`_.


Credits
=======

Thanks to:

- Serge S. Koval for the tornado implementation;
- VoiSmart s.r.l for sponsoring the project.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sockjs-cyclone, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size sockjs-cyclone-1.0.0.tar.gz (19.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page