API gateway: deadline budget запроса

Определите один общий deadline для пользовательского намерения

Общий deadline начинается в вашем приложении в момент, когда сервер принял намерение, и заканчивается до того, как интерфейс обязан показать честный статус. Это не равно только socket timeout внешнего вызова. В budget входят проверка прав, чтение локальных данных, очередь, попытка запроса, обработка ответа и небольшой резерв на сохранение результата. Если у каждого слоя отдельные 30 секунд, цепочка может ждать минуты и всё равно закончиться непонятно.

Значение deadline выбирается из пользовательского сценария, а не из неподтверждённого предположения о модели. Черновик ответа и необратимое действие имеют разные границы и разные способы сообщить задержку. Зафиксируйте выбранное число в конфигурации приложения, добавьте владельца решения и пересматривайте его после наблюдаемых данных. Не публикуйте его как обещание доступности RussiaAPI, OpenAI или другого поставщика.

Распределите время между понятными шагами

Полезно оставить часть budget на локальную проверку и финальное сохранение, а внешний вызов ограничить остатком. Тогда backend не отправит новую попытку в момент, когда пользователь уже получил timeout, а база ещё не записала предыдущее состояние. Перед каждым шагом вычисляйте остаток времени. Когда его мало, не начинайте работу, которую не сможете корректно завершить и отразить в локальном журнале.

Внутри очереди храните не только время создания, но и deadline или допустимый срок задачи. Worker перед стартом проверяет, не истёк ли budget, и возвращает понятный статус вместо бесполезного вызова. Это application-side правило: оно не отменяет задачу у внешней стороны и не утверждает, что удалённый процесс остановился. Для неизвестного состояния нужен отдельный путь сверки, а не предположение о результате.

Повторяйте только до безопасной границы

Retry допустим лишь когда операция доказуемо безопасна и после него остаётся budget на проверку результата. Для чистого чтения можно применить ограниченную задержку с jitter; для создания задачи, отправки сообщения или изменения данных сначала проверяйте локальный operation ID и идемпотентность. Не запускайте новую попытку после deadline только ради того, чтобы скрыть ошибку интерфейса: она может завершиться позже и создать конфликт со следующим действием пользователя.

Не переносите общие советы по retry на каждый endpoint. Коды ответа, допустимые параметры и поведение конкретного маршрута сверяются с актуальным контрактом и staging-тестом. В логах фиксируйте попытку, остаток budget, локальную категорию ошибки и request ID без prompt, ключей, Authorization или полного тела. Такая запись помогает понять, где исчерпано время, не превращая наблюдаемость в канал утечки данных.

Разделите отмену ожидания и отмену работы

Кнопка «перестать ждать» может завершить ожидание в интерфейсе, но не доказывает отмену уже отправленной операции. Сервер должен сохранить локальное состояние, показать пользователю способ проверить итог и не выдавать ложное «отменено». Если текущий контракт конкретного маршрута документирует отмену, всё равно проверьте её ограничения, статус и поведение на staging; не предполагайте аналогичную функцию для остальных моделей.

Для действий с заметным риском предусмотрите ручную эскалацию: оператор смотрит локальный operation ID, состояние и безопасные метаданные, затем решает, нужна ли повторная попытка. Такая ветка немного медленнее, зато не подменяет неизвестный исход выдуманным успехом или отказом. Пользователь должен видеть, что именно известно сейчас и когда можно проверить состояние снова, без обещания точного времени завершения.

Проверьте budget в тестах и при изменениях

Синтетический тест должен моделировать медленную локальную проверку, внешний timeout, поздний ответ, двойной retry и истёкший deadline в очереди. Убедитесь, что процесс не начинает новый side effect при нулевом остатке, сохраняет честный статус и не раскрывает входные данные в ошибке. Такой тест запускается без сети и без ключей: он проверяет только правила вашего приложения.

После обновления SDK, middleware, маршрута, модели или очереди повторите staging-проверку с обезличенным запросом. Сравните версии, дату и наблюдаемый класс результата, но не делайте из одного прогона вывод о постоянной производительности. При регрессии выключите новый путь feature flag, вернитесь к проверенной конфигурации и уточните контракт до следующего rollout.

Пример безопасной server-side проверки

Пример ниже иллюстрирует только логику приложения. Он не делает сетевой вызов, не содержит реальных ключей и не доказывает поддержку конкретного endpoint. Проверьте актуальный договор и API-контракт перед подключением рабочего маршрута.

export function canStartAttempt({ startedAt, deadlineMs, now = Date.now(), minRemainingMs = 250 }) {
  const remainingMs = startedAt + deadlineMs - now;
  if (remainingMs < minRemainingMs) return { allowed: false, remainingMs };
  return { allowed: true, timeoutMs: remainingMs, remainingMs };
}

// Call this before a local attempt. It performs no network request and cannot cancel remote work.

Граница ответственности и данных

Это инженерный шаблон для клиентского приложения, а не гарантия возможностей внешнего API. Не помещайте в браузер, тикет, статью или обычный журнал API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt или персональные данные. Условия обработки данных, права на контент и применимые требования проверяются по политике организации, договору и с ответственным специалистом.

Контроль перед выпуском

Перед release проверьте синтетический сценарий, запреты на секреты и персональные данные в логах, роли и tenant boundary, понятное сообщение для пользователя и ручную ветку для неизвестного результата. Сохраните дату, версию адаптера и результат теста. При обновлении SDK, модели, schema или маршрута повторите проверку; не переносите выводы старого теста на новый контракт.

Для выбора маршрута откройте RussiaAPI и сверяйте действующие условия в каталоге. Используйте только ключ своего аккаунта на сервере. RussiaAPI не является официальным представителем упомянутых поставщиков; доступность моделей, функций, цены, лимиты и правила обработки данных требуют отдельного подтверждения.

Полезные материалы

Google SRE Book: Addressing Cascading Failures · AWS Builders Library: Timeouts, retries, and backoff with jitter

FAQ

Чем общий deadline отличается от timeout одного запроса?

Общий deadline ограничивает всё пользовательское намерение: проверку, очередь, попытку запроса и сохранение состояния. Timeout внешнего вызова — лишь один участок. Без общего budget независимые таймеры разных слоёв могут растянуть ожидание и породить опасный retry.

Можно ли повторять запрос после истечения deadline?

Обычно нет. Сначала нужно проверить локальную операцию и показать честный статус. Новый retry после границы может завершиться позже интерфейса и создать дубликат или конфликт. Для безопасного чтения правила всё равно следует подтвердить тестом.

Отменяет ли закрытие окна удалённую задачу?

Нет, закрытие интерфейса отменяет лишь локальное ожидание. Оно не доказывает отмену уже отправленной работы. Храните operation ID, показывайте способ проверки результата и проверяйте возможности отмены только по текущему контракту маршрута.

Следующий шаг

Продолжите с материалами: Circuit breaker для AI API · 429: retry и backoff · Idempotency key для повтора. Затем проверьте текущие условия и безопасно протестируйте интеграцию на staging перед production-трафиком.