Merge branch 'master' of github.com:andrewgodwin/channels into doc-update

channels/auth.py

@@ -0,0 +1,66 @@
+import functools
+
+from django.contrib import auth
+from .decorators import channel_session, http_session
+
+
+def transfer_user(from_session, to_session):
+    """
+    Transfers user from HTTP session to channel session.
+    """
+    to_session[auth.BACKEND_SESSION_KEY] = from_session[auth.BACKEND_SESSION_KEY]
+    to_session[auth.SESSION_KEY] = from_session[auth.SESSION_KEY]
+    to_session[auth.HASH_SESSION_KEY] = from_session[auth.HASH_SESSION_KEY]
+
+
+def channel_session_user(func):
+    """
+    Presents a message.user attribute obtained from a user ID in the channel
+    session, rather than in the http_session. Turns on channel session implicitly.
+    """
+    @channel_session
+    @functools.wraps(func)
+    def inner(message, *args, **kwargs):
+        # If we didn't get a session, then we don't get a user
+        if not hasattr(message, "channel_session"):
+            raise ValueError("Did not see a channel session to get auth from")
+        if message.channel_session is None:
+            message.user = None
+        # Otherwise, be a bit naughty and make a fake Request with just
+        # a "session" attribute (later on, perhaps refactor contrib.auth to
+        # pass around session rather than request)
+        else:
+            fake_request = type("FakeRequest", (object, ), {"session": message.channel_session})
+            message.user = auth.get_user(fake_request)
+        # Run the consumer
+        return func(message, *args, **kwargs)
+    return inner
+
+
+def http_session_user(func):
+    """
+    Wraps a HTTP or WebSocket consumer (or any consumer of messages
+    that provides a "COOKIES" attribute) to provide both a "session"
+    attribute and a "user" attibute, like AuthMiddleware does.
+
+    This runs http_session() to get a session to hook auth off of.
+    If the user does not have a session cookie set, both "session"
+    and "user" will be None.
+    """
+    @http_session
+    @functools.wraps(func)
+    def inner(message, *args, **kwargs):
+        # If we didn't get a session, then we don't get a user
+        if not hasattr(message, "http_session"):
+            raise ValueError("Did not see a http session to get auth from")
+        if message.http_session is None:
+            message.user = None
+        # Otherwise, be a bit naughty and make a fake Request with just
+        # a "session" attribute (later on, perhaps refactor contrib.auth to
+        # pass around session rather than request)
+        else:
+            fake_request = type("FakeRequest", (object, ), {"session": message.http_session})
+            message.user = auth.get_user(fake_request)
+        # Run the consumer
+        return func(message, *args, **kwargs)
+    return inner

channels/backends/base.py

@@ -93,3 +93,16 @@ class BaseChannelBackend(object):
 
     def __str__(self):
         return self.__class__.__name__
+
+    def lock_channel(self, channel):
+        """
+        Attempts to get a lock on the named channel. Returns True if lock
+        obtained, False if lock not obtained.
+        """
+        raise NotImplementedError()
+
+    def unlock_channel(self, channel):
+        """
+        Unlocks the named channel. Always succeeds.
+        """
+        raise NotImplementedError()

channels/backends/database.py

@@ -3,7 +3,7 @@ import json
 import datetime
 
 from django.apps.registry import Apps
-from django.db import models, connections, DEFAULT_DB_ALIAS
+from django.db import models, connections, DEFAULT_DB_ALIAS, IntegrityError
 from django.utils.functional import cached_property
 from django.utils.timezone import now
 
@@ -71,6 +71,26 @@ class DatabaseChannelBackend(BaseChannelBackend):
                 editor.create_model(Group)
         return Group
 
