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). This PR is scoped to the server SDK only; the classifier helpers it consumes ship separately in #204.

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

• 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.

The classifier this SDK depends on — FailureClass and HttpErrors.classify* helpers — ships in #204.

Testing

• Unit tests — Full suite green. New coverage: 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

• 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.

Dependencies (why CI is red)

Two unreleased upstream artifacts:

• launchdarkly-java-sdk-internal ≥ 1.11.0 — Must be released before this PR can build against Maven Central. Ships via feat(internal): add FailureClass enum and classifier helpers to HttpErrors (SDK-2789) #204 + its release-please chore.
• okhttp-eventsource ≥ 5.0.0 — Must be released before this PR can build against Maven Central. Ships via launchdarkly/okhttp-eventsource#110.

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 data sources no longer treat HTTP auth and other “unexpected” failures as terminal. Streaming and polling keep retrying in the background with classified backoff instead of moving to State.OFF (e.g. 401/403).

Polling switches from fixed-rate scheduling to a self-driven loop backed by new PollingStrategy: normal cadence at pollInterval, extended exponential backoff (default 5 min → 1 hr cap, jitter) after FailureClass.UNEXPECTED, reset after two consecutive successes.

Streaming adopts okhttp-eventsource 5.x multi-regime RetryDelayStrategy: normal reconnect caps at 30s; on unexpected failures the SDK activates an extended strategy (5 min → 1 hr) and relies on a 60s healthy-connection threshold to return to normal timing.

Public docs and tests align with the new model: DataSourceStatusProvider Javadoc and LDClient init wording no longer describe HTTP errors as permanent shutdown; contract-test service advertises retry-conformance capabilities; unit/e2e tests assert continued retry and extended-regime behavior. Dependencies bump launchdarkly-java-sdk-internal and okhttp-eventsource for HttpErrors classification and strategy APIs.

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

[tanderson-ld]

CI Failures will be resolved once okhttp-eventsource and internal release. But waiting on initial review in this PR to make sure all the APIs on okhttp-eventsource and internal aren't going to need changes.

[jsonbailey]

Reviewed this alongside #204 and okhttp-eventsource#110 to check the API assumptions against the source rather than take the description's word for them. Broadly this holds up well — I specifically tried to break the two-consecutive-successes reset, the activateRetryDelayStrategy timing, and the polling loop lifecycle, and all three survived. The #110 integration is correct on every point I checked, including the one I most expected to be wrong: activation is a pointer swap that does not reset progression, so repeated 401s really do double 5→10→20→40→60 min. Using an explicit inExtended flag instead of comparing initialDelay == normalInterval avoids a real bug, and nInExtendedDoublesEvenWhenPollIntervalEqualsExtendedInitial is a good regression test for exactly that case.

I have a longer list of medium/low observations I'll hold for now. Two things I think block merge:

1. Won't compile against #204 HEAD. classifyAndLogHTTPFailure was renamed to classifyAndLogHttpFailure in #204's f67fd5e ("address review feedback on classifier helpers"). This branch predates that rename, and the local mavenLocal() snapshot is what hides it. Two call sites, inline below. Calling it out separately because it is not the unreleased-dependency-pin issue the description covers — it survives releasing both artifacts.

2. Worth one test before deciding anything else: the TLS classification may be far broader than intended. FailureClass.hasTlsOrCertificateCause (in #204) returns UNEXPECTED for any SSLException or GeneralSecurityException anywhere in the cause chain, and StreamIOException sets the underlying IOException as its cause, so the chain is reachable from StreamProcessor.handleError. Since all LD traffic is HTTPS, every transport error against the real endpoint arrives through the TLS layer — so SSLHandshakeException: Remote host terminated the handshake from a load balancer or proxy dropping mid-handshake reads as UNEXPECTED and pushes streaming into 5 min–1 hr backoff for a transient blip. The compounding part: a flapping stream never accumulates the 60 s of continuous connectivity the healthy-op reset needs, so it cannot climb back out.

I could not settle whether JSSE actually throws SSLException for these cases (no JVM available where I was reviewing), and about 20 lines answers it: open an SSLServerSocket, complete the handshake, then setSoLinger(true, 0) + close(), and read from the client — observe the exception type. Worth running before deciding: if the classification is as broad as it reads, this is the largest production-impact item in the change; if it isn't, the test costs nothing. Narrowing to SSLHandshakeException / SSLPeerUnverifiedException / CertificateException, or excluding causes that are themselves SocketException / SocketTimeoutException, would settle it either way.

On your test plan: the PollingStrategy transition semantics and the handleError ordering both check out — I traced the reset across intervening-failure and mixed NORMAL/UNEXPECTED orderings and found no off-by-one, and inExtended is cleared so a later UNEXPECTED re-fires the transition. No objection to the comment style.

[tanderson-ld]

Thanks @jsonbailey — both blocking items handled.

The classifyAndLogHttpFailure rename is fixed in 14de006 (both call sites), and d345b08 fixes a builder-test regression the earlier State.OFF-on-close change introduced. On the TLS breadth: you were right, and it reproduces — a peer closing mid-handshake with a FIN yields SSLHandshakeException: Remote host terminated the handshake (caused by EOFException) and classified UNEXPECTED, while the same fault as a RST yields SocketException and classified NORMAL. It's also a divergence from Go, which matches only certificate errors; the fix is in #206, narrowing to CertificateException / CertPathValidatorException / CertPathBuilderException / SSLPeerUnverifiedException.

Bugbot's two-consecutive-successes latency comment is resolved as working-as-specified per the polling spec — detail in that thread.

Still blocked on releases of #206 and launchdarkly/okhttp-eventsource#110 before the version pins can drop and CI can compile — note that means no tests run here today, which is how the builder-test regression stayed hidden. Happy to take the medium/low list whenever.

[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 92b58e1. Configure here.}

[jsonbailey]

One follow-up on the init future.

[jsonbailey]

Three more, all questions rather than blockers — one on diagnostics, two on polling test coverage.

Orphaned helper. verifyHttpErrorCausedShutdown (PollingProcessorTest.java:343) has no callers left — the rewrite removed all of them, since asserting State.OFF on an HTTP error is exactly the behavior this PR removes. Worth deleting rather than leaving as dead code. (Commenting here rather than inline because line 343 isn't in the diff.)

Relatedly, nothing asserts close() produces State.OFF. That's the entire purpose of d3b56a6, and d345b08 shows it's load-bearing — those two builder tests only needed a sink because close() now publishes status. A small test would cover both.