README

Closure-first retry with fixed/exponential backoff, full/additive jitter, time budgets, testable clock/sleeper/randomizer interfaces, observability hooks, and a PSR-18 HTTP client decorator that honors Retry-After.

Using an AI coding assistant? llms.txt contains a compact API reference you can share with the model.

Requirements

PHP 8.3+
psr/clock ^1.0
psr/http-client ^1.0
psr/http-message ^1.0 || ^2.0

Installation

composer require rasuvaeff/retry

Usage

use Rasuvaeff\Retry\Retry;

$value = Retry::new()
    ->maxAttempts(3)
    ->withExponential(baseMs: 100, multiplier: 2.0, capMs: 30_000)
    ->jitter(factor: 0.2)
    ->retryOn(RuntimeException::class)
    ->retryIf(fn(Throwable $e): bool => $e->getCode() >= 500)
    ->stopIf(fn(Throwable $e): bool => $e instanceof InvalidArgumentException)
    ->stopAfterMs(budgetMs: 10_000)
    ->onRetry(fn(AttemptRecord $record): null => null)
    ->run(fn(): string => flakyOperation());

Named policy factories return a ready-to-use builder:

Retry::fixed(delayMs: 500, maxAttempts: 3);
Retry::exponential(maxAttempts: 3);
Retry::immediate(maxAttempts: 3);

Tune a builder with the with* methods:

Retry::new()->withExponential(baseMs: 100, multiplier: 2.0, capMs: 30_000);
Retry::new()->withFixed(delayMs: 500);
Retry::new()->withImmediate();
Retry::new()->withClock(new SystemClock());

Every factory and builder method is a real, statically analysable method — there are no magic __call/__callStatic aliases.

By default a retry triggers on any \Exception. \Error (e.g. \TypeError, assertion failures) is not retried — opt in explicitly with retryOn(\Error::class). retryOn() replaces the class list (so you can narrow the default), while retryIf() and stopIf() layer extra predicates.

Jitter

jitter() selects a strategy with the Jitter\JitterMode enum. factor applies only to Additive (it is ignored for Full and None).

use Rasuvaeff\Retry\Jitter\JitterMode;

Retry::new()->jitter(factor: 0.2, mode: JitterMode::Additive); // equal jitter: [(1-factor)·delay, delay]
Retry::new()->jitter(mode: JitterMode::Full);                  // random in [0, delay]
Retry::new()->jitter(mode: JitterMode::None);                  // no jitter

Additive is "equal jitter": it only spreads the delay downward, so the jittered value never exceeds the backoff delay and capMs stays a hard ceiling. Or inject a strategy directly with withJitter(new Jitter\FullJitter()).

Retrying on a returned value

retryIfResult() retries when the operation returns successfully but the value is unacceptable (no exception needed). On exhaustion the rejected value is available via RetryExhausted::lastException (an UnacceptableResult).

$value = Retry::new()
    ->maxAttempts(5)
    ->retryIfResult(fn(Response $r): bool => $r->status === 'pending')
    ->run(fn(): Response => $api->poll());

Time budget

stopAfterMs() caps the total wall-clock time spent retrying. Attempt 1 always runs; a follow-up attempt is skipped when elapsed + nextDelay would exceed the budget, so unused sleep time is not added.

Retry::new()
    ->maxAttempts(maxAttempts: 10)
    ->withExponential(baseMs: 200)
    ->stopAfterMs(budgetMs: 5_000)
    ->run(fn(): string => flakyOperation());

Each AttemptRecord in RetryExhausted::history carries elapsedMs, the milliseconds between run() start and that attempt. onRetry callbacks receive the full AttemptRecord; onExhausted callbacks receive the RetryExhausted. RetryExhausted::reason is an ExhaustionReason (MaxAttempts or TimeBudget) explaining why the loop gave up. The terminal AttemptRecord has delayMs of null (no sleep followed it).

Result integration

This package does not depend on a Result type. To get a Result<T, RetryExhausted> without exceptions, wrap run() with your own Result library. With rasuvaeff/result:

use Rasuvaeff\Result\Result;

$result = Result::fromThrowable(
    fn() => Retry::new()->maxAttempts(3)->run(fn(): string => flakyOperation()),
);

$value = $result->unwrapOr('fallback');

Result::fromThrowable() catches any Throwable from run() (including RetryExhausted), so the error channel is Throwable unless you narrow it with mapErr().

PSR-18 decorator

RetryingHttpClient decorates any PSR-18 client. retryOnResponse decides which responses are retried; Http\RetryDecisions ships ready-made predicates.

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Rasuvaeff\Retry\Http\HttpAttemptRecord;
use Rasuvaeff\Retry\Http\HttpRetryExhausted;
use Rasuvaeff\Retry\Http\RetryDecisions;
use Rasuvaeff\Retry\Http\RetryingHttpClient;
use Rasuvaeff\Retry\RetryPolicy;

