feat(retries): never repeat non-idempotent or verdict requests

Saloon retries whenever an exception is thrown (handleRetry defaults to true)
and both connectors set tries = 3, so POST /payoffs, PATCH /payoffs/{id}/accept
and SBP QrcReversalRequest were sent to the bank up to three times while the
caller believed it had made a single request. For payouts a repeated POST is a
duplicate-payment risk, not a harmless retry.

HasSafeRetries replaces the HasTries default at the connector level (Saloon
retries only when the per-send callable, the request and the connector all
allow it):
- a deterministic bank verdict (4xx/5xx) is never retried;
- an explicit deny-list covers money operations;
- an explicit allow-list keeps retries for read-only SBP operations, since that
  API uses POST even for reads (GetQrcReversalDataRequest stays denied: the bank
  matches the following reversal against it, EBD 44 / I14044);
- by default only GET/HEAD/OPTIONS are retried.

Every decision is logged through the connector's PSR-3 logger as
'[alfa-sdk][retry]', so physical request count per operation is countable via
X-Request-ID.

Tests: tests/Feature/RetryPolicyTest.php (23 tests), including an assertion on
the real retry loop that a failing non-idempotent POST is sent exactly once,
while a read-only GET still uses all configured attempts.
This commit is contained in:
2026-09-29 10:41:22 +03:00
parent 012a4e780d
commit 29645b7a5f
5 changed files with 647 additions and 4 deletions

View File

@@ -13,7 +13,12 @@ use Apoloz\AlfaBank\Http\Middleware\LoggingResponseMiddleware;
use Apoloz\AlfaBank\Http\Middleware\RequestIdMiddleware;
use Apoloz\AlfaBank\Http\Middleware\VerifyJwsResponseMiddleware;
use Apoloz\AlfaBank\Http\Pagination\AlfaOffsetPaginator;
use Apoloz\AlfaBank\Requests\NominalAccounts\Payouts\CreatePayoffRequest;
use Apoloz\AlfaBank\Requests\NominalAccounts\Payouts\CreateTaxRefundRequest;
use Apoloz\AlfaBank\Requests\NominalAccounts\Payouts\PayoffAcceptRequest;
use Apoloz\AlfaBank\Requests\NominalAccounts\Payouts\TaxRefundAcceptRequest;
use Apoloz\AlfaBank\Traits\HasAlfaErrorHandling;
use Apoloz\AlfaBank\Traits\HasSafeRetries;
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Saloon\Helpers\OAuth2\OAuthConfig;
@@ -26,7 +31,6 @@ use Saloon\PaginationPlugin\OffsetPaginator;
use Saloon\Traits\OAuth2\AuthorizationCodeGrant;
use Saloon\Traits\Plugins\AlwaysThrowOnErrors;
use Saloon\Traits\Plugins\HasTimeout;
use Saloon\Traits\RequestProperties\HasTries;
class AlfaBankConnector extends Connector implements HasPagination
{
@@ -34,7 +38,9 @@ class AlfaBankConnector extends Connector implements HasPagination
use AuthorizationCodeGrant;
use HasAlfaErrorHandling;
use HasTimeout;
use HasTries;
// Replaces the HasTries default handleRetry (always retry) with a safe policy:
// transport failures are retried for read-only requests only, bank verdicts never.
use HasSafeRetries;
public function __construct(
protected AlfaConfig $alfaConfig,
@@ -45,6 +51,15 @@ class AlfaBankConnector extends Connector implements HasPagination
$this->tries = 3;
$this->retryInterval = 500;
$this->logger = $this->logger ?? new NullLogger;
// Money operations: repeating them is a duplicate-payment risk, so they are
// denied explicitly in addition to the read-only-method rule.
$this->denyRetriesFor([
CreatePayoffRequest::class,
PayoffAcceptRequest::class,
CreateTaxRefundRequest::class,
TaxRefundAcceptRequest::class,
]);
}
public function resolveBaseUrl(): string