Publish-Subscribe with web sockets in Python and Firefox

WebSockets provide a way to communicate through a bi-directional channel on a single TCP connection. This technology is especially interesting since it allows a web server to push data to a browser (client) without having the client to constantly poll for it. In contrast to normal HTTP requests where a new TCP connection gets opened and closed for each request web socket connections are kept open until one party closes them. This allows for communication in both directions, and calls can be made multiple times on the same connection.

In this little article I basically combine what I found on Sylvain Hellegouarch's documentation for ws4py (a WebSocket client and server library for Python) and the article HTML5 Web Socket in Essence by Wayne Ye.

More specifically the examples below shows how multiple clients subscribe via websockets to a cherrypy server through a web socket connection. The first of the two clients in the example below is a very lightweight client based solely on the ws4py package, the other (javascript) implementation is supposed to run in Firefox.

The server

This example provides a minimal publishing engine implemented with cherrypy. An instance of class WebSocketTool is hooked up into cherrypy as a so-called cherrypy tool, and a web socket handler (the Publisher-class) is bound to this tool as a handler for calls to the path /ws:

import cherrypy
from ws4py.server.cherrypyserver import WebSocketPlugin, WebSocketTool
from ws4py.websocket import WebSocket

cherrypy.config.update({'server.socket_port': 9000})
WebSocketPlugin(cherrypy.engine).subscribe()
cherrypy.tools.websocket = WebSocketTool()

SUBSCRIBERS = set()

class Publisher(WebSocket):
    def __init__(self, *args, **kw):
        WebSocket.__init__(self, *args, **kw)
        SUBSCRIBERS.add(self)

    def closed(self, code, reason=None):
        SUBSCRIBERS.remove(self)

class Root(object):
    @cherrypy.expose
    def index(self):
        return open('ws_browser.html').read()

    @cherrypy.expose
    def ws(self):
        "Method must exist to serve as a exposed hook for the websocket"

    @cherrypy.expose
    def notify(self, msg):
        for conn in SUBSCRIBERS:
            conn.send(msg)

cherrypy.quickstart(Root(), '/', 
    config={'/ws': {'tools.websocket.on': True,
                    'tools.websocket.handler_cls': Publisher}})

The only purpose of the Root.ws()-method is to make this method available under /ws in the web server through the cherrypy.expose decorator. Whenever a websocket client makes a request to /ws an instance of class Publisher is created, which registers itself to the global SUBSCRIBERS set on __init__(). When the server goes down, or the client disconnects, its closed() method is called.

The only packages needed for this example are cherrypy and ws4py. Both can be easily installed via easy_install or pip. Save the code above as ws_server.py and start it with

python ws_server.py

Now the server is ready to accept client connections through the web socket protocol. As soon as one of the clients described below has subscribed to this server messages can be published by calling the Root.notify() method. Since it is exposed it is possible to call it from the command line with

curl localhost:9000/notify?msg=HelloWorld

Of course wget works as well.

A pure Python client

The Python client's code is quite short. ws4py provides three sample client implementations, the threaded one has been chosen for this example. The others are using gevent or Tornado.

from ws4py.client.threadedclient import WebSocketClient

class Subscriber(WebSocketClient):
    def handshake_ok(self):
        self._th.start()
        self._th.join()

    def received_message(self, m):
        print "=> %d %s" % (len(m), str(m))

if __name__ == '__main__':
    ws = Subscriber('ws://localhost:9000/ws')
    ws.connect()

The method handshake_ok() has been overridden to keep the thread stored in self._th running continuously (the original implementation quits after one second). After the Subscriber-class has been instantiated it connects to the cherrypy server. Whenever the server sends a message it will be delegated to the method received_message() where it gets printed to stdout.

Just store this code into a file, e.g. ws_subscriber.py and start it in from a new shell. The cherrypy server should print a message to the console that it received a web socket connection.

Now again call the notify-method in the server:

curl localhost:9000/notify?msg=HelloWorld

and the python client should print your message to the screen.

A web socket client in Firefox

This browser client uses the web socket protocol built into Firefox. The example below works for me in FF14, it failed for FF8. I'm not sure which version of Firefox starts to support it. Safari version 5.0 also fails. IE has not been tested.

<html>
  <head>
    <script>
      var websocket = new WebSocket('ws://localhost:9000/ws');
      websocket.onopen    = function (evt) { console.log("Connected to WebSocket server."); };
      websocket.onclose   = function (evt) { console.log("Disconnected"); };
      websocket.onmessage = function (evt) { document.getElementById('msg').innerHTML = evt.data; };
      websocket.onerror   = function (evt) { console.log('Error occured: ' + evt.data); };
    </script>
  </head>
  <body>
    <h1>Websocket demo</h1>
    Message: <span id="msg" />
  </body>
</html>

At load time a Websocket-instance is created and event handlers are installed. The interesting one is the onMessage-handler: it is called for each message received, it copies the message into the SPAN element and thus makes it visible.

Make sure to store this html page in the same directory as the ws_server.py above since we are going to open it through cherrypy's index method. For this to work it has to be named ws_browser.html. Now open Firefox and direct it to http://localhost:9000. You should immediately see this page. The SPAN element should be empty.

Again repeat the curl or wget command in your shell and both the python client (if it is still running) and the SPAN element should display your "HelloWorld" message.