feat: Add automatic retry with exponential backoff and circuit breaker

[sapientpants]

Summary

Implements intelligent retry logic with exponential backoff and circuit breaker pattern for improved reliability when the DeepSource API experiences transient failures. This feature ensures high availability without user intervention during API instability, rate limit spikes, or temporary network issues.

Changes

Core Retry Components

• Retry Policy Configuration (retry-policy.ts): Configurable policies for different endpoint types (aggressive, standard, cautious, none)
• Exponential Backoff (exponential-backoff.ts): Implements exponential backoff with jitter to prevent thundering herd
• Circuit Breaker (circuit-breaker.ts): Per-endpoint circuit breakers with three states (closed, open, half-open)
• Retry Budget (retry-budget.ts): Prevents resource exhaustion with per-minute retry limits
• Retry Executor (retry-executor.ts): Orchestrates all retry components

Integration

• Updated BaseClient to use retry logic for all GraphQL queries
• Enhanced error handlers to identify retriable errors
• Added comprehensive test coverage (unit + integration tests)
• Updated documentation with configuration options

Key Features

✅ Automatic Retry for Transient Failures

• Network errors (ECONNREFUSED, ETIMEDOUT, ECONNRESET)
• Server errors (502, 503, 504, 5XX)
• Rate limit errors (429) with Retry-After header support

✅ Safety Features

• Only retries idempotent operations (queries/GET requests)
• Never retries mutations (update_metric_threshold, update_metric_setting)
• Transparent to MCP clients - no user-visible errors during transient failures

✅ Resource Protection

• Circuit breaker prevents cascade failures
• Retry budget limits resource consumption
• Maximum duration caps to prevent infinite retries

Configuration

All retry parameters are configurable via environment variables:

Variable	Default	Description
RETRY_MAX_ATTEMPTS	3	Maximum retry attempts
RETRY_BASE_DELAY_MS	1000	Base delay for exponential backoff
RETRY_MAX_DELAY_MS	30000	Maximum delay between retries
RETRY_BUDGET_PER_MINUTE	10	Max retries per minute
CIRCUIT_BREAKER_THRESHOLD	5	Failures before opening circuit
CIRCUIT_BREAKER_TIMEOUT_MS	30000	Recovery timeout

Testing

• ✅ Comprehensive unit tests for all retry components
• ✅ Integration tests for retry behavior
• ✅ Property-based tests for jitter distribution
• ✅ Test coverage maintained above 80%

Impact

This change significantly improves the reliability of the DeepSource MCP server:

• Zero downtime during transient API failures
• Automatic recovery from rate limiting
• Better user experience - no manual intervention needed
• Production-ready for enterprise environments

Closes #153

🤖 Generated with Claude Code

[deepsource-io]

Here's the code health analysis summary for commits 74870dc..e93988a. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
Test coverage	❌ Failure	❗ 30 occurences introduced	View Check ↗
JavaScript	✅ Success		View Check ↗

Code Coverage Report

Metric	Aggregate	Javascript
Branch Coverage	88.5% (up 0.5% from main)	88.5% (up 0.5% from main)
Composite Coverage	89.6%	89.6%
Line Coverage	89.9% (down 0.1% from main)	89.9% (down 0.1% from main)
New Branch Coverage	96.6%	96.6%
New Composite Coverage	91.1%	91.1%
New Line Coverage	90%	90%

---

💡 If you’re a repository administrator, you can configure the quality gates from the settings.

[Copilot]

Pull Request Overview

This PR implements automatic retry logic with exponential backoff and circuit breaker patterns to improve reliability when the DeepSource API experiences transient failures. The implementation ensures high availability without user intervention during API instability, rate limiting, or temporary network issues.

Key changes include:

• Intelligent retry policies for different operation types (aggressive for critical reads, none for mutations)
• Exponential backoff with jitter and circuit breaker patterns for fault tolerance
• Retry budget management to prevent resource exhaustion

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/utils/retry/retry-policy.ts	Configurable retry policies with environment variable support
src/utils/retry/retry-executor.ts	Main orchestrator combining all retry components
src/utils/retry/retry-budget.ts	Budget management to limit retries per time window
src/utils/retry/exponential-backoff.ts	Exponential backoff calculations with jitter
src/utils/retry/circuit-breaker.ts	Circuit breaker implementation for fault tolerance
src/utils/retry/index.ts	Export aggregation for retry utilities
src/utils/errors/handlers.ts	Enhanced error handlers with retry support
src/client/base-client.ts	Integration of retry logic into GraphQL execution
src/__tests__/utils/retry/*.test.ts	Comprehensive test coverage for all components

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}