WebSocket Introduction

Basic WebSocket

AutobahnPython provides a Message-based API to WebSocket plus auxiliary methods and callbacks.

The message-based API closely resembles the API of WebSocket available to JavaScript in browsers.

Most of the time, this API is what you should use, unless you have specific needs (frame-based / streaming processing, see below).

Message-based Processing

The interface autobahn.websocket.interfaces.IWebSocketChannel defines the API for message-based WebSocket processing and consists of these callbacks and methods

The message-based API is implemented in the following methods and callbacks

autobahn.websocket.interfaces.IWebSocketChannel.onOpen

autobahn.websocket.interfaces.IWebSocketChannel.sendMessage

autobahn.websocket.interfaces.IWebSocketChannel.onMessage

autobahn.websocket.interfaces.IWebSocketChannel.sendClose

autobahn.websocket.interfaces.IWebSocketChannel.onClose

Prepared Messages

In case you want to send a single WebSocket message to multiple peers, AutobahnPython provides an optimized way of sending using

autobahn.websocket.protocol.WebSocketFactory.prepareMessage

autobahn.websocket.interfaces.IWebSocketChannel.sendPreparedMessage

Handshake Hooks

AutobahnPython allows you to hook into the initial WebSocket opening handshake (e.g. for handling HTTP cookies, subprotocols, etc):

autobahn.websocket.protocol.WebSocketServerProtocol.onConnect

autobahn.websocket.protocol.WebSocketClientProtocol.onConnect

Ping/Pong Processing

The basic API also allows for explicit processing of WebSocket Pings and Pongs:

autobahn.websocket.interfaces.IWebSocketChannel.onPing

autobahn.websocket.interfaces.IWebSocketChannel.onPong

autobahn.websocket.interfaces.IWebSocketChannel.sendPing

autobahn.websocket.interfaces.IWebSocketChannel.sendPong

Note that explicit processing of Pings/Pongs is unnecessary normally - AutobahnPython will do the right thing under the hood.

Implementation

The basic API is implemented in the following classes

autobahn.websocket.protocol.WebSocketProtocol
autobahn.websocket.protocol.WebSocketServerProtocol
autobahn.websocket.protocol.WebSocketClientProtocol
autobahn.twisted.websocket.WebSocketServerProtocol
autobahn.twisted.websocket.WebSocketClientProtocol
autobahn.asyncio.websocket.WebSocketServerProtocol
autobahn.asyncio.websocket.WebSocketClientProtocol

Advanced WebSocket

A WebSockets message consists of a potentially unlimited number of fragments ("message frames"), each of which can have a payload between 0 and 2^63 octets.

The implementation of the basic API is message-based, and thus has to buffer all data received for a message frame, and buffer all frames received for a message, and only when the message finally ends, flattens all buffered data and fires autobahn.websocket.interfaces.IWebSocketChannel.onMessage.

Usually, when you produce/consume messages of small to limited size (like say <256k), this is absolutely sufficient and convenient.

However, when you want to process messages consisting of a large number of message fragments, or you want to process messages that contain message fragments of large size, this buffering will result in excessive memory consumption.

In these cases, you might want to process message fragments on a per frame basis, or you may even want to process data incoming, as it arrives.

The advanced API provides you all the necessary methods and callbacks to do WebSockets using frame-based processing or even completely streaming processing - both sending and receiving.

Frame-based API

The interface autobahn.websocket.interfaces.IWebSocketChannelFrameApi defines the API for frame-based WebSocket processing and consists of these callbacks and methods

autobahn.websocket.interfaces.IWebSocketChannelFrameApi.onMessageBegin

autobahn.websocket.interfaces.IWebSocketChannelFrameApi.onMessageFrame

autobahn.websocket.interfaces.IWebSocketChannelFrameApi.onMessageEnd

autobahn.websocket.interfaces.IWebSocketChannelFrameApi.beginMessage

autobahn.websocket.interfaces.IWebSocketChannelFrameApi.sendMessageFrame

autobahn.websocket.interfaces.IWebSocketChannelFrameApi.endMessage

is implemented in the following classes

autobahn.websocket.protocol.WebSocketProtocol
autobahn.websocket.protocol.WebSocketServerProtocol
autobahn.websocket.protocol.WebSocketClientProtocol
autobahn.twisted.websocket.WebSocketServerProtocol
autobahn.twisted.websocket.WebSocketClientProtocol
autobahn.asyncio.websocket.WebSocketServerProtocol
autobahn.asyncio.websocket.WebSocketClientProtocol

Streaming API

The interface autobahn.websocket.interfaces.IWebSocketChannelStreamingApi defines the API for streaming WebSocket processing and consists of these callbacks and methods

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.onMessageBegin

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.onMessageFrameBegin

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.onMessageFrameData

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.onMessageFrameEnd

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.onMessageEnd

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.beginMessage

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.beginMessageFrame

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.sendMessageFrameData

autobahn.websocket.interfaces.IWebSocketChannelStreamingApi.endMessage