fix: Make FDv1 fallback TTL-based and recover to FDv2 after the TTL

[beekld]

Requirements

• I have added test coverage for new or changed functionality
• I have followed the repository's pull request submission guidelines
• I have validated my changes against all supported platform versions (CI runs Java 8/11/17/19; tested locally on Java 17)

Related issues

SDK-2987 (part of SDK-2935). Spec: sdk-specs#251 (DATASYSTEM v2 1.6). Reference: cpp-sdks#631.

Describe the solution you've provided

Makes the server SDK's FDv1 fallback directive TTL-based. Fallback no longer lasts forever, and the SDK goes back to FDv2 when the TTL is up.

• The TTL is read from X-LD-FD-Fallback-TTL (polling and streaming) and from goodbye.protocolFallbackTTL. If a goodbye has protocolFallbackTTL, that counts as a directive by itself.
• A TTL in (0, 1h] is used as-is, with no jitter. A TTL that is missing, malformed, zero, negative, or over 1h is replaced by the default: 1h minus a uniform random [0, 30m], so it lands in [30m, 1h]. This logic lives in the package-private FDv1FallbackDirective.
• On fallback, the FDv2 synchronizers that were available are suspended, not blocked for good. Once the TTL passes they come back, starting from the primary, and the FDv1 synchronizer is stopped. Synchronizers that had already failed terminally stay blocked.
• If no FDv1 fallback synchronizer is configured, the data source no longer goes to OFF. It reports INTERRUPTED (keeping the original error), runs no synchronizer during the TTL, then goes back to FDv2.
• If the FDv1 fallback synchronizer gets a new directive, the new TTL replaces the old one and FDv1 is not restarted (1.6.4.6).

Implementation details

• Single writer: All store writes still happen on the single FDv2DataSource run thread, and only results from the active synchronizer get applied. When no synchronizer replaces the active one, SourceManager.getNextAvailableSynchronizerAndSetActive now closes it. Without this, the FDv2 synchronizer that sent the directive would stay connected while the SDK waits out the TTL with no FDv1 fallback.
• TTL timer: FDv1FallbackExpiryCondition is a new condition type. While fallback is engaged, it is the only condition on the FDv1 synchronizer, so the normal fallback/recovery conditions don't apply. It resets its timer whenever it sees a result that carries a directive.
• Recovery restarts synchronizers only. Initializers are not re-run, which 1.6.4.2 allows.
• No FDv1 synchronizer: If an initializer sends the directive, start() stays pending until FDv2 recovers instead of finishing with false, so LDClient startup waits up to startWait. If there are no FDv2 synchronizers to go back to, the FDv1 synchronizer just keeps running.
• Public surface: the only additions are on the experimental FDv2SourceResult: getFdv1FallbackTtl() and 2-arg interrupted/terminalError/changeSet/goodbye overloads that take a nullable Duration (non-null means the result carries a directive with that TTL). The existing boolean fdv1Fallback factories still work; true with no TTL means the jittered default.
• Tests: Added unit tests showing that valid TTLs pass through unchanged, invalid TTLs get a default in [30m, 1h], and the header and goodbye TTLs are parsed. Also added data-source tests for recovery with and without an FDv1 synchronizer, for an FDv1-received directive replacing the TTL, and for the FDv1 synchronizer being stopped on recovery. The two tests that asserted OFF with no FDv1 synchronizer now assert INTERRUPTED followed by recovery.

Describe alternatives you've considered

Parsing protocolFallbackTTL in lib/shared/internal's Goodbye/FDv2ActionGoodbye. This PR deliberately leaves Goodbye.java unchanged. The server SDK depends on the released launchdarkly-java-sdk-internal (1.12.2), so a change there would need its own internal release and then a bump PR before the server could use it. Instead, the server reads protocolFallbackTTL straight from the goodbye event's JSON (FDv1FallbackDirective.fromGoodbye). That parsing can move into Goodbye in a later change if reviewers want it.

Additional context

No contract test changes, because the sdk-test-harness has no fallback-TTL coverage yet.

Link to Devin session: https://app.devin.ai/sessions/cdc21935a71a406bbe1b22dba462357c
Open in Devin Desktop: https://app.devin.ai/desktop/session/cdc21935a71a406bbe1b22dba462357c?variant=devin
Requested by: @beekld

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[beekld]

This makes me nervous. Why does this need to be public?

[devin-ai-integration]

There wasn't a good reason for it. FDv2SourceResult is public and in another package, so the directive type ended up public just so the result could carry it. In be4646a it's package-private now (com.launchdarkly.sdk.server.FDv1FallbackDirective, static helpers only).

The only public additions left are on the already-experimental FDv2SourceResult, and they follow the spec's fallbackToFDv1 + Duration? fallbackTTL shape:

• getFdv1FallbackTtl()
• 2-arg interrupted/terminalError/changeSet/goodbye overloads that take a nullable Duration

The data source applies the (0, 1h] check and the jittered default via FDv1FallbackDirective.ttlOrDefault, so the existing boolean factories still work: true with no TTL means the jittered default.

[beekld]

It's confusing to have FDv1FallbackDirective and FDv1FallbackDirectives. It would be nice if we could merge them.

[devin-ai-integration]

Merged in be4646a. There's now a single package-private FDv1FallbackDirective with ttlOrDefault, fromHeaders, and fromGoodbye, and its tests are in FDv1FallbackDirectiveTest.

[beekld]

Previously, fdv1 fallback was using just factory.block() and factory.unblock(). Why do we need this new suspendedForFDv1Fallback list?

[devin-ai-integration]

Before this PR, fallback was one-way, so a plain block() was enough. Now endFDv1Fallback() has to undo it. But Blocked also means "failed terminally" (TERMINAL_ERROR → blockCurrentSynchronizer(), "will not be used again until application restart"), so on recovery we can't just unblock every non-FDv1 synchronizer. That would bring back synchronizers that had failed permanently, for example after a 401. The list remembers which ones were Available when fallback started.

A simpler option, if you'd prefer it: add a third state, Suspended, to SynchronizerFactoryWithState. fdv1Fallback() would move Available → Suspended and endFDv1Fallback() would move Suspended → Available. That gets rid of the list and keeps everything in the existing state model. Happy to switch to it.