score.uws

Module integrating uwebsockets into your SCORE application.

Installation

This package was written to work with libuv, it needs to compile its own version of the uws library. So you will first need to install the development package for libuv and cython:

$ sudo apt install libuv1-dev
$ pip install cython

After that, you can just checkout the desired version and build/install the python package manually using pip:

$ git clone --recurse-submodules https://github.com/score-framework/py.uws score.uws
$ pip install score.uws

Quickstart

Just create an instance of the UwsWorker and add your hooks:

from score.uws import UwsWorker

class PolitePingServer(UwsWorker):

    def prepare(self):
        super().prepare()
        self.hub.add_connect_callback(self.on_connect)
        self.hub.add_message_callback(self.on_message)

    def on_connect(self, client):
        client.send('Hello!')

    def on_message(self, client, message):
        client.send(message)

You can store state information on the client object’s data dict:

from score.uws import UwsWorker

class RudePingServer(UwsWorker):

    def prepare(self):
        super().prepare()
        self.hub.add_connect_callback(self.on_connect)
        self.hub.add_message_callback(self.on_message)

    def on_connect(self, client):
        client.data['counter'] = 0

    def on_message(self, client, message):
        client.send(message)
        client.data['counter'] += 1
        if client.data['counter'] >= 3:
            client.send('Enough! Go bother someone else!')
            client.disconnect()

Afterwards, you can export this worker from your module and update your score.serve configuration to include your module:

class ConfiguredMyApplication(ConfiguredModule):

    # ...

    def score_serve_workers(self):
        return PolitePingServer(self.ws)

[score.init]
modules =
    score.ws  # note: score.ws, not uws!
    myapplication

[serve]
modules =
    myapplication

API

class score.uws.Hub

Representation of the uws hub handling all connections.

add_connect_callback

Register a callable that will be invoked whenever a new connection is received. The callback will just receive a single argument: the connected Client.

add_disconnect_callback

Register a callable that will be invoked whenever a client is disconnected. The callback will receive three arguments: the Client, the numeric code and the message string.

add_message_callback

Register a callable that will be invoked whenever a message is received from a connected client. The callback will receive two arguments: the Client and the message string.

listen

Sets the host and port combination to use when the server starts. This function just configures the server, use start() to start acceping connections.

remove_connect_callback

Removes a previously registered connect callback.

remove_disconnect_callback

Removes a previously registered disconnect callback.

remove_message_callback

Removes a previously registered message callback.

start

Starts the uws server.

stop

Stops the uws server.

stop_listening

The server stops accepting new connections. Existing connections will still be handled. Use stop() to stop the server from frunning the uvloop.

class score.uws.Client

Representation of a uwebsocket client connected to a Hub.

hub

The Hub this client belongs to.

data

A dict that can be used by your applicat6ion to store connection-specific information.