From 9f2e4c82ea4c3d0485195731cb76332008d612c2 Mon Sep 17 00:00:00 2001 From: Owen Pearson Date: Wed, 28 Jun 2023 11:41:36 +0100 Subject: [PATCH] feat: optionally return `ChannelStateChange` from attach methods --- textile/features.textile | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/textile/features.textile b/textile/features.textile index 9050433cd..5ea2e8843 100644 --- a/textile/features.textile +++ b/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@) 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 // 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