+    @cached_property
+    def lock_model(self):
+        """
+        Initialises a new model to store groups; not done as part of a
+        models.py as we don't want to make it for most installs.
+        """
+        # Make the model class
+        class Lock(models.Model):
+            channel = models.CharField(max_length=200, unique=True)
+            expiry = models.DateTimeField(db_index=True)
+            class Meta:
+                apps = Apps()
+                app_label = "channels"
+                db_table = "django_channel_locks"
+        # Ensure its table exists
+        if Lock._meta.db_table not in self.connection.introspection.table_names(self.connection.cursor()):
+            with self.connection.schema_editor() as editor:
+                editor.create_model(Lock)
+        return Lock
+
     def send(self, channel, message):
         self.channel_model.objects.create(
             channel = channel,
@@ -97,6 +117,7 @@ class DatabaseChannelBackend(BaseChannelBackend):
         # Include a 10-second grace period because that solves some clock sync
         self.channel_model.objects.filter(expiry__lt=now() - datetime.timedelta(seconds=10)).delete()
         self.group_model.objects.filter(expiry__lt=now() - datetime.timedelta(seconds=10)).delete()
+        self.lock_model.objects.filter(expiry__lt=now() - datetime.timedelta(seconds=10)).delete()
 
     def group_add(self, group, channel, expiry=None):
         """
@@ -123,5 +144,27 @@ class DatabaseChannelBackend(BaseChannelBackend):
         self._clean_expired()
         return list(self.group_model.objects.filter(group=group).values_list("channel", flat=True))
 
+    def lock_channel(self, channel, expiry=None):
+        """
+        Attempts to get a lock on the named channel. Returns True if lock
+        obtained, False if lock not obtained.
+        """
+        # We rely on the UNIQUE constraint for only-one-thread-wins on locks
+        try:
+            self.lock_model.objects.create(
+                channel = channel,
+                expiry = now() + datetime.timedelta(seconds=expiry or self.expiry),
+            )
+        except IntegrityError:
+            return False
+        else:
+            return True
+
+    def unlock_channel(self, channel):
+        """
+        Unlocks the named channel. Always succeeds.
+        """
+        self.lock_model.objects.filter(channel=channel).delete()
+
     def __str__(self):
         return "%s(alias=%s)" % (self.__class__.__name__, self.connection.alias)

channels/backends/memory.py

@@ -5,6 +5,7 @@ from .base import BaseChannelBackend
 
 queues = {}
 groups = {}
+locks = set()
 
 class InMemoryChannelBackend(BaseChannelBackend):
     """
@@ -72,3 +73,22 @@ class InMemoryChannelBackend(BaseChannelBackend):
         """
         self._clean_expired()
         return groups.get(group, {}).keys()
+
+    def lock_channel(self, channel):
+        """
+        Attempts to get a lock on the named channel. Returns True if lock
+        obtained, False if lock not obtained.
+        """
+        # Probably not perfect for race conditions, but close enough considering
+        # it shouldn't be used.
+        if channel not in locks:
+            locks.add(channel)
+            return True
+        else:
+            return False
+
+    def unlock_channel(self, channel):
+        """
+        Unlocks the named channel. Always succeeds.
+        """
+        locks.discard(channel)

channels/backends/redis_py.py

@@ -101,5 +101,20 @@ class RedisChannelBackend(BaseChannelBackend):
 
     # TODO: send_group efficient implementation using Lua
 
+    def lock_channel(self, channel, expiry=None):
+        """
+        Attempts to get a lock on the named channel. Returns True if lock
+        obtained, False if lock not obtained.
+        """
+        key = "%s:lock:%s" % (self.prefix, channel)
+        return bool(self.connection.setnx(key, "1"))
+
+    def unlock_channel(self, channel):
+        """
+        Unlocks the named channel. Always succeeds.
+        """
+        key = "%s:lock:%s" % (self.prefix, channel)
+        self.connection.delete(key)
+
     def __str__(self):
         return "%s(host=%s, port=%s)" % (self.__class__.__name__, self.host, self.port)

channels/decorators.py

@@ -3,16 +3,77 @@ import hashlib
 from importlib import import_module
 
 from django.conf import settings
-from django.utils import six
-from django.contrib import auth
 
-from channels import channel_backends, DEFAULT_CHANNEL_BACKEND
+
+def linearize(func):
+    """
+    Makes sure the contained consumer does not run at the same time other
+    consumers are running on messages with the same reply_channel.
+
+    Required if you don't want weird things like a second consumer starting
+    up before the first has exited and saved its session. Doesn't guarantee
+    ordering, just linearity.
+    """
+    @functools.wraps(func)
+    def inner(message, *args, **kwargs):
+        # Make sure there's a reply channel
+        if not message.reply_channel:
+            raise ValueError("No reply_channel sent to consumer; @no_overlap can only be used on messages containing it.")
+        # Get the lock, or re-queue
+        locked = message.channel_backend.lock_channel(message.reply_channel)
+        if not locked:
+            raise message.Requeue()
+        # OK, keep going
+        try:
+            return func(message, *args, **kwargs)
+        finally:
+            message.channel_backend.unlock_channel(message.reply_channel)
+    return inner
+
+
+def channel_session(func):
+    """
+    Provides a session-like object called "channel_session" to consumers
+    as a message attribute that will auto-persist across consumers with
+    the same incoming "reply_channel" value.
+
+    Use this to persist data across the lifetime of a connection.
+    """
+    @functools.wraps(func)
+    def inner(message, *args, **kwargs):
+        # Make sure there's a reply_channel
+        if not message.reply_channel:
+            raise ValueError("No reply_channel sent to consumer; @channel_session can only be used on messages containing it.")
+        # Make sure there's NOT a channel_session already
+        if hasattr(message, "channel_session"):
+            raise ValueError("channel_session decorator wrapped inside another channel_session decorator")
+        # Turn the reply_channel into a valid session key length thing.
+        # We take the last 24 bytes verbatim, as these are the random section,
+        # and then hash the remaining ones onto the start, and add a prefix
+        reply_name = message.reply_channel.name
+        session_key = "skt" + hashlib.md5(reply_name[:-24]).hexdigest()[:8] + reply_name[-24:]
+        # Make a session storage
+        session_engine = import_module(settings.SESSION_ENGINE)
+        session = session_engine.SessionStore(session_key=session_key)
+        # If the session does not already exist, save to force our
+        # session key to be valid.
+        if not session.exists(session.session_key):
+            session.save(must_create=True)
+        message.channel_session = session
+        # Run the consumer
+        try:
+            return func(message, *args, **kwargs)
+        finally:
+            # Persist session if needed
+            if session.modified:
+                session.save()
+    return inner
 
 
 def http_session(func):
     """
-    Wraps a HTTP or WebSocket consumer (or any consumer of messages
+    Wraps a HTTP or WebSocket connect consumer (or any consumer of messages
-    that provides a "COOKIES" or "GET" attribute) to provide a "session"
+    that provides a "cooikies" or "get" attribute) to provide a "http_session"
     attribute that behaves like request.session; that is, it's hung off of
     a per-user session key that is saved in a cookie or passed as the
     "session_key" GET parameter.
@@ -21,13 +82,16 @@ def http_session(func):
     don't have one - that's what SessionMiddleware is for, this is a simpler
     read-only version for more low-level code.
 
-    If a user does not have a session we can inflate, the "session" attribute will
+    If a message does not have a session we can inflate, the "session" attribute
-    be None, rather than an empty session you can write to.
+    will be None, rather than an empty session you can write to.
     """
     @functools.wraps(func)
     def inner(message, *args, **kwargs):
         if "cookies" not in message.content and "get" not in message.content:
-            raise ValueError("No cookies or get sent to consumer; this decorator can only be used on messages containing at least one.")
+            raise ValueError("No cookies or get sent to consumer - cannot initialise http_session")
+        # Make sure there's NOT a http_session already
+        if hasattr(message, "http_session"):
+            raise ValueError("http_session decorator wrapped inside another http_session decorator")
         # Make sure there's a session key
         session_key = None
         if "get" in message.content:
@@ -43,7 +107,7 @@ def http_session(func):
             session = session_engine.SessionStore(session_key=session_key)
         else:
             session = None
-        message.session = session
+        message.http_session = session
         # Run the consumer
         result = func(message, *args, **kwargs)
         # Persist session if needed (won't be saved if error happens)
@@ -51,65 +115,3 @@ def http_session(func):
             session.save()
         return result
     return inner
-
-
-def http_django_auth(func):
-    """
-    Wraps a HTTP or WebSocket consumer (or any consumer of messages
-    that provides a "COOKIES" attribute) to provide both a "session"
-    attribute and a "user" attibute, like AuthMiddleware does.
-
-    This runs http_session() to get a session to hook auth off of.
-    If the user does not have a session cookie set, both "session"
-    and "user" will be None.
-    """
-    @http_session
-    @functools.wraps(func)
-    def inner(message, *args, **kwargs):
-        # If we didn't get a session, then we don't get a user
-        if not hasattr(message, "session"):
-            raise ValueError("Did not see a session to get auth from")
-        if message.session is None:
-            message.user = None
-        # Otherwise, be a bit naughty and make a fake Request with just
-        # a "session" attribute (later on, perhaps refactor contrib.auth to
-        # pass around session rather than request)
-        else:
-            fake_request = type("FakeRequest", (object, ), {"session": message.session})
-            message.user = auth.get_user(fake_request)
-        # Run the consumer
-        return func(message, *args, **kwargs)
-    return inner
-
-
-def channel_session(func):
-    """
-    Provides a session-like object called "channel_session" to consumers
-    as a message attribute that will auto-persist across consumers with
-    the same incoming "reply_channel" value.
-    """
-    @functools.wraps(func)
-    def inner(message, *args, **kwargs):
-        # Make sure there's a reply_channel in kwargs
-        if not message.reply_channel:
-            raise ValueError("No reply_channel sent to consumer; this decorator can only be used on messages containing it.")
-        # Turn the reply_channel into a valid session key length thing.
-        # We take the last 24 bytes verbatim, as these are the random section,
-        # and then hash the remaining ones onto the start, and add a prefix
-        # TODO: See if there's a better way of doing this
-        reply_name = message.reply_channel.name
-        session_key = "skt" + hashlib.md5(reply_name[:-24]).hexdigest()[:8] + reply_name[-24:]
-        # Make a session storage
-        session_engine = import_module(settings.SESSION_ENGINE)
-        session = session_engine.SessionStore(session_key=session_key)
-        # If the session does not already exist, save to force our session key to be valid
-        if not session.exists(session.session_key):
-            session.save()
-        message.channel_session = session
-        # Run the consumer
-        result = func(message, *args, **kwargs)
-        # Persist session if needed (won't be saved if error happens)
-        if session.modified:
-            session.save()
-        return result
-    return inner

channels/interfaces/websocket_twisted.py

@@ -18,7 +18,7 @@ class InterfaceProtocol(WebSocketServerProtocol):
         self.channel_backend = channel_backends[DEFAULT_CHANNEL_BACKEND]
         self.request_info = {
             "path": request.path,
-            "GET": request.params,
+            "get": request.params,
         }
 
     def onOpen(self):

channels/message.py

@@ -10,6 +10,13 @@ class Message(object):
     to use to reply to this message's end user, if that makes sense.
     """
 
+    class Requeue(Exception):
+        """
+        Raise this while processing a message to requeue it back onto the
+        channel. Useful if you're manually ensuring partial ordering, etc.
+        """
+        pass
+
     def __init__(self, content, channel, channel_backend, reply_channel=None):
         self.content = content
         self.channel = channel

channels/tests/test_backends.py

@@ -10,7 +10,7 @@ class MemoryBackendTests(TestCase):
     backend_class = InMemoryChannelBackend
 
     def setUp(self):
-        self.backend = self.backend_class()
+        self.backend = self.backend_class(routing={})
 
     def test_send_recv(self):
         """
@@ -33,7 +33,7 @@ class MemoryBackendTests(TestCase):
         self.assertEqual(message, {"value": "red"})
 
     def test_message_expiry(self):
-        self.backend = self.backend_class(expiry=-100)
+        self.backend = self.backend_class(routing={}, expiry=-100)
         self.backend.send("test", {"value": "blue"})
         channel, message = self.backend.receive_many(["test"])
         self.assertIs(channel, None)
@@ -72,7 +72,7 @@ class MemoryBackendTests(TestCase):
         self.assertEqual(message, {"value": "orange"})
 
     def test_group_expiry(self):
-        self.backend = self.backend_class(expiry=-100)
+        self.backend = self.backend_class(routing={}, expiry=-100)
         self.backend.group_add("tgroup", "test")
         self.backend.group_add("tgroup", "test2")
         self.assertEqual(

channels/worker.py

@@ -1,5 +1,6 @@
 import traceback
 from .message import Message
+from .utils import name_that_thing
 
 
 class Worker(object):
@@ -31,5 +32,8 @@ class Worker(object):
                 self.callback(channel, message)
             try:
                 consumer(message)
+            except Message.Requeue:
+                self.channel_backend.send(channel, content)
             except:
+                print "Error processing message with consumer %s:" % name_that_thing(consumer)
                 traceback.print_exc()

docs/backends.rst

@@ -8,6 +8,13 @@ you wish; the API is very simple and documented below.
 In-memory
 ---------
 
+The in-memory backend is the simplest, and not really a backend as such;
+it exists purely to enable Django to run in a "normal" mode where no Channels
+functionality is available, just normal HTTP request processing. You should
+never need to set it explicitly.
+
+This backend provides no network transparency or non-blocking guarantees.
+
 Database
 --------
 

docs/getting-started.rst

@@ -235,105 +235,31 @@ like, so you can understand when they're called. If you run three or four
 copies of ``runworker`` you'll probably be able to see the tasks running
 on different workers.
 
-Authentication
---------------
-
-Now, of course, a WebSocket solution is somewhat limited in scope without the
-ability to live with the rest of your website - in particular, we want to make
-sure we know what user we're talking to, in case we have things like private
-chat channels (we don't want a solution where clients just ask for the right
-channels, as anyone could change the code and just put in private channel names)
-
-It can also save you having to manually make clients ask for what they want to
-see; if I see you open a WebSocket to my "updates" endpoint, and I know which
-user ID, I can just auto-add that channel to all the relevant groups (mentions
-of that user, for example).
-
-Handily, as WebSockets start off using the HTTP protocol, they have a lot of
-familiar features, including a path, GET parameters, and cookies. We'd like to
-use these to hook into the familiar Django session and authentication systems;
-after all, WebSockets are no good unless we can identify who they belong to
-and do things securely.
-
-In addition, we don't want the interface servers storing data or trying to run
-authentication; they're meant to be simple, lean, fast processes without much
-state, and so we'll need to do our authentication inside our consumer functions.
-
-Fortunately, because Channels has standardised WebSocket event
-:doc:`message-standards`, it ships with decorators that help you with
-authentication, as well as using Django's session framework (which authentication
-relies on). Channels can use Django sessions either from cookies (if you're running your websocket
-server on the same port as your main site, which requires a reverse proxy that
-understands WebSockets), or from a ``session_key`` GET parameter, which
-is much more portable, and works in development where you need to run a separate
-WebSocket server (by default, on port 9000).
-
-All we need to do is add the ``django_http_auth`` decorator to our views,
-and we'll get extra ``session`` and ``user`` keyword attributes on ``message`` we can use;
-let's make one where users can only chat to people with the same first letter
-of their username::
-
-    from channels import Channel, Group
-    from channels.decorators import django_http_auth
-
-    @django_http_auth
-    def ws_add(message):
-        Group("chat-%s" % message.user.username[0]).add(message.reply_channel)
-
-    @django_http_auth
-    def ws_message(message):
-        Group("chat-%s" % message.user.username[0]).send(message.content)
-
-    @django_http_auth
-    def ws_disconnect(message):
-        Group("chat-%s" % message.user.username[0]).discard(message.reply_channel)
-
-Now, when we connect to the WebSocket we'll have to remember to provide the
-Django session ID as part of the URL, like this::
-
-    socket = new WebSocket("ws://127.0.0.1:9000/?session_key=abcdefg");
-
-You can get the current session key in a template with ``{{ request.session.session_key }}``.
-Note that Channels can't work with signed cookie sessions - since only HTTP
-responses can set cookies, it needs a backend it can write to separately to
-store state.
-
 Persisting Data
 ---------------
 
-Doing chatrooms by username first letter is a nice simple example, but it's
+Echoing messages is a nice simple example, but it's
 skirting around the real design pattern - persistent state for connections.
-A user may open our chat site and select the chatroom to join themselves, so we
+Let's consider a basic chat site where a user requests a chat room upon initial
-should let them send this request in the initial WebSocket connection,
+connection, as part of the query string (e.g. ``http://host/websocket?room=abc``).
-check they're allowed to access it, and then remember which room a socket is
-connected to when they send a message in so we know which group to send it to.
 
-The ``reply_channel`` is our unique pointer to the open WebSocket - as you've
+The ``reply_channel`` attribute you've seen before is our unique pointer to the
-seen, we do all our operations on it - but it's not something we can annotate
+open WebSocket - because it varies between different clients, it's how we can
-with data; it's just a simple string, and even if we hack around and set
+keep track of "who" a message is from. Remember, Channels is network-trasparent
-attributes on it that's not going to carry over to other workers.
+and can run on multiple workers, so you can't just store things locally in
+global variables or similar.
 
-Instead, the solution is to persist information keyed by the send channel in
+Instead, the solution is to persist information keyed by the ``reply_channel`` in
 some other data store - sound familiar? This is what Django's session framework
 does for HTTP requests, only there it uses cookies as the lookup key rather
 than the ``reply_channel``.
 
-Now, as you saw above, you can use the ``django_http_auth`` decorator to get
+Channels provides a ``channel_session`` decorator for this purpose - it
-both a ``user`` and a ``session`` attribute on your message - and,
+provides you with an attribute called ``message.channel_session`` that acts
-indeed, there is a ``http_session`` decorator that will just give you
+just like a normal Django session.
-the ``session`` attribute.
-
-However, that session is based on cookies, and so follows the user round the
-site - it's great for information that should persist across all WebSocket and
-HTTP connections, but not great for information that is specific to a single
-WebSocket (such as "which chatroom should this socket be connected to"). For
-this reason, Channels also provides a ``channel_session`` decorator,
-which adds a ``channel_session`` attribute to the message; this works just like
-the normal ``session`` attribute, and persists to the same storage, but varies
-per-channel rather than per-cookie.
 
 Let's use it now to build a chat server that expects you to pass a chatroom
-name in the path of your WebSocket request (we'll ignore auth for now)::
+name in the path of your WebSocket request (we'll ignore auth for now - that's next)::
 
     from channels import Channel
     from channels.decorators import channel_session
@@ -364,9 +290,102 @@ name in the path of your WebSocket request (we'll ignore auth for now)::
 
 If you play around with it from the console (or start building a simple
 JavaScript chat client that appends received messages to a div), you'll see
-that you can now request which chat room you want in the initial request. We
+that you can now request which chat room you want in the initial request.
-could easily add in the auth decorator here too and do an initial check in
+
-``connect`` that the user had permission to join that chatroom.
+Authentication
+--------------
+
+Now, of course, a WebSocket solution is somewhat limited in scope without the
+ability to live with the rest of your website - in particular, we want to make
+sure we know what user we're talking to, in case we have things like private
+chat channels (we don't want a solution where clients just ask for the right
+channels, as anyone could change the code and just put in private channel names)
+
+It can also save you having to manually make clients ask for what they want to
+see; if I see you open a WebSocket to my "updates" endpoint, and I know which
+user you are, I can just auto-add that channel to all the relevant groups (mentions
+of that user, for example).
+
+Handily, as WebSockets start off using the HTTP protocol, they have a lot of
+familiar features, including a path, GET parameters, and cookies. We'd like to
+use these to hook into the familiar Django session and authentication systems;
+after all, WebSockets are no good unless we can identify who they belong to
+and do things securely.
+
+In addition, we don't want the interface servers storing data or trying to run
+authentication; they're meant to be simple, lean, fast processes without much
+state, and so we'll need to do our authentication inside our consumer functions.
+
+Fortunately, because Channels has standardised WebSocket event
+:doc:`message-standards`, it ships with decorators that help you with
+both authentication and getting the underlying Django session (which is what
+Django authentication relies on).
+
+Channels can use Django sessions either from cookies (if you're running your websocket
+server on the same port as your main site, which requires a reverse proxy that
+understands WebSockets), or from a ``session_key`` GET parameter, which
+is much more portable, and works in development where you need to run a separate
+WebSocket server (by default, on port 9000).
+
+You get access to a user's normal Django session using the ``http_session``
+decorator - that gives you a ``message.http_session`` attribute that behaves
+just like ``request.session``. You can go one further and use ``http_session_user``
+which will provide a ``message.user`` attribute as well as the session attribute.
+
+Now, one thing to note is that you only get the detailed HTTP information
+during the ``connect`` message of a WebSocket connection (you can read more
+about what you get when in :doc:`message-standards`) - this means we're not
+wasting bandwidth sending the same information over the wire needlessly.
+
+This also means we'll have to grab the user in the connection handler and then
+store it in the session; thankfully, Channels ships with both a ``channel_session_user``
+decorator that works like the ``http_session_user`` decorator you saw above but
+loads the user from the *channel* session rather than the *HTTP* session,
+and a function called ``transfer_user`` which replicates a user from one session
+to another.
+
+Bringing that all together, let's make a chat server one where users can only
+chat to people with the same first letter of their username::
+
+    from channels import Channel, Group
+    from channels.decorators import channel_session
+    from channels.auth import http_session_user, channel_session_user, transfer_user
+
+    # Connected to websocket.connect
+    @channel_session
+    @http_session_user
+    def ws_add(message):
+        # Copy user from HTTP to channel session
+        transfer_user(message.http_session, message.channel_session)
+        # Add them to the right group
+        Group("chat-%s" % message.user.username[0]).add(message.reply_channel)
+
+    # Connected to websocket.keepalive
+    @channel_session_user
+    def ws_keepalive(message):
+        # Keep them in the right group
+        Group("chat-%s" % message.user.username[0]).add(message.reply_channel)
+
+    # Connected to websocket.receive
+    @channel_session_user
+    def ws_message(message):
+        Group("chat-%s" % message.user.username[0]).send(message.content)
+
+    # Connected to websocket.disconnect
+    @channel_session_user
+    def ws_disconnect(message):
+        Group("chat-%s" % message.user.username[0]).discard(message.reply_channel)
+
+Now, when we connect to the WebSocket we'll have to remember to provide the
+Django session ID as part of the URL, like this::
+
+    socket = new WebSocket("ws://127.0.0.1:9000/?session_key=abcdefg");
+
+You can get the current session key in a template with ``{{ request.session.session_key }}``.
+Note that Channels can't work with signed cookie sessions - since only HTTP
+responses can set cookies, it needs a backend it can write to separately to
+store state.
+
 
 Models
 ------
@@ -440,6 +459,72 @@ command run via ``cron``. If we wanted to write a bot, too, we could put its
 listening logic inside the ``chat-messages`` consumer, as every message would
 pass through it.
 
+Linearization
+-------------
+
+There's one final concept we want to introduce you to before you go on to build
+sites with Channels - linearizing consumers.
+
+Because Channels is a distributed system that can have many workers, by default
+it's entirely feasible for a WebSocket interface server to send out a ``connect``
+and a ``receive`` message close enough together that a second worker will pick
+up and start processing the ``receive`` message before the first worker has
+finished processing the ``connect`` worker.
+
+This is particularly annoying if you're storing things in the session in the
+``connect`` consumer and trying to get them in the ``receive`` consumer - because
+the ``connect`` consumer hasn't exited, its session hasn't saved. You'd get the
+same effect if someone tried to request a view before the login view had finished
+processing, but there you're not expecting that page to run after the login,
+whereas you'd naturally expect ``receive`` to run after ``connect``.
+
+But, of course, Channels has a solution - the ``linearize`` decorator. Any
+handler decorated with this will use locking to ensure it does not run at the
+same time as any other view with ``linearize`` **on messages with the same reply channel**.
+That means your site will happily mutitask with lots of different people's messages,
+but if two happen to try to run at the same time for the same client, they'll
+be deconflicted.
+
+There's a small cost to using ``linearize``, which is why it's an optional
+decorator, but generally you'll want to use it for most session-based WebSocket
+and other "continuous protocol" things. Here's an example, improving our
+first-letter-of-username chat from earlier::
+
+    from channels import Channel, Group
+    from channels.decorators import channel_session, linearize
+    from channels.auth import http_session_user, channel_session_user, transfer_user
+
+    # Connected to websocket.connect
+    @linearize
+    @channel_session
+    @http_session_user
+    def ws_add(message):
+        # Copy user from HTTP to channel session
+        transfer_user(message.http_session, message.channel_session)
+        # Add them to the right group
+        Group("chat-%s" % message.user.username[0]).add(message.reply_channel)
+
+    # Connected to websocket.keepalive
+    # We don't linearize as we know this will happen a decent time after add
+    @channel_session_user
+    def ws_keepalive(message):
+        # Keep them in the right group
+        Group("chat-%s" % message.user.username[0]).add(message.reply_channel)
+
+    # Connected to websocket.receive
+    @linearize
+    @channel_session_user
+    def ws_message(message):
+        Group("chat-%s" % message.user.username[0]).send(message.content)
+
+    # Connected to websocket.disconnect
+    # We don't linearize as even if this gets an empty session, the group
+    # will auto-discard after the expiry anyway.
+    @channel_session_user
+    def ws_disconnect(message):
+        Group("chat-%s" % message.user.username[0]).discard(message.reply_channel)
+
+
 Next Steps
 ----------
 

docs/message-standards.rst

@@ -11,8 +11,7 @@ In addition to the standards outlined below, each message may contain a
 separate connection and data receiving messages (like WebSockets) will only
 contain the connection and detailed client information in the first message;
 use the ``@channel_session`` decorator to persist this data to consumers of
-the received data (the decorator will take care of handling persistence and
+the received data (or something else based on ``reply_channel``).
-ordering guarantees on messages).
 
 All messages must be able to be encoded as JSON; channel backends don't
 necessarily have to use JSON, but we consider it the lowest common denominator