feat!: make channels.release() throw unless the channel is detached (RTS4e)

packages/core/ably.d.ts

@@ -3452,7 +3452,7 @@
    */
   getDerived(name: string, deriveOptions: DeriveOptions, channelOptions?: ChannelOptions): T;
   /**
-   * Releases all SDK-held references to a {@link Channel} or {@link RealtimeChannel} object, enabling it to be garbage collected. Warning: this method has no guardrails; using a channel reference after it has been released is undefined behaviour. It can be useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe you, don't call it. Realtime channels not already in the `INITIALIZED`, `DETACHED`, or `FAILED` state are detached before release.
+   * Releases all SDK-held references to a {@link Channel} or {@link RealtimeChannel} object, enabling it to be garbage collected. Warning: this method has no guardrails; using a channel reference after it has been released is undefined behaviour. It can be useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe you, don't call it. A realtime channel can only be released when it is in the `INITIALIZED`, `DETACHED`, or `FAILED` state.
    *
    * @param name - The channel name.
    */
@@ -4243,7 +4243,7 @@
    * Creates an APNs broadcast channel for use with an iOS Live Activity. Call once before starting the Live Activity and persist the returned ids for the session.
    *
    * @experimental This is a preview feature and may change in a future non-major release.
    *
    * @param options - Options for the broadcast, including the `messageStoragePolicy`.
    * @returns A promise resolving to the broadcast `{ id, apnsChannelId }`.
    */
@@ -4266,7 +4266,7 @@
    * Sends a push-to-start notification to all devices subscribed to the given Ably channels. Each targeted device starts a new Live Activity using its registered push-to-start token.
    *
    * @experimental This is a preview feature and may change in a future non-major release.
    *
    * @param params - The recipient channels, the broadcast `id`, and a valid APNs Live Activity start payload.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
    */
@@ -4275,7 +4275,7 @@
    * Sends a `content-state` update to all devices with an active Live Activity on the broadcast channel. A single push is sent to the channel; APNs handles fan-out to all subscribed devices.
    *
    * @experimental This is a preview feature and may change in a future non-major release.
    *
    * @param params - The broadcast `id` and a valid APNs Live Activity update payload.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
    */
@@ -4284,7 +4284,7 @@
    * Ends the Live Activity on all subscribed devices and cleans up the APNs channel. After this call, the broadcast `id` is no longer valid.
    *
    * @experimental This is a preview feature and may change in a future non-major release.
    *
    * @param params - The broadcast `id` and a valid APNs Live Activity end payload.
    * @returns A promise which resolves upon success of the operation and rejects with an {@link ErrorInfo} object upon its failure.
    */

packages/core/src/common/lib/client/baserealtime.ts

@@ -231,24 +231,13 @@ class Channels extends EventEmitter {
     if (!channel) {
       return;
     }
-    const s = channel.state;
-    if (s === 'initialized' || s === 'detached' || s === 'failed') {
-      delete this.all[name];
-      return;
+    // RTS4e
+    const err = channel.getReleaseErr();
+    if (err) {
+      throw err;
     }
-    channel
-      .detach()
-      .catch((err) => {
-        Logger.logAction(
-          this.logger,
-          Logger.LOG_ERROR,
-          'Channels.release()',
-          'Error detaching channel ' + name + ' prior to release: ' + Utils.inspectError(err),
-        );
-      })
-      .then(() => {
-        delete this.all[name];
-      });
+    // RTS4d
+    delete this.all[name];
   }
 }
 

packages/core/src/common/lib/client/realtimechannel.ts

