SockJS-Twisted

A simple library for adding SockJS support to your twisted application.

Status

SockJS-Twisted passes all SockJS-Protocol v0.3.3 tests, and all SockJS-Client qunit tests. It has been used in production environments, and should be free of any critical bugs.

Usage

Use txsockjs.factory.SockJSFactory to wrap your factories. That's it!

from txsockjs.factory import SockJSFactory
reactor.listenTCP(8080, SockJSFactory(factory_to_wrap))

There is nothing else to it, no special setup involved.

Do you want a secure connection? Use listenSSL() instead of listenTCP().

Advanced Usage

For those who want to host multiple SockJS services off of one port, txsockjs.factory.SockJSMultiFactory is designed to handle routing for you.

from txsockjs.factory import SockJSMultiFactory
f = SockJSMultiFactory()
f.addFactory(EchoFactory(), "echo")
f.addFactory(ChatFactory(), "chat")
reactor.listenTCP(8080, f)

http://localhost:8080/echo and http://localhost:8080/chat will give you access to your EchoFactory and ChatFactory.

Integration With Websites

It is possible to offer static resources, dynamic pages, and SockJS endpoints off of a single port by using txsockjs.factory.SockJSResource.

from txsockjs.factory import SockJSResource
root = resource.Resource()
root.putChild("echo", SockJSResource(EchoFactory()))
root.putChild("chat", SockJSResource(ChatFactory()))
site = server.Site(root)
reactor.listenTCP(8080, site)

Multiplexing [Experimental]

SockJS-Twisted also has built-in support for multiplexing. See the Websocket-Multiplex library for how to integrate multiplexing client side.

from txsockjs.multiplex import SockJSMultiplexResource
multiplex = SockJSMultiplexResource()
multiplex.addFactory("echo", EchoFactory())
multiplex.addFactory("chat", ChatFactory())
root = resource.Resource()
root.putChild("multiplex", multiplex)
site = server.Site(root)
reactor.listenTCP(8080, site)

Options

A dictionary of options can be passed into the factory to control SockJS behavior.

options = {
    'websocket': True,
    'cookie_needed': False,
    'heartbeat': 25,
    'timeout': 5,
    'streaming_limit': 128 * 1024,
    'encoding': 'cp1252', # Latin1
    'sockjs_url': 'https://d1fxtkz8shb9d2.cloudfront.net/sockjs-0.3.js',
    'proxy_header': None
}
SockJSFactory(factory_to_wrap, options)
SockJSMultiFactory().addFactory(factory_to_wrap, prefix, options)
SockJSResource(factory_to_wrap, options)
SockJSMultiplexResource(options)

websocket :

whether websockets are supported as a protocol. Useful for proxies or load balancers that don't support websockets.

cookie_needed :

whether the JSESSIONID cookie is set. Results in less performant protocols being used, so don't require them unless your load balancer requires it.

heartbeat :

how often a heartbeat message is sent to keep the connection open. Do not increase this unless you know what you are doing.

timeout :

maximum delay between connections before the underlying protocol is disconnected

streaming_limit :

how many bytes can be sent over a streaming protocol before it is cycled. Allows browser-side garbage collection to lower RAM usage.

encoding :

All messages to and from txsockjs should be valid UTF-8. In the event that a message received by txsockjs is not UTF-8, fall back to this encoding.

sockjs_url :

The url of the SockJS library to use in iframes. By default this is served over HTTPS and therefore shouldn't need changing.

proxy_header :

The HTTP header to pull a proxied IP address out of. Leave as None to get the unproxied IP. Do not change this unless you are behind a proxy you control.

License

SockJS-Twisted is (c) 2012 Christopher Gamble and is made available under the BSD license.