Таймауты и повторы
Таймауты задают, сколько ждать одну попытку и всю операцию. Повторы задают, что делать, когда попытка не удалась. По умолчанию повторов нет: повтор — осознанное решение.
Четыре таймаута
| Таймаут | Ограничивает | По умолчанию |
|---|---|---|
connect |
установку соединения (DNS, TCP, TLS) | 5 с |
total |
одну попытку от начала до конца | 30 с |
idle |
зависшую передачу: медленнее N байт/с дольше заданного времени | выключен |
deadline |
всю операцию: все попытки и паузы между ними | выключен |
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 и оставляет защиту от зависания:
$client->get('backups/latest')
->withTimeouts(Timeouts::forDownload(idle: 60, minBytesPerSecond: 1024))
->sinkTo('/var/backups/latest.tar.gz')
->send();Передача прерывается, только если 60 секунд подряд приходит меньше 1 КиБ/с.
Повторы
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 может, например, создать заказ дважды, поэтому его нужно разрешить явно:
RetryPolicy::exponential()->withNonIdempotent(); // + POST, PATCH
RetryPolicy::exponential()->withMethods(Method::GET); // только GETСетевые ошибки. Только временные: не удалось подключиться, истёк таймаут, обрыв при отправке или приёме, пустой ответ, ошибка HTTP/2. Неизвестный хост и ошибка проверки сертификата не повторяются: от повтора они не исправятся.
Статусы. Ни один, пока не перечислен:
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 секунд.