Creating a chat with Django Channels

Redis

- Hey, wait a minute! Why do we need Redis? We came here to read about websockets. - The typical reader.

- Django-channels are not only about websockets. - Anonymous

Django-channels consist of three components:

• Interface servers - which handle requests (WSGI and ASGI) and put them in a queue.
• Channels- is a first-in first-out queue for messages that need to be stored in data structures such as Redis, IPC etc. The message can be delivered only to one listener, message delivery order depends only on its getting into the queue.
• Workers - monitor channels and handle requests.

For more detailed information, see documentation;

Note that such architecture can scale horizontally the app. You can vary the number of processes for each component and run them on separate servers.

Let’s configure django-channels so that it will use the above-mentioned redis as the channel storage.

We will add the following lines to multichat/settings.py:

We will create multichat/routing.py (next to settings.py) and add a basic message handler. For example we will display text of a received message in the console. The file will look like this:

Also, it was needed to initialize the django-channels routing.

Now let’s make a digression and check whether it all works.

For this we will need any websocket client.

Now let’s run the Django web server ./manage.py runserver, as well as open the interactive session interpreter in a parallel window:

First of all, let’s join our websocket, django-channels runs it by default on the same the url, but the protocol ws/wss is used depending on whether encryption is used or not, so in our case the address of the connection is ws://localhost:8000. We are connecting:

If we take a look at our web server logs, we'll see something like this:

So it means we have successfully connected. Now, let’s try to send a message:

As we can see, the message has been duplicated in our server log:

Profit!

Authorization

Let’s create a template for our future application:

Now let’s add it to the INSTALLED_APPS:

Then, add a base template and some styles.

Create static/main.css style file with the following content.

It is now up to the basic template templates/base.html:

We will expand it later.

Let’s work with a homepage, we will create a template templates/index.html for it:

But so that we could get to it, let's add a corresponding view in the chat/views.py, here's what you should get in the end:

Now let's add it to the multichat/urls.py:

We have a homepage. For logout and login we use the built-in view from contrib.auth:

By default, django.contrib.auth.views.login view uses a template registration/login.html, which we have not set yet. We’ll create templates/registration/login.html with the following content:

Now, to enable the user to get on the home page after logging in, we need to add the following line in the multichat/settings.py:

LOGIN_REDIRECT_URL = "/"

The same for logout:

LOGOUT_REDIRECT_URL = "/"

That’s all. Let's go to the main page and verify our authorization, enter your user data which was created earlier:

Voila:

Rooms

Let's talk about rooms, each room can have its own name, also it would be nice to be able to create separate rooms where only superusers can enter. Let’s add a ‘Room’ class to chat/models.py:

Create and run the migrations:

It would be nice to provide the possibility of adding them, for this we can certainly create a separate page, provide access rights etc., but it is easier to just use django admin control panel. Add the following line in the chat/admin.py:

Voila, now we can create, edit and delete via django standard admin control panel.

Let’s add displaying of registered rooms list on our home page, for this we add a queryset with rooms to the home page context:

Then we can display them in the templates/index.html (do not forget to envisage the absence of rooms, in this case you can simply ask the user to add them with reference to django):

Event handlers

The handlers may include such events as: a user connection or disconnection from the websocket, data sending to the websocket. We also need to keep track of when the user logs into the chat, disconnects from it and sends a message.

User connects to the websocket

When a user connects to the websocket, first of all we have to identify it. In this case there is a decorator channel_session_user_from_http in the django-channels arsenal, but how does it work? This decorator takes a user from http session and inserts it into the channel-base session (which uses the django standard SESSION_ENGINE documentation), after which it will be available in the message.user attribute.

We must also take care of creating a channel_session rooms for the user. It is necessary to be able to subscribe the user to the events in a particular room.

To do this, we’ll create a chat/consumers.py file and declare ws_connect function in it:

User disconnects from the websocket

When a user disconnects from the websocket, we need to clean up his opening session. To identify the user, we’ll need the channel_session_user which adds user instance to the received message, based on the user ID from the channel session. Unlike channel_session_user_from_http, it turns on channel session implicitly.

In order to provide a possibility to send a message to all users who are in a particular room, django-channels provides an excellent opportunity to group channels (more details here).

Let’s add the models Room method websocket_group, which will return a unique channels.Group for each room through id:

Now let’s add the following lines into chat/consumers.py:

Message Processing

For comfortable work we will send the data in the form of json, so when you receive a message, we will parse json, and send the received data into the channel.

Let’s add the following lines into chat/consumers.py:

User logged into the chat

One of the important features of our app is the ability to enter a specific chat room, but what will happen if an unauthorized user tries to do it? and what if the requested room does not exist? or if the user has no rights to enter this room at all? That's right, an error will occur! And in the first two cases, it will clearly be thrown at the system level, and in the third case the user will likely get to the secret room. To prevent such a trouble from happening, you need to add error handling.

