PHASE 5 — Topic 17: Handling Reconnection, Offline Users, and Connection State Recovery

We touched on reconnection basics back in Topic 12. Now we go deeper, into what actually happens to your data during a disconnect, and how Socket.IO can automatically restore it.

The Real Problem With Reconnection

Automatic reconnection solves getting the connection back. It does not, by itself, solve what happens to the data that was sent while the client was disconnected. Consider our chat app: if a user's WiFi drops for 10 seconds, and two messages get sent during that gap, a plain reconnect brings the socket back online, but those two messages are simply gone for that user. Nobody stored them anywhere for later delivery.

This is exactly the gap that Connection State Recovery was built to close.

What Connection State Recovery Actually Does

When enabled, Socket.IO temporarily stores a disconnected client's state on the server, so that on reconnection, it can restore:

• The socket's id
• The rooms it had joined
• Any custom data attached to the socket
• Any events it missed while disconnected

Here's how it works internally, in plain terms:

• During the handshake, the server assigns the client a private session ID, separate from the usual public socket.id
• Every event sent to the client also carries a small offset marker
• If the client disconnects, the server holds onto its state for a limited time
• When the client reconnects, it sends back its session ID and the last offset it successfully received
• If the server still has that session stored, it restores the rooms, data, and replays any events the client missed

Enabling It on the Server

This is a single option passed when creating the Socket.IO server:

    const io = new Server<
        ClientToServerEvents,
        ServerToClientEvents,
        InterServerEvents,
        SocketData
    >(httpServer, {
        path: "/api/socket",
        connectionStateRecovery: {
            maxDisconnectionDuration: 2 * 60 * 1000,
            skipMiddlewares: true,
        },
    });

• maxDisconnectionDuration controls how long the server keeps a disconnected client's state around, in milliseconds. The default is 2 minutes. If the client does not reconnect within this window, the state is discarded permanently.
• skipMiddlewares controls whether your connection middleware (which we will build in the next post) runs again during a recovery. Setting this to true lets a reconnecting client skip re-running those checks, which is convenient, but worth being careful with, since it also means a client who was, say, banned during their disconnection window could still reconnect without being re-checked. Use this setting thoughtfully.

Checking Whether Recovery Succeeded

On the server, inside your connection handler, socket.recovered tells you whether this connection is a fresh one or a restored one:

    io.on("connection", (socket) => {
        if (socket.recovered) {
            console.log("Session recovered:", socket.id);
        } else {
            console.log("New or unrecoverable session:", socket.id);
        }
    });

If socket.recovered is true, socket.rooms and socket.data are already restored automatically, you don't need to manually re-join rooms or reassign data yourself.

Checking It on the Client

The client has the same flag available:

    socket.on("connect", () => {
        console.log("Recovered?", socket.recovered);
    });

This is useful for deciding whether your UI needs to re-fetch fresh state from scratch, or whether it can trust that any missed events have already been replayed automatically.

Applying This to Our Chat App

Update server.ts to enable recovery, as shown above. Then, on the client, you can use socket.recovered to skip unnecessary re-initialization:

    socket.on("connect", () => {
        setIsConnected(true);
        if (!socket.recovered) {
            console.log("Fresh connection, state was not recoverable");
        }
    });

If a user's connection drops briefly and comes back within the recovery window, any chat messages broadcast during that gap will simply appear in their message list automatically, without you writing any manual "catch up" logic.

Important Limitations to Know

Connection state recovery is genuinely useful, but it is not a magic fix for all reconnection scenarios, and you should not treat it as one:

• It is only designed for temporary disconnections, within the configured time window, not long absences
• Storing missed packets is not compatible with the Redis Adapter's pub/sub mechanism, which we will cover in Phase 6, this matters if you scale to multiple servers later
• Real-world testing has shown edge cases, for example, switching from WiFi to mobile data does not always trigger recovery reliably, since the old connection may not register as disconnected in time on the server
• It only recovers what Socket.IO itself is aware of, rooms, socket data, and emitted events, it does not know about arbitrary application state you manage separately, like React state that was never sent through a socket event

Because of these limitations, connection state recovery should be treated as a helpful convenience layer, not a replacement for designing your application to handle reconnections and resynchronization properly at the data level.

Summary

• Connection state recovery lets Socket.IO automatically restore a client's rooms, custom data, and missed events after a short disconnection
• It is enabled with the connectionStateRecovery option on the server, controlling how long state is retained and whether middleware re-runs on recovery
• socket.recovered, available on both server and client, tells you whether a connection was restored or is brand new
• It only handles temporary disconnections within a configured time window, and has known limitations, such as unreliable behavior across network switches and incompatibility with Redis pub/sub
• It should be treated as a convenience layer, not a substitute for proper resynchronization logic in your application

In the next post, we cover authentication, making sure only logged-in users can connect to your Socket.IO server in the first place.