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!
});