Skip to content

Commit 73a370a

Browse files
SimonWoolfclaude
andcommitted
Deprecate releasing a realtime channel that isn't detached (RTS4b)
Spec 6.3.0 deletes RTS4a, under which release() detaches the channel and then removes it, and replaces it with RTS4e, under which releasing a channel that isn't INITIALIZED, DETACHED or FAILED raises 90011 instead. RTS4b lets SDKs that already implement the old behaviour keep it until their next major version, provided they log a deprecation warning when release() is called on a channel in any other state. Also add UTS-derived tests for RTS4c and RTS4d, and a test for the deprecation warning. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 0188152 commit 73a370a

3 files changed

Lines changed: 140 additions & 4 deletions

File tree

‎lib/src/main/java/io/ably/lib/realtime/AblyRealtime.java‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,8 @@ public interface Channels extends ReadOnlyMap<String, Channel> {
178178
/**
179179
* Releases a {@link Channel} object, deleting it, and enabling it to be garbage collected.
180180
* It also removes any listeners associated with the channel.
181-
* To release a channel, the {@link ChannelState} must be INITIALIZED, DETACHED, or FAILED.
181+
* A realtime channel should only be released when it is in the INITIALIZED, DETACHED, or FAILED state;
182+
* releasing a realtime channel in any other state is deprecated and will throw an error in the next major version.
182183
* <p>
183184
* Spec: RSN4, RTS4
184185
* @param channelName The channel name.
@@ -223,9 +224,22 @@ public Channel get(final String channelName, final ChannelOptions channelOptions
223224

224225
@Override
225226
public void release(String channelName) {
226-
Channel channel = map.remove(channelName);
227+
Channel channel = map.get(channelName);
227228
if(channel != null) {
228-
channel.markAsReleased();
229+
ChannelState state;
230+
// The channel's state transitions hold its monitor, so holding it here stops the channel
231+
// from starting to attach between the state check and it being marked as released.
232+
synchronized (channel) {
233+
if (!map.remove(channelName, channel)) {
234+
return;
235+
}
236+
state = channel.state;
237+
channel.markAsReleased();
238+
}
239+
if (state != ChannelState.initialized && state != ChannelState.detached && state != ChannelState.failed) {
240+
// RTS4b
241+
Log.w(TAG, "Calling `channels.release()` on a channel in the " + state + " state is deprecated, and will throw an error in the next major version. Call `channel.detach()` and wait for it to complete before calling `channels.release(channelName)`.");
242+
}
229243
try {
230244
channel.detach();
231245
} catch (AblyException e) {
Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
package io.ably.lib.uts.unit.realtime
2+
3+
import io.ably.lib.uts.infra.unit.*
4+
import io.ably.lib.realtime.ChannelState
5+
import io.ably.lib.realtime.ConnectionState
6+
import io.ably.lib.types.ProtocolMessage
7+
import io.ably.lib.util.Log
8+
import io.ably.lib.uts.infra.awaitChannelState
9+
import io.ably.lib.uts.infra.awaitState
10+
import kotlinx.coroutines.test.runTest
11+
import java.util.UUID
12+
import java.util.concurrent.CopyOnWriteArrayList
13+
import kotlin.test.*
14+
15+
class ChannelsCollectionTest {
16+
17+
/**
18+
* @UTS realtime/unit/RTS4c/release-nonexistent-noop-0
19+
*/
20+
@Test
21+
fun `RTS4c - release on non-existent channel is no-op`() {
22+
val channelName = "test-RTS4c-nonexistent-${UUID.randomUUID()}"
23+
val client = TestRealtimeClient { autoConnect = false }
24+
25+
client.channels.release(channelName)
26+
27+
assertFalse(client.channels.containsKey(channelName))
28+
client.close()
29+
}
30+
31+
/**
32+
* @UTS realtime/unit/RTS4d/release-removes-channel-0
33+
*/
34+
@Test
35+
fun `RTS4d - release removes an initialized channel`() {
36+
val channelName = "test-RTS4d-${UUID.randomUUID()}"
37+
val client = TestRealtimeClient { autoConnect = false }
38+
39+
val channel = client.channels.get(channelName)
40+
assertEquals(ChannelState.initialized, channel.state)
41+
assertTrue(client.channels.containsKey(channelName))
42+
43+
client.channels.release(channelName)
44+
45+
assertFalse(client.channels.containsKey(channelName))
46+
client.close()
47+
}
48+
49+
/**
50+
* @UTS realtime/unit/RTS4d/release-after-detach-1
51+
*/
52+
@Test
53+
fun `RTS4d - release removes a channel once detached`() = runTest {
54+
val channelName = "test-RTS4d-detached-${UUID.randomUUID()}"
55+
val warnings = CopyOnWriteArrayList<String>()
56+
val client = TestRealtimeClient {
57+
autoConnect = false
58+
install(attachDetachMock())
59+
logHandler = Log.LogHandler { severity, _, msg, _ -> if (severity == Log.WARN) warnings.add(msg) }
60+
}
61+
val channel = client.channels.get(channelName)
62+
63+
client.connect()
64+
awaitState(client, ConnectionState.connected)
65+
66+
channel.attach()
67+
awaitChannelState(channel, ChannelState.attached)
68+
channel.detach()
69+
awaitChannelState(channel, ChannelState.detached)
70+
71+
client.channels.release(channelName)
72+
73+
assertFalse(client.channels.containsKey(channelName))
74+
assertTrue(warnings.none { it.contains("channels.release()") })
75+
client.close()
76+
}
77+
78+
@Test
79+
fun `RTS4b - release of an attached channel logs a deprecation warning and still releases it`() = runTest {
80+
val channelName = "test-RTS4b-attached-${UUID.randomUUID()}"
81+
val warnings = CopyOnWriteArrayList<String>()
82+
val client = TestRealtimeClient {
83+
autoConnect = false
84+
install(attachDetachMock())
85+
logHandler = Log.LogHandler { severity, _, msg, _ -> if (severity == Log.WARN) warnings.add(msg) }
86+
}
87+
val channel = client.channels.get(channelName)
88+
89+
client.connect()
90+
awaitState(client, ConnectionState.connected)
91+
92+
channel.attach()
93+
awaitChannelState(channel, ChannelState.attached)
94+
95+
client.channels.release(channelName)
96+
97+
assertFalse(client.channels.containsKey(channelName))
98+
assertEquals(ChannelState.detached, channel.state)
99+
val deprecationWarnings = warnings.filter { it.contains("channels.release()") }
100+
assertEquals(1, deprecationWarnings.size)
101+
assertContains(deprecationWarnings[0], "attached state is deprecated")
102+
client.close()
103+
}
104+
105+
private fun attachDetachMock(): MockWebSocket {
106+
lateinit var mockWs: MockWebSocket
107+
mockWs = MockWebSocket {
108+
onConnectionAttempt = { conn -> conn.respondWithSuccess(CONNECTED_MESSAGE) }
109+
onMessageFromClient = { msg ->
110+
when (msg.action) {
111+
ProtocolMessage.Action.attach ->
112+
mockWs.sendToClient(ProtocolMessage(ProtocolMessage.Action.attached, msg.channel))
113+
ProtocolMessage.Action.detach ->
114+
mockWs.sendToClient(ProtocolMessage(ProtocolMessage.Action.detached, msg.channel))
115+
else -> Unit
116+
}
117+
}
118+
}
119+
return mockWs
120+
}
121+
}

‎pubsub-adapter/src/main/kotlin/com/ably/pubsub/Channels.kt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,8 @@ public interface Channels<ChannelType> : Iterable<ChannelType> {
3939
/**
4040
* Releases a [Channel] object, deleting it, and enabling it to be garbage collected.
4141
* It also removes any listeners associated with the channel.
42-
* To release a channel, the [ChannelState] must be `INITIALIZED`, `DETACHED`, or `FAILED`.
42+
* A realtime channel should only be released when it is in the `INITIALIZED`, `DETACHED`, or `FAILED` state;
43+
* releasing a realtime channel in any other state is deprecated and will throw an error in the next major version.
4344
* <p>
4445
* Spec: RSN4, RTS4
4546
* @param name The channel name.

0 commit comments

Comments
 (0)