Resolves #85

What is the feature

This pull request introduces a CircuitBreaker class that implements the Circuit Breaker design pattern. The class manages the states of 'closed', 'open', and 'half-open' to prevent continuous failures from overloading the system. It depends on the MemoryCache class (from issue #84) to persist its state across different executions. The CircuitBreaker allows configurable settings for failureThreshold and resetTimeout through the constructor or setter methods.

Why we need the feature

Implementing a Circuit Breaker is essential for building resilient applications that can handle failures gracefully. Without it, a failing service could cause cascading failures throughout the system, leading to system-wide outages. The CircuitBreaker class helps prevent this by:

• Protecting resources: It stops retrying operations that are likely to fail, freeing up resources for other operations.
• Improving stability: By controlling the failure flow, it prevents the system from being overwhelmed by a high volume of failed operations.
• Enhancing user experience: It provides faster failure responses when a service is unavailable, allowing the application to fall back or inform the user promptly.

How to implement and why

1. Create the CircuitBreaker class in src/CircuitBreaker.php:

   • Dependencies:
     • Inject an instance of MemoryCache to handle state persistence.
     • This allows the circuit breaker to maintain its state across different requests or processes.
   • Configurable Settings:
     • Allow failureThreshold and resetTimeout to be set via the constructor or setter methods.
     • This provides flexibility to adjust the sensitivity and recovery time of the circuit breaker based on application requirements.
   • State Variables:
     • Initialize state (default 'closed'), failureCount, and lastFailureTime.
     • These track the current status and help determine when to open or close the circuit.
   • Implement State Persistence Methods:
     • saveState(): Saves the current state to the cache.
     • loadState(): Loads the state from the cache during initialization.
     • Ensures that the circuit breaker retains its state even if the application restarts.

2. Implement the execute method:

   • State Checks:
     • If the state is 'open' and the reset timeout has passed, change the state to 'half-open'.
     • If the state is 'open' and the timeout hasn't passed, throw a CircuitBreakerOpenException.
     • This prevents operations from being executed when the circuit is open.
   • Operation Execution:
     • If the circuit is 'closed' or 'half-open', attempt to execute the provided callable.
     • On success:
       • Reset the circuit breaker using the reset() method.
       • This sets the state back to 'closed' and clears failure counts.
     • On failure:
       • Handle the failure using the handleFailure() method.
       • Increment the failure count and update the last failure time.
       • If the failure threshold is reached, set the state to 'open'.
   • Exception Handling:
     • Catch exceptions from the operation and re-throw them after handling.
     • Ensure that state is saved regardless of success or failure.

3. Implement State Transition Methods:

   • handleFailure():
     • Increments failureCount and updates lastFailureTime.
     • Checks if failureCount exceeds failureThreshold to open the circuit.
   • isTimeoutReached():
     • Determines if the reset timeout has passed since lastFailureTime.
     • Used to transition from 'open' to 'half-open' state.
   • reset():
     • Resets failureCount, lastFailureTime, and sets state to 'closed'.
     • Called after a successful operation during 'half-open' or 'closed' states.

4. Create the CircuitBreakerOpenException in src/Exceptions/CircuitBreakerOpenException.php:

   • Custom exception to indicate that the circuit is currently open.
   • Provides information on when the circuit will attempt to reset.

5. Add Unit Tests in tests/CircuitBreakerTest.php:

   • Test Initialization:
     • Ensure that the circuit breaker initializes correctly with default and custom settings.
   • Test State Transitions:
     • Simulate failures to reach the failure threshold and confirm state changes.
     • Test the transition from 'open' to 'half-open' after the reset timeout.
   • Test Execution Flow:
     • Verify that successful executions reset the circuit breaker.
     • Confirm that exceptions are thrown when the circuit is open.
   • Test Persistence:
     • Check that state is persisted between executions using MemoryCache.

6. Update Documentation:

   • Usage Guide:
     • Add examples and instructions on how to use the CircuitBreaker class.
     • Explain how to configure the settings and handle exceptions.
   • API Reference:
     • Document public methods and properties for clarity.

7. Why these steps:

   • Step-by-Step Implementation:
     • Breaking down the implementation ensures each component works correctly before moving on.
     • Allows for easier debugging and maintenance.
   • Dependency Injection:
     • Improves testability and flexibility.
   • State Persistence:
     • Essential for the circuit breaker's effectiveness across multiple requests.
   • Thorough Testing:
     • Validates that the circuit breaker behaves as expected in various scenarios.
   • Documentation:
     • Assists other developers in understanding and utilizing the new feature effectively.

About backward compatibility

This addition is backward compatible as it introduces new classes and functionality without altering existing code. The CircuitBreaker class and CircuitBreakerOpenException are new components that do not interfere with or modify any current interfaces or classes in the system. Existing codebases will continue to function as before, and developers can opt to use the circuit breaker at their discretion.

Test these changes locally

git checkout -b gitauto/issue-#85-a839d2b3-6218-417c-a9d3-625fdce6fd73
git pull origin gitauto/issue-#85-a839d2b3-6218-417c-a9d3-625fdce6fd73