Жизненный цикл запроса
Путь одного вызова send() шаг за шагом. Знать это не обязательно, но это объясняет, почему
middleware выполняются один раз, откуда берётся User-Agent и что именно повторяется.
send()
├─ 1. подготовка адрес, заголовки клиента, привязка к клиенту
├─ 2. middleware по порядку добавления, один раз
├─ 3. обмен ┌─ настройки = клиент ⟵ запрос
│ ├─ попытки (повторы, дедлайн)
│ └─ редиректы → снова попытки
├─ 4. транспорт cURL: хендл из пула, опции, приём тела
└─ 5. ответ info(), лог, throwOnError1. Подготовка
- Любой PSR-7 запрос превращается в
CastRequest(CastRequest::from()), поэтому дальше доступны все его методы. - Относительный адрес дописывается к базовому
(правило склейки). Нет базового адреса —
RequestException. - Заголовки клиента добавляются туда, где в запросе нет заголовка с тем же именем.
- Запрос привязывается к клиенту.
2. Middleware
Цепочка строится так, что первым выполняется первый добавленный. Последнее звено цепочки — «обмен» (шаг 3). Middleware видят запрос уже с заголовками клиента и могут его поправить.
3. Обмен
Настройки. Сливаются настройки клиента и запроса: запрос сильнее. Делается это здесь, а
не на шаге 1, поэтому middleware может изменить и настройки запроса — например, поставить
withTimeout().
Проверка адреса. Схема только http или https.
Попытки. Для каждой попытки:
- если задан дедлайн — проверить, сколько осталось, и ограничить этим
totalпопытки; - начиная со второй — перемотать тело и вернуть цель
sinkTo()к начальной позиции; - отправить через транспорт;
- при сетевой ошибке — повторить, если это разрешено политикой, ошибка временная, и пауза помещается в дедлайн; иначе — исключение;
- при ответе со статусом из
withStatuses()— повторить на тех же условиях; если попытки кончились — вернуть ответ.
Повтор возможен, только если тело и цель sinkTo() можно вернуть к началу.
Редиректы. Если ответ — 301, 302, 303, 307 или 308 с Location и редиректы
включены, строится новый запрос
(правила), и для него снова
выполняются попытки. Счётчик попыток общий для всех переходов.
4. Транспорт
CurlTransport выполняет одну попытку:
- берёт хендл из пула;
- выставляет опции в порядке приоритета: значения по умолчанию →
withCurlOptions()→ таймауты → служебные опции, которые не перекрываются; - ставит метод так, как ждёт cURL:
HEAD— без ожидания тела; - собирает заголовки:
Content-Lengthставит cURL по телу,Expect: 100-continueотключён, User-Agent получает суффиксWinterCast/… curl/…; - тело: до 1 МиБ — из памяти, больше или неизвестного размера — потоком, multipart с файлами — полями cURL, которые читают файлы сами;
- выполняет передачу — в Fiber через общий
curl_multi, иначеcurl_exec; - возвращает хендл в пул, а после ошибки выбрасывает его.
Заголовки ответа. Каждая строка статуса (100 Continue, ответ прокси на CONNECT)
начинает ответ заново, поэтому в результате только заголовки итогового ответа.
Тело ответа. Когда заголовки итогового ответа получены, решается, куда пойдёт тело:
- 2xx и задан
sinkTo()— в цель; файл по пути открывается на первых байтах; - иначе — в память (
CastStream::temp(): до 2 МиБ в памяти, дальше во временном файле), с проверкойmaxResponseSizeпоContent-Lengthи по мере приёма.
Ошибки. Код ошибки cURL превращается в TimeoutException (28), TooLargeException
(превышен предел) или NetworkException. Недописанный файл sinkTo() удаляется.
5. Ответ
info()получает число попыток, переходов и итоговый адрес;- логгер клиента пишет строку
debug; повторы ушли строкамиwarning, отказ —error; send()сwithThrowOnError()превращает 4xx/5xx вHttpException,sendRequest()— никогда.