feat: Wire FDv2 connection-mode resolution in common_client (#279)

## Summary

Wires the FDv2 mode-resolution scaffolding (merged via #274) into the
`common_client` runtime path. Keeps the FDv1 `ConnectionMode` enum and
all existing public API signatures unchanged.

This is the first half of the further split of the original behavior PR
(#275, now closed). The follow-up flutter-only PR wires this into the
Flutter SDK.

**LDCommonClient**
- `setMode(ConnectionMode)` keeps its FDv1 signature; internally maps
the 3 legacy modes to `ResolvedConnectionMode` before forwarding to
`DataSourceManager`.
- New `setResolvedMode(ResolvedConnectionMode)` is the advanced FDv2
entry point. Documented as EAP / not-stable. **No internal caller in
this PR** -- the Flutter SDK's `ConnectionManager` invokes it in the
follow-up flutter PR.
- `DataSourceFactoriesFn` (the public, optional constructor seam) stays
typed `Map<ConnectionMode, DataSourceFactory>` so external callers can
still customize streaming + polling. `_backgroundFactory` is SDK-managed
(background is FDv2-only), and `_composeFactoriesForManager` translates
the FDv1 map into the FDv2-keyed `Map<FDv2ConnectionMode,
DataSourceFactory>` consumed by `DataSourceManager`.

**DataSourceManager** (internal, not publicly exported)
- Active mode held as `ResolvedConnectionMode`.
- Factory map keyed by `FDv2ConnectionMode`.
- `ResolvedOffline` branches dispatch status as `setOffline` /
`networkUnavailable` / `backgroundDisabled` depending on
`OfflineDetail`.

Tests updated to match.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes core data-source connection and status behavior (including
removal of manager-level network toggling); public API is preserved but
internal mode transitions and offline semantics are more complex until
the Flutter layer adopts setResolvedMode.
> 
> **Overview**
> Wires **FDv2** connection-mode resolution into the `common_client`
runtime while keeping the public **`ConnectionMode`** API unchanged.
> 
> **`DataSourceManager`** now tracks **`FDv2ConnectionMode`** plus
**`OfflineDetail`**, accepts **`ResolvedConnectionMode`** via `setMode`,
and keys factories by FDv2 modes (including **background**). Offline no
longer always means “set offline”: **`ResolvedOffline`** maps
**`OfflineSetOffline`**, **`OfflineNetworkUnavailable`**, and
**`OfflineBackgroundDisabled`** to the matching data-source status
without starting a connection. Internal **`setNetworkAvailable`** on the
manager is removed—network-unavailable behavior is expected to come
through resolved offline modes instead.
> 
> **`LDCommonClient`** maps legacy `setMode(ConnectionMode)` to resolved
modes, adds EAP **`setResolvedMode`**, composes FDv1 custom factories
into an FDv2 factory map via **`_composeFactoriesForManager`**, and
registers an SDK-managed **background** polling factory.
`setNetworkAvailability` no longer touches the data source manager
(events only).
> 
> Tests are updated for FDv2 modes and the new offline status branches.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
0921328. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: tanderson-ld

packages/common_client/lib/src/data_sources/data_source_manager.dart

@@ -4,6 +4,9 @@ import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart'
     show LDContext, LDLogger;
 
 import '../connection_mode.dart';
+import '../fdv2_connection_mode.dart';
+import '../offline_detail.dart';
+import '../resolved_connection_mode.dart';
 import 'data_source.dart';
 import 'data_source_event_handler.dart';
 import 'data_source_status_manager.dart';
@@ -13,16 +16,21 @@ typedef DataSourceFactory = DataSource Function(LDContext context);
 /// The data source manager controls which data source is connected to
 /// the data source status as well as the data source event handler.
 final class DataSourceManager {
-  ConnectionMode _activeMode;
+  /// The mode that drives factory lookup and status dispatch.
+  FDv2ConnectionMode _activeConnectionMode;
+
+  /// Semantically meaningful only when [_activeConnectionMode] is
+  /// [FDv2Offline]. Otherwise carries a stale value from the last time the
+  /// SDK was offline (or the construction-time default), and is intentionally
+  /// only read inside the [FDv2Offline] arm of [_setupConnection].
+  OfflineDetail _offlineDetail;
+
   LDContext? _activeContext;
 
   final LDLogger _logger;
   final DataSourceStatusManager _statusManager;
   final DataSourceEventHandler _dataSourceEventHandler;
-  final Map<ConnectionMode, DataSourceFactory> _dataSourceFactories = {};
-
-  // At start we assume the network is available.
-  bool _networkAvailable = true;
+  final Map<FDv2ConnectionMode, DataSourceFactory> _dataSourceFactories = {};
 
   DataSource? _activeDataSource;
   StreamSubscription<MessageStatus?>? _subscription;
@@ -35,15 +43,20 @@ final class DataSourceManager {
     required DataSourceStatusManager statusManager,
     required DataSourceEventHandler dataSourceEventHandler,
     required LDLogger logger,
-  })  : _activeMode = startingMode,
+  })  : _activeConnectionMode = switch (startingMode) {
+          ConnectionMode.streaming => const FDv2Streaming(),
+          ConnectionMode.polling => const FDv2Polling(),
+          ConnectionMode.offline => const FDv2Offline(),
+        },
+        _offlineDetail = const OfflineSetOffline(),
         _logger = logger.subLogger('DataSourceManager'),
         _statusManager = statusManager,
         _dataSourceEventHandler = dataSourceEventHandler;
 
   /// Set the available data source factories. These factories will not apply
   /// until the next identify call. Currently factories will be set once during
   /// startup and before the first identify.
-  void setFactories(Map<ConnectionMode, DataSourceFactory> factories) {
+  void setFactories(Map<FDv2ConnectionMode, DataSourceFactory> factories) {
     _dataSourceFactories.clear();
     _dataSourceFactories.addAll(factories);
   }
@@ -55,25 +68,21 @@ final class DataSourceManager {
     _setupConnection();
   }
 
-  void setMode(ConnectionMode mode) {
-    if (mode == _activeMode) {
-      _logger.debug('Mode already active: $_activeMode');
-      return;
-    }
-    _logger.debug('Changing data source mode from: $_activeMode to: $mode');
-    _activeMode = mode;
-    _setupConnection();
-  }
-
-  void setNetworkAvailable(bool available) {
-    if (_networkAvailable == available) {
-      _logger.debug('Network availability set to same value: $available');
+  void setMode(ResolvedConnectionMode mode) {
+    final newConnectionMode = mode.connectionMode;
+    final newDetail = mode is ResolvedOffline ? mode.detail : null;
+    final isOffline = newConnectionMode is FDv2Offline;
+    if (newConnectionMode == _activeConnectionMode &&
+        (!isOffline || newDetail == _offlineDetail)) {
+      _logger.debug('Mode is already set to: $mode');
       return;
     }
-
     _logger.debug(
-        'Network availability changed from: $_networkAvailable to: $available');
-    _networkAvailable = available;
+        'Changing connection mode from: $_activeConnectionMode to: $mode');
+    _activeConnectionMode = newConnectionMode;
+    if (newDetail != null) {
+      _offlineDetail = newDetail;
+    }
     _setupConnection();
   }
 
@@ -83,7 +92,7 @@ final class DataSourceManager {
     _activeDataSource = null;
   }
 
-  DataSource? _createDataSource(ConnectionMode mode) {
+  DataSource? _createDataSource(FDv2ConnectionMode mode) {
     if (_activeContext != null) {
       if (_dataSourceFactories[mode] == null) {
         _logger.debug('No data source factory exists for mode: $mode');
@@ -107,33 +116,24 @@ final class DataSourceManager {
 
     _stopConnection();
 
-    // If the active mode is offline, then we do not need to setup
-    // a new connection. Additionally if we are offline, and the network
-    // is not available, our data source status should remain offline.
-    if (_activeMode == ConnectionMode.offline) {
-      _statusManager.setOffline();
-      return;
-    }
-
-    // We are not offline, but the network is not available, so we are going
-    // to set the status as unavailable and not start a new connection.
-    if (!_networkAvailable) {
-      _statusManager.setNetworkUnavailable();
-      return;
-    }
-
-    switch (_activeMode) {
-      case ConnectionMode.offline:
-        _statusManager.setOffline();
-      case ConnectionMode.streaming:
-      case ConnectionMode.polling:
-      // default:
-      // We may want to consider adding another state to the data source state
-      // for the intermediate between switching data sources, or for identifying
-      // a new context.
+    switch (_activeConnectionMode) {
+      case FDv2Offline():
+        switch (_offlineDetail) {
+          case OfflineSetOffline():
+            _statusManager.setOffline();
+          case OfflineNetworkUnavailable():
+            _statusManager.setNetworkUnavailable();
+          case OfflineBackgroundDisabled():
+            _statusManager.setBackgroundDisabled();
+        }
+        return;
+      case FDv2Streaming():
+      case FDv2Polling():
+      case FDv2Background():
+        break;
     }
 
-    _activeDataSource = _createDataSource(_activeMode);
+    _activeDataSource = _createDataSource(_activeConnectionMode);
     _subscription = _activeDataSource?.events.asyncMap((event) async {
       if (_activeContext == null) {
         _logger.error(

packages/common_client/lib/src/ld_common_client.dart

@@ -8,12 +8,17 @@ import 'config/data_source_config.dart';
 import 'config/defaults/credential_type.dart';
 import 'config/defaults/default_config.dart';
 import 'connection_mode.dart';
+import 'fdv2_connection_mode.dart';
+import 'offline_detail.dart';
+import 'resolved_connection_mode.dart';
 import 'context_modifiers/anonymous_context_modifier.dart';
 import 'context_modifiers/context_modifier.dart';
 import 'context_modifiers/env_context_modifier.dart';
 import 'hooks/hook.dart';
 import 'hooks/hook_runner.dart';
+import 'data_sources/data_source.dart';
 import 'data_sources/data_source_event_handler.dart';
+import 'data_sources/fdv2/built_in_modes.dart';
 import 'data_sources/data_source_manager.dart';
 import 'data_sources/data_source_status.dart';
 import 'data_sources/data_source_status_manager.dart';
@@ -76,35 +81,76 @@ typedef DataSourceFactoriesFn = Map<ConnectionMode, DataSourceFactory> Function(
 
 Map<ConnectionMode, DataSourceFactory> _defaultFactories(
     LDCommonConfig config, LDLogger logger, HttpProperties httpProperties) {
-  final pollingDataSourceConfig = PollingDataSourceConfig(
-      useReport: config.dataSourceConfig.useReport,
-      withReasons: config.dataSourceConfig.evaluationReasons,
+  final useReport = config.dataSourceConfig.useReport;
+  final withReasons = config.dataSourceConfig.evaluationReasons;
+
+  final foregroundPollingConfig = PollingDataSourceConfig(
+      useReport: useReport,
+      withReasons: withReasons,
       pollingInterval: config.dataSourceConfig.polling.pollingInterval);
+
+  DataSource streaming(LDContext context) {
+    return StreamingDataSource(
+        credential: config.sdkCredential,
+        context: context,
+        endpoints: config.serviceEndpoints,
+        logger: logger,
+        dataSourceConfig: StreamingDataSourceConfig(
+            useReport: useReport, withReasons: withReasons),
+        pollingDataSourceConfig: foregroundPollingConfig,
+        httpProperties: httpProperties);
+  }
+
   return {
-    ConnectionMode.streaming: (LDContext context) {
-      return StreamingDataSource(
-          credential: config.sdkCredential,
-          context: context,
-          endpoints: config.serviceEndpoints,
-          logger: logger,
-          dataSourceConfig: StreamingDataSourceConfig(
-              useReport: config.dataSourceConfig.useReport,
-              withReasons: config.dataSourceConfig.evaluationReasons),
-          pollingDataSourceConfig: pollingDataSourceConfig,
-          httpProperties: httpProperties);
-    },
+    ConnectionMode.streaming: streaming,
     ConnectionMode.polling: (LDContext context) {
       return PollingDataSource(
           credential: config.sdkCredential,
           context: context,
           endpoints: config.serviceEndpoints,
           logger: logger,
-          dataSourceConfig: pollingDataSourceConfig,
+          dataSourceConfig: foregroundPollingConfig,
           httpProperties: httpProperties);
     },
   };
 }
 
+/// Background factory is SDK-managed; it always uses the built-in
+/// reduced-frequency polling configuration. Customizing the background
+/// factory is intentionally not exposed via [DataSourceFactoriesFn].
+DataSourceFactory _backgroundFactory(
+    LDCommonConfig config, LDLogger logger, HttpProperties httpProperties) {
+  final backgroundPollingConfig = PollingDataSourceConfig(
+      useReport: config.dataSourceConfig.useReport,
+      withReasons: config.dataSourceConfig.evaluationReasons,
+      pollingInterval: BuiltInModes.defaultBackgroundPollInterval);
+  return (LDContext context) {
+    return PollingDataSource(
+        credential: config.sdkCredential,
+        context: context,
+        endpoints: config.serviceEndpoints,
+        logger: logger,
+        dataSourceConfig: backgroundPollingConfig,
+        httpProperties: httpProperties);
+  };
+}
+
+/// Translate the public, FDv1-keyed factory map (optionally with a custom
+/// override via [DataSourceFactoriesFn]) into the FDv2-keyed map consumed by
+/// [DataSourceManager], adding the SDK-managed background factory.
+Map<FDv2ConnectionMode, DataSourceFactory> _composeFactoriesForManager({
+  required Map<ConnectionMode, DataSourceFactory> fdv1Factories,
+  required DataSourceFactory backgroundFactory,
+}) {
+  return {
+    if (fdv1Factories[ConnectionMode.streaming] case final f?)
+      const FDv2Streaming(): f,
+    if (fdv1Factories[ConnectionMode.polling] case final f?)
+      const FDv2Polling(): f,
+    const FDv2Background(): backgroundFactory,
+  };
+}
+
 typedef EventProcessorFactory = EventProcessor Function(
     {required LDLogger logger,
     required bool indexEvents,
@@ -382,16 +428,16 @@ final class LDCommonClient {
     _updateEventSendingState();
 
     if (!_config.offline) {
-      _dataSourceManager
-          .setFactories(_dataSourceFactories(_config, _logger, httpProperties));
+      _dataSourceManager.setFactories(_composeFactoriesForManager(
+        fdv1Factories: _dataSourceFactories(_config, _logger, httpProperties),
+        backgroundFactory: _backgroundFactory(_config, _logger, httpProperties),
+      ));
     } else {
+      DataSource nullSource(LDContext _) => NullDataSource();
       _dataSourceManager.setFactories({
-        ConnectionMode.streaming: (LDContext context) {
-          return NullDataSource();
-        },
-        ConnectionMode.polling: (LDContext context) {
-          return NullDataSource();
-        },
+        const FDv2Streaming(): nullSource,
+        const FDv2Polling(): nullSource,
+        const FDv2Background(): nullSource,
       });
     }
   }
@@ -754,6 +800,20 @@ final class LDCommonClient {
 
   /// Set the connection mode the SDK should use.
   void setMode(ConnectionMode mode) {
+    _dataSourceManager.setMode(switch (mode) {
+      ConnectionMode.streaming => const ResolvedStreaming(),
+      ConnectionMode.polling => const ResolvedPolling(),
+      ConnectionMode.offline => const ResolvedOffline(OfflineSetOffline()),
+    });
+  }
+
+  /// Set a resolved FDv2 connection mode the SDK should use.
+  ///
+  /// 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 setResolvedMode(ResolvedConnectionMode mode) {
     _dataSourceManager.setMode(mode);
   }
 
@@ -764,7 +824,6 @@ final class LDCommonClient {
       return;
     }
     _networkAvailable = available;
-    _dataSourceManager.setNetworkAvailable(available);
     _updateEventSendingState();
   }