WebSockets

The pulsar.apps.ws contains a WSGI middleware for handling the WebSocket protocol. Web sockets allow for bidirectional communication between the browser and server. Pulsar implementation uses the WSGI middleware WebSocket for the handshake and a class derived from WS handler for the communication part.

API

WebSocket

class pulsar.apps.ws.WebSocket(handle, extensions=None)

A WSGI middleware for handling w websocket handshake and starting a custom WS connection. It implements the protocol version 13 as specified at http://www.whatwg.org/specs/web-socket-protocol/.

Web Sockets are not standard HTTP connections. The “handshake” is HTTP, but after that, the protocol is message-based. To create a valid WebSocket middleware initialise as follow:

from pulsar.apps import wsgi, ws

class MyWS(ws.WS):
    ...

wm = ws.WebSocket(handle=MyWS())
app = wsgi.WsgiHandler(middleware=(..., wm))

wsgi.createServer(callable=app).start()

See http://tools.ietf.org/html/rfc6455 for the websocket server protocol and http://www.w3.org/TR/websockets/ for details on the JavaScript interface.

WebSocket Handler

class pulsar.apps.ws.WS

A web socket handler. It maintains an open socket with a remote web-socket and exchange messages in an asynchronous fashion. The communication is started by the WebSocket middleware after a successful handshake.

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

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

from pulsar.apps import ws

class EchoWS(ws.WS):

    def on_open(self, environ):
        print("WebSocket opened")

    def on_message(self, environ, message):
        return message

    def on_close(self, environ):
        print("WebSocket closed")

on_handshake(environ, headers)

Invoked just before sending the upgraded headers to the client. This is a chance to add or remove header’s entries.

on_open(environ)

Invoked when a new WebSocket is opened.

on_message(environ, message)

Handle incoming messages on the WebSocket. This method must be overloaded.

on_close(environ)

Invoked when the WebSocket is closed.

close(environ, msg=None)

Invoked when the web-socket needs closing.

Frame

class pulsar.apps.ws.Frame(message=None, opcode=None, version=None, masking_key=None, final=False, rsv1=0, rsv2=0, rsv3=0)

build_frame(message)

Builds a frame from the instance’s attributes.

mask(data)

Performs the masking or unmasking operation on data using the simple masking algorithm:

j                   = i MOD 4
transformed-octet-i = original-octet-i XOR masking-key-octet-j

unmask(data)

Performs the masking or unmasking operation on data using the simple masking algorithm:

j                   = i MOD 4
transformed-octet-i = original-octet-i XOR masking-key-octet-j

class pulsar.apps.ws.FrameParser(version=None, kind=0)

Parser for the version 8 protocol.

kind

0 for parsing client’s frames and sending server frames (to be used in the server), 1 for parsing server frames and sending client frames (to be used by the client)