circuit_breaker

Portuguese Brazil | Spanish

Implementation of the Circuit Breaker design pattern in Dart.

Version: 2.0.0 · License: See LICENSE

pub package Build Status GitHub top language

Why this project

  • Protects downstream services by automatically tripping when error rates rise.
  • Supports sliding-window failure rates, exponential backoff, health checks, fallbacks, retries, and basic persistence.
  • Small, dependency-light library that integrates with package:http.

Features

  • Circuit states: closed, open, halfOpen
  • Sliding window failure-rate detection
  • Exponential backoff for recovery timeouts
  • Optional health checks and fallback handlers
  • Retry policies and concurrency limiting (bulkhead)
  • Metrics and event stream for monitoring
  • Pluggable storage via CircuitBreakerStorage (in-memory and JSON helpers included)

Getting started

Prerequisites: Dart SDK 3.0+ (see pubspec.yaml).

Quick example

Future<void> genericExecuteExample() async {
  final CircuitBreaker cb = CircuitBreaker(
    failureThreshold: 2,
    timeout: const Duration(seconds: 2),
  );

  Future<String> fetchData(String id) async {
    // Simulate some async logic (not necessarily HTTP)
    if (id == 'fail') {
      throw Exception('Database connection error');
    }
    return 'Data for $id';
  }

  final String result = await cb.execute(() => fetchData('123'));

  try {
    await cb.execute(() => fetchData('fail'));
  } catch (e) {
    print('Caught error: $e');
  }

  try {
    await cb.execute(() => fetchData('fail'));
  } catch (e) {
    print('Caught error: $e');
  }

  print('Current state: ${cb.state}');

  // Execution when open with fallback
  final String fallbackResult = await cb.execute(
    () => fetchData('456'),
    fallback: (Object error) async => 'Cached data (fallback)',
  );
  print('Result with fallback: $fallbackResult');
}

Request

import 'package:http/http.dart' as http;
import 'package:circuit_breaker/circuit_breaker.dart';

Future<void> main() async {
  // Cria um CircuitBreaker
  final CircuitBreaker cb = CircuitBreaker(
    failureThreshold: 3,
    successThreshold: 2,
  );

  final http.Request request = http.Request('GET', Uri.parse('https://api.example.com/ping'));

  try {
    final http.StreamedResponse streamed = await cb.executeRequest(request);
    final http.Response response = await http.Response.fromStream(streamed);
    print('status: ${response.statusCode}');
    print('metrics: ${cb.metrics}');
  } catch (e) {
    print('Requisição falhou: $e');
  }
}

Using a fallback

import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:circuit_breaker/circuit_breaker.dart';

Future<void> main() async {
  final CircuitBreaker cb = CircuitBreaker(
    failureThreshold: 2,
    timeout: const Duration(seconds: 1),
    fallback: (http.BaseRequest request, Object? error) async {
      // Return a fallback response when circuit is open or request fails
      final Uint8List bytes = utf8.encode('{"fallback":true}');
      return http.StreamedResponse(Stream<Uint8List>.fromIterable(<Uint8List>[bytes]), 200, headers: <String, String>{
        'content-type': 'application/json',
        'content-length': bytes.length.toString(),
      });
    },
  );

  final http.Request request = http.Request('GET', Uri.parse('https://api.example.com/data'));
  final http.StreamedResponse streamed = await cb.executeRequest(request);
  final http.Response response = await http.Response.fromStream(streamed);
  print('body: ${response.body}');
}

More examples

For more examples see: example/main.dart

API surface

Primary entry points are in the library barrel: lib/circuit_breaker.dart. Key types:

  • CircuitBreaker — main class to create/lookup breakers (forHost, forEndpoint)
  • FallbackCallback, HealthCheckCallback, StateChangeCallback
  • RetryPolicy, CircuitBreakerMetrics, CircuitState, CircuitBreakerStorage

See the lib/src/ sources for implementation and examples of advanced options.

Where to get help

Maintainers & Contributing

  • Maintainer: DouglasMedeiros — see repository homepage in pubspec.yaml
  • Want to contribute? Please open an issue or PR. Add tests and follow existing code style.

If you plan large changes, open an issue first to discuss the design.

License

This project is available under the terms in the LICENSE file in this repository.

Small, focused library to make HTTP calls safer and more resilient. For detailed API docs, consult the source in lib/src/ and the tests in test/ for usage patterns.

Libraries

circuit_breaker