Let's create chat/exceptions.py file and declare ClientError class in it:

In the future, if any error occurs, when using this class we will notify the client-side. Now let's create chat/utils.py and declare decorators needed for error handling there.

Since we want to notify users about something, let's add some gradation of messages by a level of importance. To do this, let's create a chat/settings.py, where we define the types of messages:

Also, we will need a simple way to deliver a message of any content to all users connected to this room. To do this, let’s add the send_message method the Room class, after that it will be as follows:

Add the following lines into chat/consumers.py:

User left the chat

Let’s add the following lines into chat/consumers.py:

User sent a message

Let’s add the following lines to chat/consumers.py:

Connecting handlers

After previous actions our chat/consumers.py should look as follows:

Let’s create chat/routing.py and add declared signals there:

And now we’ll add routing that we have created in the main multichat/routing.py, after which it will look as follows multichat/routing.py:

Chat!

We have written a lot of things on the backend, but where is the chat itself? So, let's create a front end part.

Firstly, we’ll create static/main.js, where we will be coding. Let’s connect it, also we will need jquery and any library to reconnect to websocket. In this example we will use ReconnectingWebSocket. We open our templates/index.html and append the following lines:

And also do not forget to create several rooms, I'm sure that if you are reading this article, then you know how to use Django admin panel for sure :)

Now it is possible to code a chat, as we know, only the authorized user can get into this page, so we will not make any further checks in this regard (but if you decide to use this code in production, the additional check on the front end will be useful).

Connecting to the socket

Why do we use ReconnectingWebSocket? Everything is very simple. With this library, WebSocket will be automatically re-connected after calling the onclose event. I just want to note that reconnection does not start immediately, but with a small delay that can be adjusted by transmitting value in milliseconds to the designer of the reconnectInterval class. If you want, you can specify timeoutInterval. But will it work if we lose the connection? I don’t think so. :)

Let’s connect to our socket:

Stop, stop, stop. This code will be difficult to debug, let's display in the event console, such as the attempt to connect, the client is successfully connected and disconnected from the socket. WebSocket provides the ability to define onopen and onclose methods, which will be called when the connection is successful, or when there is disconnection from the server. As a result, we get something like this:

Let's open the console, reload the page and see what we've got. If you see the following lines, then life is good:

Connecting and disconnecting from the rooms

It's time to add the possibility to connect and disconnect from a particular room. We do not want to bother with page making, this article has purely training nature, so we will add the necessary elements directly from js. Is it good or bad? Within this training material - it is acceptable, especially when reading these lines, you understand that we are sorry for what we’ve done.

And so, as the WebSocket provides duplex communication, we can send data to a server, socket.send method is used for it. This method accepts any string and sends it through the WebSocket to the server. As you can remember, our message handler expects to receive JSON - let’s not disappoint it, we will wrap a dictionary with the data in JSON.stringify.

Let’s add the following code to the static/main.js:

Let's take a look at our Code carefully and think what we are lack of. There is no processing of responses from the server. It will help us in the onmessage event, whenever any kind of information is received, the socket.onmessage method will be called.

As a parameter it receives a message, and as you can remember, we expect to get valid json which we have to parse. Also, we should take into account the processing errors from the server, in this training material we will just show an error as an alert for a user. So, let’s add the following code:

You have the right to fully control the data returned in the response, see message.reply_channel.send in chat/consumers.py.

Let's check what we've got. Make sure that the console is open, refresh the page and try clicking once on the room button to connect to it and disconnect from it. Everything is fine, if you see the following lines in the console:

Sending and receiving messages

Our work with the chat proceeds, there is not much left to do - we will add the possibility to send and receive messages. We’ll begin with sending of course.

As you can see in the previous chapter, when we get the information from the server about the successful connection to the room, we add a form with an input field of the message text and a button to send it in our template. Now let's hung the submit event handler on it, with which we will send the text input field entered in WebSocket. Add the following code:

I think that if you've read up to this point, then the code seems rather obvious and there is no need in further explanation.

We need to display messages received from users who are with us in the same room. Let’s renew our onmessage:

The final static/main.js will look like this:

In it we are trying to define a user’s message, and depending on the type, display the message.

Well, that's all, our chat is ready and it even can be used. :)

All code shown in this tutorial material was taken from here, it has only minor cosmetic changes.

Also you can find it in our repository.

Conclusion

The django-channels framework is designed to simplify the developer's life, bringing the WebSockets and HTTP2 support in the world of simple and ordinary HTTP 1.1. Using this library allows to standardize the communication with WebSocket, and standardization of our work is very important. Among other things, this library allows horizontal scaling, as well as does not create any problems associated with asynchrony.