refactor!: share one exponential backoff calculation

[spydon]

Tier 3 of #1572, third of four PRs. Stacked on #1645 (which is stacked on #1644).

What

The same "double the delay, cap it" math existed in three places:

Site	Before
RetryOptions.delay (supabase_common)	delayFactor * pow(2, min(attempt, 31)) * jitter, capped at maxDelay
RetryTimer.createRetryFunction (realtime_client)	firstDelay << min(tries - 1, maxShift), capped at maxDelay, in milliseconds
PostgrestBuilder._defaultRetryDelay	Duration(seconds: min(pow(2, attempt), 30))

All three now call one helper in supabase_common:

Duration exponentialBackoff(
  int attempt, {
  required Duration initialDelay,
  required Duration maxDelay,
  double randomizationFactor = 0,
  Random? random,
});

attempt is zero based, so attempt 0 waits initialDelay and each attempt after that doubles until maxDelay. Jitter is opt-in per caller, since only the storage upload retry uses it today.

No behaviour change

Each call site keeps the delays it had:

• realtime keeps its one-based tries and its millisecond return type, so RealtimeClient(reconnectAfterMs: ...) and the TimerCalculation typedef are untouched. It just passes tries - 1 to the helper.
• RetryOptions.delay keeps returning Duration.zero for attempt 0 and keeps its jitter.
• postgrest still starts at one second and caps at thirty.

maxShift (a public top-level const in realtime_client) is removed: the exponent clamp that stops the doubling from overflowing now lives with the shared calculation. It was not registered in the compliance matrix.

Realtime's millisecond-based options (reconnectAfterMs, heartbeatIntervalMs, longpollerTimeout) would read better as Durations, but converting them is a separate change; doing only reconnectAfterMs here would leave that API half converted.

Testing

New backoff_test.dart covers the start delay, the doubling, the cap, the absence of jitter by default and the jitter bounds with an injected Random. realtime_client's existing retry_timer_test.dart and postgrest's retry_test.dart pass unchanged, which is the real check that the delays did not move.

melos analyze and melos format clean; gotrue, postgrest, storage_client, realtime_client, supabase and supabase_common suites pass against the local stack. Capability matrix symbol and drift checks pass.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0dfec23b-f9b9-4894-b01c-ba38fba4cc69

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}