v0.9 and v1.0 release notes

[mattheworiordan]

We need to write a blog post / create an article in this repo that outlines considerations for a v0.8 -> v0.9 & v1.0 upgrade. Note v0.9 and v1.0 are the same.

We can touch on new functionality, but the purpose of this post is to ensure developers understand the implications of an upgrade. As a starting point, I think people need to consider:

• Impact of ChannelEvent being emitted instead of ChannelState
• Channel state and presence state no longer needs to be actively managed by the client. New channel suspended state and a new ChannelStateChange object is emitted with each event on the channel. The resume attribute on a ChannelStateChange object when becoming ATTACHED or when emitting an UPDATED event (see below) indicates whether continuity has been provided on the channel or not. If resume is false, then this indicates that the channel has lost continuity and can no longer guarantee that messages have not been lost. This may occur for example when a connection becomes disconnected for too long, moves into the SUSPENDED state, and later becomes ATTACHED but is unable to provide continuity on that channel which was SUSPENDED.
• Calls to authorize behave differently now (authorization always occurs)
• Inline authorization means the connection will no longer disconnect
• Failure to authorize on a realtime connection moves the connection to DISCONNECTED or SUSPENDED instead of FAILED
• Channels emit an UPDATED event when the channel state has changed. For example, if continuity is lost on a channel, then an UPDATED event will fire with a ChannelStateChange object with resumed set to false. If resumed is true, then this indicates continuity has not been lost on a channel.
• Connections too can emit an UPDATED event which indicates the connection state has been updated. This may occur for example following a token becoming expired, a new token being obtained by the library automatically and the connection being upgraded with the new token.
• An implicit attach on a channel when calling subscribe on the channel will still register the listener even if the attach operation fails.

Other new features / improvement

• request method to access undocumented / unreleased Ably APIs such as channel enumeration
• Fallback hosts can now be specified when using a customer endpoint (this is useful for Enterprise customers with dedicated environments / custom CNAMEs)
• Messages now have an extras field which is reserved for future functionality such as push notification payloads
• Heartbeat functionality has been improved in all libraries to improve detection of a connection becoming inactive when TCP/IP is incorrectly reporting it as still connected.
• TokenDetails and TokenRequest both provide fromJson constructors that accept a JsonObject or a string to ease creation of these objects as part of the authentication process. For example, if your server provides a TokenDetails object as JSON in response to your clients requesting a new token, you can use TokenDetails.fromJson to create a TokenDetails object from that JSON Object. This helps to reduce bugs that may occur due to idiomatic differences in languages such as durations typically being in seconds for iOS and milliseconds for Javascript.

Javascript specific

• Javascript from the Ably CDN without a major version number is deprecated. This is to ensure that breaking changes moving forwards in our Javascript library are not mistakenly used by existing clients who are using https://cdn.ably.io/lib/ably.min.js. Instead, https://cdn.ably.io/lib/ably.min-1.js or https://cdn.ably.io/lib/ably.min-1.0.js should be used to lock into all v1 or v1.0 releases respectively.

[SimonWoolf]

Other changes in all client-libraries:

• Message and PresenceMessage now have fromEncoded and fromEncodedArray methods, useful for decoding with queues and webhooks
• stats: MessageCount now has failed and refused attributes, MessageTraffic has sharedQueue and externalQueue

Some more probably-ably-js-specific changes:

• useBinaryProtocol now defaults to true for node (but still false for browsers)
• tokenParams and authOptions provided to requestToken, createTokenrequest, and authorize now replace the stored options, rather than attempting to merge them. (Worth emphasizing that this means that it is no longer valid to do requestToken({queryTime: true}, ...), authorize({force: true}, ..), etc. . force is no longer necessary as authorize always forces, and the best way to use queryTime is to pass it to the constructor as a clientOption (it doesn't do anything past the first time anyway, as the time offset is stored)). [Though I've put some padding in so {force: true} doesn't break things as it was quite common; will probably remove that for 1.1 or 2.0. (wonder if you can harden a soft-deprecation in a minor version in semver?)
• EventEmitter now supports arrays everywhere, so you can do e.g. channel.presence.subscribe(['enter', 'update'], ...), channel.on(['attached', 'update'], ...), etc.
• The library now supports arbitrary numbers of pending presence events, useful for people using enterClient to enter multiple clients
• on node, we now start with websockets straight off rather than starting with comet and upgrading to websocket. To get the old upgrading behaviour back, specify transports: ['comet', 'web_socket'].
• Lots of error code changes for conformity with the spec and with other client libraries: all timeouts now have a statusCode of 408; non-timeout connection errors now have a statusCode of 400; channel attach timeouts have a code of 90007; operations on detached channels now have a code of 90001 (and probably some others I've missed)
• We have a typescript definition file
• NativeScript support
• ReactNative support

[ricardopereira]

On iOS, the only breaking change that I'm aware of is the Objective-C connection event enum:

v0.8:

[realtime.connection once:ARTRealtimeConnected callback:^(ARTConnectionStateChange *stateChange) {
                          ^

v0.9:

[realtime.connection once:ARTRealtimeConnectionEventConnected callback:^(ARTConnectionStateChange *stateChange) {
                          ^

This can break as well in Swift when the user uses it like once: ARTRealtimeConnectionState.Connected but for convenience it is used mostly like: once: .Connected.

[mattheworiordan]

This is all covered in https://blog.ably.io/v1-0-client-libraries-released-8a375dca7a26