feat: opt-in HTTP client resilience layer (retry/backoff/jitter)

Client::withRetryPolicy()/setRetryPolicy()/getRetryPolicy() enable automatic
retry of transient failures (connection errors, timeouts, 408/425/429/5xx) with
exponential backoff, bounded jitter, a max-attempts cap and Retry-After support.
New InitPHP\HTTP\Client\Retry\ namespace; the single cURL attempt is exposed
as a protected Client::transport() seam. Backward compatible: with no policy the
client stays single-attempt and still returns (never throws) 4xx/5xx per PSR-18.

Author: muhammetsafak

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Content-Type-aware body parsing** in `createFromGlobals` (JSON / urlencoded / multipart).
 - **nginx + php-fpm header fallback** in `createFromGlobals` for environments without `apache_request_headers()`.
 - **`Client::withTimeout()` / `withConnectTimeout()` / `withFollowRedirects()` / `withCurlOptions()`** for production-grade configuration.
+- **Opt-in HTTP client resilience layer** — `Client::withRetryPolicy()` / `setRetryPolicy()` / `getRetryPolicy()` enable automatic retry of transient failures (connection errors, timeouts, and the retryable status set `408/425/429/500/502/503/504`) with exponential backoff, bounded jitter, a max-attempts cap, and `Retry-After` support. New `InitPHP\HTTP\Client\Retry\` namespace: `RetryPolicy` (config value object), `Backoff` (exponential + equal-jitter calculator), `RetryAfter` (RFC 7231 header parser), `Sleeper`/`SleeperInterface` (injectable pacing). The single cURL attempt is exposed as a protected `Client::transport()` seam for testing/overriding. **Backward compatible: with no policy attached the client stays single-attempt** and still returns (never throws) 4xx/5xx per PSR-18.
 - **`Facadable` trait and `FacadableInterface`** — canonical names replacing the misspelled `Facadeble[Interface]` (old names kept as `@deprecated` aliases).
 - **`docs/` directory** with PSR-7/17/18 guides, emitter walk-throughs, recipes, status-code reference and an upgrade guide.
 - **Comprehensive `tests/Unit/` suite** complementing the upstream PSR integration tests.

README.md

@@ -146,6 +146,51 @@ $response = $client->post('https://api.example.com/users', '{"name":"Ada"}', [
 
 PSR-18 contract is honoured: **4xx/5xx responses are returned, not thrown**. Only transport failures raise `Psr\Http\Client\NetworkExceptionInterface`.
 
+#### Resilience: retry with exponential backoff + jitter
+
+The client is single-attempt by default. Attach a `RetryPolicy` to opt in to
+automatic retries of *transient* failures — connection errors, timeouts and the
+retryable HTTP status set (`408, 425, 429, 500, 502, 503, 504` by default) — with
+exponential backoff, bounded jitter, a hard max-attempts cap, and `Retry-After`
+support:
+
+```php
+use InitPHP\HTTP\Client\Client;
+use InitPHP\HTTP\Client\Retry\RetryPolicy;
+
+$client = (new Client())->withRetryPolicy(new RetryPolicy(
+    maxAttempts: 4,        // 1 initial try + up to 3 retries
+    baseDelay:   0.1,      // first backoff interval, seconds
+    multiplier:  2.0,      // 0.1s, 0.2s, 0.4s, ...
+    maxDelay:    30.0,     // cap on any single interval
+    jitter:      0.5,      // up to 50% random reduction (anti thundering-herd)
+));
+
+// Every verb helper inherits the policy transparently.
+$response = $client->get('https://api.example.com/flaky');
+```
+
+Behaviour and backward-compatibility:
+
+- **Default (no policy) = exactly one attempt** — identical to previous releases.
+- A non-retryable `4xx`/`5xx` response is still **returned, never thrown** (PSR-18).
+- A retryable response that exhausts the attempt cap is returned as-is (the last
+  response); a transport exception that exhausts the cap is re-thrown.
+- A parseable `Retry-After` header (delay-seconds or HTTP-date) on a retryable
+  response **overrides** the computed backoff unless you disable it.
+- The retryable status set, whether transport exceptions are retried, and
+  `Retry-After` handling are all configurable on `RetryPolicy`.
+
+```php
+// Customise: only retry 429/503, never on transport exceptions, ignore Retry-After.
+new RetryPolicy(
+    maxAttempts:          5,
+    retryOnException:     false,
+    retryableStatusCodes: [429, 503],
+    respectRetryAfter:    false,
+);
+```
+
 ### Emitting a response (SAPI)
 
 ```php

