Connection state and recovery
Connections to Ably will transition through multiple states throughout their lifecycle. States can be observed and triggered using methods available on the connection object.
Although connection state is temporary, Ably provides continuity of message delivery between a client and the service provided that a dropped connection is re-established by the client within a limited interval (typically around two minutes). After that time the connection becomes stale and the system will not attempt to recover the connection state.
An Ably SDK is responsible for managing a connection. This includes:
- Selecting a transport, when multiple transports are available.
- Selecting a new host to connect to when automatically falling back to an alternate datacenter if needed.
- Managing continuity of operation when the connection drops.
When an SDK is instantiated it will establish a connection immediately, and if the connection drops at any time it will attempt to re-establish it by making repeated connection attempts every 15 seconds for up to two minutes.
Available connection states
The different connection states are:
| State | Description |
|---|---|
initialized | A Connection object has been initialized but not yet connected. |
connecting | A connection attempt has been initiated, this state is entered as soon as an SDK has completed initialization, and is re-entered each time connection is re-attempted following disconnection. |
connected | A connection exists and is active. |
disconnected | A temporary failure condition when no current connection exists. The disconnected state is entered if an established connection is dropped, or if a connection attempt is unsuccessful. In the disconnected state an SDK will periodically attempt to open a new connection (approximately every 15 seconds), anticipating the connection will be re-established soon and connection and channel continuity will be possible. In this state, developers can continue to publish messages as they are automatically placed in a local queue, sent when connection is re-established. Messages published by other clients whilst this client is disconnected will be delivered to it when reconnected if the connection was resumed within two minutes. After two minutes have elapsed, recovery is no longer possible and the connection will move to the suspended state. Publishing: Attempting to publish while disconnected will return error code 80003. |
suspended | A long term failure condition when no current connection exists because there is no network connectivity or available host. The suspended state is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended state, an SDK will periodically attempt to open a new connection every 30 seconds. Developers are unable to publish messages in this state. A new connection attempt can also be triggered by an explicit call to connect() on the Connection object. Once the connection has been re-established, channels will be automatically re-attached. The client has been disconnected for too long for them to resume from where they left off, so if it wants to catch up on messages published by other clients while it was disconnected, it needs to use the history API. Publishing: Attempting to publish while suspended will return error code 80002. |
closing | An explicit request by the developer to close the connection has been sent to the Ably service. If a reply is not received from Ably shortly, the connection will be forcibly terminated and the connection state will become closed. |
closed | The connection has been explicitly closed by the client. In the closed state, no reconnection attempts are made automatically by an SDK, and clients may not publish messages. No connection state is preserved by the service or by an SDK. A new connection attempt can be triggered by an explicit call to connect() on the Connection object, which will result in a new connection. |
failed | This state is entered if an SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service (e.g. an attempt to connect with an incorrect API key), or some local terminal error (e.g. the token in use has expired and the SDK does not have any way to renew it). In the failed state, no reconnection attempts are made automatically by an SDK, and clients may not publish messages. A new connection attempt can be triggered by an explicit call to connect() on the Connection object. Publishing: Attempting to publish while failed will return error code 80000. |
Example connection state sequences
There are a number of potential connection state sequences, but some of the more common sequences are covered in this section.
The SDK is initialized and initiates a successful connection:
initialized → connecting → connected
An existing connection is dropped and re-established on the first attempt:
connected → disconnected → connecting → connected
An existing connection is dropped, and re-established after several attempts but within a two minute interval:
connected → disconnected → connecting → disconnected → … → connecting → connected
There is no connection established after initializing the SDK:
initialized → connecting → disconnected → connecting → … → suspended
After a period of being offline a connection is re-established:
suspended → connecting → suspended → … → connecting → connected
Listen for connection state change
The Connection object is an EventEmitter and emits an event whose name is the new state whenever there is a connection state change. An event listener function is passed a ConnectionStateChange object as the first argument for state change events.
The Connection object can also emit an event that is not a state change: an update event. This happens when there's a change to connection conditions and there is no applicable status or the state doesn't change, such as when an SDK remains connected after a reauth.