feat!: multi-strategy retry delay API for regime switching

[tanderson-ld]

Summary

Redesigns the retry-delay API on EventSource to support the LaunchDarkly RETRY-specification regime-switching pattern. Replaces the narrow setInitialRetryDelayMillis / setMaxRetryDelayMillis shape from the previous PR (#109) with a multi-strategy activation model.

Draft while the downstream consumer (java-server-sdk via java-core PR #200) is reworked to validate the new API end-to-end.

Tracks SDK-2789 under the RETRY-conformance epic SDK-2775.

Motivation

The previous PR's narrow setters had two fatal design smells:

• EventSource.setMaxRetryDelayMillis had to reach through the abstract RetryDelayStrategy to a concrete DefaultRetryDelayStrategy via instanceof. Custom strategies got a silent no-op.
• The apply(long baseDelayMillis) argument conflated wire retry hints with backoff progression, forcing every caller to pass a base value the strategy usually ignored.

The multi-strategy shape resolves both: no instanceof, no argument coupling, and per-strategy initial delays become expressible so an extended-regime strategy can start at 5 min while normal starts at 1 s.

What ships

RetryDelayStrategy (breaking)

• apply(long) and Result are removed.
• getDelayMillis() returns the delay for the current retry.
• getNext() returns the successor instance (immutable-progression pattern).
• withBaseDelayMillis(long) (default no-op) is the mutation channel for server-directed retry: hints. Custom strategies without a base concept opt out by not overriding.

DefaultRetryDelayStrategy

• New initialDelay(long, TimeUnit) builder method for per-strategy initial delay.
• Consolidated to a single baseDelayMillis field.
• Jitter uses ThreadLocalRandom instead of SecureRandom (backoff jitter doesn't need cryptographic entropy).

EventSource

• activateRetryDelayStrategy(RetryDelayStrategy) swaps the active registered strategy at runtime. Null / unregistered = silent no-op.
• Builder.retryDelayStrategy(RetryDelayStrategy) has additive semantics: first call sets the default (initially active AND the healthy-op reset target); subsequent calls register additional strategies for later activation.
• Each registered strategy retains its own backoff progression state across activations.
• Server-directed retry: hints are stored in serverDirectedInitialDelayMillis and applied to every registered strategy's reset instance — sticky across activations, matching WHATWG semantics.
• Reconnect-delay compute is deferred to sleep time so activation or wire hints received during the fault window affect the impending reconnect, not the one after.
• Removed getBaseRetryDelayMillis() / getNextRetryDelayMillis(). The reconnect delay is observable via the "Waiting X milliseconds before reconnecting" log message.
• Removed the historical delayNow = nextDelay - (now - disconnectedTime) subtraction — aligned with Go, .NET, and Swift SSE clients which sleep for the full computed delay.

Consumer example

```java
RetryDelayStrategy normal = RetryDelayStrategy.defaultStrategy()
.initialDelay(1, TimeUnit.SECONDS)
.maxDelay(30, TimeUnit.SECONDS);

RetryDelayStrategy extended = RetryDelayStrategy.defaultStrategy()
.initialDelay(5, TimeUnit.MINUTES)
.maxDelay(1, TimeUnit.HOURS);

EventSource es = new EventSource.Builder(...)
.retryDelayStrategy(normal) // first call = default
.retryDelayStrategy(extended) // second call = additional
.build();

// On extended-regime classification:
es.activateRetryDelayStrategy(extended);

// On healthy-op reset (revert to normal):
es.activateRetryDelayStrategy(normal);
```

Testing

• All ~215 existing tests pass; jacoco coverage passes.
• New tests in EventSourceRetryDelayStrategyUsageTest cover: activation swap, per-strategy state preservation across activations, healthy-op reset reverting to default, null/unregistered no-op.
• Test observability of reconnect delays migrated from es.nextReconnectDelayMillis field reads to a readReconnectDelayFromLog() helper that consumes the info log.

Downstream

Consumed by java-core PR #200 for the Java Server SDK's RETRY-conformance work. That PR's CI will be red until this ships to Maven Central.

---

Note

Overview
Breaking redesign of reconnect delay so callers can register multiple RetryDelayStrategy instances and switch among them at runtime (activateRetryDelayStrategy), for LaunchDarkly RETRY regime switching.

RetryDelayStrategy.apply / Result are replaced by immutable snapshots: getDelayMillis(), getNext(), and optional withBaseDelayMillis for SSE retry: hints. DefaultRetryDelayStrategy now owns its initial delay (initialDelay(...)) and rolls jitter once at construction (ThreadLocalRandom).

Builder.retryDelayStrategy is additive: first call is the default (healthy-op reset target); later calls register extra strategies. Each keeps its own backoff state across activations. Wire retry: values stick across resets. Reconnect delay is computed at sleep time (full delay, no elapsed-time subtraction). getBaseRetryDelayMillis / getNextRetryDelayMillis are removed.

^{Reviewed by Cursor Bugbot for commit 8fc09bd. 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 2 potential issues.

^{❌ 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 8fc09bd. Configure here.}

[cursor]

Healthy-op reset uses wrong duration

High Severity

Deferring reconnect-delay computation moved the healthy-op check to sleep time, but it still measures now - connectedTime. That includes the gap after disconnect, so a short connection plus a pause before reconnect can falsely reset backoff. The duration needs to reflect only the prior connection (for example via disconnectedTime - connectedTime), which matches the old fault-time behavior this PR intentionally deferred.

 

^{Reviewed by Cursor Bugbot for commit 8fc09bd. Configure here.}

[cursor]

Max delay not applied to current base

Medium Severity

maxDelay is enforced only when building the successor in getNext(), not when constructing the current instance. So getDelayMillis() can exceed the configured maximum whenever initialDelay or withBaseDelayMillis (including sticky retry: hints) sets a base above max. The previous apply() path pinned every attempt, including the first.

Additional Locations (1)

• src/main/java/com/launchdarkly/eventsource/DefaultRetryDelayStrategy.java#L156-L160

 

^{Reviewed by Cursor Bugbot for commit 8fc09bd. Configure here.}

[jsonbailey]

Overall, looks good. I'll hold off on approval until the cursor comments are addressed.

[jsonbailey]

This comment seems like it should be above the wait line.