Пакет · cast

Таймауты и повторы

Таймауты задают, сколько ждать одну попытку и всю операцию. Повторы задают, что делать, когда попытка не удалась. По умолчанию повторов нет: повтор — осознанное решение.

Четыре таймаута

Таймаут Ограничивает По умолчанию
connect установку соединения (DNS, TCP, TLS) 5 с
total одну попытку от начала до конца 30 с
idle зависшую передачу: медленнее N байт/с дольше заданного времени выключен
deadline всю операцию: все попытки и паузы между ними выключен
php
use Flytachi\Winter\Cast\Client\Timeouts;

$client->withTimeout(10);                 // total 10 с, connect остаётся 5 с
$client->withTimeout(10, connect: 2);

$client->withTimeouts(
  Timeouts::of(total: 10, connect: 2)
      ->withIdle(15, minBytesPerSecond: 100)
      ->withDeadline(25),
);

withTimeout() на запросе меняет только total (и connect, если передан): idle и deadline клиента сохраняются. withTimeouts() на запросе заменяет все таймауты клиента.

Зачем дедлайн

total действует на одну попытку. С тремя попытками по 30 с и паузами между ними запрос может длиться полторы минуты. Если вызывающему коду нужен ответ за 25 секунд — например, он сам отвечает пользователю, — задайте withDeadline(25):

  • последняя попытка получает столько времени, сколько осталось до дедлайна;
  • пауза, которая не помещается в оставшееся время, не делается;
  • по истечении — TimeoutException, у которого isDeadline() возвращает true.

Большие файлы

Для скачивания ограничение на всю попытку мешает: медленный, но живой канал не успеет. Timeouts::forDownload() снимает total и оставляет защиту от зависания:

php
$client->get('backups/latest')
  ->withTimeouts(Timeouts::forDownload(idle: 60, minBytesPerSecond: 1024))
  ->sinkTo('/var/backups/latest.tar.gz')
  ->send();

Передача прерывается, только если 60 секунд подряд приходит меньше 1 КиБ/с.

Повторы

php
use Flytachi\Winter\Cast\Client\RetryPolicy;

$client->withRetry(RetryPolicy::exponential());                 // 3 попытки: 500 мс, 1 с
$client->withRetry(RetryPolicy::exponential(attempts: 5, delayMs: 200));
$client->withRetry(RetryPolicy::fixed(4, 1000));                // каждые 1 с
$client->get('x')->withoutRetry()->send();                      // не повторять этот запрос

attempts — число попыток всего, включая первую.

Что повторяется

Методы. Только идемпотентные: GET, HEAD, PUT, DELETE, OPTIONS, TRACE. Повтор POST может, например, создать заказ дважды, поэтому его нужно разрешить явно:

php
RetryPolicy::exponential()->withNonIdempotent();          // + POST, PATCH
RetryPolicy::exponential()->withMethods(Method::GET);     // только GET

Сетевые ошибки. Только временные: не удалось подключиться, истёк таймаут, обрыв при отправке или приёме, пустой ответ, ошибка HTTP/2. Неизвестный хост и ошибка проверки сертификата не повторяются: от повтора они не исправятся.

Статусы. Ни один, пока не перечислен:

php
RetryPolicy::exponential()->withStatuses(429, 502, 503, 504);

Если попытки кончились, а статус всё ещё в списке, возвращается последний ответ, без исключения.

Паузы

  • exponential(): задержка удваивается с каждой попыткой, ±30 % случайного разброса — чтобы много клиентов не повторяли синхронно;
  • fixed(): одинаковая задержка;
  • Retry-After из ответа (секунды или дата) имеет приоритет над расчётной паузой;
  • любая пауза не больше withMaxDelay() — по умолчанию 30 с; respectRetryAfter(false) отключает учёт заголовка.

Пауза не блокирует остальное: в корутине Swoole уступает очередь другим корутинам, внутри sendAll() не задерживает остальные запросы.

Что происходит при повторе

  • Middleware не повторяются. Повторы идут внутри цепочки, ближе к сети, поэтому авторизация не запрашивает токен на каждую попытку.
  • Тело перематывается к началу. Тело-поток, который перемотать нельзя, не повторяется: первая же ошибка уходит к вам.
  • Файл sinkTo() начинается заново. Путь открывается с обрезкой, ресурс и поток возвращаются в позицию, с которой начиналась запись.
  • Счёт. $response->info()->attempts — число попыток. Каждый повтор — строка warning в логгере клиента.

Пример для внешнего API

RetryPolicy::exponential(3)->withStatuses(429, 502, 503, 504) вместе с Timeouts::of(10)->withDeadline(25): временные сбои не доходят до кода, а запрос никогда не длится дольше 25 секунд.