feat: RetryProfile API for switching retry regimes at runtime

[tanderson-ld]

Summary

Adds a RetryProfile API so a caller can register multiple retry-timing profiles on a single stream and switch between them at runtime via Stream.ActivateProfile. Enables consumers to run a multi-regime retry policy (e.g., a normal regime + an extended regime for auth failures) while keeping the library's single-regime timing path intact for existing callers.

API additions

• NewRetryProfile(options ...RetryProfileOption) *RetryProfile — construct an opaque handle.
• RetryProfileBaseDelay(d), RetryProfileMaxDelay(d), RetryProfileJitter(r) — profile options.
• StreamOptionDefaultRetryProfile(profile) — designate as the stream's effective default.
• StreamOptionRegisterRetryProfile(profile) — register as an additional switchable profile.
• Stream.ActivateProfile(profile *RetryProfile) — switch the currently-active profile at runtime.
• StreamErrorHandlerResult.ActivateProfile — activate a profile from an error handler result (applied before the impending reconnect).
• DefaultProfile — package-level sentinel meaning "revert to the effective default."
• MaxServerDirectedRetryDelay = time.Hour — clamp ceiling for the SSE retry: field.

Legacy stream options (StreamOptionInitialRetry, StreamOptionUseBackoff, StreamOptionUseJitter, StreamOptionRetryResetInterval) continue to work unchanged; when no explicit RetryProfile is provided they synthesize the effective default.

Semantics

• Lazy overlay resolution. At delay-computation time, each property is resolved by walking active-profile.spec → effective-default.spec → hard-coded fallback. Profile specs are immutable.
• Per-profile formula counter n. Each registered profile tracks its own backoff-formula counter. Progression is retained across activations, so rapid oscillation between regimes preserves each regime's state.
• Healthy-op reset. When elapsed >= resetInterval, zeros every profile's n and reverts active to the effective default. Does NOT clear server-directed base-delay overrides (matches HTML5 SSE spec's "reconnection time is set until updated").
• Server retry: field. Updates every registered profile's base-delay override (stream-wide per HTML5). Never touches any profile's declared maxDelay ceiling.
• Wire clamp. SSE retry: values above MaxServerDirectedRetryDelay are clamped, in milliseconds before the time.Millisecond multiplication, so extreme int64 wire values cannot overflow the Duration.

Internal notes for reviewers

• backoffStrategy.applyBackoff and jitterStrategy.applyJitter interfaces were widened to accept per-call maxDelay / ratio. Math bodies are unchanged from the pre-existing library; only the parameter source moved from receiver fields to method args, so one strategy instance can serve multiple profiles.
• Internal SetBaseDelay renamed to ApplyRetryTime; it now iterates all registered profiles.

Test plan

• Full test suite passes (go test ./...).
• SSE contract-test harness passes (make contract-tests — "All tests passed").
• Pre-existing backoff/jitter math bodies preserved byte-for-byte in effect (only parameter sourcing changed).
• Library-maintainer review.

Refs SDK-2788.

---

Note

Overview
Introduces a RetryCurve model so one SSE stream can register multiple retry-timing profiles and switch the active profile at runtime via Stream.ActivateCurve, StreamErrorHandlerResult.ActivateCurve, and new options StreamOptionDefaultRetryCurve / StreamOptionRegisterRetryCurve. Each curve keeps its own backoff counter; healthy-period reset still reverts to the effective default (and overrides a same-tick activation), while server retry: hints apply stream-wide with a 1h clamp via MaxServerDirectedRetryDelay.

retryDelayStrategy is refactored from a single delay config to a map of curves with lazy property overlay (curve → default → fallbacks). Legacy StreamOptionInitialRetry / backoff / jitter options still synthesize the default when no explicit curve is set; retry option fields are now pointers so unset vs explicit zero (e.g. immediate retry) is preserved. SetBaseDelay becomes ApplyRetryTime; jitter gets a guard so zero-delay retries do not panic.

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

[tanderson-ld]

For reviewers: renamed, existing name was misleading, even on main this did more than set base delay.

[tanderson-ld]

For reviewers: Jitter is now passed as a param to the strategy at jitter application time.

[tanderson-ld]

For reviewers: backoffStrategy and jitterStrategy are internal only interfaces. The max and jitter are now properties of the retry curve and not fixed in the strategy.

[tanderson-ld]

For reviewers: jitter ratio moved to the retry curve to support cases of different jitters in different sitatuions.

[tanderson-ld]

For reviewers: if a default curve was not provided, we will make a default curve from the old stream options in order to not be a breaking change.

[tanderson-ld]

For reviewers: the baseDelayOverride is set via the server directed retry: event.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 3 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 295ff5f. Configure here.}