Reconnection

Overview

Production connections drop for reasons that have nothing to do with your application code: the broker restarts during a rolling upgrade, a load balancer fails over, a network blip severs the connection. Without built-in reconnection, every client in your fleet needs its own hand-rolled retry-connect loop, and it's easy to get the backoff wrong — too aggressive and you hammer a recovering broker, too slow and you leave the application dark longer than necessary. Automatic reconnection moves that logic into the client itself, so the connection self-heals without any code the application has to write or maintain.

It works by passing a reconnect option to KubeMQClient.create() — initialDelayMs, multiplier, maxDelayMs, maxAttempts, and jitter: 'full' to randomize retry timing and avoid a thundering herd when many clients reconnect at once. The client emits lifecycle events ('connected', 'disconnected', 'reconnecting', 'reconnected', 'stateChange', 'closed') that the application can subscribe to via client.on(...) for diagnostics, and client.state exposes the current state on demand. Gotchas: event handlers run on the client's event loop, so blocking work inside one stalls further processing; in-flight sendEvent calls made during the outage window still fail immediately — the policy governs the connection, not individual calls; and maxAttempts: -1 (unlimited) will retry forever against a broker that's gone for good, so pair it with alerting on the 'reconnecting' event's attempt counter rather than assuming it will eventually succeed.

Prerequisites

• KubeMQ server running on localhost:50000
• Node.js SDK installed (npm install kubemq-js)

Code

/**
 * Example: Automatic Reconnection with Backoff
 *
 * Demonstrates how the SDK automatically reconnects when the connection
 * is lost. The reconnection policy uses exponential backoff with jitter
 * to avoid thundering herd problems.
 *
 * Prerequisites:
 *   - KubeMQ server running on localhost:50000
 *
 * Run: npx tsx examples/error-handling/reconnection.ts
 */
import { KubeMQClient, ConnectionState, createEventMessage } from 'kubemq-js';

async function main(): Promise<void> {
  const client = await KubeMQClient.create({
    address: 'localhost:50000',
    clientId: 'js-error-handling-reconnection-client',
    // Configure reconnection behavior.
    reconnect: {
      maxAttempts: 10, // -1 for unlimited attempts
      initialDelayMs: 500, // first retry after ~500ms
      maxDelayMs: 30_000, // cap backoff at 30 seconds
      multiplier: 2.0, // double delay each attempt
      jitter: 'full', // randomize to avoid thundering herd
    },
  });

  try {
    // Listen for connection lifecycle events.
    client.on('connected', () => {
      console.log('[Event] Connected');
    });

    client.on('disconnected', () => {
      console.log('[Event] Disconnected');
    });

    client.on('reconnecting', (attempt: number) => {
      console.log(`[Event] Reconnecting (attempt ${attempt})...`);
    });

    client.on('reconnected', () => {
      console.log('[Event] Reconnected successfully');
    });

    client.on('stateChange', (state: ConnectionState) => {
      console.log(`[Event] State changed to: ${state}`);
    });

    client.on('closed', () => {
      console.log('[Event] Client closed');
    });

    // Publish some events to verify the connection is working.
    for (let i = 1; i <= 3; i++) {
      await client.sendEvent(
        createEventMessage({
          channel: 'js-error-handling.reconnection',
          body: `heartbeat-${i}`,
        }),
      );
      console.log(`Published heartbeat #${i}`);
    }

    console.log('\nConnection is active. Current state:', client.state);
    console.log('If the server restarts, the SDK will automatically reconnect.');
    console.log('Waiting 10 seconds to observe any reconnection events...');

    await new Promise((resolve) => setTimeout(resolve, 10_000));
  } finally {
    await client.close();
    console.log('Client closed. Final state:', client.state);
  }
}

main().catch(console.error);

How It Works

• The reconnect option on KubeMQClient.create() enables automatic exponential-backoff reconnection: initialDelayMs sets the first retry wait, multiplier doubles it each attempt, and jitter: 'full' adds randomization to prevent thundering-herd storms.
• The SDK emits lifecycle events ('connected', 'disconnected', 'reconnecting', 'reconnected', 'stateChange', 'closed') so the application can log diagnostics without polling client.state.
• client.on('reconnecting', (attempt) => ...) passes the zero-based attempt counter, letting you implement adaptive alerting (e.g. warn after attempt 3, page after attempt 7).
• When maxAttempts: -1 (unlimited), the SDK keeps retrying indefinitely — useful in long-running services that must survive extended server outages.

Related

• Node.js SDK Reference
• Connection Error
• Graceful Shutdown