WebSockets & Realtime Systems Programming · Lesson

Handling Disconnections and Reconnects

Implement client-side and server-side logic for detecting disconnections and automatically attempting reconnection.

Handling Disconnections and Reconnects is a free WebSockets & Realtime Systems Programming lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the WebSockets & Realtime Systems Programming learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Connections Drop

In the real world, network connections aren't always perfect. WebSockets, despite being persistent, can break due to many reasons.

Ignoring these disconnections can lead to unresponsive applications and a poor user experience. This lesson explores how to gracefully handle these interruptions.

Causes of Connection Loss

What makes a WebSocket connection drop?

Network Issues: Wi-Fi drops, internet outages, proxy problems.
Server Restarts: The server application might restart for updates or maintenance.
Client Offline: The user closes their browser, loses power, or puts their device to sleep.
Idle Timeouts: Some proxies or firewalls might close idle connections.

Client Detects Disconnects

On the client side, the browser's native WebSocket API provides events to notify you about connection status changes.

The most important event for detecting a disconnection is the onclose event. It fires when the connection is either gracefully closed by the server or abruptly lost.

Simple Reconnect Attempt

When onclose fires, you can immediately try to reconnect. This simple approach works for temporary glitches but can be problematic.

Try running this basic client-side example:

let ws;
function connect() {
  ws = new WebSocket("ws://localhost:8080");

  ws.onopen = () => console.log("Connected!");
  ws.onmessage = (event) => console.log("Received:", event.data);
  ws.onerror = (error) => console.error("WebSocket Error:", error);

  ws.onclose = () => {
    console.log("Disconnected. Reconnecting...");
    setTimeout(connect, 1000); // Try again in 1 second
  };
}
connect();

Why Simple Retries Fail

Continuously trying to reconnect immediately (e.g., every 1 second) can overwhelm both the client and the server.

Client Resource Drain: Constant connection attempts consume CPU and network resources.
Server Overload: If many clients disconnect and then flood the server with reconnect requests, it can lead to a Denial of Service (DoS) situation.
No Backoff: It doesn't account for prolonged outages.

Smart Reconnection: Backoff

To prevent overloading and provide a better experience, we use reconnection backoff strategies.

A backoff strategy introduces delays between reconnection attempts, and these delays typically increase with each failed attempt. This gives the server time to recover and prevents a "thundering herd" problem.

Exponential Backoff Logic

Exponential backoff is a common and effective strategy. It means the delay between retries increases exponentially.

First retry: 1 second
Second retry: 2 seconds
Third retry: 4 seconds
Fourth retry: 8 seconds

You usually cap the maximum delay to prevent excessively long waits and add some random "jitter" to avoid synchronized retries.

Client with Exponential Backoff

Let's enhance our client-side code to use exponential backoff with a maximum delay and some random jitter. Try running it!

let ws;
let reconnectInterval = 1000; // Start with 1 second
const maxReconnectInterval = 30000; // Max 30 seconds
let reconnectTimer;

function connect() {
  ws = new WebSocket("ws://localhost:8080");

  ws.onopen = () => {
    console.log("Connected!");
    reconnectInterval = 1000; // Reset on successful connection
    clearTimeout(reconnectTimer);
  };
  ws.onmessage = (event) => console.log("Received:", event.data);
  ws.onerror = (error) => console.error("WebSocket Error:", error);

  ws.onclose = () => {
    console.log(`Disconnected. Retrying in ${reconnectInterval / 1000}s...`);
    reconnectTimer = setTimeout(connect, reconnectInterval);
    reconnectInterval = Math.min(reconnectInterval * 2, maxReconnectInterval);
    // Add some random jitter (e.g., +/- 10%) for better distribution
    reconnectInterval += (Math.random() - 0.5) * reconnectInterval * 0.2;
    reconnectInterval = Math.floor(reconnectInterval);
  };
}
connect();

Server-Side Disconnects

The server also needs to know when a client disconnects. This is crucial for cleaning up resources, updating connected user lists, or stopping data streams for that client.

Using a library like ws in Node.js, the WebSocket server emits a 'close' event on the individual client connection object when it disconnects.

Server Cleanup on Disconnect

Here's a basic Node.js WebSocket server example showing how to handle client disconnections and remove them from an active connections list.

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

let clients = new Set();

wss.on('connection', function connection(ws) {
  clients.add(ws);
  console.log('Client connected. Total:', clients.size);

  ws.on('message', function incoming(message) {
    console.log('received: %s', message);
  });

  ws.on('close', function close() {
    clients.delete(ws);
    console.log('Client disconnected. Total:', clients.size);
  });

  ws.send('Welcome!');
});

console.log('WebSocket server started on port 8080');

Check Your Understanding

Consider a client-side WebSocket application that needs to handle disconnections robustly.

Which of the following are good practices for implementing a reconnection strategy?

Recap: Robust Connections

We've explored how crucial it is to handle disconnections in realtime applications. Both client and server play a role in maintaining connection resilience.

Clients use onclose to detect disconnections.
Exponential backoff with jitter and a max delay prevents server overload during reconnections.
Servers use on('close') to clean up resources when clients leave.

These strategies ensure your realtime apps remain responsive and reliable, even in unstable network conditions.

Frequently asked questions

Is the “Handling Disconnections and Reconnects” lesson free?

Yes — the full text of “Handling Disconnections and Reconnects” is free to read here on the web, and the WebSockets & Realtime Systems Programming course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the WebSockets & Realtime Systems Programming course, upgrade to CoddyKit PRO.

What will I learn in “Handling Disconnections and Reconnects”?

Implement client-side and server-side logic for detecting disconnections and automatically attempting reconnection. You practise WebSockets & Realtime Systems Programming with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start WebSockets & Realtime Systems Programming?

No prior experience is required. WebSockets & Realtime Systems Programming on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Handling Disconnections and Reconnects” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this WebSockets & Realtime Systems Programming lesson?

Yes. Every WebSockets & Realtime Systems Programming lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Handling Disconnections and Reconnects
Robust Error Propagation and Recovery
Heartbeats and Keep-Alives
Message Acknowledgement and Delivery Guarantees

← Back to WebSockets & Realtime Systems Programming