Everything You Need to Know About WebSocketConsumer

Table of Contents show

Introduction

WebSocketConsumer is a class provided by Django Channels that allows you to write asynchronous WebSocket consumers in Django. WebSocketConsumer is built on top of the Channels layer, which in turn is built on top of the Django framework. If you are looking to build a real-time application that requires a WebSocket connection, then WebSocketConsumer is the way to go.

What is WebSocket?

WebSocket is a protocol that allows for full-duplex, two-way communication between a client and a server over a single, long-lived connection. WebSocket is designed to overcome the limitations of HTTP by providing a persistent connection between a client and a server, which allows for real-time data transfer without the overhead of HTTP requests and responses.

What is Django Channels?

Django Channels is a third-party package for Django that extends the framework to handle real-time applications. Django Channels allows you to write asynchronous code that handles WebSocket connections, which can be used to build real-time applications such as chat applications, real-time games, and more.

What is a WebSocketConsumer?

A WebSocketConsumer is a class provided by Django Channels that allows you to write asynchronous WebSocket consumers in Django. A WebSocketConsumer handles WebSocket connections and is responsible for processing incoming messages and sending outgoing messages.

Creating a WebSocketConsumer in Django

The first step in creating a WebSocketConsumer in Django is to create a new Django app. You can create a new app using the following command:

python manage.py startapp myapp

Next, you need to create a new file called consumers.py in your app directory. This file will contain your WebSocketConsumer class.

Here’s an example of a simple WebSocketConsumer:

from channels.generic.websocket import AsyncWebsocketConsumerimport jsonclass MyConsumer(AsyncWebsocketConsumer):async def connect(self):await self.accept()
async def disconnect(self, close_code):pass
async def receive(self, text_data):text_data_json = json.loads(text_data)message = text_data_json['message']
await self.send(text_data=json.dumps({'message': message}))

Let’s break down what’s happening here:

The AsyncWebsocketConsumer class is imported from the channels.generic.websocket module.
A new class called MyConsumer is defined that inherits from AsyncWebsocketConsumer.
The connect() method is called when a new WebSocket connection is established. In this example, we simply accept the connection and do nothing else.
The disconnect() method is called when a WebSocket connection is closed. In this example, we don’t need to do anything when the connection is closed.
The receive() method is called when a new message is received over the WebSocket connection. In this example, we parse the incoming message as JSON and then send it back to the client.

Routing WebSocket requests to a consumer

Once you have defined your WebSocketConsumer, you need to route WebSocket requests to it. This is done using a URL router.

Here’s an example of a URL router that routes WebSocket requests to MyConsumer:

from django.urls import re_pathfrom . import consumers
websocket_urlpatterns = [re_path(r'ws/mywebsocket/$', consumers.MyConsumer.as_asgi()),]

Let’s break down what’s happening here:

The re_path function is imported from django.urls.
The MyConsumer class is imported from the consumers module.
A new list called websocket_urlpatterns is defined.
A new URL pattern is defined using re_path. This pattern matches requests to /ws/mywebsocket/ and routes them to MyConsumer.
The as_asgi() method is called on MyConsumer to convert it to an ASGI application instance.

Connecting to a WebSocketConsumer from a client

Now that you have created a WebSocketConsumer and defined a URL route for it, you can connect to it from a client. Here’s an example of how to connect to a WebSocketConsumer using JavaScript:

var ws = new WebSocket('ws://localhost:8000/ws/mywebsocket/');ws.onmessage = function(event) {var data = JSON.parse(event.data);console.log(data);};
ws.onopen = function(event) {ws.send(JSON.stringify({'message': 'Hello, world!'}));};
ws.onclose = function(event) {console.log('Connection closed.');};

Let’s break down what’s happening here:

A new WebSocket connection is created using the URL ws://localhost:8000/ws/mywebsocket/.
The onmessage function is called whenever a new message is received over the WebSocket connection. In this example, we simply log the message to the console.
The onopen function is called when the WebSocket connection is opened. In this example, we send a new message over the WebSocket connection.
The onclose function is called when the WebSocket connection is closed. In this example, we simply log a message to the console.

WebSocketConsumer vs. WebSocketHandler

Before the release of Django Channels 2.0, WebSocketHandler was the recommended way to handle WebSocket connections in Django. WebSocketHandler is still supported in Django Channels 2.0 and later, but WebSocketConsumer is now the recommended way to handle WebSocket connections.

WebSocketHandler and WebSocketConsumer have a similar API, but WebSocketConsumer is built on top of the Channels layer, which provides additional features such as support for asynchronous code and handling multiple connections in a single process.

Conclusion

WebSocketConsumer is a powerful tool for building real-time applications in Django. With WebSocketConsumer, you can easily write asynchronous WebSocket consumers that handle WebSocket connections and process incoming messages. If you are looking to build a real-time application in Django, then WebSocketConsumer is definitely worth exploring.

FAQ

What is the difference between WebSocket and HTTP?

WebSocket is a protocol that allows for full-duplex, two-way communication between a client and a server over a single, long-lived connection. HTTP is a protocol that allows for one-way communication between a client and a server through a series of requests and responses.

What is Django Channels?

What is a WebSocketConsumer?

What is the difference between WebSocketConsumer and WebSocketHandler?

WebSocketConsumer is built on top of the Channels layer, which provides additional features such as support for asynchronous code and handling multiple connections in a single process. WebSocketHandler is still supported in Django Channels 2.0 and later, but WebSocketConsumer is now the recommended way to handle WebSocket connections.