fix(supabase_flutter): replace lifecycle state tracking with serial Future chain

Replace complex lifecycle reconnection logic (_disconnectFuture,
_realtimeReconnectOperation, cancel flag) with a serial Future chain
and target-state pattern.

Operations are serialized via _pendingLifecycleOperation so disconnect
and connect never overlap. _targetLifecycleState tracks the most recent
lifecycle request, allowing stale operations to be skipped and
reconnects to be cancelled if the app goes back to background.

Add idempotency guards on both connect (isConnected) and disconnect
(isConnected || isConnecting) paths.

Add tests for rapid lifecycle flapping and cancellation edge cases.

Author: brunovsiqueira

packages/supabase_flutter/lib/src/supabase.dart

@@ -13,7 +13,6 @@ import 'package:supabase_flutter/src/supabase_auth.dart';
 
 import 'hot_restart_cleanup_stub.dart'
     if (dart.library.js_interop) 'hot_restart_cleanup_web.dart';
-
 import 'version.dart';
 
 final _log = Logger('supabase.supabase_flutter');
@@ -169,14 +168,20 @@ class Supabase with WidgetsBindingObserver {
   /// Wraps the `recoverSession()` call so that it can be terminated when `dispose()` is called
   late CancelableOperation _restoreSessionCancellableOperation;
 
-  CancelableOperation<void>? _realtimeReconnectOperation;
+  /// Serial queue for lifecycle operations (connect/disconnect). Each event
+  /// appends via `.then()` so operations never overlap.
+  Future<void> _pendingLifecycleOperation = Future.value();
 
-  Future<void>? _disconnectFuture;
+  /// The most recently requested lifecycle state. Checked inside
+  /// [_processLifecycle] after each `await` to skip stale operations
+  /// (e.g. abort a reconnect if the app went back to background).
+  AppLifecycleState? _targetLifecycleState;
 
   StreamSubscription? _logSubscription;
 
   /// Dispose the instance to free up resources.
   Future<void> dispose() async {
+    _targetLifecycleState = null;
     await _restoreSessionCancellableOperation.cancel();
     _logSubscription?.cancel();
     client.dispose();
@@ -226,80 +231,59 @@ class Supabase with WidgetsBindingObserver {
   void didChangeAppLifecycleState(AppLifecycleState state) {
     switch (state) {
       case AppLifecycleState.resumed:
-        onResumed();
-      case AppLifecycleState.detached:
       case AppLifecycleState.paused:
-        _realtimeReconnectOperation?.cancel();
-        _disconnectFuture = Supabase.instance.client.realtime.disconnect();
+      case AppLifecycleState.detached:
+        _targetLifecycleState = state;
+        _pendingLifecycleOperation = _pendingLifecycleOperation
+            .then((_) => _processLifecycle(state))
+            .catchError((_) {});
       default:
+        break;
     }
   }
 
-  Future<void> onResumed() async {
+  /// Processes a lifecycle state change. Operations are serialized via
+  /// [_pendingLifecycleOp] so that disconnect and connect never overlap.
+  ///
+  /// [captured] is the lifecycle state at the time the event was enqueued.
+  /// If a newer event has arrived since, this one is skipped (stale).
+  Future<void> _processLifecycle(AppLifecycleState captured) async {
+    // Skip if a newer lifecycle event has superseded this one.
+    if (captured != _targetLifecycleState) return;
+
     final realtime = Supabase.instance.client.realtime;
-    if (realtime.channels.isNotEmpty) {
-      final disconnectFuture = _disconnectFuture;
-      if (disconnectFuture != null) {
-        // If a disconnect is still in progress from e.g.
-        // [AppLifecycleState.paused] we should wait for it to finish before
-        // reconnecting. This avoids accessing conn! which may be nullified.
-        //
-        // We clear _disconnectFuture only after the future completes (not
-        // eagerly) so that a second resumed event (e.g. inactive → resumed)
-        // still sees the in-progress disconnect and waits for it instead of
-        // falling through to the else branch where connect() would no-op.
-
-        bool cancel = false;
-        final connectFuture = disconnectFuture.then((_) async {
-          // Only clear if not replaced by a newer disconnect from a
-          // subsequent paused event.
-          if (_disconnectFuture == disconnectFuture) {
-            _disconnectFuture = null;
-          }
-
-          // Make this connect cancelable so that it does not connect if the
-          // disconnect took so long that the app is already in background
-          // again.
-          if (!cancel) {
-            // ignore: invalid_use_of_internal_member
-            await realtime.connect();
-            for (final channel in realtime.channels) {
-              // ignore: invalid_use_of_internal_member
-              if (channel.isJoined) {
-                // ignore: invalid_use_of_internal_member
-                channel.forceRejoin();
-              }
-            }
-          }
-        }, onError: (error) {
-          if (_disconnectFuture == disconnectFuture) {
-            _disconnectFuture = null;
-          }
-        });
-        _realtimeReconnectOperation = CancelableOperation.fromFuture(
-          connectFuture,
-          onCancel: () => cancel = true,
-        );
-      } else if (!realtime.isConnected) {
-        // Reconnect if the socket is currently not connected.
-        // When coming from [AppLifecycleState.paused] this should be the case,
-        // but when coming from [AppLifecycleState.inactive] no disconnect
-        // happened and therefore connection should still be intact and we
-        // should not reconnect.
 
-        // ignore: invalid_use_of_internal_member
-        await realtime.connect();
-        for (final channel in realtime.channels) {
-          // Only rejoin channels that think they are still joined and not
-          // which were manually unsubscribed by the user while in background
+    if (captured == AppLifecycleState.resumed) {
+      // No channels subscribed — nothing to reconnect.
+      if (realtime.channels.isEmpty) return;
 
+      // Already connected (e.g. coming from [AppLifecycleState.inactive]
+      // where no disconnect happened).
+      if (realtime.isConnected) return;
+
+      // ignore: invalid_use_of_internal_member
+      await realtime.connect();
+
+      // Abort rejoin if app went back to background during connect.
+      if (_targetLifecycleState != AppLifecycleState.resumed) return;
+
+      // Re-send join messages for channels that were previously joined.
+      // After a disconnect/reconnect the WebSocket is fresh, but the
+      // channel objects still have joined state — forceRejoin() restores
+      // the server-side subscriptions.
+      for (final channel in realtime.channels) {
+        // ignore: invalid_use_of_internal_member
+        if (channel.isJoined) {
           // ignore: invalid_use_of_internal_member
-          if (channel.isJoined) {
-            // ignore: invalid_use_of_internal_member
-            channel.forceRejoin();
-          }
+          channel.forceRejoin();
         }
       }
+    } else {
+      // paused or detached — disconnect the WebSocket if it is active.
+      if (realtime.isConnected ||
+          realtime.connState == SocketStates.connecting) {
+        await realtime.disconnect();
+      }
     }
   }
 }

packages/supabase_flutter/test/lifecycle_test.dart

@@ -159,16 +159,15 @@ void main() {
       Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.paused);
       await Future<void>.delayed(Duration.zero);
 
-      // first resumed → captures _disconnectFuture
+      // first resumed → queues reconnect after disconnect
       Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.resumed);
       await Future<void>.delayed(Duration.zero);
 
-      // inactive → does nothing
+      // inactive → does nothing (not a tracked lifecycle state)
       Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.inactive);
       await Future<void>.delayed(Duration.zero);
 
-      // second resumed → should still see _disconnectFuture
-      // (not eagerly cleared)
+      // second resumed → queues another reconnect (idempotent)
       Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.resumed);
       await Future<void>.delayed(Duration.zero);
 
@@ -182,5 +181,70 @@ void main() {
       expect(realtime.connState, isNot(SocketStates.disconnecting));
       expect(realtime.conn, isNotNull);
     });
+
+    test(
+        'rapid paused → resumed → paused → resumed '
+        'ends up connected', () async {
+      await initWithMockTransport();
+      final realtime = Supabase.instance.client.realtime;
+
+      realtime.channel('test');
+
+      await connectAndReady(realtime);
+      expect(realtime.connState, SocketStates.open);
+
+      // Rapid lifecycle flapping
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.paused);
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.resumed);
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.paused);
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.resumed);
+
+      // Complete all pending ready futures as they appear
+      for (final c in readyCompleters) {
+        if (!c.isCompleted) c.complete();
+      }
+      await Future<void>.delayed(const Duration(milliseconds: 200));
+
+      // Also complete any new ready futures created during processing
+      for (final c in readyCompleters) {
+        if (!c.isCompleted) c.complete();
+      }
+      await Future<void>.delayed(const Duration(milliseconds: 200));
+
+      expect(realtime.connState, SocketStates.open);
+    });
+
+    test(
+        'resumed then paused before connect completes '
+        'cancels reconnect', () async {
+      await initWithMockTransport();
+      final realtime = Supabase.instance.client.realtime;
+
+      realtime.channel('test');
+
+      await connectAndReady(realtime);
+      expect(realtime.connState, SocketStates.open);
+
+      // paused → triggers disconnect
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.paused);
+      await Future<void>.delayed(Duration.zero);
+
+      // resumed → queues reconnect
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.resumed);
+      await Future<void>.delayed(Duration.zero);
+
+      // paused again before connect completes → should cancel the
+      // reconnect (target state is now paused)
+      Supabase.instance.didChangeAppLifecycleState(AppLifecycleState.paused);
+
+      // Complete all pending ready futures
+      for (final c in readyCompleters) {
+        if (!c.isCompleted) c.complete();
+      }
+      await Future<void>.delayed(const Duration(milliseconds: 200));
+
+      // Should be disconnected since the last event was paused
+      expect(realtime.connState, SocketStates.disconnected);
+    });
   });
 }