Skip to content

feat: Apply RETRY to FDv2 synchronizer orchestration - #423

Open
beekld wants to merge 26 commits into
mainfrom
bklimt/SDK-3507/retry-orchestration
Open

beekld wants to merge 26 commits into
mainfrom
bklimt/SDK-3507/retry-orchestration

Conversation

@beekld

@beekld beekld commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Applies the RETRY behavior to FDv2 synchronizer orchestration in the Android SDK, following launchdarkly/java-core#252 and launchdarkly/java-core#253. A synchronizer that fails is parked and retried later, instead of being blocked for good.

Parking

  • A synchronizer that fails unexpectedly is parked. That covers a terminal error, a failed or throwing next(), a failure to build, or shutting down on its own. The park delay starts at 5 minutes, doubles with each failure up to 1 hour, and has jitter. After a park, the next synchronizer starts after a failover delay of 0.5-1 seconds.
  • A synchronizer's park count resets when it meets its reset threshold. For the FDv2 polling and FDv1 fallback synchronizers, that's two successful polls in a row. For streaming, it's staying connected for 60 seconds.
  • The poll that a ping event triggers counts as a success or a failure for the streaming reset threshold.
  • When every synchronizer is parked, the data source reports INTERRUPTED and waits for the earliest unpark time. Synchronization stops only when the data source is stopped.
  • Fallback and recovery switch only to a synchronizer that isn't parked. When the fallback condition is met but no other synchronizer is available, the current synchronizer keeps running.
  • An exception on the stream thread is now terminal, so the streaming synchronizer is parked and rebuilt instead of staying dead.
  • The FDv2 status sink in ConnectivityManager now records an INTERRUPTED status with no error as a failure instead of a successful connection.

Directed fallback

  • The fallback to FDv1 now ends after a TTL, which defaults to 1 hour with jitter. The data source then restarts the FDv2 synchronizers.
  • A directive received during the fallback extends the TTL.
  • A directive with no FDv1 fallback synchronizer configured is no longer ignored. The data source reports INTERRUPTED, runs no synchronizer, and restarts the FDv2 synchronizers when the TTL ends.
  • When an initializer's directive comes with a payload that has no selector, the payload is applied but no longer marks the data source ready. Readiness waits for the next source's data, as the data system spec requires.

Deadlines

  • The synchronizer loop checks its fallback, recovery, unpark, and TTL deadlines each time it wakes. The deadlines use System.nanoTime(), so changes to the system clock don't move them. FDv2DataSourceConditions is removed.

Public API

This extends the public FDv2SourceResult class in com.launchdarkly.sdk.android.subsystems, the result type that initializers and synchronizers return. It adds two methods:

  • isResetThresholdMet() returns true if the source met its reset threshold at the time of the result. When a synchronizer returns such a result, the data source resets that synchronizer's park count. Results from the existing changeSet() and status() factory methods return false.
  • withResetThresholdMet() returns a copy of the result with isResetThresholdMet() set to true.

FDv2SourceResult is part of the early access FDv2 data system. It now carries the same note as the other early access types, saying that it is not stable and not subject to backwards compatibility guarantees or semantic versioning.

Not included

  • Treating TLS certificate failures as terminal. That needs FailureClass from a newer java-sdk-internal.
  • Honoring Retry-After, and reading the TTL from the response. Every directive uses the 1-hour default.

Note

Overview
Replaces permanent synchronizer blocking with park/backoff retry: unexpected failures park the active synchronizer (exponential delay from 5 minutes up to 1 hour, with jitter), wait on monotonic deadlines, then pick the next eligible source after a short failover delay. Fallback and recovery are driven inside FDv2DataSource via MonotonicTime waits instead of the removed FDv2DataSourceConditions timer futures.

Adds a reset threshold on FDv2SourceResult (isResetThresholdMet() / withResetThresholdMet()): polling/FDv1 fallback report it after two consecutive successful polls; streaming starts a timer (60s by default) after the first healthy result and emits a no-op changeset when the stream stays healthy. Meeting the threshold clears park counts so a recovered synchronizer can become preferred again.

FDv1 directive fallback now runs for a default 1-hour TTL (jittered), blocks FDv2 sources during the window, restarts FDv2 when TTL expires, and extends TTL if another directive arrives while already on FDv1. If no FDv1 synchronizer is configured, the data source stays INTERRUPTED with no active synchronizer until retry.

Connectivity treats INTERRUPTED status without an error as a failure (synthesizing or preserving the last error) so connection info does not show spurious success. Streaming treats an unexpected stream-thread exit as terminal so orchestration can park and rebuild. Initializer FDv1 directives only mark the data source ready when the applied payload includes a selector.

Reviewed by Cursor Bugbot for commit 81c3ae7. Bugbot is set up for automated code reviews on this repo. Configure here.

@beekld
beekld force-pushed the bklimt/SDK-3507/retry-orchestration branch from f6af197 to c2788f3 Compare November 12, 2026 22:51
@beekld
beekld marked this pull request as ready for review November 13, 2026 18:11
@beekld
beekld requested a review from a team as a code owner November 13, 2026 18:11

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix All in Cursor

❌ 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 843447f. Configure here.

@cursor cursor Bot added the risk:medium label Nov 13, 2026

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: medium.

Automated risk review (dry run): Medium

This PR would not be automatically approved. Human approval required.

Why: This reworks FDv2 synchronizer parking, retry, fallback TTL, and the public FDv2SourceResult API in FDv2DataSource, SourceManager, and related synchronizers. Cursor Bugbot also reported an unresolved medium-severity issue in FDv2StreamingSynchronizer where a failed ping poll can be overwritten by the reset-threshold timer.

If you disagree with this review, share this PR in #feedback-agent-approvals or submit a changes-requested review explaining why.

Open in Web View Automation 

Sent by Cursor Approval Agent: Dry-Run PR Approver

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant