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 SSE reconnect timing: retry configuration moves from Builder.retryDelay(...) and RetryDelayStrategy.apply(long) into immutable strategy instances (getDelayMillis() / getNext()), with optional initialDelay(...) on DefaultRetryDelayStrategy and wire overrides via withBaseDelayMillis(long).

EventSource now registers multiple strategies at build time (first call = default + healthy-op reset target; later calls = additional). Runtime switching uses activateRetryDelayStrategy, with per-strategy backoff state preserved across swaps. Server retry: hints are clamped (1h cap), applied to all registered strategies, and stay sticky through resets. Reconnect sleep is computed at sleep time (not at fault time), healthy-op duration uses connection length only, and getBaseRetryDelayMillis / getNextRetryDelayMillis are removed.

Contract tests and the full test suite migrate to retryDelayStrategy(defaultStrategy().initialDelay(...)) and log-based delay assertions.

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

[jsonbailey]

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

[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 4999d92. Configure here.}

[tanderson-ld]

Waiting to merge/release until java-server PR is done with review.