From ba79aba258380f00028df0324863baaefc8d1655 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Fri, 6 Sep 2024 16:13:22 -0300 Subject: [PATCH] Add opt-out of implicit attach when subscribing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an attachOnSubscribe channel option, which, if set to false, allows users to opt out of the implicit attach that’s triggered by `subscribe`-ing to channel or presence messages. The Chat SDK has decided that in its API, subscribing to a room’s messages or presence messages should not trigger a channel attach operation (see [1] for decision record). The JS Chat SDK uses private ably-js API to, essentially, call `subscribe` without triggering an implicit attach. For the Swift and Kotlin SDKs, we’d like to avoid this, hence this new API. I’m not sure what’s the better approach out of adding a new channel option (I don’t love the fact that we just ignore the user-provided “on attach” callback) or adding a new method called something like `subscribeWithoutAttach` (which, given that it’d be part of the public API, might be quite confusing for users when it appears in their IDE autocomplete or whatever). Resolves #202. [1] https://ably.atlassian.net/wiki/spaces/CHA/pages/3156705308/CHADR-038+API+Design+Separating+Listeners+from+Lifecycle --- textile/features.textile | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/textile/features.textile b/textile/features.textile index 2a760271..f3b9a50e 100644 --- a/textile/features.textile +++ b/textile/features.textile @@ -686,7 +686,9 @@ h3(#realtime-channel). RealtimeChannel * @(RTL7)@ @RealtimeChannel#subscribe@ function: ** @(RTL7a)@ Subscribe with a single listener argument subscribes a listener to all messages ** @(RTL7b)@ Subscribe with a name argument and a listener argument subscribes a listener to only messages whose @name@ member matches the string name -** @(RTL7c)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@, @DETACHING@, or @DETACHED@ states. The optional callback, if provided, is called according to "@RTL4d@":#RTL4d based on the implicit attach operation. The listener will always be registered regardless of the implicit attach result +** @(RTL7c)@ This clause has been replaced by "@RTL7g@":#RTL7g. It was valid up to and including specification version @3.0@. +** @(RTL7g)@ If the @attachOnSubscribe@ channel option is @true@, implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@, @DETACHING@, or @DETACHED@ states. The optional callback, if provided, is called according to "@RTL4d@":#RTL4d based on the implicit attach operation. The listener will always be registered regardless of the implicit attach result +** @(RTL7h)@ If the @attachOnSubscribe@ channel option is @false@, the optional callback must not be called. ** @(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 @@ -778,7 +780,9 @@ h3(#realtime-presence). RealtimePresence * @(RTP6)@ @RealtimePresence#subscribe@ function: ** @(RTP6a)@ Subscribe with a single listener argument subscribes a listener to all presence messages ** @(RTP6b)@ Subscribe with an action argument and a listener argument - such as @ENTER@, @LEAVE@, @UPDATE@ or @PRESENT@ - subscribes a listener to receive only presence messages with that action. In lanuages where method overloading is supported the action argument may also be an array of actions to receive only presence messages with an action included in the supplied array. -** @(RTP6c)@ Implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@, @DETACHING@, or @DETACHED@ states. The optional callback, if provided, is called according to "@RTL4d@":#RTL4d based on the implicit attach operation. The listener will always be registered regardless of the implicit attach result +** @(RTP6c)@ This clause has been replaced by "@RTP6d@":#RTP6d. It was valid up to and including specification version @3.0@. +** @(RTP6d)@ If the @attachOnSubscribe@ channel option is @true@, implicitly attaches the @RealtimeChannel@ if the channel is in the @INITIALIZED@, @DETACHING@, or @DETACHED@ states. The optional callback, if provided, is called according to "@RTL4d@":#RTL4d based on the implicit attach operation. The listener will always be registered regardless of the implicit attach result +** @(RTP6e)@ If the @attachOnSubscribe@ channel option is @false@, the optional callback must not be called. * @(RTP7)@ @RealtimePresence#unsubscribe@ function: ** @(RTP7c)@ Unsubscribe with no arguments unsubscribes all listeners ** @(RTP7a)@ Unsubscribe with a single listener argument unsubscribes the listener if previously subscribed with an action-specific subscription @@ -1693,6 +1697,7 @@ h4. ChannelOptions *** @(TB2b2)@ A @CipherParamOptions@ instance. In this case, the client library should call @getDefaultParams@, passing it the options hash, to obtain a @CipherParams@ instance ** @(TB2c)@ @params@ (for realtime client libraries only) a @Dict@ of key/value pairs ** @(TB2d)@ @modes@ (for realtime client libraries only) an array of @ChannelMode@ s, where a @ChannelMode@ is a member of an enum containing the names of those children of "@TR3@":#TR3 whose value is ≥16 (or see the IDL below) +** @(TB4)@ @attachOnSubscribe@ (for realtime client libraries only) a boolean which determines whether calling @subscribe@ on a channel or presence object should trigger an implicit attach. Defaults to @true@. * @(TB3)@ The client lib may optionally provide an alternative constructor @withCipherKey@ for ChannelOptions that takes a @key@ only. (This must be differentiated from the normal constructor such that it is clear that the value being passed in is a key). (This is intended for languages where requiring a hash map is unidiomatic) h4. DeriveOptions