1.0.0 Release Notes
===================

.. note::
    These release notes are in development. Channels 1.0.0 is not yet released.


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.

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.


Demultiplexer Overhaul
~~~~~~~~~~~~~~~~~~~~~~

TBD


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.