How to read the Ably client library specification

Working with spec version 6a1d650 (I think this is the nearest published one that’s still available.)

Gonna start scanning spec for some of these things. No intention of being comprehensive.

The thing about the spec is that all of these kinds of things are all interspersed. I want to focus on one thing at a time (e.g. all of the state). That’s how I’ll try and attack this.


Here’s a list (that I’ve inferred from the spec) of all the state that the library manages.



The above (in some places there’s a corresponding realtime spec point that kinda says the same thing, haven’t mentioned those), plus:

For connection / channel / presence:

OK, this list is done.

(Are any of these the same thing, e.g. Connection#serial and “the latest connectionSerial received on the connection”?)

What model of a state machine does the push activation one fit into? It has more than one piece of state, by the looks of it. And has stuff like an event queue for no matching transitions.


These are just things I noticed whilst looking at state, not comprehensive

I guess these imply some kind of state

Thoughts on structure

What does the Connection do?

I think that there are some layers going on, even though the spec doesn’t make it clear, and it would be good to think about what each layer adds on top of the previous.

Can 1-3 each be broken and re-created transparently? TCP connection definitely.

  1. TCP connection
  2. Transport
  3. Connection

    What about Auth, where does that fit in?

  4. Channel

    Not sure if this counts as another layer in terms of transport.

    Also note that the channel is not invisible to the connection – e.g. RTN11d says that the connection can reset state on the channel when connect is called

    Also note that RTN11d implies that if the connection is in a given state, then the channel is already in the corresponding state? which, depending on threading, might not be true

There probably should be a layer in between connection and channel that handles connection events that affect all channels, instead of directly fanning out to all channels

Let’s scan through the Connection and see roughly what kind of things it does on top of the transport (I haven’t defined exactly what the transport does yet though):

TODO when can the connection’s ID change? This is what I wanted to know to flesh out “a connection might actually be multiple connections”

The transport

Thoughts on implementation

Interactions between the components

Maybe next I’ll document all the places where the feature spec mentions the interaction points between the components.