feat: Debounce lifecycle, network, and setMode signals

[tanderson-ld]

Summary

Implements CSFDV2 CONNMODE section 3.5 state-change debouncing for the Flutter SDK. Lifecycle, network, and user-requested-mode signals accumulate over a configurable window (default 1 second) before driving automatic mode resolution. Per spec 3.5.6, identify calls do not participate.

Stacked on #280 (-flutter); rebase onto main once that merges.

StateDebounceManager (common_client/data_sources/fdv2)

• DebouncedState holds networkAvailable, inForeground, requestedMode.
• Per-setter early-return on unchanged value.
• Duration.zero bypasses the timer (synchronous fire) for tests and FDv1-style immediate behavior.
• Injectable DebounceTimerFactory for fake_async-based testing.
• close() cancels any pending timer; setters after close are no-ops.

Flutter ConnectionManager integration

• ConnectionManagerConfig.debounceWindow (default 1s).
• Lifecycle and network listeners feed the debouncer instead of calling _handleState() directly. The debouncer's reconcile callback invokes _handleState() once the window closes.
• setMode(ConnectionMode? mode) sets _modeOverride synchronously (CONNMODE 2.0.3 -- automatic transitions suppressed immediately) and pushes through the debouncer (CONNMODE 3.5.5 -- mode application is debounced).
• Foreground -> background transition flushes synchronously per CONNMODE 3.3.1 (the process may be killed before the window closes); the debouncer still handles the resulting mode change.
• Network-availability propagation to the destination remains synchronous; only the mode-resolution outcome is debounced.

Tests

• state_debounce_manager_test: single-fire, flap-and-return, multi-axis change, requested-mode, close cancellation, immediate mode.
• connection_manager_test: existing assertions pinned to Duration.zero (preserve FDv1-style synchronous semantics); three new debounce-window tests using fake_async.

Resolves the two TODO sites in connection_manager.dart previously tagged SDK-2187.

---

Note

Medium Risk
Changes when connection modes flip (up to 1s delay by default), which affects streaming/polling/offline transitions; behavior is spec-driven and heavily tested, but timing-sensitive app logic could notice the difference from immediate resolution.

Overview
Adds FDv2 CONNMODE §3.5 debouncing so rapid lifecycle, network, and user setMode signals coalesce before automatic connection-mode resolution runs (default 1s window, configurable via ConnectionManagerConfig.debounceWindow).

Introduces StateDebounceManager in common_client with DebouncedState, timer reset on change, Duration.zero for immediate/test behavior, and public exports. Flutter ConnectionManager routes detector/setMode updates through the debouncer while offline, foreground→background flush, and destination network availability stay synchronous. setMode still sets the override immediately but applies the resolved mode after debounce. initialApplicationState (from FlutterStateDetector’s sync lifecycle read) seeds lifecycle so apps that start in background aren’t treated as foreground until the first event.

Tests use fake_async; existing connection-manager tests pin debounceWindow: Duration.zero; new tests cover debounce coalescing, immediate flush, and override-vs-network mid-window.

Note: ld_client.dart currently contains a duplicate if (config.offline) block (likely accidental).

