channels

4.3.0 Release Notes

Channels 4.3 is a maintenance release in the 4.x series.

Bugfixes & Small Changes

• Updated asgiref dependency to v3.9+.

  The ApplicationCommunicator testing utility will now return its result if the application is finished when sending input. Assert the CancelledError` rather than allowing a timeout in your tests if you're affected by this change.

• Dropped support for EOL Python and Django versions. Python 3.9 is now the minimum supported version.

• Fixed compatibility of ChannelsLiveServerTestCase with Django 5.2.

• Fixed DB setup for spawned testing subprocess, typically on Windows and macOS.

4.2.2 Release Notes

Channels 4.2.2 is a bugfix release in the 4.2 series.

Bugfixes & Small Changes

• Added fallbacks for old valid channel/group name checks.

  These (internal) methods were renamed in v4.2.1 without deprecation. This release adds (deprecated) fallback aliases to allow time for channel layers to update.

4.2.1 Release Notes

Channels 4.2.1 is a bugfix release in the 4.2 series.

Bugfixes & Small Changes

• Added official support for Django 5.2 LTS.

• Added official support for Python 3.13.

• Added a warning for the length of the channel layer group names.

4.2.0 Release Notes

Channels 4.2 introduces a couple of major but backwards-compatible changes, including most notably enhanced async support and fixing a long-standing bug where tests would try and close db connections and erroneously fail.

Additionally, support has been added for Django 5.1.

Enhanced Async Support

Support for asynchronous consumers has been greatly improved. The documentation has been updated to reflect the async ORM features added in Django 4.2. A new channels.db.aclose_old_connections function has been added to easily close old database connections in async consumers.

Warning: Channels now automatically closes connections in async consumers before a new connection, after receiving message (but before dispatching to consumer code), and after disconnecting.

This change has been made to more closely align with Django's request/response cycle, and to help users avoid attempting to use stale/broken connections.

Notably, Channels does NOT close connections before or after a consumer sends data. This is to avoid database churn and more closely align with user expectations. Instead, users are expected to call aclose_old_connections occasionally during long-lived async connections.

Additionally, channels will automatically use the new async interface for sessions if Django 5.1 or greater is installed. This new interface can be slightly faster in certain cases as it does not always need to context-switch into synchronous execution. This does require a backwards-incompatible change to channels.sessions.InstanceSessionWrapper: the save_session function is now async. If InstanceSessionWrapper was being subclassed in some way (note that this class is an implementation detail and not documented) and save_session was being called or overridden, it will need to be updated to be called with await or defined as async, respectively.

Bugfixes & Small Changes

• InMemoryChannelLayer has been greatly improved: it now honors expiry times and per-channel capacities, has parallel sending and a safer internal implementation. Note: queue capacities can no longer be changed after a channel has been created.

  Thanks to @devkral (Alexander)

• Database connections are no longer closed inside tests, which prevents erroneous "Cannot operate on a closed database" errors when running tets.

  Thanks to Jon Janzen.

• An old import override and an unused deprecation message were removed

  Thanks to @sevdog (Devid) and Jon Janzen.

• WebsocketCommunicator now has informative assert error messages

  Thanks to Karel Hovorka.

• WebsocketConsumer now checks that "text" is not None before attempting to use it. This improves support for Hypercorn.

  Thanks to Joaquín Ossandon.

• BaseChannelLayer now has prototypes on all its methods to improve the hit-rate for smart autocompleters when users need to author their own channel layer and need to implement all required methods.

  Thanks to Jophy Ye.

4.1.0 Release Notes

Channels 4.1 is maintenance release in the 4.x series.

Python and Django support

• A Python version of 3.8 or higher is required.

• Django 4.2 is now the minimum supported version.

Bugfixes & Small Changes

• Exceptions in HttpConsumer are now correctly propagated.

  Thanks to Adam Johnson.

• URLRouter is updated for compatibility with in-development changes in Django.

  Thanks to Adam Johnson.

• URLRouter is updated to correctly handle root_path.

  Thanks to Alejandro R. Sedeño.

• Websocket consumers are updated for newer ASGI spec versions, adding the headers parameter for the accept event, and reason for the close event.

  Thanks to Kristján Valur Jónsson.

4.0.0 Release Notes

Channels 4 is the next major version of the Channels package. Together with the matching Daphne v4 and channels-redis v4 releases, it updates dependencies, fixes issues, and removes outdated code. It so provides the foundation for Channels development going forward.

In most cases, you can update now by updating channels, daphne, and channels-redis as appropriate, with pip, and by adding daphne at the top of your INSTALLED_APPS setting.

First pip:

pip install -U 'channels[daphne]' channels-redis

Then in your Django settings file:

INSTALLED_APPS = [
    "daphne",
    ...
]

Read on for the details.

Updated Python and Django support

In general Channels will try to follow Python and Django supported versions.

As of release, that means Python 3.7, 3.8, 3.9, and 3.10, as well as Django 3.2, 4.0, and 4.1 are currently supported.

As a note, we reserve the right to drop older Python versions, or the older Django LTS, once the newer one is released, before their official end-of-life if this is necessary to ease development.

Dropping older Python and Django versions will be done in minor version releases, and will not be considered to require a major version change.

The async support in both Python and Django continues to evolve rapidly. We advise you to always upgrade to the latest versions in order to avoid issues in older versions if you're building an async application.

• Dropped support for Python 3.6.

• Minimum Django version is now Django 3.2.

• Added compatibility with Django 4.1.

Decoupling of the Daphne application server

In order to allow users of other ASGI servers to use Channels without the overhead of Daphne and Twisted, the Daphne application server is now an optional dependency, installable either directly or with the daphne extra, as per the pip example above.

• Where Daphne is used daphne>=4.0.0 is required. The channels[daphne] extra assures this.

• The runserver command is moved to the daphne package.

  In order to use the runserver command, add daphne to your INSTALLED_APPS, before django.contrib.staticfiles:

  INSTALLED_APPS = [
      "daphne",
      ...
  ]

  There is a new system check to ensure this ordering.

  Note, the runworker command remains a part of the channels app.

• Use of ChannelsLiveServerTestCase still requires Daphne.

Removal of the Django application wrappers

In order to add initial ASGI support to Django, Channels originally provided tools for wrapping your Django application and serving it under ASGI. This included an ASGI handler class, an ASGI HTTP request object, and an ASGI compatible version of the staticfiles handler for use with runserver

Improved equivalents to all of these are what has been added to Django since Django version 3.0. As such serving of Django HTTP applications (whether using sync or async views) under ASGI is now Django's responsibility, and the matching Channels classes have been removed.

Use of these classes was deprecated in Channels v3 and, if you've already moved to the Django equivalents there is nothing further to do.

• Removed deprecated static files handling in favor of django.contrib.staticfiles.

• Removed the deprecated AsgiHandler, which wrapped Django views, in favour of Django's own ASGI support. You should use Django's get_asgi_application to provide the http handler for ProtocolTypeRouter, or an appropriate path for URLRouter, in order to route your Django application.

• The supporting AsgiRequest is also removed, as it was only used for AsgiHandler.

• Removed deprecated automatic routing of http protocol handler in ProtocolTypeRouter. You must explicitly register the http handler in your application if using ProtocolTypeRouter.

The minimal asgi.py file routing the Django ASGI application under a ProtocolTypeRouter will now look something like this:

import os

from channels.routing import ProtocolTypeRouter
from django.core.asgi import get_asgi_application

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
})

i.e. We use Django's get_asgi_application(), and explicitly route an http handler for ProtocolTypeRouter. This is merely for illustration of the changes. Please see the docs for more complete examples.

Other changes

• The use of the guarantee_single_callable() compatibility shim is removed. All applications must be ASGI v3 single-callables.

• Removed the consumer_started and consumer_finished signals, unused since the 2.0 rewrite.

• Fixed ChannelsLiveServerTestCase when running on systems using the spawn multiprocessing start method, such as macOS and Windows.

3.0.5 Release Notes

Channels 3.0.5 is a bugfix release in the 3.0 series.

Bugfixes & Small Changes

• Removed use of providing_args keyword argument to consumer started signal, as support for this was removed in Django 4.0.

Backwards Incompatible Changes

• Drops support for end-of-life Python 3.6 and Django 3.0 and 3.1.

3.0.4 Release Notes

Channels 3.0.4 is a bugfix release in the 3.0 series.

Bugfixes & Small Changes

• Usage of urlparse in OriginValidator is corrected to maintain compatibility with recent point-releases of Python.

• The import of django.contrib.auth.models.AnonymousUser in channels.auth is deferred until runtime, in order to avoid errors if AuthMiddleware or AuthMiddlewareStack were imported before django.setup() was run.

• CookieMiddleware adds support for the samesite flag.

• WebsocketConsumer.init() and AsyncWebsocketConsumer.init() no longer make a bad super() call to object.init().

Backwards Incompatible Changes

None.

3.0.3 Release Notes

Channels 3.0.3 fixes a security issue in Channels 3.0.2

CVE-2020-35681: Potential leakage of session identifiers using legacy AsgiHandler

The legacy channels.http.AsgiHandler class, used for handling HTTP type requests in an ASGI environment prior to Django 3.0, did not correctly separate request scopes in Channels 3.0. In many cases this would result in a crash but, with correct timing responses could be sent to the wrong client, resulting in potential leakage of session identifiers and other sensitive data.

This issue affects Channels 3.0.x before 3.0.3, and is resolved in Channels 3.0.3.

Users of ProtocolTypeRouter not explicitly specifying the handler for the 'http' key, or those explicitly using channels.http.AsgiHandler, likely to support Django v2.2, are affected and should update immediately.

Note that both an unspecified handler for the 'http' key and using channels.http.AsgiHandler are deprecated, and will raise a warning, from Channels v3.0.0

This issue affects only the legacy channels provided class, and not Django's similar ASGIHandler, available from Django 3.0. It is recommended to update to Django 3.0+ and use the Django provided ASGIHandler.

A simplified asgi.py script will look like this:

import os

from django.core.asgi import get_asgi_application

# Fetch Django ASGI application early to ensure AppRegistry is populated
# before importing consumers and AuthMiddlewareStack that may import ORM
# models.
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
django_asgi_app = get_asgi_application()

# Import other Channels classes and consumers here.
from channels.routing import ProtocolTypeRouter, URLRouter

application = ProtocolTypeRouter({
    # Explicitly set 'http' key using Django's ASGI application.
    "http": django_asgi_app,
    ),
})

Please see /deploying for a more complete example.

3.0.2 Release Notes

Channels 3.0.2 fixes a bug in Channels 3.0.1

Bugfixes

• Fixes a bug in Channels 3.0 where StaticFilesWrapper was not updated to the ASGI 3 single-callable interface.

• Users of the runworker command should ensure to update asgiref to version 3.3.1 or later, where an issue in asgiref.server.StatelessServer was addressed.

3.0.1 Release Notes

Channels 3.0.1 fixes a bug in Channels 3.0.

Bugfixes

• Fixes a bug in Channels 3.0 where SessionMiddleware would not correctly isolate per-instance scopes.

3.0.0 Release Notes

The Channels 3 update brings Channels into line with Django's own async ASGI support, introduced with Django 3.0.

Channels now integrates with Django's async HTTP handling, whilst continuing to support WebSockets and other exciting consumer types.

Channels 3 supports Django 3.x and beyond, as well continuing to support the Django 2.2 LTS. We will support Django 2.2 at least until the Django 3.2 LTS is released, yet may drop support after that, but before Django 2.2 is officially end-of-life.

Likewise, we support Python 3.6+ but we strongly advise you to update to the latest Python versions, so 3.9 at the time of release.

In both our Django and Python support, we reflect the reality that async Python and async Django are still both evolving rapidly. Many issues we see simply disappear if you update. Whatever you are doing with async, you should make sure you're on the latest versions.

The highlight of this release is the upgrade to ASGI v3, which allows integration with Django's ASGI support. There are also two additional deprecations that you will need to deal with if you are updating an existing application.

Update to ASGI 3

• Consumers are now ASGI 3 single-callables with the signature:

  application(scope, receive, send)

  For generic consumers this change should be largely transparent, but you will need to update __init__() (no longer taking the scope) and __call__() (now taking the scope) if you implemented these yourself.

• Consumers now have an as_asgi() class method you need to call when setting up your routing:

  websocket_urlpatterns = [
      re_path(r'ws/chat/(?P<room_name>\w+)/$', consumers.ChatConsumer.as_asgi()),
  ]

  This returns an ASGI application that will instantiate the consumer per-request. It's similar to Django's as_view(), which serves the same purpose. You can pass in keyword arguments for initialization if your consumer requires them.

• Middleware will also need to be updated to the ASGI v3 signature. The channels.middleware.BaseMiddleware class is simplified, and available as an example. You probably don't need to actually subclass it under ASGI 3.

Deprecations

• Using ProtocolTypeRouter without an explicit "http" key is now deprecated.

  Following Django conventions, your entry point script should be named asgi.py, and you should use Django's get_asgi_application(), that is used by Django's default asgi.py template to route the "http" handler:

  from django.core.asgi import get_asgi_application
  
  application = ProtocolTypeRouter({
      "http": get_asgi_application(),
      # Other protocols here.
  })

  Once the deprecation is removed, when we drop support for Django 2.2, not specifying an "http" key will mean that your application will not handle HTTP requests.

• The Channels built-in HTTP protocol AsgiHandler is also deprecated. You should update to Django 3.0 or higher and use Django's get_asgi_application(). Channel's AsgiHandler will be removed when we drop support for Django 2.2.

2.4.0 Release Notes

Channels 2.4 brings compatibility with Django 3.0s async_unsafe() checks. (Specifically we ensure session save calls are made inside an asgiref database_sync_to_async().)

If you are using Daphne, it is recommended that you install Daphne version 2.4.1 or later for full compatibility with Django 3.0.

Backwards Incompatible Changes

In line with the guidance provided by Django's supported versions policy we now also drop support for all Django versions before 2.2, which is the current LTS.

2.3.0 Release Notes

Channels 2.3.0 updates the AsgiHandler HTTP request body handling to use a spooled temporary file, rather than reading the whole request body into memory.

This significantly reduces the maximum memory requirements when serving Django views, and protects from DoS attacks, whilst still allowing large file uploads — a combination that had previously been difficult.

Many thanks to Ivan Ergunov for his work on the improvements! 🎩

Backwards Incompatible Changes

As a result of the reworked body handling, AsgiRequest.__init__() is adjusted to expect a file-like stream, rather than the whole body as bytes.

Test cases instantiating requests directly will likely need to be updated to wrap the provided body in, e.g., io.BytesIO.

Next Up...

We're looking to address a few issues around AsyncHttpConsumer. Any human-power available to help on that, truly appreciated. 🙂

2.2.0 Release Notes

Channels 2.2.0 updates the requirements for ASGI version 3, and the supporting Daphne v2.3 release.

Backwards Incompatible Changes

None.

2.1.7 Release Notes

Channels 2.1.7 is another bugfix release in the 2.1 series, and the last release (at least for a long while) with Andrew Godwin as the primary maintainer.

Thanks to everyone who has used, supported, and contributed to Channels over the years, and I hope we can keep it going with community support for a good while longer.

Bugfixes & Small Changes

• HTTP request body size limit is now enforced (the one set by the DATA_UPLOAD_MAX_MEMORY_SIZE setting)

• database_sync_to_async now closes old connections before it runs code, which should prevent some connection errors in long-running pages or tests.

• The auth middleware closes old connections before it runs, to solve similar old-connection issues.

Backwards Incompatible Changes

None.

2.1.6 Release Notes

Channels 2.1.6 is another bugfix release in the 2.1 series.

Bugfixes & Small Changes

• HttpCommunicator now extracts query strings correctly from its provided arguments

• AsyncHttpConsumer provides channel layer attributes following the same conventions as other consumer classes

• Prevent late-Daphne import errors where importing daphne.server didn't work due to a bad linter fix.

Backwards Incompatible Changes

None.

2.1.5 Release Notes

Channels 2.1.5 is another bugfix release in the 2.1 series.

Bugfixes & Small Changes

• Django middleware caching now works on Django 1.11 and Django 2.0. The previous release only ran on 2.1.

Backwards Incompatible Changes

None.

2.1.4 Release Notes

Channels 2.1.4 is another bugfix release in the 2.1 series.

Bugfixes & Small Changes

• Django middleware is now cached rather than instantiated per request resulting in a significant speed improvement. Some middleware took seconds to load and as a result Channels was unusable for HTTP serving before.

• ChannelServerLiveTestCase now serves static files again.

• Improved error message resulting from bad Origin headers.

• runserver logging now goes through the Django logging framework to match modern Django.

• Generic consumers can now have non-default channel layers - set the channel_layer_alias property on the consumer class

• Improved error when accessing scope['user'] before it's ready - the user is not accessible in the constructor of ASGI apps as it needs an async environment to load in. Previously it raised a generic error when you tried to access it early; now it tells you more clearly what's happening.

Backwards Incompatible Changes

None.

2.1.3 Release Notes

Channels 2.1.3 is another bugfix release in the 2.1 series.

Bugfixes & Small Changes

• An ALLOWED_ORIGINS value of "*" will now also allow requests without a Host header at all (especially important for tests)

• The request.path value is now correct in cases when a server has SCRIPT_NAME set.

• Errors that happen inside channel listeners inside a runworker or Worker class are now raised rather than suppressed.

Backwards Incompatible Changes

None.

2.1.2 Release Notes

Channels 2.1.2 is another bugfix release in the 2.1 series.

Special thanks to people at the DjangoCon Europe sprints who helped out with several of these fixes.

Major Changes

Session and authentication middleware has been overhauled to be non-blocking. Previously, these middlewares potentially did database or session store access in the synchronous ASGI constructor, meaning they would block the entire event loop while doing so.

Instead, they have now been modified to add LazyObjects into the scope in the places where the session or user will be, and then when the processing goes through their asynchronous portion, those stores are accessed in a non-blocking fashion.

This should be an un-noticeable change for end users, but if you see weird behaviour or an unresolved LazyObject, let us know.

Bugfixes & Small Changes

• AsyncHttpConsumer now has a disconnect() method you can override if you want to perform actions (such as leaving groups) when a long-running HTTP request disconnects.

• URL routing context now includes default arguments from the URLconf in the context's url_route key, alongside captured arguments/groups from the URL pattern.

• The FORCE_SCRIPT_NAME setting is now respected in ASGI mode, and lets you override where Django thinks the root URL of your application is mounted.

• ALLOWED_HOSTS is now set correctly during LiveServerTests, meaning you will no longer get 400 Bad Request errors during these test runs.

Backwards Incompatible Changes

None.

2.1.1 Release Notes

Channels 2.1.1 is a bugfix release for an important bug in the new async authentication code.

Major Changes

None.

Bugfixes & Small Changes

Previously, the object in scope["user"] was one of Django's SimpleLazyObjects, which then called our get_user async function via async_to_sync.

This worked fine when called from SyncConsumers, but because async environments do not run attribute access in an async fashion, when the body of an async consumer tried to call it, the asgiref library flagged an error where the code was trying to call a synchronous function during a async context.

To fix this, the User object is now loaded non-lazily on application startup. This introduces a blocking call during the synchronous application constructor, so the ASGI spec has been updated to recommend that constructors for ASGI apps are called in a threadpool and Daphne 2.1.1 implements this and is recommended for use with this release.

Backwards Incompatible Changes

None.

2.1.0 Release Notes

Channels 2.1 brings a few new major changes to Channels as well as some more minor fixes. In addition, if you've not yet seen it, we now have a long-form tutorial to better introduce some of the concepts and sync versus async styles of coding.

Major Changes

Async HTTP Consumer

There is a new native-async HTTP consumer class, channels.generic.http.AsyncHttpConsumer. This allows much easier writing of long-poll endpoints or other long-lived HTTP connection handling that benefits from native async support.

You can read more about it in the /topics/consumers documentation.

WebSocket Consumers

These consumer classes now all have built-in group join and leave functionality, which will make a consumer join all group names that are in the iterable groups on the consumer class (this can be a static list or a @property method).

In addition, the accept methods on both variants now take an optional subprotocol argument, which will be sent back to the WebSocket client as the subprotocol the server has selected. The client's advertised subprotocols can, as always, be found in the scope as scope["subprotocols"].

Nested URL Routing

URLRouter instances can now be nested inside each other and, like Django's URL handling and include, will strip off the matched part of the URL in the outer router and leave only the unmatched portion for the inner router, allowing reusable routing files.

Note that you cannot use the Django include function inside of the URLRouter as it assumes a bit too much about what it is given as its left-hand side and will terminate your regular expression/URL pattern wrongly.

Login and Logout

As well as overhauling the internals of the AuthMiddleware, there are now also login and logout async functions you can call in consumers to log users in and out of the current session.

Due to the way cookies are sent back to clients, these come with some caveats; read more about them and how to use them properly in /topics/authentication.

In-Memory Channel Layer

The in-memory channel layer has been extended to have full expiry and group support so it should now be suitable for drop-in replacement for most test scenarios.

Testing

The ChannelsLiveServerTestCase has been rewritten to use a new method for launching Daphne that should be more resilient (and faster), and now shares code with the Daphne test suite itself.

Ports are now left up to the operating system to decide rather than being picked from within a set range. It also now supports static files when the Django staticfiles app is enabled.

In addition, the Communicator classes have gained a receive_nothing method that allows you to assert that the application didn't send anything, rather than writing this yourself using exception handling. See more in the /topics/testing documentation.

Origin header validation

As well as removing the print statements that accidentally got into the last release, this has been overhauled to more correctly match against headers according to the Origin header spec and align with Django's ALLOWED_HOSTS setting.

It can now also enforce protocol (http versus https) and port, both optionally.

Bugfixes & Small Changes

• print statements that accidentally got left in the Origin validation code were removed.

• The runserver command now shows the version of Channels you are running.

• Orphaned tasks that may have caused warnings during test runs or occasionally live site traffic are now correctly killed off rather than letting them die later on and print warning messages.

• WebsocketCommunicator now accepts a query string passed into the constructor and adds it to the scope rather than just ignoring it.

• Test handlers will correctly handle changing the CHANNEL_LAYERS setting via decorators and wipe the internal channel layer cache.

• SessionMiddleware can be safely nested inside itself rather than causing a runtime error.

Backwards Incompatible Changes

• The format taken by the OriginValidator for its domains has changed and *.example.com is no longer allowed; instead, use .example.com to match a domain and all its subdomains.

• If you previously nested URLRouter instances inside each other both would have been matching on the full URL before, whereas now they will match on the unmatched portion of the URL, meaning your URL routes would break if you had intended this usage.

2.0.2 Release Notes

Channels 2.0.2 is a patch release of Channels, fixing a bug in the database connection handling.

As always, when updating Channels make sure to also update its dependencies (asgiref and daphne) as these also get their own bugfix updates, and some bugs that may appear to be part of Channels are actually in those packages.

New Features

• There is a new channels.db.database_sync_to_async wrapper that is like sync_to_async but also closes database connections for you. You can read more about usage in /topics/databases.

Bugfixes

• SyncConsumer and all its descendant classes now close database connections when they exit.

Backwards Incompatible Changes

None.

2.0.1 Release Notes

Channels 2.0.1 is a patch release of channels, adding a couple of small new features and fixing one bug in URL resolution.

As always, when updating Channels make sure to also update its dependencies (asgiref and daphne) as these also get their own bugfix updates, and some bugs that may appear to be part of Channels are actually in those packages.

New Features

• There are new async versions of the Websocket generic consumers, AsyncWebsocketConsumer and AsyncJsonWebsocketConsumer. Read more about them in /topics/consumers.

• The old allowed_hosts_only decorator has been removed (it was accidentally included in the 2.0 release but didn't work) and replaced with a new OriginValidator and AllowedHostsOriginValidator set of ASGI middleware. Read more in /topics/security.

Bugfixes

• A bug in URLRouter which didn't allow you to match beyond the first URL in some situations has been resolved, and a test suite was added for URL resolution to prevent it happening again.

Backwards Incompatible Changes

None.

2.0.0 Release Notes

Channels 2.0 is a major rewrite of Channels, introducing a large amount of changes to the fundamental design and architecture of Channels. Notably:

• Data is no longer transported over a channel layer between protocol server and application; instead, applications run inside their protocol servers (like with WSGI).

• To achieve this, the entire core of channels is now built around Python's asyncio framework and runs async-native down until it hits either a Django view or a synchronous consumer.

• Python 2.7 and 3.4 are no longer supported.

More detailed information on the changes and tips on how to port your applications can be found in our /one-to-two documentation in the 2.x docs version.

Backwards Incompatible Changes

Channels 2 is regrettably not backwards-compatible at all with Channels 1 applications due to the large amount of re-architecting done to the code and the switch from synchronous to asynchronous runtimes.

A migration guide is available in the 2.x docs version, and a lot of the basic concepts are the same, but the basic class structure and imports have changed.

Our apologies for having to make a breaking change like this, but it was the only way to fix some of the fundamental design issues in Channels 1. Channels 1 will continue to receive security and data-loss fixes for the foreseeable future, but no new features will be added.

1.1.6 Release Notes

Channels 1.1.5 is a packaging release for the 1.1 series, released on June 28th, 2017.

Major Changes

None.

Minor Changes & Bugfixes

• The runserver server_cls override no longer fails with more modern Django versions that pass an ipv6 parameter.

Backwards Incompatible Changes

None.

1.1.5 Release Notes

Channels 1.1.5 is a packaging release for the 1.1 series, released on June 16th, 2017.

Major Changes

None.

Minor Changes & Bugfixes

• The Daphne dependency requirement was bumped to 1.3.0.

Backwards Incompatible Changes

None.

1.1.4 Release Notes

Channels 1.1.4 is a bugfix release for the 1.1 series, released on June 15th, 2017.

Major Changes

None.

Minor Changes & Bugfixes

• Pending messages correctly handle retries in backlog situations

• Workers in threading mode now respond to ctrl-C and gracefully exit.

• request.meta['QUERY_STRING'] is now correctly encoded at all times.

• Test client improvements

• ChannelServerLiveTestCase added, allows an equivalent of the Django LiveTestCase.

• Decorator added to check Origin headers (allowed_hosts_only)

• New TEST_CONFIG setting in CHANNEL_LAYERS that allows varying of the channel layer for tests (e.g. using a different Redis install)

Backwards Incompatible Changes

None.

1.1.3 Release Notes

Channels 1.1.3 is a bugfix release for the 1.1 series, released on April 5th, 2017.

Major Changes

None.

Minor Changes & Bugfixes

• enforce_ordering now works correctly with the new-style process-specific channels

• ASGI channel layer versions are now explicitly checked for version compatibility

Backwards Incompatible Changes

None.

1.1.2 Release Notes

Channels 1.1.2 is a bugfix release for the 1.1 series, released on April 1st, 2017.

Major Changes

None.

Minor Changes & Bugfixes

• Session name hash changed to SHA-1 to satisfy FIPS-140-2.

• scheme key in ASGI-HTTP messages now translates into request.is_secure() correctly.

• WebsocketBridge now exposes the underlying WebSocket as .socket.

Backwards Incompatible Changes

• When you upgrade all current channel sessions will be invalidated; you should make sure you disconnect all WebSockets during upgrade.

1.1.1 Release Notes

Channels 1.1.1 is a bugfix release that fixes a packaging issue with the JavaScript files.

Major Changes

None.

Minor Changes & Bugfixes

• The JavaScript binding introduced in 1.1.0 is now correctly packaged and included in builds.

Backwards Incompatible Changes

None.

1.1.0 Release Notes

Channels 1.1.0 introduces a couple of major but backwards-compatible changes, including most notably the inclusion of a standard, framework-agnostic JavaScript library for easier integration with your site.

Major Changes

• Channels now includes a JavaScript wrapper that wraps reconnection and multiplexing for you on the client side. For more on how to use it, see the javascript documentation.

• Test classes have been moved from channels.tests to channels.test to better match Django. Old imports from channels.tests will continue to work but will trigger a deprecation warning, and channels.tests will be removed completely in version 1.3.

Minor Changes & Bugfixes

• Bindings now support non-integer fields for primary keys on models.

• The enforce_ordering decorator no longer suffers a race condition where it would drop messages under high load.

• runserver no longer errors if the staticfiles app is not enabled in Django.

Backwards Incompatible Changes

None.

1.0.3 Release Notes

Channels 1.0.3 is a minor bugfix release, released on 2017/02/01.

Changes

• Database connections are no longer force-closed after each test is run.

• Channel sessions are not re-saved if they're empty even if they're marked as modified, allowing logout to work correctly.

• WebsocketDemultiplexer now correctly does sessions for the second/third/etc. connect and disconnect handlers.

• Request reading timeouts now correctly return 408 rather than erroring out.

• The rundelay delay server now only polls the database once per second, and this interval is configurable with the --sleep option.

Backwards Incompatible Changes

None.

1.0.2 Release Notes

Channels 1.0.2 is a minor bugfix release, released on 2017/01/12.

Changes

• Websockets can now be closed from anywhere using the new WebsocketCloseException, available as channels.exceptions.WebsocketCloseException(code=None). There is also a generic ChannelSocketException you can base any exceptions on that, if it is caught, gets handed the current message in a run method, so you can do custom behaviours.

• Calling Channel.send or Group.send from outside a consumer context (i.e. in tests or management commands) will once again send the message immediately, rather than putting it into the consumer message buffer to be flushed when the consumer ends (which never happens)

• The base implementation of databinding now correctly only calls group_names(instance), as documented.

Backwards Incompatible Changes

None.

1.0.1 Release Notes

Channels 1.0.1 is a minor bugfix release, released on 2017/01/09.

Changes

• WebSocket generic views now accept connections by default in their connect handler for better backwards compatibility.

Backwards Incompatible Changes

None.

1.0.0 Release Notes

Channels 1.0.0 brings together a number of design changes, including some breaking changes, into our first fully stable release, and also brings the databinding code out of alpha phase. It was released on 2017/01/08.

The result is a faster, easier to use, and safer Channels, including one major change that will fix almost all problems with sessions and connect/receive ordering in a way that needs no persistent storage.

It was unfortunately not possible to make all of the changes backwards compatible, though most code should not be too affected and the fixes are generally quite easy.

You must also update Daphne to at least 1.0.0 to have this release of Channels work correctly.

Major Features

Channels 1.0 introduces a couple of new major features.

WebSocket accept/reject flow

Rather than be immediately accepted, WebSockets now pause during the handshake while they send over a message on websocket.connect, and your application must either accept or reject the connection before the handshake is completed and messages can be received.

You must update Daphne to at least 1.0.0 to make this work correctly.

This has several advantages:

• You can now reject WebSockets before they even finish connecting, giving appropriate error codes to browsers and not letting the browser-side socket ever get into a connected state and send messages.

• Combined with Consumer Atomicity (below), it means there is no longer any need for the old "slight ordering" mode, as the connect consumer must run to completion and accept the socket before any messages can be received and forwarded onto websocket.receive.

• Any send message sent to the WebSocket will implicitly accept the connection, meaning only a limited set of connect consumers need changes (see Backwards Incompatible Changes below)

Consumer Atomicity

Consumers will now buffer messages you try to send until the consumer completes and then send them once it exits and the outbound part of any decorators have been run (even if an exception is raised).

This makes the flow of messages much easier to reason about - consumers can now be reasoned about as atomic blocks that run and then send messages, meaning that if you send a message to start another consumer you're guaranteed that the sending consumer has finished running by the time it's acted upon.

If you want to send messages immediately rather than at the end of the consumer, you can still do that by passing the immediately argument:

Channel("thumbnailing-tasks").send({"id": 34245}, immediately=True)

This should be mostly backwards compatible, and may actually fix race conditions in some apps that were pre-existing.

Databinding Group/Action Overhaul

Previously, databinding subclasses had to implement group_names(instance, action) to return what groups to send an instance's change to of the type action. This had flaws, most notably when what was actually just a modification to the instance in question changed its permission status so more clients could see it; to those clients, it should instead have been "created".

Now, Channels just calls group_names(instance), and you should return what groups can see the instance at the current point in time given the instance you were passed. Channels will actually call the method before and after changes, comparing the groups you gave, and sending out create, update or delete messages to clients appropriately.

Existing databinding code will need to be adapted; see the "Backwards Incompatible Changes" section for more.

Demultiplexer Overhaul

Demuliplexers have changed to remove the behaviour where they re-sent messages onto new channels without special headers, and instead now correctly split out incoming messages into sub-messages that still look like websocket.receive messages, and directly dispatch these to the relevant consumer.

They also now forward all websocket.connect and websocket.disconnect messages to all of their sub-consumers, so it's much easier to compose things together from code that also works outside the context of multiplexing.

For more, read the updated /generic docs.

Delay Server

A built-in delay server, launched with manage.py rundelay, now ships if you wish to use it. It needs some extra initial setup and uses a database for persistence; see /delay for more information.

Minor Changes

• Serializers can now specify fields as __all__ to auto-include all fields, and exclude to remove certain unwanted fields.

• runserver respects FORCE_SCRIPT_NAME

• Websockets can now be closed with a specific code by calling close(status=4000)

• enforce_ordering no longer has a slight mode (because of the accept flow changes), and is more efficient with session saving.

• runserver respects --nothreading and only launches one worker, takes a --http-timeout option if you want to override it from the default 60,

• A new @channel_and_http_session decorator rehydrates the HTTP session out of the channel session if you want to access it inside receive consumers.

• Streaming responses no longer have a chance of being cached.

• request.META['SERVER_PORT'] is now always a string.

• http.disconnect now has a path key so you can route it.

• Test client now has a send_and_consume method.

Backwards Incompatible Changes

Connect Consumers

If you have a custom consumer for websocket.connect, you must ensure that it either:

• Sends at least one message onto the reply_channel that generates a WebSocket frame (either bytes or text is set), either directly or via a group.

• Sends a message onto the reply_channel that is {"accept": True}, to accept a connection without sending data.

• Sends a message onto the reply_channel that is {"close": True}, to reject a connection mid-handshake.

Many consumers already do the former, but if your connect consumer does not send anything you MUST now send an accept message or the socket will remain in the handshaking phase forever and you'll never get any messages.

All built-in Channels consumers (e.g. in the generic consumers) have been upgraded to do this.

You must update Daphne to at least 1.0.0 to make this work correctly.

Databinding group_names

If you have databinding subclasses, you will have implemented group_names(instance, action), which returns the groups to use based on the instance and action provided.

Now, instead, you must implement group_names(instance), which returns the groups that can see the instance as it is presented for you; the action results will be worked out for you. For example, if you want to only show objects marked as "admin_only" to admins, and objects without it to everyone, previously you would have done:

def group_names(self, instance, action):
    if instance.admin_only:
        return ["admins"]
    else:
        return ["admins", "non-admins"]

Because you did nothing based on the action (and if you did, you would have got incomplete messages, hence this design change), you can just change the signature of the method like this:

def group_names(self, instance):
    if instance.admin_only:
        return ["admins"]
    else:
        return ["admins", "non-admins"]

Now, when an object is updated to have admin_only = True, the clients in the non-admins group will get a delete message, while those in the admins group will get an update message.

Demultiplexers

Demultiplexers have changed from using a mapping dict, which mapped stream names to channels, to using a consumers dict which maps stream names directly to consumer classes.

You will have to convert over to using direct references to consumers, change the name of the dict, and then you can remove any channel routing for the old channels that were in mapping from your routes.

Additionally, the Demultiplexer now forwards messages as they would look from a direct connection, meaning that where you previously got a decoded object through you will now get a correctly-formatted websocket.receive message through with the content as a text key, JSON-encoded. You will also now have to handle websocket.connect and websocket.disconnect messages.

Both of these issues can be solved using the JsonWebsocketConsumer generic consumer, which will decode for you and correctly separate connection and disconnection handling into their own methods.