Connection
Connection Properties
The Connection object exposes the following public properties:
id
A unique public identifier String for this connection, used to identify this member in presence events and messages.
state
The current state String of this Connection. See the Connection states for more information.
errorReason
When a connection failure occurs this property contains the ErrorInfo.
key
A unique private connection key String used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the recoveryKey is used in the recover client options as it contains both the key and the last message serial.
This private connection key can also be used by other REST clients to publish on behalf of this client. See the publishing over REST on behalf of a realtime client documentation for more info.
Connection Methods
connect
connect(): void
Explicitly calling connect is unnecessary unless the ClientOptions attribute autoConnect is false. Unless already connected or connecting, this method causes the connection to open, entering the connecting state.
close
close(): void
Causes the connection to close, entering the closing state. Once closed, the library will not attempt to re-establish the connection without an explicit call to connect().
on
There are three overloaded versions of this method:
on(String event, listener(ConnectionStateChange stateChange))
Register the given listener listener for the specified ConnectionEvent on the Connection. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the event or state change.
on(String[] events, listener(ConnectionStateChange stateChange))
Same as above, but registers multiple listeners, one for each event in the array.
on(listener(ConnectionStateChange stateChange))
Register the given listener listener for all ConnectionEvents on the Connection. The listener is passed a ConnectionStateChange object that contains the current state, previous state, the event, and an optional reason for the event or state change. (For the update event, the current and previous states will be the same).
If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at error level, so as not to affect other listeners for the same event
Parameters
| Parameter | Description | Type |
|---|---|---|
| event(s) | the connection event(s) to subscribe to | String or String[] |
| listener | is a function of the form function(stateChange) to be notified for matching events | function |
once
There are two overloaded versions of this method:
once(String event, listener(ConnectionStateChange stateChange))
Register the given listener listener for a single occurrence of the specified ConnectionEvent on the Connection. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a ConnectionStateChange object that contains the current state, previous state, the event, and an optional reason for the state change. (For the update event, the current and previous states will be the same).
once(listener(ConnectionStateChange stateChange))
Register the given listener listener for a single occurrence of any ConnectionEvent on the Connection. Once the listener has been called, it is removed as a registered listener and will not be called again. The listener is passed a ConnectionStateChange object that contains the current state, previous state, and an optional reason for the state change. (For the update event, the current and previous states will be the same).
If an exception is thrown in the listener and bubbles up to the event emitter, it will be caught and logged at error level, so as not to affect other listeners for the same event
Parameters
| Parameter | Description | Type |
|---|---|---|
| event(s) | the connection event(s) to subscribe to | String or String[] |
| listener | is a function of the form function(stateChange) to be notified for a single occurrence of a matching event | function |
off
There are six overloaded versions of this method:
off(String event, listener)
Remove the given listener listener for the ConnectionEvent.
off(listener)
Remove the given listener listener for all ConnectionEvents
off(String[] states, listener)
Removes the given listener from all ConnectionEvents in the array.
off(String state)
Removes all listeners for a given ConnectionEvents.
off(String[] states)
Removes all listeners for all ConnectionEvents in the array.
off()
Removes all listeners (including both those registered against specific events and those registered without an event).
Parameters
| Parameter | Description | Type |
|---|---|---|
| event(s) | the connection event(s) to unsubscribe from | String or String[] |
| listener | is the listener function to be removed | function |
ping
ping(): Promise<Number>
When connected, sends a heartbeat ping to the Ably server and executes the callback with any error and the response time in milliseconds when a heartbeat ping request is echoed from the server. This can be useful for measuring true round-trip latency to the connected Ably server.
Returns
Returns a promise. On success, the promise resolves with a number representing the time in seconds for the heartbeat ping request to be echoed. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
listeners
listeners(eventName?): null | connectionEventCallback[]
Returns the listeners for the specified ConnectionEvent.
whenState
whenState(targetState): Promise<null | ConnectionStateChange>
If the connection is already in a given state, returns a promise which immediately resolves to null. Otherwise calls once to return a promise which resolves the next time the connection transitions to the given state.
Parameters
| Parameter | Description | Type |
|---|---|---|
| targetState | The ConnectionState to wait for | ConnectionState |
Returns
Returns a promise. If the connection is already in the given state, the promise will immediately resolve to null. If not, it will call once() to return a promise which resolves the next time the connection transitions to the given state.
createRecoveryKey
createRecoveryKey(): null | string
Generates a string that can be used by another client to recover the current connection's state using the recover property of the ClientOptions object. See connection state recover options for more information.
Related types
ConnectionState
ConnectionState is a String with a value matching any of the Realtime Connection states.
1
2
3
4
5
6
7
8
9
10
var ConnectionStates = [
'initialized',
'connecting',
'connected',
'disconnected',
'suspended',
'closing',
'closed',
'failed'
]ConnectionEvent
ConnectionEvent is a String that can be emitted as an event on the Connection object; either a Realtime Connection state or an update event.
1
2
3
4
5
6
7
8
9
10
11
var ConnectionEvents = [
'initialized',
'connecting',
'connected',
'disconnected',
'suspended',
'closing',
'closed',
'failed',
'update'
]ConnectionStateChange Object
A ConnectionStateChange is a type encapsulating state change information emitted by the Connection object. See Connection#on to register a listener for one or more events.
Properties
| Property | Description | Type |
|---|---|---|
| current | the new state | State String |
| previous | the previous state. (for the update event, this will be equal to the current state) | State String |
| event | the event that triggered this state change | ConnectionEvent |
| reason | an ErrorInfo containing any information relating to the transition | ErrorInfo |
| retryIn | Duration upon which the library will retry a connection where applicable, as milliseconds | Integer |
LastConnectionDetails
A LastConnectionDetails object provides details on the last connection in a browser environment persisted when the window beforeunload fired. This object is provided to the callback specified in the recover attribute of ClientOptions. The callback in turn instructs the client library whether the connection should be recovered or not. See connection state recovery for more information.
Please note that as sessionStorage is used to persist the LastConnectionDetails between page reloads, it is only available for pages in the same origin and top-level browsing context.
Properties
| Property | Description | Type |
|---|---|---|
| recoveryKey | An opaque string obtained from the recoveryKey attribute of the Connection object before the page was unloaded. This property is used by the library to recover the connection | String |
| disconnectedAt | the time at which the previous library was abruptly disconnected before the page was unloaded. This is represented as milliseconds since epoch | Integer |
| location | a clone of location object of the previous page's document object before the page was unloaded. A common use case for this attribute is to ensure that the previous page URL is the same as the current URL before allowing the connection to be recovered. For example, you may want the connection to be recovered only for page reloads, but not when a user navigates to a different page | String |
| clientId | the clientId of the client's Auth object before the page was unloaded. A common use case for this attribute is to ensure that the current logged in user's clientId matches the previous connection's clientId before allowing the connection to be recovered. Ably prohibits changing a clientId for an existing connection, so any mismatch in clientId during a recover will result in the connection moving to the failed state | String |