^{Reviewed by Cursor Bugbot for commit 8213de6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Raw exception text in logs

Low Severity

The reconcile error handler logs the caught value with string interpolation ($error), which can embed sensitive request URIs or other PII from exception toString() output instead of a fixed, categorized message.

 

^{Triggered by learned rule: Never expose raw exception toString() in logs or StatusEvent messages in data sources}

^{Reviewed by Cursor Bugbot for commit 8edb1a6. Configure here.}

[kinyoklion]

Comment from Claude (AI assistant) running a review pass. Posted under @rlamb's account; treat as a draft for your judgment.

Latent: background-launched SDK never reconciles the destination from the buffered initial detector emission

While testing the new initialApplicationState plumbing I found a regression: when the SDK is constructed with initialApplicationState: ApplicationState.background (e.g. iOS/Android cold-launch into AppLifecycleState.paused), the destination never receives an initial setMode(...) call, and the data source keeps running whatever mode LDCommonClient was constructed with (default streaming).

Trace

1. FlutterStateDetector constructor synchronously calls _handleApplicationLifecycle(SchedulerBinding.instance.lifecycleState) (flutter_state_detector.dart:41-44). With the system in paused/hidden that adds ApplicationState.background to the single-subscription _applicationStateController.sink, which buffers the event until ConnectionManager subscribes.
2. ConnectionManager constructor (connection_manager.dart:191, 198-208):
   • sets _applicationState = config.initialApplicationState → background
   • seeds _debouncer._pending.inForeground = (config.initialApplicationState == ApplicationState.foreground) → false
3. ConnectionManager subscribes to the detector at line 211-212 and drains the buffered background event. _onApplicationStateChanged(background) (connection_manager.dart:220-230) runs:
   • Flush guard at lines 222-227: newState == background && _applicationState == foreground && !_offline. _applicationState is already background (from step 2), so guard is false. No flush.
   • _applicationState = background is a no-op (line 228).
   • _debouncer.setInForeground(false) early-returns at state_debounce_manager.dart:104-110 because _pending.inForeground == false already.
4. No timer schedules. _handleState() never runs. The destination receives no setMode(...) call.

Observable wrong outcome: a background-launched app runs a streaming/polling connection in the background, contrary to the configured backgroundConnectionMode (default FDv2Offline). On iOS that means an active SSE socket while the platform is about to suspend the process, with unflushed events (spec Req 3.3.1 violation). On Android, battery drain from a foreground-mode connection that should have switched to the background slot.

Pre-#281 this didn't fire because _applicationState was always seeded to foreground, so the buffered background event caused a real transition through _handleState().

Test gap

The new initialApplicationState seeds the lifecycle assumption ... test at connection_manager_test.dart:770-807 only asserts behaviour under a synchronous offline=true; offline=false toggle, which forces _handleState to run. It does not assert that the destination is reconciled without that user intervention.

Bug-proving test (red on HEAD 8edb1a6)

I verified red on HEAD (No matching calls (actually, no calls at all)) and green with the fix below. Drop this into the debounce window group in connection_manager_test.dart:

test(
    'background-launched SDK reconciles the destination from the buffered '
    'initial detector emission (without user intervention)', () async {
  registerFallbackValue(ConnectionMode.streaming);

  final destination = MockDestination();
  final logAdapter = MockLogAdapter();
  final logger = LDLogger(adapter: logAdapter);
  final config = ConnectionManagerConfig(
    runInBackground: false,
    debounceWindow: Duration.zero,
    initialApplicationState: ApplicationState.background,
  );
  final mockDetector = MockStateDetector();

  final connectionManager = ConnectionManager(
    logger: logger,
    config: config,
    destination: destination,
    detector: mockDetector,
  );

  // Simulate the real FlutterStateDetector emitting its buffered
  // initial-lifecycle event after ConnectionManager subscribes.
  mockDetector.setApplicationState(ApplicationState.background);
  await mockDetector.applicationState.first;

  verify(() => destination.setMode(
      const ResolvedOffline(OfflineBackgroundDisabled()))).called(1);

  connectionManager.dispose();
});

Suggested fix (verified green; all 26 tests pass)

Keep _applicationState seeded (so the synchronous flush-edge detection in _onApplicationStateChanged still works), but don't seed the debouncer's inForeground from initialApplicationState. Then the first detector emission flips a real bit through _debouncer.setInForeground(...), schedules a reconcile, and _handleState() runs:

// connection_manager.dart, in the ConnectionManager constructor
_debouncer = StateDebounceManager(
  // Seed the debouncer's view conservatively (default foreground +
  // available) so the first detector emission flips a real bit and
  // schedules a reconcile, even when [_applicationState] was seeded
  // to background via [config.initialApplicationState]. Otherwise
  // the buffered initial background event from the detector becomes
  // a double no-op (canonical field already matches, debouncer
  // setter early-returns) and the destination never sees the
  // initial mode.
  initialState: const DebouncedState(
    networkAvailable: true,
    inForeground: true,
    requestedMode: null,
  ),
  debounceWindow: config.debounceWindow,
  onReconcile: _onDebounceReconcile,
  logger: _logger,
);

I also tried calling _handleState() once at the end of the constructor (an alternative fix), but it broke 5 existing tests by dispatching an extra setMode at construction time. The above one-line change is the smaller, lower-blast-radius fix.

Happy to push this as a follow-up commit if useful.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8213de6. Configure here.}

[cursor]

Duplicate offline assignment in client

Low Severity

The same if (config.offline) { _connectionManager.offline = true; } block appears twice in a row in LDClient’s constructor, so offline mode is set redundantly with no added behavior.

 

^{Reviewed by Cursor Bugbot for commit 8213de6. Configure here.}