cyclone.websocket — Bidirectional communication to the browser

Server-side implementation of the WebSocket protocol.

WebSocket is a web technology providing full-duplex communications channels over a single TCP connection.

For more information, check out the WebSocket demos.

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

Subclass this class to create a basic WebSocket handler.

Override messageReceived to handle incoming messages.

See for details on the JavaScript interface. The protocol is specified at

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

class EchoWebSocket(websocket.WebSocketHandler):
    def connectionMade(self):
        print "WebSocket connected"

    def messageReceived(self, message):
        self.sendMessage(u"You said: " + message)

    def connectionLost(self, reason):
        print "WebSocket disconnected"

Web Sockets are not standard HTTP connections. The “handshake” is HTTP, but after the handshake, the protocol is message-based. Consequently, most of the Cyclone HTTP facilities are not available in handlers of this type. The only communication methods available to you is sendMessage().

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) {

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


Gets called when a message is received from the peer.


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

The message may be either a string or a dict (which will be encoded as json).

exception cyclone.websocket.FrameDecodeError[source]

Frame Decode Error

class cyclone.websocket.Hixie76FrameDecoder[source]

Hixie76 Frame Decoder


Feed the frame decode with new data. Returns a list of the resulting frames or [] if the input data is insufficient to form a valid frame.

Previous topic

cyclone.jsonrpc — JSON-encoded Remote Procedure Call

Next topic

Release notes

This Page