tornado.websocket — Bidirectional communication to the browser

Server-side implementation of the WebSocket protocol.

WebSockets allow for bidirectional communication between the browser and server.

Warning

The WebSocket protocol is still in development. This module currently implements the “hixie-76” and “hybi-10” versions of the protocol. See this browser compatibility table on Wikipedia.

class tornado.websocket.WebSocketHandler(application, request, **kwargs)[source]

Subclass this class to create a basic WebSocket handler.

Override on_message to handle incoming messages. You can also override open and on_close to handle opened and closed connections.

See http://dev.w3.org/html5/websockets/ for details on the JavaScript interface. This implement the protocol as specified at http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10 The older protocol version specified at http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76. is also supported.

Here is an example Web Socket handler that echos back all received messages back to the client:

class EchoWebSocket(websocket.WebSocketHandler):
    def open(self):
        print "WebSocket opened"

    def on_message(self, message):
        self.write_message(u"You said: " + message)

    def on_close(self):
        print "WebSocket closed"

Web Sockets are not standard HTTP connections. The “handshake” is HTTP, but after the handshake, the protocol is message-based. Consequently, most of the Tornado HTTP facilities are not available in handlers of this type. The only communication methods available to you are write_message() and close(). Likewise, your request handler class should implement open() method rather than get() or post().

If you map the handler above to “/websocket” in your application, you can invoke it in JavaScript with:

var ws = new WebSocket("ws://localhost:8888/websocket");
ws.onopen = function() {
   ws.send("Hello, world");
};
ws.onmessage = function (evt) {
   alert(evt.data);
};

This script pops up an alert box that says “You said: Hello, world”.

write_message(message)[source]

Sends the given message to the client of this Web Socket.

open(*args, **kwargs)[source]

Invoked when a new WebSocket is opened.

on_message(message)[source]

Handle incoming messages on the WebSocket

This method must be overloaded

on_close()[source]

Invoked when the WebSocket is closed.

close()[source]

Closes this Web Socket.

Once the close handshake is successful the socket will be closed.

async_callback(callback, *args, **kwargs)[source]

Wrap callbacks with this if they are used on asynchronous requests.

Catches exceptions properly and closes this WebSocket if an exception is uncaught.

class tornado.websocket.WebSocketProtocol(handler)[source]

Base class for WebSocket protocol versions.

async_callback(callback, *args, **kwargs)[source]

Wrap callbacks with this if they are used on asynchronous requests.

Catches exceptions properly and closes this WebSocket if an exception is uncaught.

class tornado.websocket.WebSocketProtocol76(handler)[source]

Implementation of the WebSockets protocol, version hixie-76.

This class provides basic functionality to process WebSockets requests as specified in http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76

challenge_response(challenge)[source]

Generates the challenge response that’s needed in the handshake

The challenge parameter should be the raw bytes as sent from the client.

write_message(message)[source]

Sends the given message to the client of this Web Socket.

close()[source]

Closes the WebSocket connection.

class tornado.websocket.WebSocketProtocol8(handler)[source]

Implementation of the WebSocket protocol, version 8 (draft version 10).

Compare http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10

write_message(message, binary=False)[source]

Sends the given message to the client of this Web Socket.

close()[source]

Closes the WebSocket connection.

Previous topic

tornado.platform.twisted — Run code written for Twisted on Tornado

Next topic

tornado.wsgi — Interoperability with other Python frameworks and servers

This Page