Merge pull request #146 from Sammyjo20/feature/v2-extending-failed-response-handler

Feature | V2 Retry Functionality

Author: Sammyjo20

composer.json

@@ -33,7 +33,8 @@
         "pestphp/pest": "^1.21",
         "phpstan/phpstan": "^1.9",
         "spatie/ray": "^1.33",
-        "symfony/dom-crawler": "^6.0"
+        "symfony/dom-crawler": "^6.0",
+        "symfony/stopwatch": "^6.2"
     },
     "suggest": {
         "illuminate/collections": "Required for the response collect() method.",

src/Contracts/CanThrowRequestExceptions.php

@@ -8,6 +8,14 @@
 
 interface CanThrowRequestExceptions
 {
+    /**
+     * Determine if the request has failed.
+     *
+     * @param \Saloon\Contracts\Response $response
+     * @return bool|null
+     */
+    public function hasRequestFailed(Response $response): ?bool;
+
     /**
      * Determine if we should throw an exception if the `$response->throw()` ({@see \Saloon\Contracts\Response::throw()})
      * is used, or when AlwaysThrowOnErrors is used.

src/Contracts/Connector.php

@@ -65,6 +65,19 @@ public function sender(): Sender;
      */
     public function send(Request $request, MockClient $mockClient = null): Response;
 
+    /**
+     * Send a synchronous request and retry if it fails
+     *
+     * @param \Saloon\Contracts\Request $request
+     * @param int $maxAttempts
+     * @param int $interval
+     * @param callable|null $handleRetry
+     * @param bool $throw
+     * @param \Saloon\Contracts\MockClient|null $mockClient
+     * @return mixed
+     */
+    public function sendAndRetry(Request $request, int $maxAttempts, int $interval = 0, callable $handleRetry = null, bool $throw = false, MockClient $mockClient = null): Response;
+
     /**
      * Send a request asynchronously
      *

src/Contracts/Response.php

@@ -112,12 +112,20 @@ public function xml(mixed ...$arguments): SimpleXMLElement|bool;
     public function collect(string|int|null $key = null): Collection;
 
     /**
-     * Cast the response to a DTO.
+     * Convert the response into a DTO
      *
      * @return mixed
      */
     public function dto(): mixed;
 
+    /**
+     * Convert the response into a DTO or throw a LogicException if the response failed
+     *
+     * @throws \LogicException
+     * @return mixed
+     */
+    public function dtoOrFail(): mixed;
+
     /**
      * Determine if the request was successful.
      *

src/Traits/Connector/SendsRequests.php

@@ -9,6 +9,8 @@
 use Saloon\Http\PendingRequest;
 use Saloon\Contracts\MockClient;
 use GuzzleHttp\Promise\PromiseInterface;
+use Saloon\Exceptions\Request\RequestException;
+use Saloon\Exceptions\Request\FatalRequestException;
 use Saloon\Contracts\PendingRequest as PendingRequestContract;
 
 trait SendsRequests
@@ -30,6 +32,70 @@ public function send(Request $request, MockClient $mockClient = null): Response
         return $this->createPendingRequest($request, $mockClient)->send();
     }
 
+    /**
+     * Send a synchronous request and retry if it fails
+     *
+     * @param \Saloon\Contracts\Request $request
+     * @param int $maxAttempts
+     * @param int $interval
+     * @param callable|null $handleRetry
+     * @param bool $throw
+     * @param \Saloon\Contracts\MockClient|null $mockClient
+     * @return \Saloon\Contracts\Response
+     * @throws \ReflectionException
+     * @throws \Saloon\Exceptions\InvalidResponseClassException
+     * @throws \Saloon\Exceptions\PendingRequestException
+     * @throws \Saloon\Exceptions\Request\FatalRequestException
+     * @throws \Saloon\Exceptions\Request\RequestException
+     */
+    public function sendAndRetry(Request $request, int $maxAttempts, int $interval = 0, callable $handleRetry = null, bool $throw = true, MockClient $mockClient = null): Response
+    {
+        $currentAttempt = 0;
+        $pendingRequest = $this->createPendingRequest($request, $mockClient);
+
+        do {
+            $currentAttempt++;
+
+            // When the current attempt is greater than one, we will pause to wait
+            // for the interval.
+
+            if ($currentAttempt > 1) {
+                usleep($interval * 1000);
+            }
+
+            try {
+                // We'll attempt to send the PendingRequest. We'll also use the throw
+                // method which will throw an exception if the request has failed.
+
+                return $pendingRequest->send()->throw();
+            } catch (FatalRequestException|RequestException $exception) {
+                // We won't create another pending request if our current attempt is
+                // the max attempts we can make
+
+                if ($currentAttempt === $maxAttempts) {
+                    return $exception instanceof RequestException && $throw === false ? $exception->getResponse() : throw $exception;
+                }
+
+                $pendingRequest = $this->createPendingRequest($request, $mockClient);
+
+                // When either the FatalRequestException happens or the RequestException
+                // happens, we should catch it and check if we should retry. If someone
+                // has provided a callable into $handleRetry, we'll wait for the result
+                // of the callable to retry.
+
+                if (is_null($handleRetry) || $handleRetry($exception, $pendingRequest) === true) {
+                    continue;
+                }
+
+                // If we should not retry, we need to return the last response. If the
+                // exception was a RequestException, we should return the response,
+                // otherwise we'll throw the exception.
+
+                return $exception instanceof RequestException && $throw === false ? $exception->getResponse() : throw $exception;
+            }
+        } while ($currentAttempt < $maxAttempts);
+    }
+
     /**
      * Send a request asynchronously
      *

src/Traits/HandlesExceptions.php

@@ -9,6 +9,17 @@
 
 trait HandlesExceptions
 {
+    /**
+     * Determine if the request has failed.
+     *
+     * @param \Saloon\Contracts\Response $response
+     * @return bool|null
+     */
+    public function hasRequestFailed(Response $response): ?bool
+    {
+        return null;
+    }
+
     /**
      * Determine if the request has failed
      *

src/Traits/Responses/HasResponseHelpers.php

@@ -131,10 +131,6 @@ public function collect(string|int|null $key = null): Collection
      */
     public function dto(): mixed
     {
-        if ($this->failed()) {
-            return null;
-        }
-
         $dataObject = $this->pendingRequest->createDtoFromResponse($this);
 
         if ($dataObject instanceof WithResponse) {
@@ -144,6 +140,21 @@ public function dto(): mixed
         return $dataObject;
     }
 
+    /**
+     * Convert the response into a DTO or throw a LogicException if the response failed
+     *
+     * @throws \LogicException
+     * @return mixed
+     */
+    public function dtoOrFail(): mixed
+    {
+        if ($this->failed()) {
+            throw new \LogicException('Unable to create data transfer object as the response has failed.', 0, $this->toException());
+        }
+
+        return $this->dto();
+    }
+
     /**
      * Parse the HTML or XML body into a Symfony DomCrawler instance.
      *
@@ -194,6 +205,14 @@ public function redirect(): bool
      */
     public function failed(): bool
     {
+        $pendingRequest = $this->getPendingRequest();
+
+        $hasRequestFailed = $pendingRequest->getRequest()->hasRequestFailed($this) || $pendingRequest->getConnector()->hasRequestFailed($this);
+
+        if ($hasRequestFailed === true) {
+            return true;
+        }
+
         return $this->serverError() || $this->clientError();
     }
 

tests/Feature/RequestExceptionTest.php

@@ -15,9 +15,11 @@
 use Saloon\Tests\Fixtures\Requests\BadResponseRequest;
 use Saloon\Tests\Fixtures\Connectors\BadResponseConnector;
 use Saloon\Tests\Fixtures\Exceptions\CustomRequestException;
+use Saloon\Tests\Fixtures\Requests\CustomFailHandlerRequest;
 use Saloon\Tests\Fixtures\Connectors\CustomExceptionConnector;
 use Saloon\Tests\Fixtures\Requests\CustomExceptionUserRequest;
 use Saloon\Tests\Fixtures\Exceptions\ConnectorRequestException;
+use Saloon\Tests\Fixtures\Connectors\CustomFailHandlerConnector;
 use Saloon\Exceptions\Request\Statuses\InternalServerErrorException;
 use Saloon\Exceptions\Request\ServerException as SaloonServerException;
 
@@ -212,3 +214,33 @@
     expect($exceptionC->getMessage())->toEqual('OK (200) Response: ' . $exceptionC->getResponse()->body());
     expect($exceptionC->getPrevious())->toBeNull();
 });
+
+test('you can customise if saloon determines if a request has failed on a connector', function () {
+    $mockClient = new MockClient([
+        MockResponse::make(['message' => 'Success']),
+        MockResponse::make(['message' => 'Error: Invalid Cowboy Hat']),
+    ]);
+
+    $responseA = CustomFailHandlerConnector::make()->send(new UserRequest, $mockClient);
+
+    expect($responseA->failed())->toBeFalse();
+
+    $responseB = CustomFailHandlerConnector::make()->send(new UserRequest, $mockClient);
+
+    expect($responseB->failed())->toBeTrue();
+});
+
+test('you can customise if saloon determines if a request has failed on a request', function () {
+    $mockClient = new MockClient([
+        MockResponse::make(['message' => 'Success']),
+        MockResponse::make(['message' => 'Yee-naw: Horse Not Found']),
+    ]);
+
+    $responseA = TestConnector::make()->send(new CustomFailHandlerRequest, $mockClient);
+
+    expect($responseA->failed())->toBeFalse();
+
+    $responseB = TestConnector::make()->send(new CustomFailHandlerRequest, $mockClient);
+
+    expect($responseB->failed())->toBeTrue();
+});