channels_redis
==============
.. image:: https://github.com/django/channels_redis/workflows/Tests/badge.svg
:target: https://github.com/django/channels_redis/actions?query=workflow%3ATests
.. image:: https://img.shields.io/pypi/v/channels_redis.svg
:target: https://pypi.python.org/pypi/channels_redis
Provides Django Channels channel layers that use Redis as a backing store.
There are two available implementations:
* ``RedisChannelLayer`` is the original layer, and implements channel and group
handling itself.
* ``RedisPubSubChannelLayer`` is newer and leverages Redis Pub/Sub for message
dispatch. This layer is currently at *Beta* status, meaning it may be subject
to breaking changes whilst it matures.
Both layers support a single-server and sharded configurations.
`channels_redis` is tested against Python 3.8 to 3.12, `redis-py` versions 4.6,
5.0, and the development branch, and Channels versions 3, 4 and the development
branch there.
Installation
------------
.. code-block::
pip install channels-redis
**Note:** Prior versions of this package were called ``asgi_redis`` and are
still available under PyPI as that name if you need them for Channels 1.x projects.
This package is for Channels 2 projects only.
Usage
-----
Set up the channel layer in your Django settings file like so:
.. code-block:: python
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [("localhost", 6379)],
},
},
}
Or, you can use the alternate implementation which uses Redis Pub/Sub:
.. code-block:: python
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.pubsub.RedisPubSubChannelLayer",
"CONFIG": {
"hosts": [("localhost", 6379)],
},
},
}
Possible options for ``CONFIG`` are listed below.
``hosts``
~~~~~~~~~
The server(s) to connect to, as either URIs, ``(host, port)`` tuples, or dicts conforming to `redis Connection <https://redis-py.readthedocs.io/en/stable/connections.html#async-client>`_.
Defaults to ``redis://localhost:6379``. Pass multiple hosts to enable sharding,
but note that changing the host list will lose some sharded data.
SSL connections that are self-signed (ex: Heroku):
.. code-block:: python
"default": {
"BACKEND": "channels_redis.pubsub.RedisPubSubChannelLayer",
"CONFIG": {
"hosts":[{
"address": "rediss://user@host:port", # "REDIS_TLS_URL"
"ssl_cert_reqs": None,
}]
}
}
Sentinel connections require dicts conforming to:
.. code-block::
{
"sentinels": [
("localhost", 26379),
],
"master_name": SENTINEL_MASTER_SET,
**kwargs
}
note the additional ``master_name`` key specifying the Sentinel master set and any additional connection kwargs can also be passed. Plain Redis and Sentinel connections can be mixed and matched if
sharding.
If your server is listening on a UNIX domain socket, you can also use that to connect: ``["unix:///path/to/redis.sock"]``.
This should be slightly faster than a loopback TCP connection.
``prefix``
~~~~~~~~~~
Prefix to add to all Redis keys. Defaults to ``asgi``. If you're running
two or more entirely separate channel layers through the same Redis instance,
make sure they have different prefixes. All servers talking to the same layer
should have the same prefix, though.
``expiry``
~~~~~~~~~~
Message expiry in seconds. Defaults to ``60``. You generally shouldn't need
to change this, but you may want to turn it down if you have peaky traffic you
wish to drop, or up if you have peaky traffic you want to backlog until you
get to it.
``group_expiry``
~~~~~~~~~~~~~~~~
Group expiry in seconds. Defaults to ``86400``. Channels will be removed
from the group after this amount of time; it's recommended you reduce it
for a healthier system that encourages disconnections. This value should
not be lower than the relevant timeouts in the interface server (e.g.
the ``--websocket_timeout`` to `daphne
<https://github.com/django/daphne>`_).
``capacity``
~~~~~~~~~~~~
Default channel capacity. Defaults to ``100``. Once a channel is at capacity,
it will refuse more messages. How this affects different parts of the system
varies; a HTTP server will refuse connections, for example, while Django
sending a response will just wait until there's space.
``channel_capacity``
~~~~~~~~~~~~~~~~~~~~
Per-channel capacity configuration. This lets you tweak the channel capacity
based on the channel name, and supports both globbing and regular expressions.
It should be a dict mapping channel name pattern to desired capacity; if the
dict key is a string, it's intepreted as a glob, while if it's a compiled
``re`` object, it's treated as a regular expression.
This example sets ``http.request`` to 200, all ``http.response!`` channels
to 10, and all ``websocket.send!`` channels to 20:
.. code-block:: python
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [("localhost", 6379)],
"channel_capacity": {
"http.request": 200,
"http.response!*": 10,
re.compile(r"^websocket.send\!.+"): 20,
},
},
},
}
If you want to enforce a matching order, use an ``OrderedDict`` as the
argument; channels will then be matched in the order the dict provides them.
``symmetric_encryption_keys``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pass this to enable the optional symmetric encryption mode of the backend. To
use it, make sure you have the ``cryptography`` package installed, or specify
the ``cryptography`` extra when you install ``channels-redis``::
pip install channels-redis[cryptography]
``symmetric_encryption_keys`` should be a list of strings, with each string
being an encryption key. The first key is always used for encryption; all are
considered for decryption, so you can rotate keys without downtime - just add
a new key at the start and move the old one down, then remove the old one
after the message expiry time has passed.
Data is encrypted both on the wire and at rest in Redis, though we advise
you also route your Redis connections over TLS for higher security; the Redis
protocol is still unencrypted, and the channel and group key names could
potentially contain metadata patterns of use to attackers.
Keys **should have at least 32 bytes of entropy** - they are passed through
the SHA256 hash function before being used as an encryption key. Any string
will work, but the shorter the string, the easier the encryption is to break.
If you're using Django, you may also wish to set this to your site's
``SECRET_KEY`` setting via the ``CHANNEL_LAYERS`` setting:
.. code-block:: python
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": ["redis://:password@127.0.0.1:6379/0"],
"symmetric_encryption_keys": [SECRET_KEY],
},
},
}
``on_disconnect`` / ``on_reconnect``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The PubSub layer, which maintains long-running connections to Redis, can drop messages in the event of a network partition.
To handle such situations the PubSub layer accepts optional arguments which will notify consumers of Redis disconnect/reconnect events.
A common use-case is for consumers to ensure that they perform a full state re-sync to ensure that no messages have been missed.
.. code-block:: python
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.pubsub.RedisPubSubChannelLayer",
"CONFIG": {
"hosts": [...],
"on_disconnect": "redis.disconnect",
},
},
}
And then in your channels consumer, you can implement the handler:
.. code-block:: python
async def redis_disconnect(self, *args):
# Handle disconnect
Dependencies
------------
Redis server >= 5.0 is required for `channels-redis`. Python 3.8 or higher is required.
Used commands
~~~~~~~~~~~~~
Your Redis server must support the following commands:
* ``RedisChannelLayer`` uses ``BZPOPMIN``, ``DEL``, ``EVAL``, ``EXPIRE``,
``KEYS``, ``PIPELINE``, ``ZADD``, ``ZCOUNT``, ``ZPOPMIN``, ``ZRANGE``,
``ZREM``, ``ZREMRANGEBYSCORE``
* ``RedisPubSubChannelLayer`` uses ``PUBLISH``, ``SUBSCRIBE``, ``UNSUBSCRIBE``
Local Development
-----------------
You can run the necessary Redis instances in Docker with the following commands:
.. code-block:: shell
$ docker network create redis-network
$ docker run --rm \
--network=redis-network \
--name=redis-server \
-p 6379:6379 \
redis
$ docker run --rm \
--network redis-network \
--name redis-sentinel \
-e REDIS_MASTER_HOST=redis-server \
-e REDIS_MASTER_SET=sentinel \
-e REDIS_SENTINEL_QUORUM=1 \
-p 26379:26379 \
bitnami/redis-sentinel
Contributing
------------
Please refer to the
`main Channels contributing docs <https://github.com/django/channels/blob/master/CONTRIBUTING.rst>`_.
That also contains advice on how to set up the development environment and run the tests.
Maintenance and Security
------------------------
To report security issues, please contact security@djangoproject.com. For GPG
signatures and more security process information, see
https://docs.djangoproject.com/en/dev/internals/security/.
To report bugs or request new features, please open a new GitHub issue.
This repository is part of the Channels project. For the shepherd and maintenance team, please see the
`main Channels readme <https://github.com/django/channels/blob/master/README.rst>`_.
Raw data
{
"_id": null,
"home_page": "http://github.com/django/channels_redis/",
"name": "channels-redis",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Django Software Foundation",
"author_email": "foundation@djangoproject.com",
"download_url": "https://files.pythonhosted.org/packages/fd/c8/d8e4d369a4cbce5dc86e84a559993001d471327f1ef57c13ffc82bdc9efa/channels_redis-4.2.0.tar.gz",
"platform": null,
"description": "channels_redis\n==============\n\n.. image:: https://github.com/django/channels_redis/workflows/Tests/badge.svg\n :target: https://github.com/django/channels_redis/actions?query=workflow%3ATests\n\n.. image:: https://img.shields.io/pypi/v/channels_redis.svg\n :target: https://pypi.python.org/pypi/channels_redis\n\nProvides Django Channels channel layers that use Redis as a backing store.\n\nThere are two available implementations:\n\n* ``RedisChannelLayer`` is the original layer, and implements channel and group\n handling itself.\n* ``RedisPubSubChannelLayer`` is newer and leverages Redis Pub/Sub for message\n dispatch. This layer is currently at *Beta* status, meaning it may be subject\n to breaking changes whilst it matures.\n\nBoth layers support a single-server and sharded configurations.\n\n`channels_redis` is tested against Python 3.8 to 3.12, `redis-py` versions 4.6,\n5.0, and the development branch, and Channels versions 3, 4 and the development\nbranch there.\n\nInstallation\n------------\n\n.. code-block::\n\n pip install channels-redis\n\n**Note:** Prior versions of this package were called ``asgi_redis`` and are\nstill available under PyPI as that name if you need them for Channels 1.x projects.\nThis package is for Channels 2 projects only.\n\n\nUsage\n-----\n\nSet up the channel layer in your Django settings file like so:\n\n.. code-block:: python\n\n CHANNEL_LAYERS = {\n \"default\": {\n \"BACKEND\": \"channels_redis.core.RedisChannelLayer\",\n \"CONFIG\": {\n \"hosts\": [(\"localhost\", 6379)],\n },\n },\n }\n\nOr, you can use the alternate implementation which uses Redis Pub/Sub:\n\n.. code-block:: python\n\n CHANNEL_LAYERS = {\n \"default\": {\n \"BACKEND\": \"channels_redis.pubsub.RedisPubSubChannelLayer\",\n \"CONFIG\": {\n \"hosts\": [(\"localhost\", 6379)],\n },\n },\n }\n\nPossible options for ``CONFIG`` are listed below.\n\n``hosts``\n~~~~~~~~~\n\nThe server(s) to connect to, as either URIs, ``(host, port)`` tuples, or dicts conforming to `redis Connection <https://redis-py.readthedocs.io/en/stable/connections.html#async-client>`_.\nDefaults to ``redis://localhost:6379``. Pass multiple hosts to enable sharding,\nbut note that changing the host list will lose some sharded data.\n\nSSL connections that are self-signed (ex: Heroku):\n\n.. code-block:: python\n\n \"default\": {\n \"BACKEND\": \"channels_redis.pubsub.RedisPubSubChannelLayer\",\n \"CONFIG\": {\n \"hosts\":[{\n \"address\": \"rediss://user@host:port\", # \"REDIS_TLS_URL\"\n \"ssl_cert_reqs\": None,\n }]\n }\n }\n\nSentinel connections require dicts conforming to:\n\n.. code-block::\n\n {\n \"sentinels\": [\n (\"localhost\", 26379),\n ],\n \"master_name\": SENTINEL_MASTER_SET,\n **kwargs\n }\n\nnote the additional ``master_name`` key specifying the Sentinel master set and any additional connection kwargs can also be passed. Plain Redis and Sentinel connections can be mixed and matched if\nsharding.\n\nIf your server is listening on a UNIX domain socket, you can also use that to connect: ``[\"unix:///path/to/redis.sock\"]``.\nThis should be slightly faster than a loopback TCP connection.\n\n``prefix``\n~~~~~~~~~~\n\nPrefix to add to all Redis keys. Defaults to ``asgi``. If you're running\ntwo or more entirely separate channel layers through the same Redis instance,\nmake sure they have different prefixes. All servers talking to the same layer\nshould have the same prefix, though.\n\n``expiry``\n~~~~~~~~~~\n\nMessage expiry in seconds. Defaults to ``60``. You generally shouldn't need\nto change this, but you may want to turn it down if you have peaky traffic you\nwish to drop, or up if you have peaky traffic you want to backlog until you\nget to it.\n\n``group_expiry``\n~~~~~~~~~~~~~~~~\n\nGroup expiry in seconds. Defaults to ``86400``. Channels will be removed\nfrom the group after this amount of time; it's recommended you reduce it\nfor a healthier system that encourages disconnections. This value should\nnot be lower than the relevant timeouts in the interface server (e.g.\nthe ``--websocket_timeout`` to `daphne\n<https://github.com/django/daphne>`_).\n\n``capacity``\n~~~~~~~~~~~~\n\nDefault channel capacity. Defaults to ``100``. Once a channel is at capacity,\nit will refuse more messages. How this affects different parts of the system\nvaries; a HTTP server will refuse connections, for example, while Django\nsending a response will just wait until there's space.\n\n``channel_capacity``\n~~~~~~~~~~~~~~~~~~~~\n\nPer-channel capacity configuration. This lets you tweak the channel capacity\nbased on the channel name, and supports both globbing and regular expressions.\n\nIt should be a dict mapping channel name pattern to desired capacity; if the\ndict key is a string, it's intepreted as a glob, while if it's a compiled\n``re`` object, it's treated as a regular expression.\n\nThis example sets ``http.request`` to 200, all ``http.response!`` channels\nto 10, and all ``websocket.send!`` channels to 20:\n\n.. code-block:: python\n\n CHANNEL_LAYERS = {\n \"default\": {\n \"BACKEND\": \"channels_redis.core.RedisChannelLayer\",\n \"CONFIG\": {\n \"hosts\": [(\"localhost\", 6379)],\n \"channel_capacity\": {\n \"http.request\": 200,\n \"http.response!*\": 10,\n re.compile(r\"^websocket.send\\!.+\"): 20,\n },\n },\n },\n }\n\nIf you want to enforce a matching order, use an ``OrderedDict`` as the\nargument; channels will then be matched in the order the dict provides them.\n\n``symmetric_encryption_keys``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPass this to enable the optional symmetric encryption mode of the backend. To\nuse it, make sure you have the ``cryptography`` package installed, or specify\nthe ``cryptography`` extra when you install ``channels-redis``::\n\n pip install channels-redis[cryptography]\n\n``symmetric_encryption_keys`` should be a list of strings, with each string\nbeing an encryption key. The first key is always used for encryption; all are\nconsidered for decryption, so you can rotate keys without downtime - just add\na new key at the start and move the old one down, then remove the old one\nafter the message expiry time has passed.\n\nData is encrypted both on the wire and at rest in Redis, though we advise\nyou also route your Redis connections over TLS for higher security; the Redis\nprotocol is still unencrypted, and the channel and group key names could\npotentially contain metadata patterns of use to attackers.\n\nKeys **should have at least 32 bytes of entropy** - they are passed through\nthe SHA256 hash function before being used as an encryption key. Any string\nwill work, but the shorter the string, the easier the encryption is to break.\n\nIf you're using Django, you may also wish to set this to your site's\n``SECRET_KEY`` setting via the ``CHANNEL_LAYERS`` setting:\n\n.. code-block:: python\n\n CHANNEL_LAYERS = {\n \"default\": {\n \"BACKEND\": \"channels_redis.core.RedisChannelLayer\",\n \"CONFIG\": {\n \"hosts\": [\"redis://:password@127.0.0.1:6379/0\"],\n \"symmetric_encryption_keys\": [SECRET_KEY],\n },\n },\n }\n\n``on_disconnect`` / ``on_reconnect``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe PubSub layer, which maintains long-running connections to Redis, can drop messages in the event of a network partition.\nTo handle such situations the PubSub layer accepts optional arguments which will notify consumers of Redis disconnect/reconnect events.\nA common use-case is for consumers to ensure that they perform a full state re-sync to ensure that no messages have been missed.\n\n.. code-block:: python\n\n CHANNEL_LAYERS = {\n \"default\": {\n \"BACKEND\": \"channels_redis.pubsub.RedisPubSubChannelLayer\",\n \"CONFIG\": {\n \"hosts\": [...],\n \"on_disconnect\": \"redis.disconnect\",\n },\n },\n }\n\n\nAnd then in your channels consumer, you can implement the handler:\n\n.. code-block:: python\n\n async def redis_disconnect(self, *args):\n # Handle disconnect\n\nDependencies\n------------\n\nRedis server >= 5.0 is required for `channels-redis`. Python 3.8 or higher is required.\n\n\nUsed commands\n~~~~~~~~~~~~~\n\nYour Redis server must support the following commands:\n\n* ``RedisChannelLayer`` uses ``BZPOPMIN``, ``DEL``, ``EVAL``, ``EXPIRE``,\n ``KEYS``, ``PIPELINE``, ``ZADD``, ``ZCOUNT``, ``ZPOPMIN``, ``ZRANGE``,\n ``ZREM``, ``ZREMRANGEBYSCORE``\n\n* ``RedisPubSubChannelLayer`` uses ``PUBLISH``, ``SUBSCRIBE``, ``UNSUBSCRIBE``\n\nLocal Development\n-----------------\n\nYou can run the necessary Redis instances in Docker with the following commands:\n\n.. code-block:: shell\n\n $ docker network create redis-network\n $ docker run --rm \\\n --network=redis-network \\\n --name=redis-server \\\n -p 6379:6379 \\\n redis\n $ docker run --rm \\\n --network redis-network \\\n --name redis-sentinel \\\n -e REDIS_MASTER_HOST=redis-server \\\n -e REDIS_MASTER_SET=sentinel \\\n -e REDIS_SENTINEL_QUORUM=1 \\\n -p 26379:26379 \\\n bitnami/redis-sentinel\n\nContributing\n------------\n\nPlease refer to the\n`main Channels contributing docs <https://github.com/django/channels/blob/master/CONTRIBUTING.rst>`_.\nThat also contains advice on how to set up the development environment and run the tests.\n\nMaintenance and Security\n------------------------\n\nTo report security issues, please contact security@djangoproject.com. For GPG\nsignatures and more security process information, see\nhttps://docs.djangoproject.com/en/dev/internals/security/.\n\nTo report bugs or request new features, please open a new GitHub issue.\n\nThis repository is part of the Channels project. For the shepherd and maintenance team, please see the\n`main Channels readme <https://github.com/django/channels/blob/master/README.rst>`_.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Redis-backed ASGI channel layer implementation",
"version": "4.2.0",
"project_urls": {
"Homepage": "http://github.com/django/channels_redis/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "11df7638755c3adc8463a872562082c66737d1b7d754c2040a2ddfe3c8800f67",
"md5": "32258e4c6410e4a94ebedc7341433180",
"sha256": "2c5b944a39bd984b72aa8005a3ae11637bf29b5092adeb91c9aad4ab819a8ac4"
},
"downloads": -1,
"filename": "channels_redis-4.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32258e4c6410e4a94ebedc7341433180",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18419,
"upload_time": "2024-01-12T14:28:03",
"upload_time_iso_8601": "2024-01-12T14:28:03.982042Z",
"url": "https://files.pythonhosted.org/packages/11/df/7638755c3adc8463a872562082c66737d1b7d754c2040a2ddfe3c8800f67/channels_redis-4.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fdc8d8e4d369a4cbce5dc86e84a559993001d471327f1ef57c13ffc82bdc9efa",
"md5": "e43a397dd3049f382a9c8b91d0f62c79",
"sha256": "01c26c4d5d3a203f104bba9e5585c0305a70df390d21792386586068162027fd"
},
"downloads": -1,
"filename": "channels_redis-4.2.0.tar.gz",
"has_sig": false,
"md5_digest": "e43a397dd3049f382a9c8b91d0f62c79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20754,
"upload_time": "2024-01-12T14:28:05",
"upload_time_iso_8601": "2024-01-12T14:28:05.461136Z",
"url": "https://files.pythonhosted.org/packages/fd/c8/d8e4d369a4cbce5dc86e84a559993001d471327f1ef57c13ffc82bdc9efa/channels_redis-4.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-12 14:28:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "django",
"github_project": "channels_redis",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "channels-redis"
}
JSON