$client = new RetryingHttpClient(
    inner: $psr18Client,
    policy: RetryPolicy::exponential(maxAttempts: 3, baseMs: 100),
    retryOnResponse: RetryDecisions::onlyIdempotent(RetryDecisions::transient()),
    respectRetryAfter: true,
    maxRetryAfterMs: 300_000,
    budgetMs: null,
    retryOnException: null,
    throwOnExhausted: false,
    onRetry: [fn(HttpAttemptRecord $record): null => null],
    onExhausted: [fn(HttpRetryExhausted $exhausted): null => null],
);

Both retryOnResponse and retryOnException receive the RequestInterface as a second argument, so retries can be gated on the request method:

retryOnResponse: fn(ResponseInterface $r, RequestInterface $req): bool
    => $req->getMethod() === 'GET' && $r->getStatusCode() >= 500,

Ready-made response predicates:

Predicate	Retries on
`RetryDecisions::serverErrors()`	Any 5xx (500–599).
`RetryDecisions::rateLimited()`	429 only.
`RetryDecisions::transient()`	408, 425, 429, 500, 502, 503, 504.
`RetryDecisions::onlyIdempotent($inner)`	Wraps `$inner`; retries only idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, TRACE).

Constructor arguments beyond inner / policy / retryOnResponse:

Argument	Default	Effect
`clock`	`Clock\SystemClock`	PSR-20 clock for `Retry-After` HTTP-date parsing and budget timing.
`respectRetryAfter`	`true`	Honor the server's `Retry-After` header.
`maxRetryAfterMs`	`300_000`	Cap on a `Retry-After` delay; `null` disables the cap.
`budgetMs`	`null`	Total wall-clock budget; a retry is skipped when `elapsed + delay` would exceed it.
`retryOnException`	`null`	Predicate `fn(ClientExceptionInterface, RequestInterface): bool`; `null` retries every transport exception. Non-matching exceptions are rethrown as-is.
`throwOnExhausted`	`false`	When `true`, throw `Http\HttpRetryExhausted` (carrying the history) on exhaustion instead of returning the last response / rethrowing the last transport exception.
`onRetry`	`[]`	Callbacks `fn(HttpAttemptRecord): void` fired before each retry sleep.
`onExhausted`	`[]`	Callbacks `fn(HttpRetryExhausted): void` fired on every exhaustion (`maxAttempts` or `budgetMs`); the argument carries `attempts` and the full `history`.

A single attempt budget covers both retryable responses and PSR-18 transport exceptions, so the inner client is called at most maxAttempts times. When a retryable response carries a valid Retry-After header, that delay replaces the configured backoff (delta-seconds or IMF-fixdate; the obsolete RFC 850 and asctime date forms are ignored). The server delay carries no jitter and is capped by maxRetryAfterMs. Transport exceptions always fall back to backoff (no Retry-After is available). Pass respectRetryAfter: false to disable header handling.

Http\HttpRetryExhausted implements Psr\Http\Client\ClientExceptionInterface, so it stays within the PSR-18 contract — code that catches ClientExceptionInterface still catches it.

Each HttpAttemptRecord carries attempt, delayMs, elapsedMs, and exactly one of response / exception (never both, never neither). Inject a Clock\FakeClock to make Retry-After delays and budget timing deterministic in tests.

Public API

