cobras 1.5.3

A realtime messaging server using WebSockets and Redis.

General

Cobra is a realtime messaging server using Python3, WebSockets and Redis Streams. It was presented in great details during RedisConf 2019.

• slides
• youtube

Cobra has been used in production receiving heavy traffic for about a year. Since it was written in Python it was named after a snake as an hommage to a great programming language.

There are 4 operations that a client can execute against a cobra server: publish, subscribe, read and write. publish and subscribe are the 2 operations core to a group-chat. read and write are the typical operations that key value stores (such as memcached), or a python dictionnary provide.

• publish: send data to a channel, which will be broadcasted to anyone subscribed to that channel
• subscribe: receive events sent to a channel in real time.
• write: record some data (addressed by a key)
• read: retrieve data

News

Cobra is actively being developed, check out the changelog to know what's cooking.

Installation

With pip

pip install cobras

With docker

docker pull bsergean/cobra

For development

git clone <url>
cd cobra
python3 -m venv venv
source venv/bin/activate
make dev
make test

Usage

Cobra server and test clients

$ cobra
Usage: cobra [OPTIONS] COMMAND [ARGS]...

  Cobra is a realtime messaging server using Python3, WebSockets and Redis
  PubSub.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  admin            Run admin commands.
  health           Health check
  init             Setup cobra
  monitor          Monitor cobra
  publish          Publish to a channel
  run              Run the cobra server
  redis_subscribe  Subscribe to a channel (with redis)
  subscribe        Subscribe to a channel
  secret           Generate secrets used for authentication...

To run the server use cobra run. You can run a health-check against the server with cobra health.

cobra health --url 'ws://jeanserge.com/v2?appkey=_health' --secret A5a3BdEfbc6Df5AAFFcadE7F9Dd7F17E --role health

bavarde

bavarde is a chat client that runs against the public cobra server. Bring up 2 terminals, runs the 2 commands below and start typing.

$ bavarde client
...

$ bavarde client --username bob
...

Setup

cobras init needs to be run once to generate an app configuration file, in ~/.cobra.yaml. That file contains all the roles, secrets and apps configured. Clients will use this data to authenticate.

To run in production you will need a redis (version > 5) instance. Here are environment variables that you will likely want to tweak, to connect to 2 redis instances (for scalabity), and to bind on 0.0.0.0 so that the internet can see your instance.

- name: COBRA_HOST
  value: 0.0.0.0
- name: COBRA_REDIS_URLS
  value: redis://redis1;redis://redis2

# config can be a path to a file
- name: COBRA_APPS_CONFIG_PATH
  value: /path/to/your/cobra.yaml

# config can be a blob of gziped + base64 data (if you do not want to mount volumes)
# Generate it with:
# `gzip -c ~/.cobra.yaml | base64`
- name: COBRA_APPS_CONFIG_CONTENT
  value: BIGBLOGOFDATA

Thank you

There would be no cobra without some other amazing open-source projects and tech. Here are 3 very remarkable ones.

• Python (and asyncio, one of the killer python3 feature !)
• Redis, the swiss army knife of the internet which provide a very scalable publish/subscribe feature to dispatch messages while retaining them and allowing lookups of old messages (see [Redis Streams] (https://redis.io/topics/streams-intro).
• The python websockets library, very elegantly implementing the WebSockets protocol.