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:

• API secret: secret
• Admin user: admin
• Admin secret: admin_secret
• Accepts API requests from: 127.0.0.1
• HTTP port: 8000
• listens on all interfaces

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:

• Send a JSON request to your application, telling the server that user wants to connect to a channel called "/tutorial" - here is where authentication and authorization happens, if your application decides user can connect it should make a signed request to /connect endpoint of the server informing it who connects and to what channels.
• Grab the response from the server - it will contain current state of user (it is created if user was connecting for the first time), state of channels that user connected to, and a connection UUID.
• Return the connection UUID back to browser client
• Client uses UUID to connect to a websocket or long polling endpoint