Class	Description
`Retry`	Immutable retry builder and closure runner.
`RetryPolicy`	Reusable policy object for decorators.
`RetryPolicyInterface`	Read-only policy contract.
`RetryExhausted`	Exception with attempts, last exception, history, and `reason`.
`ExhaustionReason`	Enum: `MaxAttempts` or `TimeBudget`.
`AttemptRecord`	One failed attempt: attempt number, `delayMs` (null when terminal), elapsed, and exception.
`UnacceptableResult`	Exception carrying the value a `retryIfResult()` predicate rejected.
`BackoffStrategy\BackoffStrategyInterface`	Backoff delay contract.
`BackoffStrategy\FixedBackoff`	Constant delay.
`BackoffStrategy\ExponentialBackoff`	Exponential delay with cap.
`BackoffStrategy\ImmediateBackoff`	Zero delay.
`Jitter\JitterInterface`	Jitter contract.
`Jitter\JitterMode`	Enum selecting a strategy for `jitter()`: `Additive`, `Full`, `None`.
`Jitter\FullJitter`	Random delay between zero and computed delay.
`Jitter\AdditiveJitter`	Equal jitter: spreads the delay downward, never above it.
`Jitter\NoJitter`	Leaves delay unchanged.
`Clock\SystemClock`	PSR-20 system clock.
`Clock\FakeClock`	Mutable PSR-20 clock for tests with `advanceMs()`.
`Sleeper\SleeperInterface`	Sleep contract.
`Sleeper\SystemSleeper`	`usleep()` implementation.
`Sleeper\FakeSleeper`	Test sleeper recording delays.
`Randomizer\RandomizerInterface`	Float randomizer contract.
`Randomizer\SystemRandomizer`	Runtime randomizer.
`Randomizer\FixedRandomizer`	Deterministic test randomizer.
`Http\RetryingHttpClient`	PSR-18 retrying decorator with `Retry-After` support.
`Http\RetryDecisions`	Ready-made response predicates + `onlyIdempotent()` wrapper.
`Http\HttpAttemptRecord`	One HTTP attempt: attempt, delay, elapsed, and `response` xor `exception`.
`Http\HttpRetryExhausted`	Exhaustion descriptor passed to every `onExhausted` hook and thrown when `throwOnExhausted` is set; a `ClientExceptionInterface` carrying `attempts` and the history.
`Http\RetryAfterParser`	Parses `Retry-After` into milliseconds via PSR-20 clock.

Long-running workers (RoadRunner, Swoole, FrankenPHP)

The package is safe to reuse across requests in a long-lived worker: every class is final readonly with no global or static mutable state, and SystemClock re-reads the wall clock on each now() call (it never freezes). Build a Retry or RetryingHttpClient once and share it.

The caveat is the backoff sleep. SystemSleeper::sleepMs() calls usleep(), which blocks the current worker for the whole delay. A worker serves one request at a time, so a retry that waits — exponential backoff up to capMs (default 30s), or a server Retry-After up to maxRetryAfterMs (default 300_000 = 5 min) — ties that worker up for the duration. With a fixed worker pool, a handful of requests retrying with long delays can starve the pool and collapse throughput.

Recommendations:

Lever	Action
Cap server-driven delays	Lower `maxRetryAfterMs` (e.g. a few seconds) so a hostile/large `Retry-After` cannot pin a worker; keep `capMs` and `budgetMs` modest.
Move long retries off the hot path	Run retries with meaningful backoff from a queue / RoadRunner Jobs worker, not the synchronous request worker.
Cooperative sleep	Inject a non-blocking `SleeperInterface` via `Retry::withSleeper()` (core) or the policy's sleeper (HTTP) when your runtime offers cooperative scheduling (e.g. a Swoole coroutine sleep).

RetryingHttpClient decorates your outgoing PSR-18 client; it is unrelated to the server's inbound PSR-7/PSR-15 request handling.

Security

This package only calls closures and PSR-18 clients supplied by the application. It does not inspect credentials, URLs, request bodies, or response bodies. Hooks receive exceptions and timing metadata; do not log secrets from exception messages without application-level redaction. Retry-After values are treated as opaque timing hints and are not used to construct URLs or queries.

Idempotency. RetryingHttpClient will retry whatever request you give it, including non-idempotent methods (POST, PATCH), which can cause duplicate side effects if the server processed the first request before failing the response. Gate retries to idempotent methods with RetryDecisions::onlyIdempotent(...) or your own request-aware predicate, unless the endpoint is safe to repeat (e.g. protected by an idempotency key).

Examples

See examples/ for runnable scripts.

Script	Shows	Needs server?
`basic.php`	Closure retry with fake sleeper and fixed backoff	No
`time_budget.php`	`stopAfterMs` with FakeClock + elapsed in history	No
`result_retry.php`	`retryIfResult` on a returned value; `UnacceptableResult` on exhaustion	No
`retry_after.php`	PSR-18 decorator: `RetryDecisions`, capped `Retry-After`, `onRetry` hook	No

Development

No PHP/Composer on the host. Run commands in Docker via the composer:2 image:

docker run --rm -v "$PWD":/app -w /app composer:2 composer install
docker run --rm -v "$PWD":/app -w /app composer:2 composer build
docker run --rm -v "$PWD":/app -w /app composer:2 composer cs:fix
docker run --rm -v "$PWD":/app -w /app composer:2 composer test
docker run --rm -v "$PWD":/app -w /app composer:2 composer release-check

Or with Make:

make install
make build
make cs-fix
make test
make test-coverage
make mutation
make release-check

License

BSD-3-Clause

rasuvaeff / retry

Maintainers

Package info

Statistics

Security

README

Requirements

Installation

Usage

Jitter

Retrying on a returned value

Time budget

Result integration

PSR-18 decorator

Public API

Long-running workers (RoadRunner, Swoole, FrankenPHP)

Security

Examples

Development

License