feature: Exponential Backoff And Jitter

[ysknsid25]

resolves: #581

Summary by CodeRabbit

• New Features

  • Added exponential backoff with jitter for retries with three configurable strategies (full-jitter, equal-jitter, decorrelated-jitter)
  • Retry attempt counter now accessible in request context
  • retryBackoff configuration takes precedence over retryDelay for advanced retry control

• Documentation

  • Updated retry documentation with exponential backoff configuration guide and jitter strategy details

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds opt-in exponential backoff with jitter strategies (full-jitter, equal-jitter, decorrelated-jitter) to the retry mechanism via new retryBackoff option. Introduces computeBackoffDelay function, extends FetchContext with retryAttempt field, and threads retry state through the fetch/retry pipeline. Includes comprehensive tests and user documentation.

Changes

Retry Backoff with Jitter

Layer / File(s)	Summary
Backoff computation with strategies src/retry.ts, test/retry.test.ts	New computeBackoffDelay function implements three jitter strategies with exponent saturation, previous delay tracking, and injectable randomness. Tests cover edge cases, growth, cap enforcement, and decorrelated strategy behavior.
Type contracts and public API extensions src/types.ts	Adds retryBackoff?: RetryBackoffOptions to FetchOptions, includes retryBackoff in GlobalOptions, adds retryAttempt?: number to FetchContext, and re-exports strategy types from retry module.
Fetch retry loop with backoff and state threading src/fetch.ts, test/index.test.ts	Integrates computeBackoffDelay into retry logic via RetryInternalState, prefers retryBackoff over retryDelay, threads attempt and previous delay across retries, and sets context.retryAttempt. Tests validate attempt progression and retryBackoff precedence.
User-facing documentation README.md	Documents retryBackoff configuration shape, supported jitter strategies, precedence over retryDelay, and ctx.retryAttempt meaning during retries.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Retry with jitter, oh what delight,
No more thundering herds in the night,
Exponential backoff spreads requests with care,
Three strategies swirling through the air,
Delay, adapt, and decorate right! 🎲

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feature: Exponential Backoff And Jitter' clearly and concisely describes the main feature addition in this PR, matching the primary objective of adding exponential backoff with jitter strategies for automatic retries.
Linked Issues check	✅ Passed	The PR fully implements all coding requirements from issue #581: exposes retryBackoff with three strategies (full-jitter, equal-jitter, decorrelated-jitter), implements computeBackoffDelay with proper delay calculations, exposes retryAttempt on FetchContext, ensures retryBackoff precedence over retryDelay, and includes comprehensive unit and integration tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing retryBackoff: new src/retry.ts module, updated src/types.ts with new options and context fields, modified src/fetch.ts retry logic, comprehensive test coverage, and README documentation—all aligned with issue #581 requirements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.66%. Comparing base (27996d3) to head (0b15f3e).
⚠️ Report is 102 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #582       +/-   ##
===========================================
+ Coverage   56.86%   86.66%   +29.79%     
===========================================
  Files          16        6       -10     
  Lines         728      285      -443     
  Branches      113      140       +27     
===========================================
- Hits          414      247      -167     
+ Misses        303       33      -270     
+ Partials       11        5        -6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/retry.ts`:
- Around line 11-14: The JSDoc for the `base` field is misleading: update the
comment for `base` (in src/retry.ts) to explain it is the base/backoff factor
used to compute retry delays rather than a guaranteed minimum delay — explicitly
state that for jitter strategies like `full-jitter` and `equal-jitter` computed
delays can be below `base` (even 0); keep `cap` description as the upper bound.
Mention the relevant symbols `base`, `cap`, and the jitter strategies
(`full-jitter`, `equal-jitter`) so readers understand the semantics.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 19017108-30b1-49e8-bbb6-ac238b81518b

📥 Commits

Reviewing files that changed from the base of the PR and between dfbe3ca and 0b15f3e.

📒 Files selected for processing (6)

• README.md
• src/fetch.ts
• src/retry.ts
• src/types.ts
• test/index.test.ts
• test/retry.test.ts

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify base semantics in API docs.

base is not a strict minimum delay for full-jitter and equal-jitter (those can go below base, including 0). Please reword this to avoid misleading users.

Suggested wording

-  /** Minimum delay in milliseconds. */
+  /** Base delay in milliseconds used by backoff calculations. */
   base: number;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	/** Minimum delay in milliseconds. */
	base: number;
	/** Maximum delay in milliseconds. */
	cap: number;
	/** Base delay in milliseconds used by backoff calculations. */
	base: number;
	/** Maximum delay in milliseconds. */
	cap: number;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/retry.ts` around lines 11 - 14, The JSDoc for the `base` field is
misleading: update the comment for `base` (in src/retry.ts) to explain it is the
base/backoff factor used to compute retry delays rather than a guaranteed
minimum delay — explicitly state that for jitter strategies like `full-jitter`
and `equal-jitter` computed delays can be below `base` (even 0); keep `cap`
description as the upper bound. Mention the relevant symbols `base`, `cap`, and
the jitter strategies (`full-jitter`, `equal-jitter`) so readers understand the
semantics.