feat: optionally return ChannelStateChange from attach methods

textile/features.textile

@@ -617,6 +617,7 @@ h3(#realtime-channel). RealtimeChannel
 *** @(RTL4k1)@ If any channel parameters are requested (which may be through the @params@ field of the @ATTACH@ message or some other way opaque to the client library), the @ATTACHED@ (and any subsequent @ATTACHED@ s) will include a @params@ property (also a @Dict<String, String>@) containing the subset of those params that the server has recognised and validated. This should be exposed as a read-only @params@ field of the @RealtimeChannel@ (or a @getParams()@ method where that is more idiomatic). An @ATTACHED@ message with no @params@ property must be treated as equivalent to a @params@ of @{}@ (that is, @RealtimeChannel.params@ should be set to the empty dict)
 ** @(RTL4l)@ If the user has specified a @modes@ array in the @ChannelOptions@ ("@TB2d@":#TB2d), it must be encoded as a bitfield per "@TR3@":#TR3 and set as the @flags@ field of the @ATTACH@ @ProtocolMessage@. (For the avoidance of doubt, when multiple different spec items require flags to be set in the @ATTACH@, the final @flags@ field should be the bitwise OR of them all)
 ** @(RTL4m)@ On receipt of an @ATTACHED@, the client library should decode the @flags@ into an array of @ChannelMode@ s (that is, the same format as @ChannelOptions.modes@) and expose it as a read-only @modes@ field of the @RealtimeChannel@ (or a @getModes()@ method where that is more idiomatic). This should only contain @ChannelMode@ s: it should not contain flags which are not modes (see "@TB2d@":#TB2d)
+** @(RTL4n)@ Optionally, upon success, may return the @ChannelStateChange@ object once the channel is attached. If the channel is already attached, it should return @null@.
 * @(RTL5)@ @RealtimeChannel#detach@ function:
 ** @(RTL5a)@ If the channel state is @INITIALIZED@ or @DETACHED@ nothing is done
 ** @(RTL5i)@ If the channel is in a pending state @DETACHING@ or @ATTACHING@, do the detach operation after the completion of the pending request
@@ -667,6 +668,7 @@ h3(#realtime-channel). RealtimeChannel
 ** @(RTL7d)@ Messages delivered are automatically decoded based on the @encoding@ attribute; see @RestChannel@ encoding features. Tests should exist to publish and subscribe to encoded messages using the "AES 128":https://github.com/ably/ably-common/blob/main/test-resources/crypto-data-128.json and "AES 256":https://github.com/ably/ably-common/blob/main/test-resources/crypto-data-256.json fixture test data
 ** @(RTL7e)@ If a message cannot be decoded or decrypted successfully, it should be delivered to the listener with the @encoding@ attribute set indicating the residual encoding state, and an error should be logged
 ** @(RTL7f)@ A test should exist ensuring published messages are not echoed back to the subscriber when @echoMessages@ is set to false in the @RealtimeClient@ library constructor
+** @(RTL7g)@ Optionally, upon success, may return the @ChannelStateChange@ object once the channel is attached. If the channel is already attached, a synthetic @ChannelStateChange@ from @ATTACHED@ to @ATTACHED@ may be returned.
 * @(RTL8)@ @RealtimeChannel#unsubscribe@ function:
 ** @(RTL8c)@ Unsubscribe with no arguments unsubscribes all listeners
 ** @(RTL8a)@ Unsubscribe with a single listener argument unsubscribes the provided listener to all messages if subscribed
@@ -1925,7 +1927,7 @@ class RealtimeChannel: // RTL*
   push: PushChannel // RSH7
   modes: readonly [ChannelMode] // RTL4m
   params: readonly Dict<String, String> // RTL4k1
-  attach() => io // RTL4
+  attach() => io ChannelStateChange // RTL4
   detach() => io // RTL5
   history(
     start: Time, // RTL10a
@@ -1937,9 +1939,9 @@ class RealtimeChannel: // RTL*
   publish(Message) => io // RTL6, RTL6i
   publish([Message]) => io // RTL6, RTL6i
   publish(name: String?, data: Data?) => io // RTL6, RTL6i
-  subscribe((Message) ->) => io // RTL7, RTL7a
-  subscribe(String, (Message) ->) => io // RTL7, RTL7b
-  subscribe(MessageFilter, (Message) ->) // RTL22
+  subscribe((Message) ->) => io ChannelStateChange // RTL7, RTL7a
+  subscribe(String, (Message) ->) => io ChannelStateChange // RTL7, RTL7b
+  subscribe(MessageFilter, (Message) ->) io ChannelStateChange // RTL22
   unsubscribe() // RTL8, RTL8c
   unsubscribe((Message) ->) // RTL8, RTL8a
   unsubscribe(String, (Message) ->) // RTL8, RTL8b