eventsauce / backoff
Back-off strategy interface
Fund package maintenance!
frankdejonge
Installs: 278 959
Dependents: 6
Suggesters: 0
Security: 0
Stars: 68
Watchers: 2
Forks: 3
Open Issues: 2
Requires
- php: ^8.1
Requires (Dev)
- phpunit/phpunit: ^10
README
This library provides an interface for encapsulated back-off strategies.
composer require eventsauce/backoff
Leveraging the back-off strategies
A back-off strategy is applied in side a piece of code that retries a certain task.
<?php use EventSauce\BackOff\BackOffStrategy; class BusinessLogic { public function __construct( private ExternalDependency $dependency, private BackOffStrategy $backOff, ) {} public function performAction(): void { $tries = 0; start: try { ++$tries; $this->dependency->actionThatMayFail(); } catch (Throwable $throwable) { $this->backOff->backOff($tries, $throwable); goto start; } } }
Exponential back-off
A well-known back-off strategy is exponential back-off, which is the default provided strategy.
sleep = initial_delay * (base ^ (number_of_tries - 1)
<?php use EventSauce\BackOff\ExponentialBackOffStrategy; $backOff = new ExponentialBackOffStrategy( 100000, // initial delay in microseconds, 0.1 seconds 15, // max number of tries 2500000, // (optional) max delay in microseconds, default 2.5 seconds 2.0, // (optional) base to control the growth factor, default 2.0 ); $businessLogic = new BusinessLogic(new ExternalDependency(), $backOff); try { $businessLogic->performAction(); } catch (Throwable $throwable) { // handle the throwable }
Fibonacci back-off
The Fibonacci back-off strategy increases the back-off based on the fibonacci sequence.
sleep = initial_delay * fibonacci(number_of_tries)
<?php use EventSauce\BackOff\FibonacciBackOffStrategy; $backOff = new FibonacciBackOffStrategy( 100000, // initial delay in microseconds, 0.1 seconds 15, // max number of tries 2500000, // (optional) max delay in microseconds, default 2.5 seconds ); $businessLogic = new BusinessLogic(new ExternalDependency(), $backOff); try { $businessLogic->performAction(); } catch (Throwable $throwable) { // handle the throwable }
Linear back-off
The linear back-off strategy increases the back-off time linearly.
sleep = initial_delay * number_of_tries
<?php use EventSauce\BackOff\LinearBackOffStrategy; $backOff = new LinearBackOffStrategy( 100000, // initial delay in microseconds, 0.1 seconds 15, // max number of tries 2500000, // (optional) max delay in microseconds, default 2.5 seconds ); $businessLogic = new BusinessLogic(new ExternalDependency(), $backOff); try { $businessLogic->performAction(); } catch (Throwable $throwable) { // handle the throwable }
Jitter
When many clients are forced to retry, having deterministic interval can cause many of these clients to retry at the same time. Adding randomness to the mix ensures retrying clients are scattered across time. The randomness ensures that it is less likely for the clients to all retry at the same time.
Using Jitter
Every strategy that sleeps accepted a EventSauce\BackOff\Jitter\Jitter
implementation.
use EventSauce\BackOff\ExponentialBackOffStrategy; use EventSauce\BackOff\FibonacciBackOffStrategy; use EventSauce\BackOff\LinearBackOffStrategy; $exponential = new ExponentialBackOffStrategy(100000, 25, jitter: $jitter); $fibonacci = new FibonacciBackOffStrategy(100000, 25, jitter: $jitter); $linear = new LinearBackOffStrategy(100000, 25, jitter: $jitter);
Full Jitter
The full jitter uses a randomized value from 0 to the initial calculated sleep time.
sleep = number_between(0, sleep)
use EventSauce\BackOff\Jitter\FullJitter; $jitter = new FullJitter();
Half Jitter
The full jitter uses a randomized value from half the initial sleep to the full initial sleep time.
sleep = sleep / 2 + number_between(0 , sleep / 2)
use EventSauce\BackOff\Jitter\HalfJitter; $jitter = new HalfJitter();
Scattered Jitter
The scattered jitter uses a range in across which it's scatter the resulting values. To illustrate, here are a few examples:
jittered = sleep * range
base = sleep - jittered
sleep = base + number_between(0 , jittered * 2)
use EventSauce\BackOff\Jitter\ScatteredJitter; $jitter = new ScatteredJitter($range = 0.5);
Design rationale
Unlike other exponential back-off libraries, this library doesn't run the operation you want to retry. This makes the design of the package very simple. It also doesn't impose any limitations on the surround code.
You can retry based on a return value:
use EventSauce\BackOff\BackOffStrategy; function action(Client $client, BackOffStrategy $backOff): void { $tries = 0; start: $tries++; $response = $client->doSomething(); if ($response == SomeParticular::VALUE) { $backOff->backOff($tries, new LogicException('Exhausted back-off')); goto start; } }
You can retry on a specific exception type:
use EventSauce\BackOff\BackOffStrategy; function action(Client $client, BackOffStrategy $backOff): void { $tries = 0; start: $tries++; try { $client->doSomething(); } catch (SpecificException $exception) { $backOff->backOff($tries, $exception); goto start; } }
The choice is yours. Enjoy!
PS: yes, those were a lot of goto statements, deal with it 😎
But Frank, I'm super lazy!
Ok ok ok, well in that case, use the BackOffRunner
class to run any
callable
with a retry strategy.
use EventSauce\BackOff\BackOffRunner; use EventSauce\BackOff\ExponentialBackOffStrategy; $strategy = new ExponentialBackOffStrategy(initialDelayMs: 100, maxTries: 5); $runner = new BackOffRunner($strategy); $runner->run(function () { // Do something that might throw an exception! });
Want to only retry on certain exceptions? Pass the exception class as the second constructor argument.
use EventSauce\BackOff\BackOffRunner; use EventSauce\BackOff\ExponentialBackOffStrategy; $strategy = new ExponentialBackOffStrategy(initialDelayMs: 100, maxTries: 5); $runner = new BackOffRunner($strategy, LogicException::class); $runner->run(function () { // Only LogicException is retried, the rest is not! });