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

[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
Aligns FDv1 streaming and polling with RETRY conformance: failures that used to shut the data source down permanently (e.g. 401/403 and other UNEXPECTED classifications) now stay in INITIALIZING or INTERRUPTED and keep retrying in the background.

Polling moves from fixed-rate scheduling to a PollingStrategy loop that picks the next wait after each attempt—normal cadence at the configured interval, extended exponential backoff (5 min initial, 1 hr cap, jitter) after UNEXPECTED failures, reset after two consecutive successful polls. PollingProcessor no longer cancels polling or sets State.OFF on HTTP errors.

Streaming wires okhttp-eventsource normal vs extended RetryDelayStrategy (30 s vs 5 min→1 hr), activates extended backoff on UNEXPECTED via activateRetryDelayStrategy, and always reconnects instead of stopping on “unrecoverable” HTTP statuses. Healthy connectivity for 60 s returns normal backoff via the eventsource reset threshold.

Public DataSourceStatusProvider and LDClient docs now describe OFF as shutdown-only (not invalid SDK key) and ongoing background retry. Contract-test service adds retry-conformance-fdv1-streaming and retry-conformance-fdv1-polling capabilities; unit/e2e tests assert extended retry instead of permanent failure.

^{Reviewed by Cursor Bugbot for commit d3b56a6. 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 6d0c138. 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.

[jsonbailey]

classifyAndLogHTTPFailure → classifyAndLogHttpFailure.

#204 renamed this in f67fd5e; the only such method at #204 HEAD is classifyAndLogHttpFailure (HttpErrors.java:156), and #204's own deprecation Javadoc at HttpErrors.java:76 uses the lowercase form too. git log -S in #204 shows 52c05c2 added it all-caps and f67fd5e renamed it, so this branch was written against the earlier revision.

This will fail compileJava once #204 merges and internal 1.11.0 publishes — separate from the unreleased-pin issue, since it survives releasing both artifacts.

[jsonbailey]

Second call site for the classifyAndLogHTTPFailure → classifyAndLogHttpFailure rename — see the note on PollingProcessor.java:126.