README

This library implements a PSR-18 compliant Circuit Breaker wrapper that can be used to ensure service stability and prevent overload or degradation in remote service calls.

Acknowledgement

This library is heavily inspired by:

• ackintosh/ganesha
• PrestaShop/circuit-breaker

Installation

To use Interim, install it using composer:

composer require flavioheleno/interrupt

Usage

As a PSR-18 HTTP Client Wrapper

// any PSR-18 compliant HTTP Client implementation
// $httpClient = new ...

// resolves the service name to its scheme + host + port
// eg. https://api.example.org/v1 -> https://api.example.org
// eg. https://api.example.org:5000/v1 -> https://api.example.org:5000
// can be replaced by StaticNameResolver
$serviceNameResolver = Interrupt\ServiceNameResolvers\UriBasedResolver();

// any PSR-6 compliant Cache Item Pool implementation
// $cacheItemPool = new ...

// any PSR-20 compliant Clock implementation
// $clock = new ...

// can be replaced by FixedTimeWindowBasedRecordStrategy
$recordStrategy = new Interrupt\RecordStrategies\SlidingTimeWindowBasedRecordStrategy(
  $clock
);

// can be replaced by CountBasedCircuitBreaker
$circuitBreaker = new Interrupt\CircuitBreakers\RateBasedCircuitBreaker(
  $clock,
  $cacheItemPool,
  $recordStrategy
);

$failureDetector = new Interrupt\FailureDetectors\HttpStatusBasedFailureDetector();

$client = new Psr18Wrapper(
  $httpClient,
  $serviceNameResolver,
  $circuitBreaker,
  $failureDetector
);

// when the called service is unavailable, $client will throw an
// Interrupt\Exceptions\ServiceUnavailableException exception.

As a Guzzle Middleware

$middleware = new GuzzleMiddleware(
  $serviceNameResolver,
  $circuitBreaker,
  $failureDetector
);

$handlerStack = \GuzzleHttp\HandlerStack::create();
$handlerStack->push($middleware);

$client = new GuzzleHttp\Client(['handler' => $handlerStack]);

// when the called service is unavailable, $client will throw an
// Interrupt\Exceptions\ServiceUnavailableException exception.

Components

Interrupt is built around the concept of components to allow easy integration with different environments or frameworks, making it a flexible and customizable library.

Service Name Resolver

To keep track of services accessed by the wrapped client, Interrupt uses the concept of Service Name Resolvers, that generates consistent service names based on request attributes.

Interrupt is distributed with:

• UriBasedResolver, a resolver implementation that generates service names from the request URI components
• StaticNameResolver, a resolver implementation that always return a constant service name

Record Strategy

The Record Strategy determines how Interrupt keeps track of failure events during a period of time.

A FixedTimeWindowBasedRecordStrategy that uses a predefined time interval to register failure records within its duration. Once the interval is over, the recorded failures are cleaned up and a new fixed interval starts.

A SlidingTimeWindowBasedRecordStrategy that uses a moving or shifting time interval to register failure records. Instead of fixed intervals, the time window slides (or moves along) with the failure stream.

The Sliding Time Window approach allows for continuous analysis of the most recent data while still considering a specific timeframe.

Note

Both strategies require a PSR-20 compatible Clock implementation.

Failure Detector

Failure can be subjective to context so Interrupt relies on Failure Detector to detect context-dependant failures.

Embedded in Psr18Wrapper is the failure detection for network issues, timeouts and any other thrown exception that extends Psr\Http\Client\ClientExceptionInterface.

In addition to that, the HttpStatusBasedFailureDetector interprets the HTTP Status Code as signal of failure.

Circuit Breakers

Interrupt comes with two Circuit Breakers implementations:

A CountBasedCircuitBreaker that monitors the number of failures recorded and automatically interrupts the flow of requests if the threshold is exceeded.

A RateBasedCircuitBreaker that monitors the rate or frequency of failures recorded and automatically interrupts the flow of requests if the error rate surpasses a predefined threshold.

Note

Both circuit breakers require a PSR-6 compatible Cache implementation.

License

This library is licensed under the MIT License.