flutter_resilience 1.0.1

A production-ready Flutter/Dart package for network resilience. Implements automatic API retry, exponential backoff, circuit breaker, timeout handling, and request fallback logic. Inspired by Polly, d [...]

flutter_resilience

A production-ready Flutter/Dart package for network resilience, providing automatic API retry, exponential backoff, and circuit breaker functionality.

Overview

In modern mobile applications, network requests are prone to transient failures. flutter_resilience helps you build robust applications by providing a suite of resilience policies inspired by Polly, but designed specifically for the Flutter and Dart ecosystem.

Key Features

• 🔄 Automatic Retry: Effortlessly retry failed operations.
• 📈 Exponential Backoff & Jitter: Avoid overwhelming your backend with smart delay strategies.
• ⚡ Circuit Breaker: Prevent cascading failures by failing fast when a service is down.
• ⏱️ Timeout Handling: Ensure your app stays responsive by enforcing execution limits.
• 🛡️ Fallback Logic: Provide graceful degradation with secondary data sources.
• 🔗 Policy Composition: Combine multiple strategies into a single execution pipeline.

Why Quality Retry Logic Matters

Most developers implement basic for loops for retries, which often lack:

1. Wait and Retry: Retrying immediately can exacerbate server load.
2. Jitter: Simultaneous retries from many clients can create a "thundering herd" effect.
3. Circuit Breaking: Continuing to hit a dead service wastes battery and data.

flutter_resilience handles these complexities for you.

Installation

Add this to your pubspec.yaml:

dependencies:
  flutter_resilience: ^1.0.1

Quick Start

Simple Retry

final client = ResilientClient(retries: 3);

final response = await client.execute(() {
  return http.get(Uri.parse("https://api.example.com/data"));
});

Exponential Backoff with Jitter

final client = ResilientClient(
  retries: 5,
  strategy: RetryStrategy.jitter,
  retryDelay: Duration(seconds: 1),
);

Circuit Breaker

final circuitBreaker = CircuitBreaker(
  failureThreshold: 5,
  resetTimeout: Duration(seconds: 30),
);

final client = ResilientClient(circuitBreaker: circuitBreaker);

Fallback Support

final data = await client.execute(
  () => api.fetchData(),
  fallback: () => myOfflineCache.getData(),
);

Advanced Composition

You can compose policies manually for more control:

final policy = ResiliencePolicy(
  retry: RetryPolicy(maxRetries: 3),
  timeout: TimeoutPolicy(timeout: Duration(seconds: 2)),
  circuitBreaker: CircuitBreaker(failureThreshold: 3),
);

final result = await policy.execute(() => myAsyncAction());

Performance

• Zero unnecessary allocations: Designed for high-frequency requests.
• Thread-safe: Safe to use across multiple isolates if needed.
• Minimal overhead: Adds less than 1ms to the execution pipeline (excluding delays).

Comparison

Feature	flutter_resilience	Manual Retry
Exponential Backoff	✅	❌ (Hard)
Jitter Support	✅	❌
Circuit Breaker	✅	❌
Fallback Logic	✅	⚠️ (Manual)
Pipeline Composition	✅	❌

Best Practices

1. Use Jitter: Always use jitter for public-facing APIs to spread out retry load.
2. Filter Exceptions: Only retry on transient errors (e.g., SocketException, TimeoutException) using the retryIf parameter.
3. Dispose: Call dispose() on CircuitBreaker if it has a long-running timer and is no longer needed.

License

MIT License - see LICENSE for details.