Package · cast

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
php
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 TimeoutException whose isDeadline() returns true.

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:

php
$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

php
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 request

attempts 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:

php
RetryPolicy::exponential()->withNonIdempotent();          // + POST, PATCH
RetryPolicy::exponential()->withMethods(Method::GET);     // GET only

Network 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:

php
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-After from 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()->attempts is the number of attempts. Every retry is a warning line 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.