Migrating from previous TornadIO version¶

TornadIO2 has some incompatible API changes.

1. Instead of having one router handler, TornadIO2 exposes transports as first-class Tornado handlers. This saves some memory per active connection, because instead of having two handlers per request (router and transport), you will now have only one. This change affects how TornadIO2 is initialized and plugged into your Tornado application:

ChatServer = tornadio2.router.TornadioRouter(ChatConnection)
# Fill your routes here
routes = [(r"/", IndexHandler)]
# Extend list of routes with Tornadio2 URLs
routes.extend(ChatServer.urls)

application = tornado.web.Application(routes)

or alternative approach:

ChatServer = tornadio2.router.TornadioRouter(ChatConnection)
application = tornado.web.Application(ChatServer.apply_routes([(r"/", IndexHandler)]))

2. SocketConnection.on_open was changed to accept single request parameter. This parameter is instance of the ConnectionInfo class which contains some helper methods like get_argument(), get_cookie(), etc. Also, if you return False from your on_open handler, TornadIO2 will reject connection.

Example:

class MyConnection(SocketConnection):
    def on_open(self, request):
        self.user_id = request.get_argument('id')

        if not self.user_id:
            return False

This variable is also available for multiplexed connections and will contain query string parameters from the socket.io endpoint connection request.

3. There’s major behavioral change in exception handling. If something blows up and is not handled, whole connection is closed (including any running multiplexed connections). In previous TornadIO version it was silently dropping currently open transport connection and expecting for socket.io to reconnect.

4. Persistent connections are not dropped immediately - there’s a chance that person might reconnect with same session id and we will want to pick it up.

5. Socket.IO 0.7 dropped support for xhr-multipart transport, so you can safely remove it from your configuration file.

Unicode¶

TornadIO2 supports unicode for all transports. When you send something, it will be automatically converted to the unicode (assuming that it is not unicode already).

Few rules:

1. send has following logic in place:

   • If message is object or dictionary, it will be json encoded into unicode string
   • If message is unicode, it will be sent as is
   • If message is non-unicode, not an object and not a dictionary, it will be converted to string and converted to unicode using utf-8 encoding. If your string is in some other encoding (multi-byte, etc), it is up for you to handle encoding and pass your data in unicode (or utf-8 encoded).

2. emit has similar logic:

   • It will convert event name into unicode string (if it is not). It is expected that event name will only use latin characters
   • All emit arguments will be json encoded into unicode string

3. All incoming messages will be automatically converted to unicode strings. You can expect to receive unicode strings in your message handler and events.

Multiplexed connections¶

Starting from socket.io 0.7, there’s new concept of multiplexed connections: you can have multiple “virtual” connections working through one transport connection. TornadIO2 supports this transparently, but you have to tell TornadIO how to route multiplexed connection requests. To accomplish this, you can either use built-in routing mechanism or implement your own.

To use built-in routing, declare and initialize __endpoints__ dictionary in your main connection class:

class ChatConnection(SocketConnection):
    def on_message(self, msg):
        pass

class PingConnection(SocketConnection):
    def on_message(self, msg):
        pass

class MyRouterConnection(SocketConnection):
    __endpoints__ = {'/chat': ChatConnection,
                     '/ping': PingConnection}

    def on_message(self, msg):
        pass

MyRouter = tornadio2.router.TornadioRouter(MyRouterConnection)

On client side, create two connections:

var chat = io.connect('http://myserver/chat'),
    ping = io.connect('http://myserver/ping');

chat.send('Hey Chat');
ping.send('Hey Ping');

So, you have to have three connection classes for 2 virtual connections - that’s how socket.io works. If you want, you can send some messages to MyRouterConnection as well, if you will connect like this:

var conn = io.connect('http://myserver'),
    chat = io.connect('http://myserver/chat'),
    ping = io.connect('http://myserver/ping');

    conn.send('Hey Connection!')

Events¶

Instead of having “just” messages, socket.io 0.7 introduced new concept of events. Event is just a name and collection of parameters.

TornadIO2 provides easy-to-use syntax sugar which emulates RPC calls from the client to your python code. Check following example:

class MyConnection(SocketConnection):
    @event('hello')
    def test(self, name):
        print 'Hello %s' % name

        self.emit('thanks', name=name)
        self.emit('hello', name, 'foobar')

In your client code, to call this event, do something like:

sock.emit('hello', {name: 'Joes'});

You can also use positional parameters. For previous example, you can also do something like:

sock.emit('hello', 'Joes')

To handle event on client side, use following code:

sock.on('thanks', function(data) {
    alert(data.name);
});
sock.on('hello', function(name, dummy) {
    alert('Hey ' + name + ' ' + dummy);
});

However, take care - if method signature does not match (missing parameters, extra parameters, etc), your connection will blow up and self destruct.

event decorator can be used without parameter and it will use event handler name in this case:

