Download the PHP package gohany/rtry without Composer

Rtry — A pragmatic PHP retry & backoff toolkit

Robust, composable retries for HTTP, RPC, queues, and DB work. Rtry focuses on clear policy specs, safe defaults, and first‑class support for jitter, hedging, deadlines, and rate‑limit headers.

Namespaces used in this repo include Gohany\Rtry (implementation & policy) and Gohany\Retry (interfaces / runtime). The library targets PHP 7.4+ and works on PHP 8.x.

Table of contents

• Features
• Install
• Quick start
• Core concepts
  • Retry runtime
  • Retry policy
  • Delays & sequences
  • Jitter
  • Hedging
  • Deadlines vs. per‑attempt timeout
  • Following rate‑limit headers
  • Deciders
  • Rule‑based failure classification
• Array spec: authoring policies concisely
• Hooks
• Duration tokens
• Testing & code coverage
• CI badges
• Examples
• Contributing
• License

The specification docs are in SPEC.md.

Features

• Simple API: Retry::try(callable $op, RetryPolicyInterface $policy)
• Expressive policies: compact array spec (a, sa, dl, cap, j, h, seq, fh) or factory builders
• Backoff modes with jitter (full / plus‑minus / none)
• Hedging (concurrent lanes with stagger & cancel policy)
• Global deadlines and per‑attempt timeouts
• Follow server hints: Retry-After, RateLimit-Reset(-After), etc.
• Deciders & rules to control retry on specific failures / tags / status families
• PSR friendly: Psr\Clock\ClockInterface, Psr\Log\LoggerInterface, Psr\Http\Message\ResponseInterface
• Thorough tests and examples

Install

Via Composer:

Quick start

Core concepts

Retry runtime

Gohany\Rtry\Impl\Retry orchestrates attempts:

• asks the policy for startAfter, nextDelayMs(attempt), attemptTimeoutMs, deadlineBudgetMs, capMs, backoffMode
• applies jitter and cap
• optionally follows headers using the failure classifier (see below)
• respects deadlines and per‑attempt timeouts
• emits hooks: betweenAttempts, onGiveUp

Retry policy

Implemented by RetryPolicyInterface (base) and enriched by RtryPolicyInterface (jitter/hedge/backoff/classifier). Build via RtryPolicyFactory from an array spec or use the underlying parts (e.g., Attempts, Delay, Sequence, Jitter, Hedge).

Delays & sequences

Use a fixed backoff, exponential, or an explicit sequence.

Jitter

Jitter smooths out stampedes by randomizing delays.

JitterSpecInterface:

• mode() — 'full' | 'pm' | 'none' (pm = plus/minus)
• percent() — 0..1 (for plus/minus), or null
• windowMs() — absolute window (for plus/minus), or null
• apply(int $nominalDelayMs, ?int $seed = null): int

Spec examples for 'j':

Hedging

Run multiple lanes concurrently with a stagger delay, cancel others on first success/completion.

HedgeSpecInterface:

• getLanes(): int
• getStaggerDelayMs(): int
• getCancelPolicy(): int (CANCEL_ON_FIRST_SUCCESS=0 or CANCEL_ON_FIRST_COMPLETION=1)

Spec examples for 'h':

Deadlines vs per‑attempt timeout

• Global deadline (dl) sets a total budget for the whole retry run (sleep time counts).
• Per‑attempt timeout (timeout) limits a single attempt duration.

If there’s not enough budget for the next delay, Retry gives up and triggers the onGiveUp hook.

Following rate limit headers

With fh=1 (followHeaders=true), Retry consults the failure classifier to extract hints from responses:

• Retry-After: 1 → minimum next delay = 1000ms
• Retry-After: Wed, 21 Oct 2015 07:28:00 GMT → notBeforeUnixMs
• RateLimit-Reset(-After), X-RateLimit-Reset(-After), X-RateLimit-Reset-MS are recognized

The RateLimitBackoffRule returns FailureMetadata with minNextDelayMs or notBeforeUnixMs, and tags like RATE_LIMITED.

Deciders

Control whether to retry:

• AlwaysRetryDecider
• OnTokensDecider — retry on status codes (429, 503), families (4xx, 5xx), or named tags (RETRY-AFTER, TRANSIENT)
• CompositeDecider — OR composition (short‑circuit)

Rule‑based failure classification

RuleBasedFailureClassifier applies rules to a Throwable to derive status, tags, context patch, headers, and backoff hints:

• InstanceOfRule — match on exception class
• MessageRegexRule — match on message
• MethodStatusRule — pull status from getResponse(): ResponseInterface or getCode()
• RateLimitBackoffRule — parse standard rate‑limit headers

Derived tags include ETIMEDOUT, ECONNRESET, NETWORK_ERROR, and DB DEADLOCK heuristics.

Rtry spec: authoring policies concisely

You can configure multiple candidate values per key (the factory will validate & choose). Common keys:

Tip: numbers without unit default to milliseconds. 1.5m and 1.5s are supported; decimals for h/m/s are allowed.

Hooks

Duration tokens

• Accepted suffixes: ms, s, m, h
• Bare numbers = ms
• Decimals supported for s/m/h (e.g., 1.5s, 2.5m)
• Canonical formatting prefers compact, human‑readable units; sub‑second prints as bare ms

Testing & code coverage

Run the test suite:

Note: The test suite is configured to generate code coverage reports. If you encounter "No code coverage driver available", you'll need to install either Xdebug or PCOV:

Installing a code coverage driver

Option 1: PCOV (recommended for performance)

Then add to your php.ini:

Option 2: Xdebug

Then add to your php.ini:

Run tests without coverage:

Examples

Retry with sequence + jitter + follow headers

Hedged requests

Deciders: retry on 4xx/5xx or named tags

Contributing

• Run composer test (or vendor/bin/phpunit) before PRs
• Keep new rules/deciders covered with AAA‑style tests
• When adding new duration tokens or headers, document them here and in tests

License

MIT (see LICENSE).