Skip to main content

Welcome to Polly Dart

Polly Dart is a comprehensive resilience and transient-fault-handling library for Dart applications. Inspired by the .NET Polly library, it provides developers with powerful tools to handle failures gracefully and build robust applications.

What is Resilience?​

In distributed systems and modern applications, failures are inevitable. Network calls timeout, services become unavailable, and resources get exhausted. Resilience is the ability of your application to handle these failures gracefully, recover quickly, and continue providing value to users.

Polly Dart helps you implement resilience patterns without cluttering your business logic with error-handling boilerplate code.

Why Polly Dart?​

🎯 Purpose-Built for Resilience​

Unlike generic error handling, Polly Dart provides specialized strategies designed for specific failure scenarios:

  • Transient failures → Retry with intelligent backoff
  • Cascading failures → Circuit Breaker protection
  • Slow operations → Timeout controls
  • Service degradation → Fallback mechanisms
  • Resource overload → Rate limiting and hedging

🔧 Developer Experience​

// Before: Complex error handling scattered throughout your code
try {
  result = await apiCall();
} catch (e) {
  if (isTransientError(e)) {
    await Future.delayed(Duration(seconds: 1));
    try {
      result = await apiCall();
    } catch (e2) {
      // More nested error handling...
    }
  }
}

// After: Clean, declarative resilience policies
final pipeline = ResiliencePipelineBuilder()
    .addRetry(RetryStrategyOptions(maxRetryAttempts: 3))
    .addTimeout(Duration(seconds: 10))
    .addFallback(FallbackStrategyOptions.withValue('default'))
    .build();

final result = await pipeline.execute(() => apiCall());

🏗️ Composable Architecture​

Strategies can be combined in any order to create sophisticated resilience pipelines:

Core Concepts​

🔄 Reactive Strategies​

Handle failures after they occur:

⚡ Proactive Strategies​

Prevent failures before they impact your system:

  • Timeout - Cancel long-running operations
  • Rate Limiter - Control operation rate and concurrency

Quick Start​

Get up and running in minutes:

1. Installation​

dependencies:
  polly_dart: ^0.1.0

2. Basic Usage​

import 'package:polly_dart/polly_dart.dart';

// Create a resilience pipeline
final pipeline = ResiliencePipelineBuilder()
    .addRetry(RetryStrategyOptions(maxRetryAttempts: 3))
    .addTimeout(Duration(seconds: 10))
    .build();

// Execute with resilience
final result = await pipeline.execute((context) async {
  return await httpClient.get('https://api.example.com/data');
});

3. Real-World Example​

// HTTP client with comprehensive resilience
final httpPipeline = ResiliencePipelineBuilder()
    .addRetry(RetryStrategyOptions(
      maxRetryAttempts: 3,
      delay: Duration(seconds: 1),
      backoffType: DelayBackoffType.exponential,
      shouldHandle: (outcome) => outcome.hasException && 
                                 isTransientHttpError(outcome.exception),
    ))
    .addCircuitBreaker(CircuitBreakerStrategyOptions(
      failureRatio: 0.5,
      samplingDuration: Duration(seconds: 30),
      minimumThroughput: 10,
      breakDuration: Duration(seconds: 5),
    ))
    .addTimeout(Duration(seconds: 30))
    .addFallback(FallbackStrategyOptions(
      fallbackAction: (args) async => Outcome.fromResult(getCachedData()),
      shouldHandle: (outcome) => true,
    ))
    .build();

// Use it
final data = await httpPipeline.execute((context) async {
  final response = await httpClient.get('https://api.example.com/critical-data');
  return processResponse(response);
});

What's Next?​

🚀 Get Started

New to Polly Dart? Start with our step-by-step guide.

Installation Guide

📚 Learn Strategies

Explore the resilience strategies and when to use them.

Resilience Strategies

🔧 API Reference

Complete API documentation with all classes and methods.

API Documentation

💡 Examples

Real-world examples and use cases.

View Examples

Community & Support​

Polly Dart is inspired by the .NET Polly library and adapted for the Dart ecosystem. Special thanks to the Polly community for pioneering resilience patterns.