Как ограничить время запроса curl

Коротко: используйте опции –max-time (или -m) для общей отсечки запроса и –connect-timeout для ограничения времени установки соединения. Для защиты от медленных передач добавьте –speed-time и –speed-limit. В статье — примеры команд, сценарии применения, критерии приёмки и контрольный список для разных ролей.

Зачем ограничивать время запросов

Интернет-позвонки могут застревать: медленный DNS, проблемный TLS, временные сетевые перебои или удалённый сервер, который тупит. Ограничение времени обеспечивает предсказуемость, экономит ресурсы и упрощает обработку ошибок. Коротко:

• Уменьшает блокировки потоков и скриптов.
• Позволяет корректно реагировать на медленные сервисы (ретраи, запасной путь).
• Подходит для cron-скриптов и CI, где время выполнения критично.

Метод 1: Использование опции –max-time

Опция –max-time (алиас -m) ставит жёсткий предел на общее время выполнения запроса в секундах. Если время превышено, curl завершит работу с кодом ошибки 28 (timeout).

# Общий формат
curl --max-time [seconds] [URL]

# Пример с сохранением ответа
curl -o test.md --max-time 30 https://github.com/test/file1

Примечание: можно указывать дробные секунды: 0.3 = 300 мс, 5.46 = 5,46 с.

Метод 2: Использование опции –connect-timeout

Опция –connect-timeout ограничивает время, которое curl тратит на установку соединения: DNS-запрос, TCP/TLS/QUIC рукопожатия и т.д. Если соединение не установлено в указанный срок, curl завершит работу с кодом ошибки 28.

# Общий формат
curl --connect-timeout [seconds] [URL]

# Пример
curl -o test.md --connect-timeout 20 https://github.com/test/file

Совмещённый подход: точный контроль всех этапов

Часто удобно комбинировать опции, чтобы контролировать разные этапы запроса:

curl -o result.txt --connect-timeout 10 --max-time 30 --speed-limit 1024 --speed-time 30 https://example.com/largefile

Пояснения:

• –connect-timeout 10 — максимум 10 секунд на установку соединения.
• –max-time 30 — максимум 30 секунд на весь запрос.
• –speed-limit 1024 и –speed-time 30 — если скорость передачи упадёт ниже 1024 байт/с на протяжении 30 секунд, запрос будет прерван.

Когда эти методы могут не сработать

• На уровне сетей с нестабильными TCP-переподключениями: если промежуточный прокси скрывает реальные задержки, поведение может отличаться.
• При использовании некоторых прокси/балансировщиков, которые отвечают на соединение быстро, но задерживают передачу данных — тогда важно контролировать скорость (–speed-*).
• В редких случаях баги в библиотеке или специфичные версии curl влияют на поведение флагов; проверяйте версию curl (curl –version).

Альтернативы и дополняющие подходы

• systemd/socket-таймауты или обёртки timeout (например, GNU timeout) для внешнего контроля процесса.
• Использовать HTTP-клиенты в языке (libcurl, axios, requests) с собственными таймаутами на connect/read.
• Для долгих загрузок — использовать трансфер с возобновлением (задавать диапазоны или –continue-at).

Шпаргалка: команды и типичные сценарии

• Простой таймаут 15 с для получения страницы: curl –max-time 15 https://example.com

• Ускоренная проверка доступности хоста (только соединение): curl –connect-timeout 5 -I https://example.com

• Защита от медленной передачи: curl –max-time 120 –speed-limit 1024 –speed-time 60 https://example.com/bigfile

Критерии приёмки

• Команда завершается в установленный срок или возвращает код 28 при таймауте.
• При плохом соединении соединение прерывается в пределах –connect-timeout.
• Для медленных загрузок запрос прерывается, если скорость ниже порога заданное время (–speed-time / –speed-limit).

Роли и чек-листы

DevOps:

• Проверить шаблоны для cron и контейнеров.
• Убедиться, что внешний timeout не конфликтует с системными ограничениями.

Разработчик бэкенда:

• Локально тестировать с разными значениями –connect-timeout и –max-time.
• Логировать коды завершения для анализа (код 28 — таймаут).

QA:

• Тестовые сценарии с искусственно замедленным сервером.
• Проверять поведение при комбинациях опций (connect + max + speed).

Мини-методология для внедрения в проект

1. Определите SLA для внешних вызовов (напр., 2–5 с для API, 30–120 с для загрузок).
2. Настройте шаблон команды/клиента с рекомендуемыми флагами.
3. Автоматически логируйте и оповещайте при ошибках 28.
4. Периодически ревью значений таймаутов по реальным метрикам.

Краткий глоссарий (1 строка)

DNS — перевод доменного имени в IP; TCP — протокол передачи; TLS — шифрование соединения; QUIC — быстрый транспорт на основе UDP.

Дерево решений (когда какую опцию использовать)

flowchart TD
  A[Нужен общий предел времени?] -->|Да| B[Использовать --max-time]
  A -->|Нет| C[Нужен контроль только на соединение?]
  C -->|Да| D[Использовать --connect-timeout]
  C -->|Нет| E[Нужен контроль скорости передачи?]
  E -->|Да| F[Использовать --speed-limit и --speed-time]
  E -->|Нет| G[Комбинация опций по ситуации]

Заключение

Ограничение времени запросов curl — простая и эффективная практика для повышения надёжности автоматизированных задач и сервисов. Используйте –connect-timeout для контроля этапа установки соединения, –max-time для контроля всей операции и –speed-* для защиты от медленных передач. Комбинация этих флагов даёт вам надёжный, предсказуемый и управляемый сетевой поведение.