From 64974def46b5851bfe35aae17419b14831d77071 Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Fri, 9 Oct 2026 04:10:13 +0100 Subject: [PATCH] docs: deprecate releasing a realtime channel that isn't detached (RTS4b) Spec 6.3.0 deletes RTS4a, under which release() detaches a channel not already in the INITIALIZED, DETACHED or FAILED state before removing it, and replaces it with RTS4e, under which release() fails with error 90011 instead. RTS4b lets SDKs keep the old behaviour until their next major version, provided they log a deprecation warning when it takes effect. That warning is logged by the platform SDKs (ably-java, ably-cocoa), which perform the release and see the channel's true state. The Dart-side RealtimeChannel.state is updated asynchronously from platform events and can lag behind it, so a Dart-side check could warn spuriously. This change only updates the release() documentation to match. Co-Authored-By: Claude Opus 5.5 (1M context) --- lib/src/common/src/channels.dart | 7 ++++--- lib/src/platform/src/realtime/realtime_channels.dart | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/lib/src/common/src/channels.dart b/lib/src/common/src/channels.dart index b95a411c4..980cf13d4 100644 --- a/lib/src/common/src/channels.dart +++ b/lib/src/common/src/channels.dart @@ -40,9 +40,10 @@ abstract class Channels extends Iterable { /// Releases a [RestChannel] or [RealtimeChannel] object with a specified /// [name], deleting it. /// - /// It also removes any listeners associated with the channel. To release a - /// channel, the [ChannelState] must be `INITIALIZED`, `DETACHED`, or - /// `FAILED`. + /// It also removes any listeners associated with the channel. A realtime + /// channel should only be released when it is in the `INITIALIZED`, + /// `DETACHED`, or `FAILED` state; releasing a realtime channel in any other + /// state is deprecated and will throw an error in the next major version. void release(String name) { _channels.remove(name); } diff --git a/lib/src/platform/src/realtime/realtime_channels.dart b/lib/src/platform/src/realtime/realtime_channels.dart index caa31103b..093fe6686 100644 --- a/lib/src/platform/src/realtime/realtime_channels.dart +++ b/lib/src/platform/src/realtime/realtime_channels.dart @@ -19,9 +19,10 @@ class RealtimeChannels extends Channels { /// Releases a [RealtimeChannel] object with a specified [name], deleting it. /// - /// It also removes any listeners associated with the channel. To release a - /// channel, the [ChannelState] must be `INITIALIZED`, `DETACHED`, or - /// `FAILED`. + /// It also removes any listeners associated with the channel. A realtime + /// channel should only be released when it is in the `INITIALIZED`, + /// `DETACHED`, or `FAILED` state; releasing a realtime channel in any other + /// state is deprecated and will throw an error in the next major version. @override void release(String name) { realtime.invoke(PlatformMethod.releaseRealtimeChannel, {