Fault Tolerance Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require bugloos/fault-tolerance-bundle
   

   Ensure your project meets the requirements (PHP ≥7.4, Symfony ≥4.4).

2. Configuration Add the bundle to config/bundles.php:

   return [
       // ...
       Bugloos\FaultToleranceBundle\BugloosFaultToleranceBundle::class => ['all' => true],
   ];
   

3. Basic Setup Configure Redis (required for caching) in config/packages/bugloos_fault_tolerance.yaml:

   bugloos_fault_tolerance:
       redis:
           host: '127.0.0.1'
           port: 6379
           password: null
       circuit_breaker:
           failure_threshold: 3  # Number of failures before breaking
           reset_timeout: 30     # Seconds before resetting
   

4. First Use Case Wrap a service call in a circuit breaker:

   use Bugloos\FaultToleranceBundle\CircuitBreaker\CircuitBreaker;
   use Bugloos\FaultToleranceBundle\CircuitBreaker\CircuitBreakerInterface;
   
   $circuitBreaker = new CircuitBreaker(
       new CircuitBreakerInterface(), // Your service
       'my_service_key',              // Unique identifier
       3,                             // Failure threshold
       30                             // Reset timeout
   );
   
   try {
       $result = $circuitBreaker->execute();
   } catch (\Exception $e) {
       // Fallback logic (e.g., cached data or default response)
   }
   

Implementation Patterns

Common Workflows

1. Circuit Breaker for External APIs Use the bundle to wrap HTTP clients (e.g., Guzzle) to handle downstream service failures:

   $client = new GuzzleClient();
   $circuitBreaker = new CircuitBreaker(
       $client->getAsync('https://api.example.com/data'),
       'api_example_com',
       5,
       60
   );
   

2. Caching Responses Cache successful responses to avoid repeated calls:

   $circuitBreaker = new CircuitBreaker(
       $service->getData(),
       'cached_data_key',
       3,
       30,
       3600 // Cache TTL (1 hour)
   );
   

3. Fallback Strategies Define fallback logic for broken circuits:

   try {
       $data = $circuitBreaker->execute();
   } catch (CircuitBreakerOpenException $e) {
       $data = $this->getFallbackData(); // Static or cached fallback
   }
   

4. Symfony Integration Use dependency injection to manage circuit breakers:

   # config/services.yaml
   services:
       App\Service\ExternalApiService:
           arguments:
               $circuitBreaker: '@bugloos_fault_tolerance.circuit_breaker.external_api'
   

   Define the circuit breaker as a service:

   # config/packages/bugloos_fault_tolerance.yaml
   bugloos_fault_tolerance:
       circuit_breakers:
           external_api:
               service: App\Service\ExternalApiClient
               key: 'external_api'
               failure_threshold: 3
               reset_timeout: 30
   

Integration Tips

• Logging: Extend the bundle to log circuit breaker states:

  $circuitBreaker->onStateChange(function ($state) {
      \Log::info("Circuit Breaker state changed: {$state}");
  });
  

• Metrics: Track failures/resets with Prometheus or similar:

  $circuitBreaker->onFailure(function () {
      $this->metrics->increment('circuit_breaker_failures');
  });
  

• Dynamic Configuration: Use environment variables for thresholds/TTLs:

  bugloos_fault_tolerance:
      circuit_breaker:
          failure_threshold: '%env(int:CIRCUIT_BREAKER_THRESHOLD)%'
  

Gotchas and Tips

Pitfalls

1. Redis Dependency

   • The bundle requires Redis for caching and circuit breaker state. Ensure Redis is running and accessible.
   • Debugging: If Redis fails silently, check logs for connection errors or misconfigured bugloos_fault_tolerance.redis.

2. State Persistence

   • Circuit breaker states are stored in Redis. If Redis resets (e.g., container restart), breakers may reset unexpectedly.
   • Workaround: Use a persistent Redis instance or implement a fallback storage (e.g., database).

3. Thread Safety

   • The bundle is not thread-safe by default. In Symfony’s request-per-thread model, this is less critical, but be cautious in CLI or long-running processes.
   • Tip: Use a singleton pattern or ensure single-threaded execution for critical sections.

4. Fallback Data Freshness

   • Fallback data (cached or static) may become stale. Monitor cache TTLs and reset logic.
   • Tip: Add a last_updated timestamp to cached data and validate it before serving.

5. Exception Handling

   • The bundle catches exceptions by default. Customize which exceptions trigger failures:

     $circuitBreaker = new CircuitBreaker(
         $service->getData(),
         'key',
         3,
         30,
         null,
         [\TimeoutException::class, \ConnectException::class] // Specific exceptions
     );
     

Debugging

• Check Redis: Use redis-cli to inspect keys:

  redis-cli KEYS "*circuit_breaker*"
  redis-cli GET "circuit_breaker:my_service_key"
  

• Log Levels: Enable debug logging for the bundle:

  # config/packages/monolog.yaml
  handlers:
      main:
          level: debug
          # ...
  

• Test Locally: Simulate failures with a mock service:

  $mockService = $this->createMock(ServiceInterface::class);
  $mockService->method('getData')->willThrowException(new \RuntimeException('Simulated failure'));
  

Extension Points

1. Custom Fallback Logic Override the default fallback behavior:

   $circuitBreaker->setFallback(function () {
       return $this->fallbackRepository->findById(1); // Custom fallback
   });
   

2. Event Listeners Subscribe to circuit breaker events:

   $circuitBreaker->onOpen(function () {
       $this->alertingService->notify('Circuit breaker opened for my_service_key');
   });
   

3. Custom Storage Replace Redis with another storage backend (e.g., database) by implementing Bugloos\FaultToleranceBundle\Storage\StorageInterface.

4. Dynamic Thresholds Adjust thresholds at runtime:

   $circuitBreaker->setFailureThreshold($newThreshold);
   $circuitBreaker->setResetTimeout($newTimeout);
   

Configuration Quirks

• Default TTL for Cache: If not specified, cached responses use the circuit breaker’s reset_timeout as TTL.
• Key Naming: Use descriptive keys (e.g., service_name:operation) to avoid collisions.
• Symfony Cache: The bundle does not use Symfony’s cache system. Redis is mandatory for both circuit breaker states and caching.