Пакет · cast

Жизненный цикл запроса

Путь одного вызова send() шаг за шагом. Знать это не обязательно, но это объясняет, почему middleware выполняются один раз, откуда берётся User-Agent и что именно повторяется.

text
send()
├─ 1. подготовка      адрес, заголовки клиента, привязка к клиенту
├─ 2. middleware      по порядку добавления, один раз
├─ 3. обмен           ┌─ настройки = клиент ⟵ запрос
│                     ├─ попытки (повторы, дедлайн)
│                     └─ редиректы → снова попытки
├─ 4. транспорт       cURL: хендл из пула, опции, приём тела
└─ 5. ответ           info(), лог, throwOnError

1. Подготовка

  • Любой PSR-7 запрос превращается в CastRequest (CastRequest::from()), поэтому дальше доступны все его методы.
  • Относительный адрес дописывается к базовому (правило склейки). Нет базового адреса — RequestException.
  • Заголовки клиента добавляются туда, где в запросе нет заголовка с тем же именем.
  • Запрос привязывается к клиенту.

2. Middleware

Цепочка строится так, что первым выполняется первый добавленный. Последнее звено цепочки — «обмен» (шаг 3). Middleware видят запрос уже с заголовками клиента и могут его поправить.

3. Обмен

Настройки. Сливаются настройки клиента и запроса: запрос сильнее. Делается это здесь, а не на шаге 1, поэтому middleware может изменить и настройки запроса — например, поставить withTimeout().

Проверка адреса. Схема только http или https.

Попытки. Для каждой попытки:

  1. если задан дедлайн — проверить, сколько осталось, и ограничить этим total попытки;
  2. начиная со второй — перемотать тело и вернуть цель sinkTo() к начальной позиции;
  3. отправить через транспорт;
  4. при сетевой ошибке — повторить, если это разрешено политикой, ошибка временная, и пауза помещается в дедлайн; иначе — исключение;
  5. при ответе со статусом из withStatuses() — повторить на тех же условиях; если попытки кончились — вернуть ответ.

Повтор возможен, только если тело и цель sinkTo() можно вернуть к началу.

Редиректы. Если ответ — 301, 302, 303, 307 или 308 с Location и редиректы включены, строится новый запрос (правила), и для него снова выполняются попытки. Счётчик попыток общий для всех переходов.

4. Транспорт

CurlTransport выполняет одну попытку:

  1. берёт хендл из пула;
  2. выставляет опции в порядке приоритета: значения по умолчанию → withCurlOptions() → таймауты → служебные опции, которые не перекрываются;
  3. ставит метод так, как ждёт cURL: HEAD — без ожидания тела;
  4. собирает заголовки: Content-Length ставит cURL по телу, Expect: 100-continue отключён, User-Agent получает суффикс WinterCast/… curl/…;
  5. тело: до 1 МиБ — из памяти, больше или неизвестного размера — потоком, multipart с файлами — полями cURL, которые читают файлы сами;
  6. выполняет передачу — в Fiber через общий curl_multi, иначе curl_exec;
  7. возвращает хендл в пул, а после ошибки выбрасывает его.

Заголовки ответа. Каждая строка статуса (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() — никогда.