Django Channels

Django Channels augments Django to provide support for asynchronous protocols and tasks, including:

• WebSockets
• Long-poll HTTP
• Task offloading
• Other async support

It uses familiar Django design patterns and a flexible framework that allows for customizing behaviors or writing support for custom protocols.

You can use channel layers to offload work to worker servers listening on fixed channel names, acting as a simple, low-latency task queue.

Important Considerations:

• Delivery Guarantees: This system provides at-most-once delivery. It does not support retries or return values. For tasks requiring high reliability or guarantees, use a dedicated task queue.
• Compatibility: This feature does not work with the in-memory channel layer.
• Setup: Implementation requires two parts: sending events to a fixed channel name and setting up consumers to receive them.

ASGI (Asynchronous Server Gateway Interface) is the specification that Django Channels is built upon. An ASGI application is defined as a single asynchronous callable that accepts three arguments: scope (a dictionary defining connection properties), receive (an awaitable to receive events), and send (an awaitable to send events).

Applications are instantiated once per scope (e.g., once per HTTP request or once per WebSocket connection). The scope dictionary always contains a type key which identifies the protocol being used.

async def application(scope, receive, send):
    event = await receive()
    ...
    await send({"type": "websocket.send", ...})

Channels and ASGI operate using two core concepts: scopes and events.

• Scope: A set of details about a single incoming connection (e.g., path, IP address, user ID). The scope persists for the lifetime of the connection. For HTTP, the scope lasts for a single request; for WebSockets, it lasts for the duration of the socket connection.
• Events: User interactions that occur during the lifetime of a scope (e.g., an HTTP request, a WebSocket frame, or a chat message).

Your Channels application is instantiated once per scope and is fed a stream of events to process.

Django Channels is composed of several distinct packages that work together:

• Channels: The core Django integration layer.
• Daphne: The HTTP and WebSocket termination server.
• asgiref: The base ASGI library.
• channels_redis: An optional Redis channel layer backend for managing communication between different parts of your application.

Unlike HTTP consumers where sessions are saved automatically on non-500 responses, WebSocket consumers do not automatically save session changes.

To persist changes made to the session during a WebSocket connection, you must manually call the save method:

• For synchronous consumers: scope["session"].save()
• For asynchronous consumers: scope["session"].asave()

If you do not call these methods, changes will be available within the current consumer instance but will not be persisted to the session store for other connections or HTTP views.

To set up a local development environment for Channels, fork and clone the repository, then install the package in editable mode with the necessary test and Daphne dependencies.

Note for zsh users: If you encounter a zsh: no matches found: .[tests] error, use noglob to prevent shell globbing issues.