Timeouts and retries
Timeouts set how long to wait for one attempt and for the whole operation. Retries set what to do when an attempt fails. There are no retries by default: a retry is a deliberate decision.
Four timeouts
| Timeout | Limits | Default |
|---|---|---|
connect |
establishing the connection (DNS, TCP, TLS) | 5 s |
total |
one attempt, start to finish | 30 s |
idle |
a stalled transfer: slower than N bytes/s for longer than set | off |
deadline |
the whole operation: all attempts and the pauses between them | off |
use Flytachi\Winter\Cast\Client\Timeouts;
$client->withTimeout(10); // total 10 s, connect stays 5 s
$client->withTimeout(10, connect: 2);
$client->withTimeouts(
Timeouts::of(total: 10, connect: 2)
->withIdle(15, minBytesPerSecond: 100)
->withDeadline(25),
);withTimeout() on a request changes only total (and connect, if given): the client’s
idle and deadline stay. withTimeouts() on a request replaces all of the client’s
timeouts.
Why a deadline
total applies to one attempt. With three attempts of 30 s each and pauses in between, a
request can take a minute and a half. If the calling code needs an answer within 25 seconds —
because it answers a user itself, say — set withDeadline(25):
- the last attempt gets as much time as is left before the deadline;
- a pause that does not fit into the remaining time is not taken;
- when it runs out you get a
TimeoutExceptionwhoseisDeadline()returnstrue.
Large files
For downloads, a limit on the whole attempt gets in the way: a slow but live connection will
not make it. Timeouts::forDownload() drops total and keeps the stall protection:
$client->get('backups/latest')
->withTimeouts(Timeouts::forDownload(idle: 60, minBytesPerSecond: 1024))
->sinkTo('/var/backups/latest.tar.gz')
->send();The transfer is aborted only if less than 1 KiB/s arrives for 60 seconds in a row.
Retries
use Flytachi\Winter\Cast\Client\RetryPolicy;
$client->withRetry(RetryPolicy::exponential()); // 3 attempts: 500 ms, 1 s
$client->withRetry(RetryPolicy::exponential(attempts: 5, delayMs: 200));
$client->withRetry(RetryPolicy::fixed(4, 1000)); // every 1 s
$client->get('x')->withoutRetry()->send(); // don't retry this requestattempts is the total number of attempts, the first one included.
What is retried
Methods. Only idempotent ones: GET, HEAD, PUT, DELETE, OPTIONS, TRACE.
Retrying a POST can, for example, create an order twice, so it has to be allowed explicitly:
RetryPolicy::exponential()->withNonIdempotent(); // + POST, PATCH
RetryPolicy::exponential()->withMethods(Method::GET); // GET onlyNetwork errors. Only transient ones: could not connect, timed out, a connection dropped while sending or receiving, an empty reply, an HTTP/2 error. An unknown host and a failed certificate check are not retried: retrying will not fix them.
Statuses. None, until listed:
RetryPolicy::exponential()->withStatuses(429, 502, 503, 504);If the attempts run out while the status is still in the list, the last response is returned, without an exception.
Pauses
exponential(): the delay doubles with every attempt, with ±30 % of random spread so that many clients do not retry in lockstep;fixed(): the same delay every time;Retry-Afterfrom the response (seconds or a date) takes priority over the computed pause;- no pause is longer than
withMaxDelay()— 30 s by default;respectRetryAfter(false)turns the header off.
A pause never blocks anything else: in a Swoole coroutine it yields to other coroutines, and
inside sendAll() it does not hold up the other requests.
What happens on a retry
- Middleware does not run again. Retries happen inside the chain, closer to the network, so authentication does not fetch a token on every attempt.
- The body is rewound to the start. A stream body that cannot be rewound is not retried: the first error goes straight to you.
- The
sinkTo()file starts over. A path is reopened and truncated; a resource or stream is moved back to the position where writing began. - Counting.
$response->info()->attemptsis the number of attempts. Every retry is awarningline in the client’s logger.
An example for an external API
RetryPolicy::exponential(3)->withStatuses(429, 502, 503, 504) together with
Timeouts::of(10)->withDeadline(25): transient failures never reach your code, and a request
never lasts longer than 25 seconds.