README.md

Recovery

Recovery provides randomized exponential back off for reconnection attempts. It allows you to recover the connection in the most optimal way (for both server and client). The exponential back off is randomized to prevent a DDoS like attack on your server when it's restarted, spreading the reconnection attempts instead of having all your connections attempt to reconnect at exactly the same time.

Features

• Reconnection and progress events.
• Randomized exponential back off.
• Reconnection timeouts.
• Browserify compatible.

The code base of this module was originally written for Primus but has been extracted as separate module. It has been thoroughly tested and it's written with love <3.

Installation

As this module can be used with Node.js and browserify it's released in the npm registry and can be installed using:

npm install --save recovery

Events

As mentioned in the documentation introduction, this library provides various reconnection and progress events. Events always receive a "status" or progress object as last argument. This object contains useful informations about current reconnection progress:

• attempt: Which reconnection attempt are we currently processing.
• start: Starting time of reconnection attempt.
• duration: How long have we taken so far to establish the connection.
• scheduled: In how many ms do we schedule the next reconnection attempt.

In addition to these values it also contains all the configuration options like retries, min, max etc.

The following events are emitted during the recovery process:

Event	Arguments	Description
reconnect scheduled	status	Scheduled a new reconnection attempt.
reconnect	status, fn	It's time for you to reconnect to the server.
reconnected	status	Successfully reconnected.
reconnect failed	err, status	Failed to reconnect and ran out of attempts.
reconnect timeout	err, status	Failed to reconnect in a timely manner, will retry.

Constructing

In all code examples we assume that you've loaded the library using:

'use strict';

var Recovery = require('recovery');

The module is exported as a constructor. The constructor accepts an optional options object which allows you to configure the reconnection procedure. The following options are accepted:

• max Maximum reconnection delay. Defaults to Infinity.
• min Minimum reconnection delay. Defaults to 500 ms.
• retries Maximum amount of retries. After this we will emit a reconnect failed event. Defaults to 10.
• reconnect timeout Time you have to reconnect to the server. If it takes longer than the specified value we will emit a reconnect timeout event and schedule another reconnection attempt. Defaults to 30 seconds.
• factor Exponential back off factor. Defaults to 2.

Options that indicate a time can either be set using a human readable string like 10 seconds, 1 day, 10 ms etc. or a numeric value which represents the time in milliseconds.

var recovery = new Recovery({
  max: '30 seconds',
  min: '100 milliseconds',
  retries: 5
});

Reconnecting

Before every reconnection attempt we emit a reconnect event. You can listen to this event on your assigned event emitter. After the event is emitted we will start a timeout so your attempts have only a limited amount of time to succeed or fail. If the timeout expires we emit a reconnect timeout event and start a whole new reconnection procedure.

If your reconnection attempt is successful call the recovery.reconnected() method without any arguments. If it failed you can call the method with an error argument. If the operation failed we will automatically schedule a new reconnect attempt. When it's successful we will do some small internal clean up and emit the reconnected event. If all future attempts fail we will eventually emit the reconnect failed event which basically indicates that something horrible is going on.

recovery = new Recovery();

recovery.on('reconnect', function (opts) {
  console.log(opts.attempt);

  reconnectmyconnection(function (err) {
    if (err) return recovery.reconnected(err);
    recovery.reconnected();
  });
});

recovery.reconnect();

Alternatively you can call the callback which is provided in the reconnect event which is the same as the reconnected method.

recovery.on('reconnect', function (opts, fn) {
  reconnectmyconnection(fn);
});

To check if a reconnection attempt is already running you can call the reconnecting method which will return a boolean:

if (!recovery.reconnecting()) recovery.reconnect();

And if you wish to cancel the running reconnection attempt you can call the reset method:

if (recovery.reconnecting()) recovery.reset();

License

MIT