why deepstreamHub? compare us getting started faq
use cases
products
developers
company
blog contact

All deepstreamHub SDKs establish a persistent, bidirectional connection to the platform. This connection can be lost due to network outage, lack of mobile network coverage or similar problems – if this happens all SDKs will queue outgoing updates and try to re-establish the connection.

Reconnection behaviour

If a connection is lost, the client will immediately attempt to reconnect. Should that fail, it will wait a certain time and retry. Upon every unsuccessful attempt it will increment the time until the next attempt is made by a number of milliseconds specified in reconnectIntervalIncrement. For example if this is set to 2000 the first reconnection attempt will be made immediately, the second after two seconds, the next four seconds after that and so on. You can specify an upper limit to this as maxReconnectInterval. After a number of unsuccessful attempts configurable as maxReconnectAttempts the client will give up and change the connection-state to ERROR.

Heartbeats

Even if your connection is established, messages might not arrive. To check this, clients continuously send small ping-messages to the platform to make sure it’s still reachable. The platform responds to these immediately. If the client misses two consecutive responses it will change the connection-state to ERROR regardless of connectivity. You can configure how frequently these heartbeat messages are sent via heartbeatInterval (every 30 seconds by default).

Connection States

Each SDK provides the current connection-state as well as a way to listen for changes.

Connected

OPEN

The connection is established; everything is fine.

Not Connected

CLOSED

The connection was deliberately closed by the user via client.close(). No reconnection attempts will be made. The client also starts in this state, but almost immediatly switches to AWAITING_CONNECTION.

ERROR

The connection is finally declared unrecoverable, e.g. as a result from too many failed reconnection attempts or missed heartbeats. No further reconnection attempts will be made.

Intermediate States

AWAITING_CONNECTION

The client has established the physical connection and waits for the initial response from the server.

CHALLENGING

The client is currently undergoing a negotiation sequence that might result in a redirect or exchange of configuration.

AWAITING_AUTHENTICATION

State after the client was initialised, but before .login() was called.

AUTHENTICATING

State after .login() was called, but before the response from the platform is received.

An Example

const options = {
    // Reconnect after 10, 20 and 30 seconds
    reconnectIntervalIncrement: 10000,
    // Try reconnecting every thirty seconds
    maxReconnectInterval: 30000,
    // We never want to stop trying to reconnect
    maxReconnectAttempts: Infinity,
    // Send heartbeats only once a minute
    heartbeatInterval: 60000
};

const ds = deepstream('wss://123.deepstreamhub.com?apiKey=xxx', options );
ds.login()

// Assume we're updating a green/yellow/red indicator for connectionState with jQuery
const connectionStateIndicator = $( '#connection-state-indicator' );
ds.on( 'connectionStateChanged', connectionState => {
    connectionStateIndicator.removeClass( 'good neutral bad' );
    if( connectionState === 'OPEN' ) {
        connectionStateIndicator.addClass( 'good' );
    } else if( connectionState === 'OPEN' || connectionState === 'ERROR' ) {
        connectionStateIndicator.addClass( 'bad' );
    } else {
        connectionStateIndicator.addClass( 'neutral' );
    }
});