From 2ff6388ef2334c770f7f5b614d92bdb9f386bd01 Mon Sep 17 00:00:00 2001 From: Maik Hoepfel Date: Thu, 19 Nov 2015 14:08:14 +0100 Subject: [PATCH] Changes after PR review --- docs/concepts.rst | 8 ++++---- docs/getting-started.rst | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/concepts.rst b/docs/concepts.rst index 9d21582..fbe4275 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -11,7 +11,7 @@ which allow websites to communicate outside of this traditional cycle. And, beyond that, there are plenty of non-critical tasks that applications could easily offload until after a response as been sent - like saving things -into a cache, sending emails or thumbnailing newly-uploaded images. +into a cache or thumbnailing newly-uploaded images. Channels changes the way Django runs to be "event oriented" - rather than just responding to requests, instead Django responses to a wide array of events @@ -38,7 +38,7 @@ alternative is *at-least-once*, where normally one consumer gets the message but when things crash it's sent to more than one, which is not the trade-off we want. -There are a couple of other limitations - messages must be JSON serialisable, +There are a couple of other limitations - messages must be JSON serializable, and not be more than 1MB in size - but these are to make the whole thing practical, and not too important to think about up front. @@ -121,7 +121,7 @@ However, the key here is that you can run code (and so send on channels) in response to any event - and that includes ones you create. You can trigger on model saves, on other incoming messages, or from code paths inside views and forms. That approach comes in handy for push-style -code - where you use HTTP2's server-sent events or a WebSocket to notify +code - where you use HTML5's server-sent events or a WebSocket to notify clients of changes in real time (messages in a chat, perhaps, or live updates in an admin as another user edits something). @@ -239,7 +239,7 @@ start thinking about them. Remember, Django provides some channels but you're free to make and consume your own, and all channels are network-transparent. -One thing channels do not, however, is guaranteeing delivery. If you need +One thing channels do not, however, is guarantee delivery. If you need certainty that tasks will complete, use a system designed for this with retries and persistence (e.g. Celery), or alternatively make a management command that checks for completion and re-submits a message to the channel diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 61bd9a2..e11b0db 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -30,7 +30,7 @@ Make a new project, a new app, and put this in a ``consumers.py`` file in the ap message.reply_channel.send(response.channel_encode()) The most important thing to note here is that, because things we send in -messages must be JSON serialisable, the request and response messages +messages must be JSON serializable, the request and response messages are in a key-value format. There are ``channel_decode()`` and ``channel_encode()`` methods on both Django's request and response classes, but here we just use the message's ``content`` attribute directly for simplicity @@ -240,7 +240,7 @@ Persisting Data Echoing messages is a nice simple example, but it's skirting around the real design pattern - persistent state for connections. Let's consider a basic chat site where a user requests a chat room upon initial -connection, as part of the query string (e.g. ``https://host/websocket?room=abc``). +connection, as part of the query string (e.g. ``wss://host/websocket?room=abc``). The ``reply_channel`` attribute you've seen before is our unique pointer to the open WebSocket - because it varies between different clients, it's how we can @@ -462,7 +462,7 @@ 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. -Linearisation +Linearization ------------- There's one final concept we want to introduce you to before you go on to build