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.
- 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
As this module can be used with node.js and browserify it's released in the
registry and can be installed using:
npm install --save recovery
As mentioned in the documentation introduction, this library provides various of reconnection and progress events. Events always receive a "status" or progress object as last argument. This object contains useful information 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
The following events are emitted during the recovery process:
||status||Scheduled a new reconnection attempt.|
||status, fn||It's time for you to reconnect to the server.|
||err, status||Failed to reconnect and ran out of attempts.|
||err, status||Failed to reconnect in a timely manner, will retry.|
In all code examples we assume that you've loaded the library using:
'use strict';var 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:
maxMaximum reconnection delay. Defaults to
minMinimum reconnection delay. Defaults to
retriesMaximum amount retries after this we will emit an
reconnect failedevent. Defaults to
reconnect timeoutTime you have to reconnect to the server. If it takes longer than the specified value we will emit an
reconnect timeoutevent and schedule another reconnection attempt. Defaults to
factorExponential back off factor. Defaults to
Options that indicate a time can either be set using a human readable string
10 ms etc. or a numeric value which represents the
time in milliseconds.
var recovery =max: '30 seconds'min: '100 milliseconds'retries: 5;
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
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
reconnected event. If all future attempts fail we will eventually emit the
reconnect failed event which basically indicates that something horrible is
recovery = ;recovery;recovery;
Alternatively you also call the callback which is provided in the
event which is the same as the
To check if a reconnection attempt is already running you can call the
reconnecting method which will return a boolean:
if !recovery recovery;
And if you wish to cancel the running reconnection attempt you can call the
if recovery recovery;