class MyConnection(SocketConnection):
    @event
    def hello(self, name):
        print 'Hello %s' % name

If you don’t like this event handling approach, just override on_event in your socket connection class and handle them by yourself:

class MyConnection(SocketConnection):
    def on_event(self, name, *args, **kwargs):
        if name == 'hello':
            print 'Hello %s' % (kwargs['name'])

        self.emit('thanks', name=kwargs['name'])

There’s also some magic involved in event message parsing to make it easier to work with events.

If you send data from client using following code:

sock.emit('test', {a: 10, b: 10});

TornadIO2 will unpack dictionary into kwargs parameters and pass it to the on_event handler. However, if you pass more than one parameter, Tornadio2 won’t unpack them into kwargs and will just pass parameters as args. For example, this code will lead to args being passed to on_event handler:

sock.emit('test', 1, 2, 3, {a: 10, b: 10});

Acknowledgments¶

New feature of the socket.io 0.7+. When you send message to the client, you now have way to get notified when client receives the message. To use this, pass a callback function when sending a message:

class MyConnection(SocketConnection):
    def on_message(self, msg):
        self.send(msg, self.my_callback)

    def my_callback(self, msg, ack_data):
        print 'Got ack for my message: %s' % message

ack_data contains acknowledgment data sent from the client, if any.

To send event with acknowledgement, use SocketConnection.emit_ack method:

class MyConnection(SocketConnection):
    def on_message(self, msg):
        self.emit_ack(self.my_callback, 'hello')

    def my_callback(self, event, ack_data):
        print 'Got ack for my message: %s' % msg

If you want to send reverse confirmation with a message, just return value you want to send from your event handler:

class MyConnection(SocketConnection):
    @event('test')
    def test(self):
        return 'Joes'

and then, in your javascript code, you can do something like:

sock.emit('test', function(data) {
    console.log(data);  // data will be 'Joes'
});

If you want to return multiple arguments, return them as tuple:

class MyConnection(SocketConnection):
    @event('test')
    def test(self):
        return 'Joes', 'Mike', 'Mary'

On client-side, you can access them by doing something like:

sock.emit('test', function(name1, name2, name3) {
    console.log(name1, name2, name3);  // data will be 'Joes'
});

Generator-based asynchronous interface¶

tornadio2.gen module is a wrapper around tornado.gen API. You might want to take a look at Tornado documentation for this module, which can be found here.

While you can use tornado.gen API without any problems, sometimes you may want to handle your messages in order they were received. If you will decorate your functions with tornado.gen.engine, your code will work asynchronously - second message might get handled before first message got processed.

To prevent this situation, TornadIO2 provides helpful decorator: tornadio2.gen.sync_engine. sync_engine will queue incoming calls if there’s another instance of the function running. As a result, it will call your method synchronously without blocking the io_loop. This decorator only works with class methods, don’t try to use it for functions - it requires self to properly function.

Lets check following example:

from tornadio2 import gen

class MyConnection(SocketConnection):
    @gen.sync_engine
    def on_message(self, query):
        http_client = AsyncHTTPClient()
        response = yield gen.Task(http_client.fetch, 'http://google.com?q=' + query)
        self.send(response.body)

If client will quickly send two messages, it will work “synchronously” - on_message won’t be called for second message till handling of first message is finished.

However, if you will change decorator to gen.engine, message handling will be asynchronous and might be out of order:

from tornadio2 import gen

class MyConnection(SocketConnection):
    @gen.engine
    def on_message(self, query):
        http_client = AsyncHTTPClient()
        response = yield gen.Task(http_client.fetch, 'http://google.com?q=' + query)
        self.send(response.body)

If client will quickly send two messages, server will send response as soon as response is ready and if it takes longer to handle first message, response for second message will be sent first.

As a nice feature, you can also decorate your event handlers or even wrap main on_event method, so all events can be synchronous when using asynchronous calls.

tornadio2.gen API will only work with the yield based methods (methods that produce generators). If you implement your asynchronous code using explicit callbacks, it is up for you how to synchronize their execution order.

TBD: performance considerations, python iterator performance.

Statistics¶

TornadIO2 captures some counters:

Stats are captured by the router object and can be accessed through the stats property:

MyRouter = tornadio2.TornadioRouter(MyConnection)

print MyRouter.stats.dump()

For more information, check stats module API or stats example.

Deployment¶

Bugs and Workarounds¶

There are some known bugs in socket.io (valid for socket.io-client 0.8.6). I consider them “show-stoppers”, but you can work around them with some degree of luck.

var conn = io.connect(addr, {'force new connection': true});
conn.on('message', function(msg) { alert('msg') });

io.j = [];
io.sockets = [];

var conn = io.connect(addr);
conn.on('message', function(msg) { alert('msg') });

var conn = io.connect(addr);
conn.on('disconnect', function(msg) { conn.socket.reconnect(); });

API¶