[SDK-3630] feat: add ChannelStateChange.hasBacklog and return state change to attach promise/callback

[owenpearson]

Resolves #1328

See corresponding spec PR

These features in combination will allow users to check whether to expect a backlog of messages once attached to a realtime channel. In particular, when using rewind=1, this will allow users to create a promise which resolves once a channel is attached and, if applicable, the rewind message has been received.

[SimonWoolf]

No objection to the idea, seems like a reasonable feature.

There's nothing ably-js specific about this; if we think it's worth doing we should have a spec PR for this so it can eventually be done in all sdks (and added to api docs).

which resolves once a channel is attached and, if applicable, the rewind message has been received.

not sure I understand what the last part of that sentence means -- it resolves once the channel is attached full stop, no?

[owenpearson]

There's nothing ably-js specific about this; if we think it's worth doing we should have a spec PR for this so it can eventually be done in all sdks (and added to api docs).

@SimonWoolf Yeah we did consider this, my thinking was that this is unlikely to be needed in other SDKs so adding it to the spec would likely be futile. I'm kinda tempted to add it regardless though, will ask what the team thinks.

not sure I understand what the last part of that sentence means -- it resolves once the channel is attached full stop, no?

I'm not talking about any of the promises returned by the ably-js API here - the feature request was to make it possible to wait for a channel with rewind=1 to be attached and for the rewind message (if it exists) to be received, This wasn't possible before because there was no way to tell whether to expect a rewind message, but it should be now using the promise constructor. it wouldn't really make sense to add this promise to the library since it only works for rewind=1, any other rewind value has the possibility of a partial backlog.

[SimonWoolf]

👍

my thinking was that this is unlikely to be needed in other SDKs so adding it to the spec would likely be futile

Shrug, I think there's still some value in formalising the API in the spec even if we're not imminently intending to implement in other sdks. there's other bits of the spec that are not-mandatory ("Libraries may offer a ClientOptions#agents property...", "Client libraries can optionally save a round-trip request to the Ably service for expired tokens by detecting when a token has expired...", etc)

it wouldn't really make sense to add this promise to the library since it only works for rewind=1, any other rewind value has the possibility of a partial backlog

yeah, really for that feature you'd need realtime to tell you when the backlog is finished, and tbh I'm not sure that that'd be a good idea. (also most sensible ways of returning another promise would involve a breaking api change, and would make it a very prominent part of the api, and istm it's not worth either of those)

[lawrence-forooghian]

I wasn't aware of the rewind feature, popping a link to the documentation here for future reference.

I think that exposing the hasBacklog property (which I can't find any documentation of, e.g. in the protocol spec — how did you find out about it?) makes sense, and if I've understood the use case correctly then I think it's a broadly useful thing, and hence worth including in the spec.

As for the change to the signature of attach, I wonder whether that needs to come alongside this change. For example, a user calling attach has, until now, had no direct way to access the ChannelStateChange.resumed property, which you can imagine a user might want to use to know whether they need to fetch channel history. I guess (please correct me if wrong) that our advice to users has been that to find this information out they need to listen for a channel state change using on, so would the same advice not apply here too? That said, if we are going to change the signature of attach then I think it should be a spec change, yeah.