Fix retry/circuit breaker plugins to detect HTTP 4xx/5xx failures via Promise outcome, not synchronous throw

Author: Surfoo

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.1] - 2026-07-13
+### Fixed
+    - Retry and circuit breaker plugins now detect failures correctly: they previously assumed the HTTP client throws synchronously on error, but a spec-compliant PSR-18 client returns 4xx/5xx responses without throwing, and `ErrorPlugin` (when used) only surfaces failures as a rejected Promise. Both `RetryHandler` and `CircuitBreaker` now inspect the actual resolved outcome (status code or exception) of each attempt, so `configureRetry()`/`configureFixedRetry()`/`enableReliability()` retry on 429/5xx responses as documented.
+
+## [4.1.0] - 2026-07-03
+### Added
+    - HTTP 429 rate-limit handling: retry strategies now honor the `x-rate-limit-reset` response header (capped by `max_delay_ms`) instead of relying solely on generic backoff.
+    - `RateLimitExceededException`, thrown once retries are exhausted on a 429, exposing `getRetryAfterSeconds()` and `getResponse()`.
+
 ## [4.0.0] - 2026-06-28
 ### Added
     - Full HTTP observability tools: structured logging with token masking, per-status log levels, and custom logger support.

src/Exception/RateLimitExceededException.php

@@ -26,8 +26,6 @@ public function __construct(
 
     /**
      * Returns the response.
-     *
-     * @return ResponseInterface
      */
     public function getResponse(): ResponseInterface
     {

src/GeocachingSdk.php

@@ -986,7 +986,7 @@ private function createStatusHttpClient(): HttpMethodsClientInterface
         $rawHttpClient   = \Http\Discovery\Psr18ClientDiscovery::find();
         $reflection      = new \ReflectionClass($this->clientBuilder);
         $pluginsProperty = $reflection->getProperty('plugins');
-        $allPlugins = $pluginsProperty->getValue($this->clientBuilder);
+        $allPlugins      = $pluginsProperty->getValue($this->clientBuilder);
 
         $statusPlugins = [];
         foreach ($allPlugins as $plugin) {
@@ -999,7 +999,7 @@ private function createStatusHttpClient(): HttpMethodsClientInterface
         $pluginClient = (new \Http\Client\Common\PluginClientFactory())->createClient($rawHttpClient, $statusPlugins);
 
         $requestFactory = $reflection->getProperty('requestFactory');
-        $streamFactory = $reflection->getProperty('streamFactory');
+        $streamFactory  = $reflection->getProperty('streamFactory');
 
         return new \Http\Client\Common\HttpMethodsClient(
             $pluginClient,

src/Options.php

@@ -8,9 +8,9 @@
 use Geocaching\Enum\Environment;
 use Geocaching\Plugin\CircuitBreakerPlugin;
 use Geocaching\Plugin\GeocachingHttpLoggerPlugin;
-use Geocaching\Plugin\StorageAwareAuthenticationPlugin;
 use Geocaching\Plugin\ReliabilityPlugin;
 use Geocaching\Plugin\RetryPlugin;
+use Geocaching\Plugin\StorageAwareAuthenticationPlugin;
 use Geocaching\Reliability\CircuitBreaker;
 use Geocaching\Reliability\ExponentialBackoffStrategy;
 use Geocaching\Reliability\FixedDelayStrategy;
@@ -19,8 +19,8 @@
 use Http\Client\Common\Plugin\BaseUriPlugin;
 use Http\Discovery\Psr17FactoryDiscovery;
 use Http\Message\Authentication\Bearer;
-use League\OAuth2\Client\Provider\Geocaching;
 use League\OAuth2\Client\Plugin\TokenRefreshPlugin;
+use League\OAuth2\Client\Provider\Geocaching;
 use League\OAuth2\Client\Token\TokenStorageInterface;
 use Monolog\Formatter\LineFormatter;
 use Monolog\Handler\StreamHandler;

src/Plugin/CircuitBreakerPlugin.php

@@ -42,6 +42,6 @@ public function handleRequest(RequestInterface $request, callable $next, callabl
         }
 
         // Execute request with circuit breaker protection
-        return $this->circuitBreaker->call(fn() => $next($request));
+        return $this->circuitBreaker->call(fn () => $next($request));
     }
 }

src/Plugin/ReliabilityPlugin.php

@@ -4,12 +4,14 @@
 
 namespace Geocaching\Plugin;
 
+use Geocaching\Exception\CircuitBreakerOpenException;
 use Geocaching\Reliability\CircuitBreaker;
 use Geocaching\Reliability\RetryHandler;
 use Geocaching\Reliability\RetryStrategy;
 use Http\Client\Common\Plugin;
 use Http\Promise\Promise;
 use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
@@ -34,10 +36,25 @@ public function __construct(
 
     public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
     {
-        // First layer: Circuit Breaker protection
-        return $this->circuitBreaker->call(fn() =>
-            // Second layer: Retry logic
-            $this->retryHandler->execute(fn() => $next($request)));
+        if (!$this->circuitBreaker->canExecute()) {
+            throw new CircuitBreakerOpenException(
+                "Circuit breaker is open. Next retry at: " .
+                $this->circuitBreaker->getNextRetryTime()?->format('Y-m-d H:i:s')
+            );
+        }
+
+        return $this->retryHandler->executeRequest($request, $next)->then(
+            function (ResponseInterface $response) {
+                $this->circuitBreaker->recordSuccess();
+
+                return $response;
+            },
+            function (\Throwable $exception) {
+                $this->circuitBreaker->recordFailure();
+
+                throw $exception;
+            }
+        );
     }
 
     /**

src/Plugin/RetryPlugin.php

@@ -28,7 +28,7 @@ public function __construct(
 
     public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
     {
-        return $this->retryHandler->execute(fn() => $next($request));
+        return $this->retryHandler->executeRequest($request, $next);
     }
 
     /**

src/Reliability/CircuitBreaker.php

@@ -64,6 +64,22 @@ public function canExecute(): bool
         return !$this->isOpen();
     }
 
+    /**
+     * Record a successful call, e.g. after resolving a Promise as fulfilled.
+     */
+    public function recordSuccess(): void
+    {
+        $this->onSuccess();
+    }
+
+    /**
+     * Record a failed call, e.g. after resolving a Promise as rejected.
+     */
+    public function recordFailure(): void
+    {
+        $this->onFailure();
+    }
+
     /**
      * Get current circuit breaker state
      */

src/Reliability/ExponentialBackoffStrategy.php

@@ -6,7 +6,6 @@
 
 use Http\Client\Exception\HttpException;
 use Http\Client\Exception\NetworkException;
-use Psr\Http\Message\ResponseInterface;
 
 /**
  * Exponential backoff retry strategy
@@ -91,4 +90,9 @@ public function getMaxAttempts(): int
     {
         return $this->maxAttempts;
     }
+
+    public function isRetryableStatusCode(int $statusCode): bool
+    {
+        return in_array($statusCode, $this->retryableStatusCodes, true);
+    }
 }

src/Reliability/FixedDelayStrategy.php

@@ -6,7 +6,6 @@
 
 use Http\Client\Exception\HttpException;
 use Http\Client\Exception\NetworkException;
-use Psr\Http\Message\ResponseInterface;
 
 /**
  * Fixed delay retry strategy
@@ -80,4 +79,9 @@ public function getMaxAttempts(): int
     {
         return $this->maxAttempts;
     }
+
+    public function isRetryableStatusCode(int $statusCode): bool
+    {
+        return in_array($statusCode, $this->retryableStatusCodes, true);
+    }
 }