Merge pull request #204 from ably/rtn15h2-and-connection-states

Rtn15h2 and connection states

Author: SimonWoolf

textile/features.textile

@@ -450,6 +450,15 @@ h3(#realtime-connection). Connection
 ** @(RTN2f)@ The API version param @v@ must be included in all connections to Ably endpoints. The value to be sent is defined by "@CSV2@":#CSV2.
 ** @(RTN2g)@ The library and version (in the form described in "RSC7b":#RSC7b) should be included as the value of a @lib@ querystring param. For example, the 1.0.0 version of the JavaScript library would use the param @lib=js-1.0.0@
 * @(RTN3)@ If connection option @autoConnect@ is true, a connection is initiated immediately; otherwise a connection is only initiated following an explicit call to @connect()@
+* @(RTN27)@ The Connection is a state machine and implements the following states, which are mutually exclusive and exhaustive:
+** @(RTN27a)@ @INITIALIZED@ - the initial state of the connection. The library never transitions back to @INITIALIZED@ from any other state.
+** @(RTN27b)@ @CONNECTING@ - the state whenever the library is actively attempting to connect to the server (whether trying to obtain a token, trying to open a transport, or waiting for a @CONNECTED@ event).
+** @(RTN27c)@ @DISCONNECTED@ - a state where the library is not connected to the server and is not actively attempting to become connected, but where a reconnect attempt is scheduled in the future after the @TO3l1@ @disconnectedRetryTimeout@ elapses, and where if the library was previously connected, the next connect attempt  will be an @RTN15b@ resume attempt.
+** @(RTN27d)@ @SUSPENDED@ - a state where the library is not connected to the server and is not actively attempting to become connected, but where a reconnect attempt is scheduled in the future after the @TO3l2@ @suspendedRetryTimeout@ elapses, and where next connect attempt is a clean connection (not a resume attempt).
+** @(RTN27e)@ @CONNECTED@ - the state whenever the library is connected to the server (there is a transport currently active which has received a @CONNECTED@ @ProtocolMessage@).
+** @(RTN27f)@ @CLOSING@ - the state when the user has requested the library @close()@, and the library is waiting for a @CLOSE@ to be received on the active transport.
+** @(RTN27g)@ @CLOSED@ - the state when the library has been explicitly closed by the user, and there is no active transport.
+** @(RTN27h)@ @FAILED@ - the state when the library has encountered a failure condition it cannot recover from. It will remain in this state indefinitely, unless and until an explicit call to @connect()@ is made.
 * @(RTN4)@ The @Connection@ implements @EventEmitter@ and emits @ConnectionEvent@ events, where a @ConnectionEvent@ is either a @ConnectionState@ or @UPDATE@, and a @ConnectionState@ is either @INITIALIZED@, @CONNECTING@, @CONNECTED@, @DISCONNECTED@, @SUSPENDED@, @CLOSING@, @CLOSED@, or @FAILED@
 ** @(RTN4a)@ It emits a @ConnectionState@ @ConnectionEvent@ for every connection state change
 ** @(RTN4h)@ It emits an @UPDATE@ @ConnectionEvent@ for changes to connection conditions for which the @ConnectionState@ (e.g. @CONNECTED@) does not change. (The library must never emit a @ConnectionState@ @ConnectionEvent@ for a state equal to the previous state)
@@ -506,9 +515,11 @@ h3(#realtime-connection). Connection
 * @(RTN15)@ @Connection@ failures once @CONNECTED@:
 ** @(RTN15h)@ If a @DISCONNECTED@ message is received from Ably, then that transport will subsequently be closed by Ably
 *** @(RTN15h1)@ If the @DISCONNECTED@ message contains a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) and the library does not have a means to renew the token, the connection will transition to the @FAILED@ state and the @Connection#errorReason@ will be set
-*** @(RTN15h2)@ If the @DISCONNECTED@ message contains a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) and the library has the means to renew the token, a single attempt to create a new token should be made and a new connection attempt initiated using the new token. If the token creation fails or the next connection attempt fails due to a token error, the connection will transition to the @DISCONNECTED@ state and the @Connection#errorReason@ will be set.
+*** @(RTN15h2)@ If the @DISCONNECTED@ message contains a token error (@statusCode@ value of 401 and error @code@ value in the range @40140 <= code < 40150@) and the library has the means to renew the token, the library must initiate an immediate reconnect attempt, by transitioning to the @CONNECTING@ state, making an attempt to obtain a new token, and initiating an @RTN15b@ resume attempt to the server using that token. If the token creation fails or the next connection attempt fails due to a token error, the connection must transition to the @DISCONNECTED@ state and set the @Connection#errorReason@.
+**** @(RTN15h2i)@ The library MAY briefly transition through the @DISCONNECTED@ state on its way from the @CONNECTED@ to @CONNECTING@. (There is no need for an SDK need to implement this behaviour if it is not already present).
+*** @(RTN15h3)@ If the @DISCONNECTED@ message contains an error other than a token error, the library must initiate an immediate reconnect attempt, by transitioning into the @CONNECTING@ state and initiating an @RTN15b@ resume attempt.
 ** @(RTN15i)@ If an @ERROR@ @ProtocolMessage@ is received, this indicates a fatal error in the connection. The server will close the transport immediately after. The client should transition to the @FAILED@ state triggering all attached channels to transition to the @FAILED@ state as well. Additionally the @Connection#errorReason@ should be set with the error received from Ably
-** @(RTN15a)@ If a @Connection@ transport is disconnected unexpectedly or because a token has expired, then the @Connection@ manager will immediately attempt to reconnect and restore the connection state. Connection state recovery is provided by the Ably service and ensures that whilst the client is disconnected, all events are queued and channel state is retained on the Ably servers. When a new connection is made with the correct connection recovery key, the client is able to catch up by receiving the queued @ProtocolMessages@ from Ably.
+** @(RTN15a)@ If a transport is disconnected unexpectedly (without having received a @DISCONNECTED@ or @ERROR@ protocol message), it should respond as if it had received a non-token @DISCONNECTED@ (following @RTN15h3@).
 ** @(RTN15g)@ Connection state is only maintained server-side for a brief period, given by the @connectionStateTtl@ in the @connectionDetails@, see "CD2f":#CD2f. If a client has been disconnected for longer than the @connectionStateTtl@, it should not attempt to resume. Instead, it should clear the local connection state, and any connection attempts should be made as for a fresh connection
 *** @(RTN15g1)@ This check should be made before each connection attempt. It is generally not sufficient to merely clear the connection state when moving to @SUSPENDED@ state (though that may be done too), since the device may have been sleeping / suspended, in which case it may have been many hours since it was last actually connected, even though, having been in the @CONNECTED@ state when it was put to sleep, it has only moved out of that state very recently (after waking up and noticing it's no longer connected)
 *** @(RTN15g2)@ Another consequence of that is that the measure of whether the client been disconnected for too long (for the purpose of this check) cannot just be whether the client left the @CONNECTED@ state more than @connectionStateTtl@ ago. Instead, it should be whether the difference between the current time and the last activity time is greater than the sum of the @connectionStateTtl@ and the @maxIdleInterval@, where the last activity time is the time of the last known actual sign of activity from Ably per "RTN23a":#RTN23a