feat: drive the connection mode through ConnectionModeId

setConnectionMode now accepts a ConnectionModeId so it can reach all FDv2
built-in modes (including background) rather than only the FDv1 streaming,
polling, and offline modes.

A configured DataSystemConfig.initialConnectionMode is applied as the
connection managers initial sticky override, equivalent to calling
setConnectionMode immediately after construction. Under the FDv2 data
system the automatic-resolution foreground slot defaults to streaming and
no longer reads the FDv1 DataSourceConfig.initialConnectionMode.

Author: kinyoklion

packages/flutter_client_sdk/lib/src/connection_manager.dart

@@ -82,6 +82,14 @@ final class ConnectionManagerConfig {
   /// Defaults to [const FDv2Offline()].
   final FDv2ConnectionMode backgroundConnectionMode;
 
+  /// An initial mode override applied at construction, equivalent to calling
+  /// [ConnectionManager.setMode] immediately after creation. When non-null
+  /// the manager starts in this mode and suppresses automatic resolution
+  /// until the override is cleared.
+  ///
+  /// Defaults to null (automatic resolution from construction).
+  final FDv2ConnectionMode? initialModeOverride;
+
   /// Some platforms (windows, web, mac, linux) can continue executing code
   /// in the background.
   final bool runInBackground;
@@ -121,6 +129,7 @@ final class ConnectionManagerConfig {
   ConnectionManagerConfig({
     this.initialConnectionMode = ConnectionMode.streaming,
     this.backgroundConnectionMode = const FDv2Offline(),
+    this.initialModeOverride,
     this.runInBackground = true,
     this.disableAutomaticBackgroundHandling = false,
     this.disableAutomaticNetworkHandling = false,
@@ -153,7 +162,8 @@ final class ConnectionManager {
   StreamSubscription<NetworkState>? _networkStateSub;
 
   /// When non-null, [resolveMode] is skipped and this mode is
-  /// applied regardless of lifecycle/network.
+  /// applied regardless of lifecycle/network. Seeded from
+  /// [ConnectionManagerConfig.initialModeOverride].
   FDv2ConnectionMode? _modeOverride;
 
   ApplicationState _applicationState;
@@ -183,6 +193,7 @@ final class ConnectionManager {
         _config = config,
         _destination = destination,
         _resolutionTable = resolutionTable ?? flutterDefaultResolutionTable(),
+        _modeOverride = config.initialModeOverride,
         _applicationState = config.initialApplicationState,
         // Network has no synchronous platform API; start optimistic. If
         // the network is actually unavailable, the first detector emission
@@ -195,7 +206,7 @@ final class ConnectionManager {
         networkAvailable: true,
         inForeground:
             config.initialApplicationState == ApplicationState.foreground,
-        requestedMode: null,
+        requestedMode: config.initialModeOverride,
       ),
       debounceWindow: config.debounceWindow,
     );

packages/flutter_client_sdk/lib/src/ld_client.dart

@@ -78,11 +78,23 @@ interface class LDClient {
         DiagnosticSdkData(name: sdkName, version: sdkVersion),
         hooks: combined);
     final stateDetector = FlutterStateDetector();
+    // Under the FDv2 data system the connection mode is governed by the
+    // data system configuration, not the FDv1 data source options: the
+    // foreground slot defaults to streaming, and an initial connection mode
+    // (if configured) is applied as a sticky override, equivalent to calling
+    // setConnectionMode immediately after construction.
+    final dataSystem = config.dataSystem;
+    final initialModeOverride = switch (dataSystem?.initialConnectionMode) {
+      final id? => _fdv2FromConnectionModeId(id),
+      null => null,
+    };
     _connectionManager = ConnectionManager(
         logger: _client.logger,
         config: ConnectionManagerConfig(
-            initialConnectionMode:
-                config.dataSourceConfig.initialConnectionMode,
+            initialConnectionMode: dataSystem != null
+                ? ConnectionMode.streaming
+                : config.dataSourceConfig.initialConnectionMode,
+            initialModeOverride: initialModeOverride,
             backgroundConnectionMode:
                 FlutterDefaultConfig.defaultBackgroundConnectionMode,
             disableAutomaticBackgroundHandling:
@@ -350,18 +362,16 @@ interface class LDClient {
   /// availability) until cleared. Call with no argument (or null) to clear
   /// the override and resume automatic mode resolution.
   ///
+  /// The mode is a [ConnectionModeId], which can identify any of the FDv2
+  /// built-in modes (including [ConnectionModeId.background]).
+  ///
   /// This method is not stable, and not subject to any backwards
   /// compatibility guarantees or semantic versioning. It is in early
   /// access. If you want access to this feature please join the EAP.
   /// https://launchdarkly.com/docs/sdk/features/data-saving-mode
-  void setConnectionMode([ConnectionMode? mode]) {
-    _connectionManager.setMode(mode == null
-        ? null
-        : switch (mode) {
-            ConnectionMode.streaming => const FDv2Streaming(),
-            ConnectionMode.polling => const FDv2Polling(),
-            ConnectionMode.offline => const FDv2Offline(),
-          });
+  void setConnectionMode([ConnectionModeId? mode]) {
+    _connectionManager
+        .setMode(mode == null ? null : _fdv2FromConnectionModeId(mode));
   }
 
   /// Check if the SDK has finished initialization.
@@ -410,3 +420,13 @@ interface class LDClient {
         this, _pluginEnvironmentMetadata, [plugin], _client.logger);
   }
 }
+
+/// Translates a public [ConnectionModeId] into the internal
+/// [FDv2ConnectionMode] the connection manager drives.
+FDv2ConnectionMode _fdv2FromConnectionModeId(ConnectionModeId mode) =>
+    switch (mode) {
+      ConnectionModeId.polling => const FDv2Polling(),
+      ConnectionModeId.background => const FDv2Background(),
+      ConnectionModeId.offline => const FDv2Offline(),
+      _ => const FDv2Streaming(),
+    };

packages/flutter_client_sdk/test/persistence/connection_manager_test.dart

@@ -899,4 +899,101 @@ void main() {
       connectionManager.dispose();
     });
   });
+
+  group('given an initial mode override', () {
+    test(
+        'it applies the override on the buffered initial reconcile, without '
+        'any detector emission', () async {
+      registerFallbackValue(ConnectionMode.streaming);
+
+      final destination = MockDestination();
+      final logger = LDLogger(adapter: MockLogAdapter());
+      final config = ConnectionManagerConfig(
+        initialModeOverride: const FDv2Polling(),
+        debounceWindow: const Duration(seconds: 1),
+      );
+      final mockDetector = MockStateDetector();
+
+      final connectionManager = ConnectionManager(
+        logger: logger,
+        config: config,
+        destination: destination,
+        detector: mockDetector,
+      );
+
+      // The buffered initial reconcile fires on the next microtask after
+      // construction.
+      await Future<void>.microtask(() {});
+
+      verify(() => destination.setMode(const ResolvedPolling())).called(1);
+
+      connectionManager.dispose();
+    });
+
+    test(
+        'the override sticks across lifecycle changes and suppresses automatic '
+        'resolution', () async {
+      registerFallbackValue(ConnectionMode.streaming);
+
+      final destination = MockDestination();
+      final logger = LDLogger(adapter: MockLogAdapter());
+      final config = ConnectionManagerConfig(
+        runInBackground: true,
+        backgroundConnectionMode: const FDv2Background(),
+        initialModeOverride: const FDv2Polling(),
+        debounceWindow: Duration.zero,
+      );
+      final mockDetector = MockStateDetector();
+
+      final connectionManager = ConnectionManager(
+        logger: logger,
+        config: config,
+        destination: destination,
+        detector: mockDetector,
+      );
+
+      mockDetector.setApplicationState(ApplicationState.background);
+      await mockDetector.applicationState.first;
+      await _pumpDebouncerHop();
+
+      // The override is honored regardless of lifecycle; the background slot
+      // is never resolved while the override is active.
+      verify(() => destination.setMode(const ResolvedPolling()));
+      verifyNever(() => destination.setMode(const ResolvedBackground()));
+
+      connectionManager.dispose();
+    });
+
+    test('clearing the override resumes automatic resolution', () async {
+      registerFallbackValue(ConnectionMode.streaming);
+
+      final destination = MockDestination();
+      final logger = LDLogger(adapter: MockLogAdapter());
+      final config = ConnectionManagerConfig(
+        runInBackground: true,
+        initialModeOverride: const FDv2Polling(),
+        debounceWindow: Duration.zero,
+      );
+      final mockDetector = MockStateDetector();
+
+      final connectionManager = ConnectionManager(
+        logger: logger,
+        config: config,
+        destination: destination,
+        detector: mockDetector,
+      );
+
+      await _pumpDebouncerHop();
+      reset(destination);
+
+      // Clearing the override resumes automatic resolution; in the foreground
+      // with network available that resolves to streaming.
+      connectionManager.setMode(null);
+      await _pumpDebouncerHop();
+
+      verify(() => destination.setMode(const ResolvedStreaming()));
+
+      connectionManager.dispose();
+    });
+  });
 }