feat(server): RETRY-spec conformance in FDv1 streaming and polling

[tanderson-ld]

Summary

Implements RETRY-spec conformance in the Java server SDK's FDv1 streaming and polling data sources (SDK-2789).

Behavioral change. HTTP responses that today cause an FDv1 data source to permanently stop (notably 401 / 403 / other 4xx) and TLS / certificate validation failures are no longer terminal. Streaming enters an extended-regime backoff (5 min initial → 1 hr max, doubling); polling continues at its configured cadence but engages the extended-regime wait after an UNEXPECTED failure. Either regime returns to normal after 60 s of continuous healthy operation (streaming) or two consecutive successful polls (polling).

Scope. FDv1 streaming and polling under lib/sdk/server/. FDv2, event delivery, and other network callers are unchanged.

What changed

• FailureClass enum + classifier helpers — Live in launchdarkly-java-sdk-internal's HttpErrors. Classifies HTTP status (400/408/429/5xx = NORMAL, other 4xx = UNEXPECTED) and transport exceptions (TLS / cert = UNEXPECTED).
• PollingStrategy — New state-machine encapsulation with onFailure(class) / onSuccess() / nextWait(). State: n (formula input), initialDelay, maxDelay, priorPollWasSuccessful. Wait floor is max(pollInterval, T − J); two consecutive successes reset from extended → normal.
• PollingProcessor — Rewired to a self-driven loop that consults strategy.nextWait() between attempts. The State.OFF permanent-stop path is removed; the state stays INITIALIZING or INTERRUPTED with a lastError.
• StreamProcessor — Consumes okhttp-eventsource's new multi-strategy retry API from launchdarkly/okhttp-eventsource#110. On UNEXPECTED classification it calls activateRetryDelayStrategy on the underlying EventSource to switch into the extended-regime RetryDelayStrategy. The library's built-in healthy-op reset returns the SDK to normal-regime timing after 60 s of continuous connectivity.
• DataSourceStatusProvider docs — State.INITIALIZING, State.OFF, State.INTERRUPTED, and getStateSince OFF-case Javadocs updated to reflect the new semantics (no HTTP-error → OFF transition). Aligned with the Go server SDK's parallel doc adjustments.
• LDClient constructor Javadoc — Wording tightened so a "wrong SDK key" scenario is described as ongoing retry in the background, not as an "unsuccessful initialization" that reads as terminal.
• Contract-test service — Declares retry-conformance-fdv1-streaming and retry-conformance-fdv1-polling capabilities.

Testing

• Unit tests — Full suite green. New coverage: HttpErrorsClassificationTest (classifier), PollingStrategyTest (strategy state machine), plus extended-regime timing-observation tests in StreamProcessorTest. Existing 401 / 403 tests were rewritten to assert extended-regime retry rather than permanent stop.
• Contract tests via sdk-test-harness#404 — All 7 RETRY-conformance test cases pass end-to-end at production timing (5-minute extended-initial delay). Total wall clock ~12 min via parallel shards.

Test plan for reviewers

• Sanity-check the FailureClass mapping — particularly TLS / cert = UNEXPECTED and any 4xx other than 400 / 408 / 429 = UNEXPECTED.
• Verify PollingStrategy transition semantics: normal → extended fires exactly once per UNEXPECTED failure; two consecutive successful polls fully reset (n = 0, delay bounds back to normal, inExtended cleared so a subsequent UNEXPECTED re-triggers the transition).
• Verify StreamProcessor.handleError ordering: classifier → regime switch → updateStatus(INTERRUPTED, …), unconditionally returning true so the eventsource keeps retrying.
• Review the DataSourceStatusProvider Javadoc changes for accuracy vs. the current state machine.
• Code comments deliberately describe current behavior only — no spec section refs, no historical framing ("previously", "no longer"), no cross-SDK references. Confirm you'd expect a reader to find that acceptable.

Dependency (why CI is red)

The multi-strategy retry API and the classifier helpers are only in unreleased branches:

• okhttp-eventsource ≥ 5.0.0 (see launchdarkly/okhttp-eventsource#110) — must be released before this PR can build against Maven Central.
• launchdarkly-java-sdk-internal ≥ 1.11.0 — must be released before this PR can build against Maven Central.

Once both are released, bump their versions in lib/sdk/server/build.gradle and CI will go green. Locally, the branch builds against mavenLocal() snapshots of both.

---

Note

Overview
FDv1 streaming and polling no longer treat HTTP 401/403 (and other unexpected 4xx) or TLS/cert failures as a permanent stop. Those failures now keep retrying with an extended backoff (5 min initial, doubling to 1 hr) instead of moving the data source to State.OFF.

Streaming uses EventSource’s multi-strategy retry API and switches to the extended regime on UNEXPECTED classification, then returns to normal after 60s of healthy connectivity. Polling is a self-scheduled loop driven by a new PollingStrategy state machine; two consecutive successful polls reset to the configured poll interval.

Shared FailureClass / HttpErrors classifiers distinguish NORMAL (400/408/429/5xx, generic I/O) vs UNEXPECTED (other 4xx, TLS). Status docs and tests now assert ongoing retry rather than shutdown. Contract-test capabilities retry-conformance-fdv1-streaming and retry-conformance-fdv1-polling are advertised. FDv2 and events are unchanged.

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

[cursor]

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

^{❌ 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 9394a65. Configure here.}

[cursor]

Extended wait after poll success

Medium Severity

After a successful poll while still in the extended regime, onSuccess leaves n unchanged, so nextWait keeps returning the large extended backoff. The confirming second success can be delayed by up to an hour, which stalls recovery long after the data source is healthy again and conflicts with returning to the configured poll cadence.

 

^{Reviewed by Cursor Bugbot for commit 9394a65. Configure here.}