Configuring Failover and Reconnection with the StreamHub JavaScript API

Introduction

The latest version of StreamHub Comet Server (2.0.6) includes the ability to configure failover and reconnection in the JavaScript API. This article covers the basics of configuring a StreamHub connection to use failover. Which scripts to include and how to get started with StreamHub are not covered in this article. If you're new to StreamHub I recommend you start with the Getting Started Guide.

The New Connect Method

The connect method is now overloaded to take two types of argument, a string URL, or a JavaScript object with the failover configuration parameters. First of all, the new method is completely backwards compatible, so you will not need to change any code like below, which uses the old method of connecting:

var hub = new StreamHub();
hub.connect("http://push.example.com/");

The above configures a connection with no failover, but it does have, by default, reconnection behaviour. The default reconnection behaviour is upon connection loss to attempt to reconnect to the URL every second until the connection is re-established. This provides a quick and seamless reconnection for when the server becomes reachable again. If this isn't what you need, you'll want to make use of the new connect method. The example below uses the exact same method, but this time we pass in an anonymous JavaScript object specifying different reconnection and failover behaviour:

var hub = new StreamHub();
hub.connect({
 serverList:                  ["http://primary.example.com/",
                              "http://secondary.example.com/"],
 failoverAlgorithm:           "ordered",
 initialReconnectDelayMillis: 2000
});

Firstly, in the configuration object we specify a serverList as an array of string URLs. This is a list of StreamHub servers to which a connection can be made. The first server in the list will always be the one which is connected to first. If the connection is the lost, the failoverAlgorithm option specifies which server to try next. In this case, we use "ordered", which means proceed down the serverList in order, attempting to connect to each server in turn until a connection is successfully established. Finally, the initialReconnectDelayMillis specifies how long to wait between each reconnection attempt. Here we specify 2000 ms (2 seconds). For reference, all of these configuration options and more are documented in the JSDOC for StreamHub.connect(config).

Exponential BackOff and Limiting the Number of Reconnections

Now for a more advanced example demonstrating exponential backoff, a feature you may have seen in some JMS implementations:

var hub = new StreamHub();
hub.connect({
 serverList:                  ["https://push1.example.com/",
                              "https://push2.example.com/",
                              "https://push3.example.com/"],
 failoverAlgorithm:           "ordered",
 initialReconnectDelayMillis: 1000,
 maxReconnectDelayMillis:     30000,
 useExponentialBackOff:       true,
 backOffMultiplier:           2
});

In the above example, we've introduced a backOffMultiplier and a maximum reconnection delay. The back off feature allows you to increase the wait between each reconnection attempt over time, in this case by a multiple of 2. The best way to demonstrate how this works is with an example:

1. Client successfully connects to https://push1.example.com/


2. Client loses connection


3. Client waits 1000ms


4. Client fails to reconnect to https://push2.example.com/


5. Client waits 2000ms


6. Client fails to reconnect to https://push3.example.com/


7. Client waits 4000ms


8. Client fails to reconnect to https://push1.example.com/


9. ...

This will continue until the wait time reaches 30000ms, since this is the maxReconnectDelayMillis we specified. The reconnection attempts will still continue but with a wait time of 30000ms. To limit the number of reconnection attempts we must use the maxReconnectAttempts option, this specifies a maximum number of reconnects to attempt before giving up:

var hub = new StreamHub();
hub.connect({
 serverList:                  ["https://push1.example.com/",
                              "https://push2.example.com/",
                              "https://push3.example.com/"],
 failoverAlgorithm:           "ordered",
 initialReconnectDelayMillis: 1000,
 maxReconnectDelayMillis:     30000,
 maxReconnectAttempts:        30,
 useExponentialBackOff:       true,
 backOffMultiplier:           2
});

That's it, a quick overview of the reconnection and failover configuration available in the StreamHub JS API. As mentioned earlier in the article, for detailed coverage of all the options, refer to the JSDOC for StreamHub.connect(config).