asgi_redis 1.4.3

Usage

You’ll need to instantiate the channel layer with at least hosts, and other options if you need them.

Example:

channel_layer = RedisChannelLayer(
    host="redis",
    db=4,
    channel_capacity={
        "http.request": 200,
        "http.response*": 10,
    }
)

channel_capacity={
    "http.request": 200,
    "http.response!*": 10,
    re.compile(r"^websocket.send\!.+"): 20,
}

pip install asgi_redis[cryptography]

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "asgi_redis.RedisChannelLayer",
        "ROUTING": "my_project.routing.channel_routing",
        "CONFIG": {
            "hosts": ["redis://:password@127.0.0.1:6379/0"],
            "symmetric_encryption_keys": [SECRET_KEY],
        },
    },
}

connection_kwargs

Optional extra arguments to pass to the redis-py connection class. Options include socket_connect_timeout, socket_timeout, socket_keepalive, and socket_keepalive_options. See the redis-py documentation for more.

Local-and-Remote Mode

A “local and remote” mode is also supported, where the Redis channel layer works in conjunction with a machine-local channel layer (asgi_ipc) in order to route all normal channels over the local layer, while routing all single-reader and process-specific channels over the Redis layer.

This allows traffic on things like http.request and websocket.receive to stay in the local layer and not go through Redis, while still allowing Group send and sends to arbitrary channels terminated on other machines to work correctly. It will improve performance and decrease the load on your Redis cluster, but it requires all normal channels are consumed on the same machine.

In practice, this means you MUST run workers that consume every channel your application has code to handle on the same machine as your HTTP or WebSocket terminator. If you fail to do this, requests to that machine will get routed into only the local queue and hang as nothing is reading them.

To use it, just use the asgi_redis.RedisLocalChannelLayer class in your configuration instead of RedisChannelLayer and make sure you have the asgi_ipc package installed; no other change is needed.

Sentinel Mode

“Sentinel” mode is also supported, where the Redis channel layer will connect to a redis sentinel cluster to find the present Redis master before writing or reading data.

Sentinel mode supports sharding, but does not support multiple Sentinel clusters. To run sharding of keys across multiple Redis clusters, use a single sentinel cluster, but have that sentinel cluster monitor multiple “services”. Then in the configuration for the RedisSentinelChannelLayer, add a list of the service names. You can also leave the list of services blank, and the layer will pull all services that are configured on the sentinel master.

Redis Sentinel mode does not support URL-style connection strings, just tuple-based ones.

Configuration for Sentinel mode looks like this:

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "asgi_redis.RedisSentinelChannelLayer",
        "CONFIG": {
            "hosts": [("10.0.0.1", 26739), ("10.0.0.2", 26379), ("10.0.0.3", 26379)],
            "services": ["shard1", "shard2", "shard3"],
        },
    },
}

The “shard1”, “shard2”, etc entries correspond to the name of the service configured in your redis sentinel.conf file. For example, if your sentinel.conf says sentinel monitor local 127.0.0.1 6379 1 then you would want to include “local” as a service in the RedisSentinelChannelLayer configuration.

You may also pass a sentinel_refresh_interval value in the CONFIG, which will enable caching of the Sentinel results for the specified number of seconds. This is recommended to reduce the need to query Sentinel every time; even a low value of 5 seconds will significantly reduce overhead.

Dependencies

Redis >= 2.6 is required for asgi_redis. It supports Python 2.7, 3.4, 3.5 and 3.6.

Contributing

Please refer to the main Channels contributing docs. 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.