Channelstream

Friendly websocket server for applications

Quickstart

First install python server in your environment:

python3 -m venv channelstream_env
channelstream_env/bin/pip install channelstream>=0.7

You will also need to handle websockets client side, there is a small ES module that can handle this:

npm install @channelstream/channelstream

Generate a fresh config file:

channelstream_env/bin/channelstream_utils make_config -o config.ini

Now you can start the server itself:

channelstream_env/bin/channelstream -i config.ini

The server by default will be acessible on http://localhost:8000 - you can visit API Explorer to test requests locally.

Server defaults:


Communication flow of applications using Channelstream

Before you dive into implementing your first application it is important for you to understand the communication and security model assumed.

The flow:

  1. Client asks your application to if it can perform operation on websocket server
  2. Your application decides if the client can perform said operation (for example connect), passes that information to Channelstream, it is basically a broker.
  3. The server acts based on request from your web application and will execute the operation, for example connect user or fan out messages to all listening clients.

The server is language and framework agnostic - so it does not know nothing about architecture of your applications, It does not perform any authorization for client connections or messaging. Security is handled by your existing backend application.

Users can subscribe to various "channels" - those are separate locations where messages can be routed and can have different properties. For example "notification" channel might not store message history or will not broadcast presence information (joins/parts), this might be opposite for a "chat room" channel.

The server can also store simple state objects associated with users, for example their status or avatar information. Currently there is no persistent storage and it should be treated as ephemeral solution, restart of the server will reset this information. It is normally created on-the-fly upon first request made.

The flow by default is unidirectional - all communication that your clients send goes to your application, authorization and processing is performed there - application sends the final version of the payload to Channelstream and it is then relayed back to all listening clients based on message settings.

For example to start listening for messages you need to obtain connection identifier required for establishing new websocket connections:

You can now connect your first application.