{"id":24946388,"url":"https://github.com/machinezone/cobra","last_synced_at":"2025-04-10T05:14:48.580Z","repository":{"id":35036654,"uuid":"198926216","full_name":"machinezone/cobra","owner":"machinezone","description":"Cobra is a realtime messaging server using Python3, WebSockets and Redis","archived":false,"fork":false,"pushed_at":"2023-08-01T23:33:24.000Z","size":3312,"stargazers_count":33,"open_issues_count":15,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-06T10:58:12.568Z","etag":null,"topics":["python3","redis","websockets"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/machinezone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-26T01:41:21.000Z","updated_at":"2024-12-08T20:35:43.000Z","dependencies_parsed_at":"2024-11-15T23:36:04.206Z","dependency_job_id":"026494d9-a7f2-4779-bae9-7eab6c609647","html_url":"https://github.com/machinezone/cobra","commit_stats":{"total_commits":506,"total_committers":9,"mean_commits":56.22222222222222,"dds":0.424901185770751,"last_synced_commit":"422df4a3b64052ddd5ab70041038158254c417cd"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinezone%2Fcobra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinezone%2Fcobra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinezone%2Fcobra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/machinezone%2Fcobra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/machinezone","download_url":"https://codeload.github.com/machinezone/cobra/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161278,"owners_count":21057555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python3","redis","websockets"],"created_at":"2025-02-02T20:24:16.998Z","updated_at":"2025-04-10T05:14:48.547Z","avatar_url":"https://github.com/machinezone.png","language":"Python","readme":"# General\n\n[![PyPI version](https://badge.fury.io/py/cobras.svg)](https://badge.fury.io/py/cobras)\n[![Build Status](https://travis-ci.org/machinezone/cobra.svg?branch=master)](https://travis-ci.org/machinezone/cobra)\n[![PyPI Python Versions](https://img.shields.io/pypi/pyversions/cobras.svg)](https://img.shields.io/pypi/pyversions/cobras)\n[![License](https://img.shields.io/pypi/l/cobras.svg)](https://img.shields.io/pypi/l/cobras)\n[![Wheel](https://img.shields.io/pypi/wheel/cobras.svg)](https://img.shields.io/pypi/wheel/cobras)\n[![codecov](https://codecov.io/gh/machinezone/cobra/branch/master/graph/badge.svg)](https://codecov.io/gh/machinezone/cobra)\n\nCobra is a realtime messaging server using Python3, WebSockets and Redis Streams. It was presented in great details during [RedisConf 2019](https://events.redislabs.com/redis-conf/redis-conf-2019/). Since then we've added history support which let cobra retain messages published to a channel that no-one is subscribed to. This makes it easier to blow up your systems through [OOMs](https://en.wikipedia.org/wiki/Out_of_memory) and fill your hard drives, but it makes cobra much more useful.\n\n* [slides](https://bsergean.github.io/redis_conf_2019/slides.html)\n* [youtube](https://www.youtube.com/watch?v=o8CC8qYfRQE\u0026t=147s)\n\n[![Alt text](https://image.slidesharecdn.com/06benjaminsergeant-190507205253/95/real-time-health-analytics-with-websockets-python-3-and-redis-pubsub-benjamin-sergeant-1-638.jpg)](https://www.youtube.com/watch?v=o8CC8qYfRQE)\n\nCobra 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.\n\nThere 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.\n\n* *publish*: send data to a channel, which will be broadcasted to anyone subscribed to that channel\n* *subscribe*: receive events sent to a channel in real time.\n* *write*: record some data (addressed by a key)\n* *read*: retrieve data\n\nInterested ? Go read the [docs](https://machinezone.github.io/cobra/) ! If things don't work as expected, please create an issue in github, or even better a pull request if you know how to fix your problem.\n\n# News\n\nCobra is actively being developed, check out the [changelog](docs/CHANGELOG.md) to know what's cooking.\n\n# Installation\n\n## UNIX one liner\n\n```\n/bin/sh -c \"`curl -fsSL https://raw.githubusercontent.com/machinezone/cobra/master/tools/install.sh`\"\n```\n\nYou can see what the install script is doing first [here](https://github.com/machinezone/cobra/blob/master/tools/install.sh).\n\n## With pip\n\n```\npip install cobras\n```\n\n## With docker\n\n```\ndocker pull bsergean/cobra\n```\n\n## With docker-compose\n\nClone this repo first, then:\n\n```\nmake docker\ndocker-compose up\n```\n\nOr as a one-liner:\n\n```\n(cd /tmp \u0026\u0026 curl -O https://raw.githubusercontent.com/machinezone/cobra/master/docker-compose.yml \u0026\u0026 echo 'DOCKER_REPO=bsergean\\nTAG=latest' \u003e .env \u0026\u0026 docker-compose up)\n```\n\n## For development\n\n```\ngit clone \u003curl\u003e\ncd cobra\npython3 -m venv venv\nsource venv/bin/activate\nmake dev    # please also install redis to execute tests\nmake test\n```\n\n# Usage\n\n## Cobra server and test clients\n\n```\n$ cobra\nUsage: cobra [OPTIONS] COMMAND [ARGS]...\n\n  Cobra is a realtime messaging server using Python3, WebSockets and Redis\n  PubSub.\n\nOptions:\n  --version  Show the version and exit.\n  --help     Show this message and exit.\n\nCommands:\n  admin            Run admin commands.\n  health           Health check\n  init             Setup cobra\n  monitor          Monitor cobra\n  publish          Publish to a channel\n  run              Run the cobra server\n  redis_subscribe  Subscribe to a channel (with redis)\n  subscribe        Subscribe to a channel\n  secret           Generate secrets used for authentication...\n```\n\nTo run the server use `cobra run`. You can run a health-check against the server with `cobra health`.\n\n```\ncobra health --endpoint ws://jeanserge.com --appkey _health --rolesecret A5a3BdEfbc6Df5AAFFcadE7F9Dd7F17E --rolename health\n```\n\n## bavarde\n\n*bavarde* is a chat client that runs against the public cobra server. Bring up 2 terminals, runs the 2 commands below and start typing.\n\n```\n$ bavarde client\n...\n```\n\n```\n$ bavarde client --username bob\n...\n```\n\n\n# Setup\n\n`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.\n\nTo run in production you will need a redis (version \u003e 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.\n\n```\n- name: COBRA_HOST\n  value: 0.0.0.0\n- name: COBRA_REDIS_URLS\n  value: redis://redis1;redis://redis2\n\n# config can be a path to a file\n- name: COBRA_APPS_CONFIG_PATH\n  value: /path/to/your/cobra.yaml\n\n# config can be a blob of gziped + base64 data (if you do not want to mount volumes)\n# Generate it with:\n# `gzip -c ~/.cobra.yaml | base64`\n- name: COBRA_APPS_CONFIG_CONTENT\n  value: BIGBLOGOFDATA\n```\n\n# Users\n\nIf your company or project is using this library, feel free to open an issue or PR to amend this list.\n\n- Machine Zone\n\n# Thank you\n\nThere would be no cobra without some other amazing open-source projects and tech. Here are 3 very remarkable ones.\n\n- [Python](https://www.python.org/) (and [asyncio](https://realpython.com/async-io-python/), one of the killer python3 feature !)\n- [Redis](https://redis.io/), 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).\n- The python [websockets](https://websockets.readthedocs.io/en/stable/intro.html) library, very elegantly implementing the [WebSockets](https://tools.ietf.org/html/rfc6455) protocol using **asyncio**.\n- The python [aioredis](https://aioredis.readthedocs.io/en/v1.2.0/) library used to talk to Redis. This [redis labs](https://redislabs.com/blog/async-await-programming-basics-python-examples/) article explains some pitfalls with asyncio and how to get the best performance out of it.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmachinezone%2Fcobra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmachinezone%2Fcobra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmachinezone%2Fcobra/lists"}