krait.websockets module

This module interfaces Krait’s WebSocket support with your Python backend. WebSocket controllers are implemented as two threads, one running the networking in C++ (the main thread), and the other running the behaviour in Python (the handler thread). Your backend implements the second thread, by subclassing WebsocketsCtrlBase and overriding the relevant methods.

The WebSocket protocol requires three components:

1. A page contains JavaScript code that requests a WebSocket connection to a specific URL, by requesting a WebSocket upgrade (change of protocols) through an otherwise normal GET request. This doesn’t have to be Javascript running in a browser, but usually is.
2. A server-side script to handle a GET request on that URL and accept or deny the WebSocket upgrade
3. A WebSocket controller that runs in a separate thread, handles incoming messages and sends messages itself.

See the websockets tutorial (TODO) for a more detailed explanation.

Usage

1. Create a page with the relevant JavaScript that makes a WebSocket upgrade request to a separate URL, then communicates with the server on the new channel.
2. Create a WebSockets controller by subclassing WebsocketsCtrlBase and overriding, at least, WebsocketsCtrlBase.on_thread_start. This method should contain a loop that runs while WebsocketsCtrlBase.should_stop on self is false.
3. Create the route target Python script at the URL requested by the JavaScript client. Inspect krait.websockets.request, and if it is a valid WebSocket request (not None and protocols contains the expected subprotocol), set krait.websockets.response to a new WebsocketsResponse with a new instance of your controller and, optionally, the subprotocol that you chose.

Reference

class krait.websockets.WebsocketsRequest(http_request)

Bases: object

Represents a Websockets request. Contains additional information extracted from a Upgrade: websocket request.

Parameters:http_request (krait.Request) – The HTTP Upgrade request.

protocols

list of str, optional – The list of protocols options, or None if no options are specified.

static extract_protocols(http_request)

Extract the Websocket protocol options from an HTTP request.

Parameters:http_request (krait.Request) – The HTTP Upgrade request. Returns:The list of protocol options specified by the request, or None if no options are specified. Return type:list of str

class krait.websockets.WebsocketsResponse(controller, protocol=None)

Bases: object

Represents a Websockets response. This class is used to tell Krait what protocol has been chosen and what controller will handle the Websockets connection.

Parameters:

• controller (WebsocketsCtrlBase) – The controller to be used to serve this Websockets connection.
• protocol (str, optional) – The chosen subprotocol, or None for no protocol.

controller

WebsocketsCtrlBase – The controller to be used to serve this Websockets connection.

protocol

str, optional – The chosen subprotocol, or None for no protocol.

krait.websockets.request = None

WebsocketsRequest – The additional Websockets information sent with the HTTP Upgrade request by the client. If this is None, this is not a HTTP Upgrade: websocket request.

krait.websockets.response = None

WebsocketsResponse – The response set by the backend, containing information to be sent back to the client, and the handler for the request. If this is None, the Websockets upgrade was denied. In this case, krait.response SHOULD be a 400 Bad Request or similar.

class krait.websockets.WebsocketsCtrlBase(use_in_message_queue=True)

Bases: object

Base class responsible for handling Websockets communication. Subclass it to add behavior. Passed as an argument to WebsocketsResponse and called by Krait to communicate with the Websockets client. Do not access its (private) attributes directly, use the provided methods. These ensure thread safety, and a stable API.

Parameters:use_in_message_queue (bool) – True to use a message queue for incoming messages. Otherwise, the backend would handle these messages on an event model, by overriding on_in_message.

on_start()

Called by Krait when the controller is ready to start. This is running on the main thread. Do not perform expensive initialization here.

on_thread_start()

The handler thread’s target. Started by the controller’s on_start() method. Override this to add behavior to your controller.

on_in_message(message)

Called by Krait (indirectly) when a new message arrives from the client. By default adds the message to the message queue. Override this if the controller is not configured to use messages queues.

Parameters:message (str) – The new message.

on_in_message_internal(message)

Called by Krait (directly) when a new message arrives from the client. This only acquires the lock, then calls on_in_message.

Parameters:message (str) – The new message;

pop_in_message()

Return the first message in the input queue, popping it, if it exists. Return None otherwise. Call this to get messages from the client. Do not call this if the controller doesn’t use input message queues.

Returns:The value of the first message, or None if there are no messages. Return type:str

push_out_message(message)

Send a message. This adds it to the queue; Krait will watch the message queue and send it.

Parameters:message (str) – The message to send.

pop_out_message()

Return the first message in the output queue, and remove it, if it exists. Return None otherwise. Called by Krait to check on messages to send.

Returns:The value of the first message, or None if there are no messages. Return type:str

on_stop()

Set a flag that tells the controller thread to shut down. Called by Krait when the WebSockets connection is closing.

should_stop()

Return True if the shutdown event has been set, or False otherwise. Call this periodically from the controller thread to check if you should shut down.

wait_stopped(timeout=None)

Join the controller thread, with an optional timeout. Called by Krait until the thread has shut down.

Returns:True if the thread has shut down, False otherwise. Return type:bool