# Broadcaster (Permit fork)
This is a fork of [encode/broadcaster](https://github.com/encode/broadcaster).
----
Broadcaster helps you develop realtime streaming functionality by providing
a simple broadcast API onto a number of different backend services.
It currently supports [Redis PUB/SUB](https://redis.io/topics/pubsub), [Apache Kafka](https://kafka.apache.org/), [Apache Pulsar](https://pulsar.apache.org/) and [Postgres LISTEN/NOTIFY](https://www.postgresql.org/docs/current/sql-notify.html), plus a simple in-memory backend, that you can use for local development or during testing.
<img src="https://raw.githubusercontent.com/encode/broadcaster/master/docs/demo.gif" alt='WebSockets Demo'>
Here's a complete example of the backend code for a simple websocket chat app:
**app.py**
```python
# Requires: `starlette`, `uvicorn`, `jinja2`
# Run with `uvicorn example:app`
from broadcaster import Broadcast
from starlette.applications import Starlette
from starlette.concurrency import run_until_first_complete
from starlette.routing import Route, WebSocketRoute
from starlette.templating import Jinja2Templates
broadcast = Broadcast("redis://localhost:6379")
templates = Jinja2Templates("templates")
async def homepage(request):
template = "index.html"
context = {"request": request}
return templates.TemplateResponse(template, context)
async def chatroom_ws(websocket):
await websocket.accept()
await run_until_first_complete(
(chatroom_ws_receiver, {"websocket": websocket}),
(chatroom_ws_sender, {"websocket": websocket}),
)
async def chatroom_ws_receiver(websocket):
async for message in websocket.iter_text():
await broadcast.publish(channel="chatroom", message=message)
async def chatroom_ws_sender(websocket):
async with broadcast.subscribe(channel="chatroom") as subscriber:
async for event in subscriber:
await websocket.send_text(event.message)
routes = [
Route("/", homepage),
WebSocketRoute("/", chatroom_ws, name='chatroom_ws'),
]
app = Starlette(
routes=routes, on_startup=[broadcast.connect], on_shutdown=[broadcast.disconnect],
)
```
The HTML template for the front end [is available here](https://github.com/encode/broadcaster/blob/master/example/templates/index.html), and is adapted from [Pieter Noordhuis's PUB/SUB demo](https://gist.github.com/pietern/348262).
## Requirements
Python 3.7+
## Installation
* `pip install permit-broadcaster`
* `pip install permit-broadcaster[redis]`
* `pip install permit-broadcaster[pulsar]`
* `pip install permit-broadcaster[postgres]`
* `pip install permit-broadcaster[kafka]`
## Available backends
* `Broadcast('memory://')`
* `Broadcast("redis://localhost:6379")`
* `Broadcast("pulsar://localhost:6650")`
* `Broadcast("postgres://localhost:5432/broadcaster")`
* `Broadcast("kafka://localhost:9092")`
* `Broadcast("kafka://broker_1:9092,broker_2:9092")`
## Kafka environment variables
The following environment variables are exposed to allow SASL authentication with Kafka (along with their default assignment):
```
KAFKA_SECURITY_PROTOCOL=PLAINTEXT # PLAINTEXT, SASL_PLAINTEXT, SASL_SSL
KAFKA_SASL_MECHANISM=PLAIN # PLAIN, SCRAM-SHA-256, SCRAM-SHA-512
KAFKA_PLAIN_USERNAME=None # any str
KAFKA_PLAIN_PASSWORD=None # any str
KAFKA_SSL_CAFILE=None # CA Certificate file path for kafka connection
KAFKA_SSL_CAPATH=None # Path to directory of trusted PEM certificates for kafka connection
KAFKA_SSL_CERTFILE=None # Public Certificate path matching key to use for Kafka connection in PEM format
KAFKA_SSL_KEYFILE=None # Private key path to use for Kafka connection in PEM format
KAFKA_SSL_KEY_PASSWORD=None # Private key password
```
For full details refer to the (AIOKafka options)[https://aiokafka.readthedocs.io/en/stable/api.html#producer-class] where the variable name matches the capitalised env var with an additional `KAFKA_` prefix.
For SSL properties see (AIOKafka SSL Context)[https://aiokafka.readthedocs.io/en/stable/api.html#aiokafka.helpers.create_ssl_context].
## Apache Pulsar
Support for Apache Pulsar, a distributed messaging system, has been added.
To use Pulsar as a backend, ensure you have the necessary package installed:
```bash
pip install permit-broadcaster[pulsar]
```
You will also need a running Pulsar instance. Follow the [official Pulsar installation guide](https://pulsar.apache.org/docs/3.3.x/getting-started-home/) for detailed setup instructions. You can also start Pulsar via Docker using the provided `docker-compose.yaml` file in the repository:
```bash
docker-compose up pulsar
# The same applies for other services...
```
**In the Available backends section, add:**
```python
Broadcast("pulsar://localhost:6650")
```
Ensure you have a Pulsar server running before executing this example.
### Updated Changes
* **Added Pulsar**: Apache Pulsar is now available as a backend in Broadcaster.
## Where next?
At the moment `broadcaster` is in Alpha, and should be considered a working design document.
The API should be considered subject to change. If you *do* want to use Broadcaster in its current
state, make sure to strictly pin your requirements to `broadcaster==0.2.0`.
To be more capable we'd really want to add some additional backends, provide API support for reading recent event history from persistent stores, and provide a serialization/deserialization API...
* Serialization / deserialization to support broadcasting structured data.
* Backends for Redis Streams, Apache Kafka, and RabbitMQ.
* Add support for `subscribe('chatroom', history=100)` for backends which provide persistence. (Redis Streams, Apache Kafka) This will allow applications to subscribe to channel updates, while also being given an initial window onto the most recent events. We *might* also want to support some basic paging operations, to allow applications to scan back in the event history.
* Support for pattern subscribes in backends that support it.
Raw data
{
"_id": null,
"home_page": "https://github.com/permitio/broadcaster",
"name": "permit-broadcaster",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Tom Christie",
"author_email": "tom@tomchristie.com",
"download_url": "https://files.pythonhosted.org/packages/f0/4b/7e826e91a53f61ae546d433dd31de33cd4ff3ae4ec3e03ac3b62483cad56/permit_broadcaster-0.2.6.tar.gz",
"platform": null,
"description": "# Broadcaster (Permit fork)\n\nThis is a fork of [encode/broadcaster](https://github.com/encode/broadcaster).\n\n----\n\nBroadcaster helps you develop realtime streaming functionality by providing\na simple broadcast API onto a number of different backend services.\n\nIt currently supports [Redis PUB/SUB](https://redis.io/topics/pubsub), [Apache Kafka](https://kafka.apache.org/), [Apache Pulsar](https://pulsar.apache.org/) and [Postgres LISTEN/NOTIFY](https://www.postgresql.org/docs/current/sql-notify.html), plus a simple in-memory backend, that you can use for local development or during testing.\n\n<img src=\"https://raw.githubusercontent.com/encode/broadcaster/master/docs/demo.gif\" alt='WebSockets Demo'>\n\nHere's a complete example of the backend code for a simple websocket chat app:\n\n**app.py**\n\n```python\n# Requires: `starlette`, `uvicorn`, `jinja2`\n# Run with `uvicorn example:app`\nfrom broadcaster import Broadcast\nfrom starlette.applications import Starlette\nfrom starlette.concurrency import run_until_first_complete\nfrom starlette.routing import Route, WebSocketRoute\nfrom starlette.templating import Jinja2Templates\n\n\nbroadcast = Broadcast(\"redis://localhost:6379\")\ntemplates = Jinja2Templates(\"templates\")\n\n\nasync def homepage(request):\n template = \"index.html\"\n context = {\"request\": request}\n return templates.TemplateResponse(template, context)\n\n\nasync def chatroom_ws(websocket):\n await websocket.accept()\n await run_until_first_complete(\n (chatroom_ws_receiver, {\"websocket\": websocket}),\n (chatroom_ws_sender, {\"websocket\": websocket}),\n )\n\n\nasync def chatroom_ws_receiver(websocket):\n async for message in websocket.iter_text():\n await broadcast.publish(channel=\"chatroom\", message=message)\n\n\nasync def chatroom_ws_sender(websocket):\n async with broadcast.subscribe(channel=\"chatroom\") as subscriber:\n async for event in subscriber:\n await websocket.send_text(event.message)\n\n\nroutes = [\n Route(\"/\", homepage),\n WebSocketRoute(\"/\", chatroom_ws, name='chatroom_ws'),\n]\n\n\napp = Starlette(\n routes=routes, on_startup=[broadcast.connect], on_shutdown=[broadcast.disconnect],\n)\n```\n\nThe HTML template for the front end [is available here](https://github.com/encode/broadcaster/blob/master/example/templates/index.html), and is adapted from [Pieter Noordhuis's PUB/SUB demo](https://gist.github.com/pietern/348262).\n\n## Requirements\n\nPython 3.7+\n\n## Installation\n\n* `pip install permit-broadcaster`\n* `pip install permit-broadcaster[redis]`\n* `pip install permit-broadcaster[pulsar]`\n* `pip install permit-broadcaster[postgres]`\n* `pip install permit-broadcaster[kafka]`\n\n## Available backends\n\n* `Broadcast('memory://')`\n* `Broadcast(\"redis://localhost:6379\")`\n* `Broadcast(\"pulsar://localhost:6650\")`\n* `Broadcast(\"postgres://localhost:5432/broadcaster\")`\n* `Broadcast(\"kafka://localhost:9092\")`\n* `Broadcast(\"kafka://broker_1:9092,broker_2:9092\")`\n\n\n## Kafka environment variables\n\nThe following environment variables are exposed to allow SASL authentication with Kafka (along with their default assignment):\n\n```\nKAFKA_SECURITY_PROTOCOL=PLAINTEXT # PLAINTEXT, SASL_PLAINTEXT, SASL_SSL\nKAFKA_SASL_MECHANISM=PLAIN # PLAIN, SCRAM-SHA-256, SCRAM-SHA-512\nKAFKA_PLAIN_USERNAME=None # any str\nKAFKA_PLAIN_PASSWORD=None # any str\nKAFKA_SSL_CAFILE=None # CA Certificate file path for kafka connection\nKAFKA_SSL_CAPATH=None # Path to directory of trusted PEM certificates for kafka connection\nKAFKA_SSL_CERTFILE=None # Public Certificate path matching key to use for Kafka connection in PEM format\nKAFKA_SSL_KEYFILE=None # Private key path to use for Kafka connection in PEM format\nKAFKA_SSL_KEY_PASSWORD=None # Private key password\n```\n\nFor full details refer to the (AIOKafka options)[https://aiokafka.readthedocs.io/en/stable/api.html#producer-class] where the variable name matches the capitalised env var with an additional `KAFKA_` prefix.\nFor SSL properties see (AIOKafka SSL Context)[https://aiokafka.readthedocs.io/en/stable/api.html#aiokafka.helpers.create_ssl_context].\n\n\n## Apache Pulsar\n\nSupport for Apache Pulsar, a distributed messaging system, has been added.\n\nTo use Pulsar as a backend, ensure you have the necessary package installed:\n\n```bash\npip install permit-broadcaster[pulsar]\n```\n\nYou will also need a running Pulsar instance. Follow the [official Pulsar installation guide](https://pulsar.apache.org/docs/3.3.x/getting-started-home/) for detailed setup instructions. You can also start Pulsar via Docker using the provided `docker-compose.yaml` file in the repository:\n\n```bash\ndocker-compose up pulsar\n# The same applies for other services...\n```\n\n**In the Available backends section, add:**\n```python\nBroadcast(\"pulsar://localhost:6650\")\n```\n\nEnsure you have a Pulsar server running before executing this example.\n\n### Updated Changes\n* **Added Pulsar**: Apache Pulsar is now available as a backend in Broadcaster.\n\n\n## Where next?\n\nAt the moment `broadcaster` is in Alpha, and should be considered a working design document.\n\nThe API should be considered subject to change. If you *do* want to use Broadcaster in its current\nstate, make sure to strictly pin your requirements to `broadcaster==0.2.0`.\n\nTo be more capable we'd really want to add some additional backends, provide API support for reading recent event history from persistent stores, and provide a serialization/deserialization API...\n\n* Serialization / deserialization to support broadcasting structured data.\n* Backends for Redis Streams, Apache Kafka, and RabbitMQ.\n* Add support for `subscribe('chatroom', history=100)` for backends which provide persistence. (Redis Streams, Apache Kafka) This will allow applications to subscribe to channel updates, while also being given an initial window onto the most recent events. We *might* also want to support some basic paging operations, to allow applications to scan back in the event history.\n* Support for pattern subscribes in backends that support it.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Simple broadcast channels (Permit fork)",
"version": "0.2.6",
"project_urls": {
"Homepage": "https://github.com/permitio/broadcaster"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25db7a156ee891d824e8ce0a7e3a74c3e50c2b32f4b2ea2351d260877077fadf",
"md5": "a8b2d5268edafabb1ff8c200b68481b2",
"sha256": "21abacca84afc4dcaa2a08f7d0afbd9e4e7bbd9f1c3e030a4a64a59ff1c8f301"
},
"downloads": -1,
"filename": "permit_broadcaster-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8b2d5268edafabb1ff8c200b68481b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12431,
"upload_time": "2024-12-15T15:21:26",
"upload_time_iso_8601": "2024-12-15T15:21:26.778165Z",
"url": "https://files.pythonhosted.org/packages/25/db/7a156ee891d824e8ce0a7e3a74c3e50c2b32f4b2ea2351d260877077fadf/permit_broadcaster-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f04b7e826e91a53f61ae546d433dd31de33cd4ff3ae4ec3e03ac3b62483cad56",
"md5": "dbb10b64915a6be2d419db462d65734c",
"sha256": "826449f1f58cfde0545a776c5e5adb67eb6613411264599a7aa78b9324d682f2"
},
"downloads": -1,
"filename": "permit_broadcaster-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "dbb10b64915a6be2d419db462d65734c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13258,
"upload_time": "2024-12-15T15:21:29",
"upload_time_iso_8601": "2024-12-15T15:21:29.564136Z",
"url": "https://files.pythonhosted.org/packages/f0/4b/7e826e91a53f61ae546d433dd31de33cd4ff3ae4ec3e03ac3b62483cad56/permit_broadcaster-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 15:21:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "permitio",
"github_project": "broadcaster",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "permit-broadcaster"
}
JSON
