WebSockets¶

The pulsar.apps.ws contains 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.

This is a Web Socket handler which echoes all received messages back to the client:

from pulsar.apps import wsgi, ws

class EchoWS(ws.WS):

    def on_message(self, websocket, message):
        websocket.write(message)

To create a valid WebSocket middleware initialise as follow:

wm = ws.WebSocket('/bla', EchoWS())
app = wsgi.WsgiHandler(middleware=(..., wm))
wsgi.WSGIServer(callable=app).start()

API¶

WebSocket handler¶

class pulsar.apps.ws.WS[source]¶

A web socket handler for both servers and clients.

It implements the asynchronous message passing for a WebSocketProtocol. On the server, the communication is started by the WebSocket middleware after a successful handshake.

Override on_message() to handle incoming string messages and on_bytes() to handle incoming bytes messages.

You can also override on_open() and on_close() to perform specific tasks when the websocket is opened or closed.

These methods accept as first parameter the WebSocketProtocol created during the handshake.

on_open(websocket)[source]¶

Invoked when a new websocket is opened.

A web socket is opened straight after the upgrade headers are sent (servers) or received (clients).

on_message(websocket, message)[source]¶

Handles incoming messages on the WebSocket.

This method should be overwritten

on_bytes(websocket, body)[source]¶: Handles incoming bytes.

on_ping(websocket, message)[source]¶

Handle incoming ping message.

By default it writes back the message as a pong frame.

on_pong(websocket, body)[source]¶: Handle incoming pong message.

on_close(websocket)[source]¶: Invoked when the websocket is closed.

WebSocket¶

class pulsar.apps.ws.websocket.WebSocket(route, handle, parser_factory=None, **kwargs)[source]¶

A specialised Router for a websocket handshake.

Once the handshake is successful, the protocol consumer is upgraded to WebSocketProtocol and messages are handled by the handle attribute, an instance of WS.

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.

parser_factory¶: A factory of websocket frame parsers

protocol_class¶: alias of WebSocketProtocol

parser_factory(version=None, kind=0, extensions=None, protocols=None, pyparser=False)

Create a new FrameParser instance.

Parameters:	version – protocol version, the default is 13 kind – the kind of parser, and integer between 0 and 3 (check the `FrameParser` documentation for details) extensions – not used at the moment protocols – not used at the moment pyparser – if `True` (default `False`) uses the python frame parser implementation rather than the much faster cython implementation.

WebSocket protocol¶

class pulsar.apps.ws.websocket.WebSocketProtocol(handshake, handler, parser, loop=None)[source]¶

A ProtocolConsumer for websocket servers and clients.

handshake¶: The original handshake response/request.

handler¶: A websocket handler WS.

parser¶: A websocket FrameParser.

close_reason¶

A tuple of (code, reason) or None.

Available when a close frame is received.

cfg¶: The Config container for this protocol.

write(message, opcode=None, encode=True, **kw)[source]¶

Write a new message into the wire.

It uses the encode() method of the websocket parser.

Parameters:	message – message to send, must be a string or bytes opcode – optional `opcode`, if not supplied it is set to 1 if `message` is a string, otherwise `2` when the message are bytes.

ping(message=None)[source]¶: Write a ping frame.

pong(message=None)[source]¶: Write a pong frame.

write_close(code=None)[source]¶: Write a close frame with code.