@insession/ws-resilient-transport

A tiny (~130 LOC), dependency-free WebSocket transport that reconnects the way a production deployment actually needs it to.

Most reconnecting-WebSocket libraries give you generic backoff. The thing that bites you in production is different: on every deploy, every client is dropped at the same instant. You want those clients back immediately (the new server instance is already up behind a healthcheck), but you do not want thousands of them reconnecting on the same millisecond and stampeding it. And when the server closes a connection for good, you want reconnection to actually stop.

This transport handles exactly that:

• Fast reconnect on service restart — a configurable close code (RFC 6455 1012 Service Restart is the conventional choice) reconnects after a short fixed delay instead of waiting out a backoff.
• Jittered exponential backoff on every other drop, capped at a maximum. Every wait carries ±jitterRatio of randomness so a fleet cut at once spreads out (no thundering herd).
• Terminal close codes — a set of codes on which the transport stops reconnecting entirely (the server has said it will never accept this connection again).
• Resume signal — the first reconnect after a service restart tells your handshake resumedFromServiceRestart: true, so the server can suppress re-join side effects (re-broadcasting presence, etc.).

Generic over message types, JSON by default, and fully injectable (WebSocket implementation, timers, RNG) for Node and deterministic tests.

Install

npm install @insession/ws-resilient-transport

Published as a built ESM package (dist/index.js + dist/index.d.ts), no runtime dependencies.

Usage

import { createResilientWebSocket } from '@insession/ws-resilient-transport';

type ClientMsg = { type: string; [k: string]: unknown };
type ServerMsg = { type: string; [k: string]: unknown };

let alive = true;

const transport = createResilientWebSocket<ClientMsg, ServerMsg>({
  url: 'wss://example.com/ws',

  // Sent as soon as each connection opens (auth / join handshake).
  buildOpenMessage: async ({ resumedFromServiceRestart }) => {
    const token = await getIdToken();
    return { type: 'join', token, resume: resumedFromServiceRestart };
  },

  onMessage: (msg) => handle(msg),
  onReconnecting: () => showStatus('reconnecting…'),
  isActive: () => alive, // return false on teardown to stop everything

  // Deploy semantics: RFC 6455 1012 = fast reconnect; 4001 = terminal.
  serviceRestartCode: 1012,
  terminalCloseCodes: [4001],
});

transport.connect();
transport.send({ type: 'chat', text: 'hi' });

// On teardown:
alive = false;
transport.close();

Server side

Nothing to install — this is just a close-code convention. On graceful shutdown, close each socket with your serviceRestartCode so clients take the fast path:

for (const ws of sockets) ws.close(1012, 'server-restart');

Pair it with a healthcheck that only reports ready once the new instance can accept connections, so the fast reconnect lands on a live server.

API

createResilientWebSocket<TSend, TRecv>(options) → { connect, send, close, socket }.

| Option | Default | Meaning | | --- | --- | --- | | url | — | Endpoint to connect to. | | onMessage(msg) | — | Called with every parsed inbound message. | | buildOpenMessage(ctx) | — | Build the first message on open. ctx.resumedFromServiceRestart is true only on the fast reconnect after a service restart. Return null/throw to send nothing. | | onReconnecting() | — | Called right before a reconnect is scheduled. | | isActive() | () => true | Gate checked before delivering messages and before reconnecting. | | reconnectDelay | 500 | Base backoff (ms) for the first normal reconnect. | | maxReconnectDelay | 15000 | Backoff cap (ms). | | serviceRestartCode | null | Close code that means "come straight back". null disables the fast path. | | serviceRestartDelay | 250 | Fast-path delay (ms). | | terminalCloseCodes | [] | Close codes on which to stop reconnecting. | | jitterRatio | 0.3 | ±fraction of jitter on every wait. | | serialize / deserialize | JSON.stringify / JSON.parse | Wire codec. | | WebSocket | globalThis.WebSocket | Implementation to use (e.g. ws in Node). | | timers | global set/clearTimeout | Injectable for tests. | | random | Math.random | Injectable RNG for deterministic tests. |

Backoff for attempt n (1-indexed) is min(reconnectDelay · 2^(n−1), maxReconnectDelay), then jittered — except the first reconnect after serviceRestartCode, which uses serviceRestartDelay.

Test

node --test

The tests use a fake WebSocket plus injected timers and RNG, so they are fully deterministic (no real sockets, no wall-clock waits).

Origin

Extracted from InSession's realtime sync layer, where it keeps synchronized watch-party sessions alive across deploys. Generalizing it meant replacing the product's protocol types with generics and turning the hard-coded close codes into configuration.

License

MIT