Webserver

This is an extensible webserver implemented using Flask and websockets that allows agents to serve frontend HTML pages, along with bi-directional messaging using websockets, including custom message types specific to each application.

Server API

class WebServer(web_host='0.0.0.0', web_port=8050, ws_port=49000, ssl_cert=None, ssl_key=None, root=None, index='index.html', mounts={'/tmp/uploads': '/uploads'}, msg_callback=None, web_trace=False, **kwargs)

Bases: object

MESSAGE_JSON = 0

JSON websocket message (dict)

MESSAGE_TEXT = 1

Text websocket message (str)

MESSAGE_BINARY = 2

Binary websocket message (bytes)

MESSAGE_FILE = 3

File upload from client (bytes)

MESSAGE_AUDIO = 4

Audio samples (bytes, int16)

MESSAGE_IMAGE = 5

Image message (PIL.Image)

Instance = None

Singleton instance

MessageHandlers = []

Message handlers

__init__(web_host='0.0.0.0', web_port=8050, ws_port=49000, ssl_cert=None, ssl_key=None, root=None, index='index.html', mounts={'/tmp/uploads': '/uploads'}, msg_callback=None, web_trace=False, **kwargs)

Create HTTP/HTTPS Flask webserver with websocket messaging.

Use this by either creating an instance and providing msg_callback, or inherit from it and implement on_message() in a subclass. You can also add Flask routes to Webserver.app before start() is called.

Parameters:

• web_host (str) – network interface to bind to (0.0.0.0 for all)

• web_port (int) – port to serve HTTP/HTTPS webpages on

• ws_port (int) – port to use for websocket communication

• ssl_cert (str) – path to PEM-encoded SSL/TLS cert file for enabling HTTPS

• ssl_key (str) – path to PEM-encoded SSL/TLS cert key for enabling HTTPS

• root (str) – the root directory for serving site files (should have static/ and template/)

• index (str) – the name of the site’s index page (should be under web/templates)

• upload_dir (str) – the path to save files uploaded from client (or None to disable uploads)

• msg_callback (callable) – websocket message handler (see WebServer.on_message() for signature)

• web_trace (bool) – if true, additional debug messages will be printed when –log-level=debug

The kwargs are passed as variables to the Jinja render_template() used in the index file.

start()

Call this to start the webserver listening for new connections. It will start new worker threads and then return control to the user.

property connected

Returns true if the server is connected to any clients, otherwise false.

property num_clients

Returns the number of actively connected clients.

classmethod add_listener(callback)

Register a message handler that will be called when new websocket messages are recieved.

classmethod add_message_handler(callback)

Register a message handler that will be called when new websocket messages are recieved.

on_message(payload, payload_size=None, msg_type=0, msg_id=None, metadata=None, timestamp=None, path=None, **kwargs)

Handler for recieved websocket messages. Implement this in a subclass to process messages, otherwise msg_callback needs to be provided during initialization.

Parameters:

• payload (dict|str|bytes) – If this is a JSON message, will be a dict. If this is a text message, will be a string. If this is a binary message, will be a bytes array.

• payload_size (int) – size of the payload (in bytes)

• msg_type (int) – MESSAGE_JSON (0), MESSAGE_TEXT (1), MESSAGE_BINARY (2)

• msg_id (int) – the monotonically-increasing message ID number

• metadata (str) – message-specific string or other data

• timestamp (int) – time that the message was sent

• path (str) – if this is a file or image upload, the file path on the server

send_message(payload, type=None, timestamp=None)

Send a websocket message to client.