src/Client/Client.php

@@ -17,6 +17,8 @@
 use \InitPHP\HTTP\Message\{Request, Stream, Response};
 use \Psr\Http\Message\{RequestInterface, ResponseInterface, StreamInterface};
 use \InitPHP\HTTP\Client\Exceptions\{ClientException, NetworkException, RequestException};
+use \InitPHP\HTTP\Client\Retry\{Backoff, RetryAfter, RetryPolicy, Sleeper, SleeperInterface};
+use \Psr\Http\Client\NetworkExceptionInterface;
 
 use const CASE_LOWER;
 use const FILTER_VALIDATE_URL;
@@ -81,6 +83,27 @@ class Client implements \Psr\Http\Client\ClientInterface
      */
     protected int $maxRedirects = 10;
 
+    /**
+     * Opt-in retry policy. When null (the default), {@see Client::sendRequest()}
+     * makes exactly one transport attempt and returns/throws as before — fully
+     * backward-compatible. Attaching a policy turns on retry-with-backoff.
+     */
+    protected ?RetryPolicy $retryPolicy = null;
+
+    /**
+     * Pacing strategy used to wait between retry attempts. Injectable so the
+     * retry loop can be exercised without real wall-clock delays in tests.
+     */
+    protected SleeperInterface $sleeper;
+
+    /**
+     * Optional jitter randomness source (a callable returning a float in
+     * [0, 1)) forwarded to {@see Backoff}. null defers to Backoff's default.
+     *
+     * @var (callable(): float)|null
+     */
+    protected $jitterRandomizer = null;
+
     /**
      * Construct a client and assert ext-curl is loaded; the cURL extension
      * is the only transport this client speaks.
@@ -92,6 +115,7 @@ public function __construct()
         if (!extension_loaded('curl')) {
             throw new ClientException('The CURL extension must be installed.');
         }
+        $this->sleeper = new Sleeper();
     }
 
     /**
@@ -247,6 +271,91 @@ public function withFollowRedirects(bool $follow, int $max = 10): self
         return (clone $this)->setFollowRedirects($follow, $max);
     }
 
+    /**
+     * Attach (or clear) the retry-with-backoff policy in place. Passing null
+     * restores the default single-attempt behaviour.
+     *
+     * @param  RetryPolicy|null $policy
+     * @return $this
+     */
+    public function setRetryPolicy(?RetryPolicy $policy): self
+    {
+        $this->retryPolicy = $policy;
+
+        return $this;
+    }
+
+    /**
+     * Return a clone of the client with the retry policy replaced (or cleared).
+     *
+     * @param  RetryPolicy|null $policy
+     * @return $this
+     */
+    public function withRetryPolicy(?RetryPolicy $policy): self
+    {
+        return (clone $this)->setRetryPolicy($policy);
+    }
+
+    /**
+     * Return the active retry policy, or null when retries are disabled.
+     *
+     * @return RetryPolicy|null
+     */
+    public function getRetryPolicy(): ?RetryPolicy
+    {
+        return $this->retryPolicy;
+    }
+
+    /**
+     * Replace the inter-attempt pacing strategy (in place). Primarily a test
+     * seam: inject a no-op sleeper to exercise the retry loop instantly.
+     *
+     * @param  SleeperInterface $sleeper
+     * @return $this
+     */
+    public function setSleeper(SleeperInterface $sleeper): self
+    {
+        $this->sleeper = $sleeper;
+
+        return $this;
+    }
+
+    /**
+     * Return a clone of the client with the pacing strategy replaced.
+     *
+     * @param  SleeperInterface $sleeper
+     * @return $this
+     */
+    public function withSleeper(SleeperInterface $sleeper): self
+    {
+        return (clone $this)->setSleeper($sleeper);
+    }
+
+    /**
+     * Replace the jitter randomness source (in place) forwarded to the backoff
+     * calculator. Pass null to defer to the default mt_rand()-based source.
+     *
+     * @param  (callable(): float)|null $randomizer Returns a float in [0, 1).
+     * @return $this
+     */
+    public function setJitterRandomizer(?callable $randomizer): self
+    {
+        $this->jitterRandomizer = $randomizer;
+
+        return $this;
+    }
+
+    /**
+     * Return a clone of the client with the jitter randomness source replaced.
+     *
+     * @param  (callable(): float)|null $randomizer
+     * @return $this
+     */
+    public function withJitterRandomizer(?callable $randomizer): self
+    {
+        return (clone $this)->setJitterRandomizer($randomizer);
+    }
+
     /**
      * Dispatch a request specified as a $url + loose options array. Keys
      * are matched case-insensitively and may include `method`, `data`,
@@ -373,17 +482,98 @@ public function head(string $url, $body = null, array $headers = [], string $ver
 
     /**
      * Execute the supplied PSR-7 request and return the PSR-7 response.
+     *
+     * When no {@see RetryPolicy} is attached (the default), this performs a
+     * single transport attempt — behaviour identical to previous releases. When
+     * a policy is attached, transient failures (retryable status codes and, if
+     * enabled, transport exceptions) are retried up to the policy's
+     * max-attempts cap, spaced by exponential backoff with jitter. A
+     * `Retry-After` header on a retryable response overrides the computed delay
+     * when the policy opts in. PSR-18 semantics are preserved: a non-retryable
+     * 4xx/5xx response is returned, never thrown.
+     *
+     * @param  RequestInterface $request
+     * @return ResponseInterface
+     * @throws ClientException  When cURL cannot be initialised at all.
+     * @throws RequestException When the request itself cannot be marshalled (invalid URL, body coercion failure).
+     * @throws NetworkException When cURL reports a transport-level failure and either retries are disabled or the cap is reached.
+     */
+    public function sendRequest(RequestInterface $request): ResponseInterface
+    {
+        $policy = $this->retryPolicy;
+        if ($policy === null) {
+            return $this->transport($request);
+        }
+
+        $backoff = new Backoff($policy, $this->jitterRandomizer);
+        $attempt = 0;
+
+        while (true) {
+            $attempt++;
+            try {
+                $response = $this->transport($request);
+            } catch (NetworkExceptionInterface $e) {
+                // Transport-level failure (DNS, TCP, TLS, timeout). Retry only
+                // when the policy permits it and the attempt cap is not reached;
+                // otherwise rethrow so the caller sees the original exception.
+                if (!$policy->isRetryOnException() || !$policy->shouldRetry($attempt)) {
+                    throw $e;
+                }
+                $this->sleeper->sleep($backoff->delayFor($attempt));
+                continue;
+            }
+
+            // A successful transport call with a non-retryable status — or one
+            // that has exhausted the attempt budget — is the final answer.
+            if (!$policy->isRetryableStatus($response->getStatusCode())
+                || !$policy->shouldRetry($attempt)) {
+                return $response;
+            }
+
+            $this->sleeper->sleep($this->retryDelay($policy, $backoff, $response, $attempt));
+        }
+    }
+
+    /**
+     * Resolve the delay before the next retry for a retryable *response*:
+     * honour a parseable `Retry-After` header when the policy opts in,
+     * otherwise fall back to the jittered exponential backoff for this attempt.
+     *
+     * @param  RetryPolicy       $policy
+     * @param  Backoff           $backoff
+     * @param  ResponseInterface $response
+     * @param  int               $attempt 1-based attempt index just completed.
+     * @return float Delay in seconds.
+     */
+    private function retryDelay(RetryPolicy $policy, Backoff $backoff, ResponseInterface $response, int $attempt): float
+    {
+        if ($policy->isRespectRetryAfter()) {
+            $retryAfter = RetryAfter::fromResponse($response);
+            if ($retryAfter !== null) {
+                return $retryAfter;
+            }
+        }
+
+        return $backoff->delayFor($attempt);
+    }
+
+    /**
+     * Perform a single cURL transport attempt for $request and return the
+     * PSR-7 response. This is the retry-free primitive that
+     * {@see Client::sendRequest()} orchestrates; subclasses and tests can
+     * override it to simulate transport behaviour without touching the network.
+     *
      * The response body is wrapped in a php://temp-backed Stream so large
-     * payloads spill to disk (cURL's 2 MiB threshold) instead of pinning
-     * the full response into the process's resident memory.
+     * payloads spill to disk (cURL's 2 MiB threshold) instead of pinning the
+     * full response into the process's resident memory.
      *
      * @param  RequestInterface $request
      * @return ResponseInterface
      * @throws ClientException  When cURL cannot be initialised at all.
      * @throws RequestException When the request itself cannot be marshalled (invalid URL, body coercion failure).
      * @throws NetworkException When cURL reports a transport-level failure (DNS, TCP, TLS, timeout, ...).
      */
-    public function sendRequest(RequestInterface $request): ResponseInterface
+    protected function transport(RequestInterface $request): ResponseInterface
     {
         $response = [
             'body'      => '',