@@ -1142,7 +1142,7 @@ class RealtimeChannel extends EventEmitter {
       message:
         'Can only release a channel in a state where there is no possibility of further updates from the server being received (initialized, detached, or failed). The current state is ' +
         s,
-      code: 90001,
+      code: 90011,
       statusCode: 400,
       remediation:
         'Call channel.detach() and wait for the channel to reach "detached" before calling channels.release(name).',

packages/core/src/common/lib/types/errorcodes.ts

@@ -122,6 +122,7 @@ export type ErrorCode =
   | 50004
   | 50005
   | 50006
+  | 50007
   | 50010
   | 50205
   | 50210
@@ -200,6 +201,7 @@ export type ErrorCode =
   | 90008
   | 90009
   | 90010
+  | 90011
   | 90021
   | 91000
   | 91001
@@ -265,6 +267,7 @@ export type ErrorCode =
   | 103007
   | 103008
   | 103009
+  | 103010
   | 104000
   | 104001
   | 104002

packages/core/test/uts/realtime/unit/channels/channels_collection.test.ts

@@ -1,7 +1,7 @@
 /**
  * UTS: Channels Collection Tests
  *
- * Spec points: RTS1, RTS2, RTS3a, RTS4a
+ * Spec points: RTS1, RTS2, RTS3a, RTS4c, RTS4d, RTS4e
  * Source: uts/test/realtime/unit/channels/channels_collection.md
  *
  * Tests the RealtimeChannels collection: get, release, existence checks,
@@ -13,7 +13,7 @@
 
 import { expect } from 'chai';
 import { MockWebSocket } from '../../../mock_websocket';
-import { Ably, installMockWebSocket, restoreAll, trackClient, flushAsync } from '../../../helpers';
+import { Ably, installMockWebSocket, restoreAll, trackClient } from '../../../helpers';
 
 describe('uts/realtime/unit/channels/channels_collection', function () {
   afterEach(function () {
@@ -134,52 +134,45 @@ describe('uts/realtime/unit/channels/channels_collection', function () {
   });
 
   /**
-   * RTS4a - Release removes channel from collection
+   * RTS4c - Release on non-existent channel is no-op
    */
-  // UTS: realtime/unit/RTS4a/release-detaches-attached-2
-  it('RTS4a - release removes channel', function () {
+  // UTS: realtime/unit/RTS4c/release-nonexistent-noop-0
+  it('RTS4c - release non-existent channel is no-op', function () {
     const client = new Ably.Realtime({
       key: 'appId.keyId:keySecret',
       autoConnect: false,
       useBinaryProtocol: false,
     });
     trackClient(client);
 
-    client.channels.get('test-RTS4a');
-    expect('test-RTS4a' in client.channels.all).to.be.true;
-
-    // Channel is in 'initialized' state, so release succeeds
-    client.channels.release('test-RTS4a');
-    expect('test-RTS4a' in client.channels.all).to.be.false;
+    client.channels.release('does-not-exist');
+    expect('does-not-exist' in client.channels.all).to.be.false;
     client.close();
   });
 
   /**
-   * RTS4a - Release on non-existent channel is no-op
+   * RTS4d - Release removes an initialized channel
    */
-  // UTS: realtime/unit/RTS4a/release-nonexistent-noop-1
-  it('RTS4a - release non-existent channel is no-op', function () {
+  // UTS: realtime/unit/RTS4d/release-removes-channel-0
+  it('RTS4d - release removes initialized channel', function () {
     const client = new Ably.Realtime({
       key: 'appId.keyId:keySecret',
       autoConnect: false,
       useBinaryProtocol: false,
     });
     trackClient(client);
 
-    // Should not throw
-    client.channels.release('does-not-exist');
-    expect('does-not-exist' in client.channels.all).to.be.false;
+    const channel = client.channels.get('test-RTS4d');
+    expect(channel.state).to.equal('initialized');
+    expect('test-RTS4d' in client.channels.all).to.be.true;
+
+    client.channels.release('test-RTS4d');
+    expect('test-RTS4d' in client.channels.all).to.be.false;
     client.close();
   });
 
-  /**
-   * RTS4a - Release detaches and removes attached channel
-   *
-   * Per spec: "Detaches the channel and then releases the channel resource
-   * i.e. it's deleted and can then be garbage collected"
-   */
-  // UTS: realtime/unit/RTS4a/release-removes-channel-0
-  it('RTS4a - release detaches and removes attached channel', async function () {
+  function setupAttachDetachMock() {
+    const detachMessages: any[] = [];
     const mock = new MockWebSocket({
       onConnectionAttempt: (conn) => {
         mock.active_connection = conn;
@@ -195,6 +188,7 @@ describe('uts/realtime/unit/channels/channels_collection', function () {
           });
         } else if (msg.action === 12) {
           // DETACH
+          detachMessages.push(msg);
           mock.active_connection!.send_to_client({
             action: 13,
             channel: msg.channel,
@@ -203,6 +197,15 @@ describe('uts/realtime/unit/channels/channels_collection', function () {
       },
     });
     installMockWebSocket(mock.constructorFn);
+    return { detachMessages };
+  }
+
+  /**
+   * RTS4d - Release removes a channel once detached
+   */
+  // UTS: realtime/unit/RTS4d/release-after-detach-1
+  it('RTS4d - release removes channel once detached', async function () {
+    setupAttachDetachMock();
 
     const client = new Ably.Realtime({
       key: 'appId.keyId:keySecret',
@@ -214,19 +217,51 @@ describe('uts/realtime/unit/channels/channels_collection', function () {
     client.connect();
     await new Promise<void>((resolve) => client.connection.once('connected', resolve));
 
-    const channel = client.channels.get('test-RTS4a-attached');
+    const channel = client.channels.get('test-RTS4d-detached');
     await channel.attach();
-    expect(channel.state).to.equal('attached');
+    await channel.detach();
+    expect(channel.state).to.equal('detached');
+
+    client.channels.release('test-RTS4d-detached');
+    expect('test-RTS4d-detached' in client.channels.all).to.be.false;
+    client.close();
+  });
 
-    client.channels.release('test-RTS4a-attached');
+  /**
+   * RTS4e - Release of an attached channel fails
+   */
+  // UTS: realtime/unit/RTS4e/release-attached-fails-0
+  it('RTS4e - release of attached channel fails', async function () {
+    const { detachMessages } = setupAttachDetachMock();
+
+    const client = new Ably.Realtime({
+      key: 'appId.keyId:keySecret',
+      autoConnect: false,
+      useBinaryProtocol: false,
+    });
+    trackClient(client);
+
+    client.connect();
+    await new Promise<void>((resolve) => client.connection.once('connected', resolve));
 
-    // release() detaches asynchronously then removes via .then() after detach resolves
-    await new Promise<void>((resolve) => channel.once('detached', resolve));
-    // The delete happens in .then() after the detach promise resolves — yield to let it execute
-    await flushAsync();
+    const channel = client.channels.get('test-RTS4e-attached');
+    await channel.attach();
+    expect(channel.state).to.equal('attached');
 
-    // Channel should be removed from the collection
-    expect('test-RTS4a-attached' in client.channels.all).to.be.false;
+    let error: any;
+    try {
+      client.channels.release('test-RTS4e-attached');
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).to.exist;
+    expect(error.code).to.equal(90011);
+    expect(error.statusCode).to.equal(400);
+    expect(channel.state).to.equal('attached');
+    expect('test-RTS4e-attached' in client.channels.all).to.be.true;
+    expect(client.channels.get('test-RTS4e-attached')).to.equal(channel);
+    expect(detachMessages).to.be.empty;
     client.close();
   });