Merge pull request #179 from ably/RTN16f1-proposal

Spec on what should happen when the recover option is malformed.

textile/features.textile

@@ -533,6 +533,7 @@ h3(#realtime-connection). Connection
 * @(RTN16)@ @Connection@ recovery:
 ** @(RTN16i)@ Connection recovery is similar to connection resumption (see "RTN15c":#RTN15c), except that instead of the library resuming from a time at which that library instance was previously connected, it is doing so from external state provided in the client options, "(TO3i)":#TO3i. Since the library has no state at the time of connection, the channels must be explicitly attached by the user; continuity preservation is achieved by the @channelSerial@s for each channel being stored in the recovery key.
 ** @(RTN16f)@ When a library is instantiated with the @recover@ client option, it should initialize its internal @msgSerial@ counter to the @msgSerial@ component of the @recoveryKey@. (If the recover fails, the counter should be reset to 0 per "RTN15c7":#RTN15c7 )
+*** @(RTN16f1)@ If the recovery key provided in the @recover@ client option cannot be deserialized due to malformed data, then an error should be logged and the connection should be made like no @recover@ option was provided.
 ** @(RTN16j)@ When a library is instantiated with the @recover@ client option, for every channel/channelSerial pair in the @recoveryKey@, it should instantiate a corresponding channel and set its "RTL15b":#RTL15b @channelSerial@.
 ** @(RTN16k)@ When the library first connects to Ably after being instantiated with a @recover@ client option, it should add an additional @recover@ querystring param to the websocket request, set from the @connectionKey@ component of the @recoveryKey@. Once the library has successfully connected to Ably, it should never again supply a @recover@ querystring param.
 ** @(RTN16g)@ @Connection#createRecoveryKey@ is a function that returns a string which incorporates the @connectionKey@, the current @msgSerial@, and a collection of pairs of channel @name@ and current @channelSerial@ for every currently attached channel.
@@ -1249,7 +1250,7 @@ h3(#local-device). LocalDevice
 ** @(RSH8a)@ The @LocalDevice@ is initialised when first required, either as a result of a call to @RestClient#device@ or @RealtimeClient#device@, or as a result of an operation involving the Activation State Machine. The @LocalDevice@ @id@, @clientId@, @deviceSecret@ and @deviceIdentityToken@ attributes are populated, together with any @recipient@-related attributes, to the extent that they exist, from the persisted state.
 ** @(RSH8b)@ The @LocalDevice@ @id@ and @deviceSecret@ attributes are generated, and persisted as part of the @LocalDevice@ state, when required by step "@(RSH3a2b)@":#RSH3a2b in the Activation State Machine. At that time, the @clientId@ attribute is also initialised, if the client is identified according to "@(RSA7)@":#RSA7.
 ** @(RSH8c)@ Following successful registration of a @LocalDevice@, following the procedure in "@(RSH3c2a)@":#RSH3c2a, the now known @deviceIdentityToken@ is set and persisted.
-** @(RSH8d)@ If the @LocalDevice* is created by an unidentified client (see "@(RSA7)@":#RSA7 ) and therefore has no @clientId@ set, but the client subsequently becomes identified (as a result of "@(RSA7b2)@":#RSA7b2 or "@(RSA7b3)@":#RSA7b3 ), then the @LocalDevice@ @clientId@ is set and persisted.
+** @(RSH8d)@ If the @LocalDevice@ is created by an unidentified client (see "@(RSA7)@":#RSA7 ) and therefore has no @clientId@ set, but the client subsequently becomes identified (as a result of "@(RSA7b2)@":#RSA7b2 or "@(RSA7b3)@":#RSA7b3 ), then the @LocalDevice@ @clientId@ is set and persisted.
 ** @(RSH8e)@ If the @LocalDevice@ @clientId@ becomes set as a result of "@(RSH8d)@":#RSH8d, and the @LocalDevice@ is already registered (ie the @deviceIdentityToken@ is set), and the ActivationStateMachine is in any state other than @NotActivated@, then a @GotPushDeviceDetails@ event is sent to "the state machine":#RSH3 once the effects of "@(RSH8d)@":#RSH8d are visible, ie. once @LocalDevice@ @clientId@ is set.
 ** @(RSH8f)@ If the @LocalDevice@ is created by an unidentified client (see "@(RSA7)@":#RSA7 ) and therefore has no @clientId@ set, but on receipt of a registration response (see "@(RSH3c2)@":#RSH3c2 ) the registered device has a non-empty @clientId@, then the @LocalDevice@ @clientId@ is set with that @clientId@.
 ** @(RSH8g)@ Whenever any change arises of the push transport details for local device (eg an FCM registration token update triggered by the platform), a @GotPushDeviceDetails@ event is sent to "the state machine":#RSH3.