Files
mtusi2026lab4/openspec/specs/graceful-shutdown/spec.md
T

15 KiB
Raw Blame History

graceful-shutdown Specification

Purpose

Как сервис останавливается по SIGTERM: перестаёт принимать новые запросы, дорабатывает текущие и завершается за заявленный срок, до того как Docker применит SIGKILL.

Requirements

Requirement: Новые запросы после SIGTERM не принимаются

После получения SIGTERM сервис SHALL прекращать принимать новые соединения и MUST NOT начинать обработку новых запросов на уже открытых простаивающих соединениях.

Scenario: Нагрузка во время остановки

  • WHEN во время непрерывной отправки сообщений контейнеру отправлен SIGTERM
  • THEN запросы, начатые после сигнала, завершаются ошибкой соединения, а не ответом сервиса

Requirement: Текущие запросы дорабатывают

Запросы, начатые до SIGTERM, SHALL получать ответ, если укладываются в срок [app] graceful_shutdown_seconds. Запросы, которые не уложились, SHALL отменяться, чтобы процесс всё равно завершился.

Scenario: Запрос в полёте

  • WHEN SIGTERM приходит, пока сервис обрабатывает запрос
  • THEN клиент получает ответ на этот запрос, после чего процесс завершается

Requirement: Завершение за заявленный срок

Процесс SHALL завершаться после SIGTERM не дольше чем за [app] graceful_shutdown_seconds плюс время shutdown в lifespan. Это значение MUST быть не больше 9 с: Docker применяет SIGKILL через 10 с. Код выхода MUST NOT быть 137 (SIGKILL).

Scenario: docker stop

  • WHEN выполняется docker stop для работающего контейнера
  • THEN команда завершается быстрее 10 с, а код выхода контейнера не равен 137

Requirement: Остановка видна в журнале

Этапы остановки SHALL записываться в журнал сервиса JSON-записями с временем: начало остановки, завершение lifespan, завершение процесса. По меткам времени SHALL определяться длительность остановки.

Scenario: Журнал остановки

  • WHEN контейнер остановлен по SIGTERM
  • THEN в журнале по порядку есть «Shutting down», «Stopped API» и «Finished server process», и разница их timestamp меньше 10 с

Requirement: Остановка реплики за балансировщиком

Реплика API за балансировщиком (LB) после SIGTERM SHALL сразу перестать принимать соединения и дорабатывать начатые запросы (требования выше). Новое соединение с ней LB SHALL получать как отказ соединения и передавать такой запрос другой реплике. Поэтому штатная остановка одной реплики из двух (docker stop) под постоянной нагрузкой через LB MUST NOT давать клиенту ошибок от недоступности реплики. На время обнаружения отказа допустим рост задержки.

Единственное исключение — запрос, который LB отправил в простаивающее keep-alive соединение в тот момент, когда реплика закрывает его при остановке. Ответа на него нет, LB отвечает 502 и не повторяет его. Такие ошибки SHALL учитываться. Доля успешных ответов в каждой секунде фазы MUST NOT опускаться ниже 99 %.

Scenario: docker stop под нагрузкой

  • WHEN через LB с постоянной интенсивностью идут запись с ключом и чтение истории, и одна из двух реплик остановлена docker stop
  • THEN доля успешных ответов в каждой секунде фазы не ниже 99 %, время восстановления 0 с, а неуспешные ответы, если есть, — одиночные 502 в момент SIGTERM; так для остановки каждой из реплик по очереди

Scenario: Клиент с новым соединением на запрос

  • WHEN клиент открывает новое соединение на каждый запрос, как публичная проверка make test-failover, и реплика остановлена docker stop
  • THEN клиент не получает ни одной ошибки: его запрос не идёт в простаивающее соединение с репликой

Requirement: Простаивающие соединения закрывает балансировщик

Реплика SHALL держать простаивающее keep-alive соединение дольше, чем LB держит простаивающее соединение с ней. Тогда простаивающее соединение LB → реплика закрывает LB, и он не отправляет запрос в соединение, которое реплика в этот момент закрывает. Срок простоя на стороне реплики SHALL задаваться настройкой [app] keep_alive_seconds. LB MUST NOT держать простаивающие соединения с репликой дольше своего срока простоя клиентского соединения.

Scenario: Клиенты молчат после всплеска

  • WHEN через LB прошёл всплеск запросов от клиентов с keep-alive, а затем клиенты остаются подключены и молчат
  • THEN соединения на порт API внутри каждой реплики закрываются раньше keep_alive_seconds с момента последнего запроса, по сроку простоя LB

Requirement: Плановая остановка реплики без ошибок

При плановой остановке реплики за балансировщиком (поочерёдная замена, load-balancing) реплика SHALL сначала выводиться из LB. Только когда у неё не осталось запросов в полёте, она получает SIGTERM. Поэтому плановая остановка под постоянной нагрузкой MUST NOT давать клиенту ни одной ошибки, включая 502 гонки keep-alive из требования «Остановка реплики за балансировщиком».

Поведение процесса по SIGTERM не меняется: требования выше действуют. Не меняется и остановка без дренажа (scripts/stop-one.sh, docker stop): она имитирует отказ, и исключение для 502 гонки keep-alive к ней по-прежнему применяется.

Scenario: Остановка после дренажа под нагрузкой

  • WHEN через LB с постоянной интенсивностью идут запись с ключом и чтение истории, и реплика остановлена после вывода из LB
  • THEN ни одного неуспешного ответа, в том числе 502, а журнал LB не показывает ошибок соединения с этой репликой

Scenario: Остановка за заявленный срок после дренажа

  • WHEN реплика выведена из LB и получила SIGTERM
  • THEN процесс завершается быстрее 10 с с кодом выхода не 137, а в её журнале есть «Shutting down», «Stopped API» и «Finished server process»

Requirement: Остановка во время старта

SIGTERM и SIGINT, пришедшие процессу сервиса во время старта, SHALL его останавливать, а не теряться. Это действует и в контейнере, где сервер — процесс с PID 1, и в консоли. Действует с первых строк точки входа, ещё до импорта приложения.

  • Пока сервер не установил свои обработчики сигналов и не начал принимать соединения, запросов у процесса нет. Процесс SHALL завершаться сразу, без ожидания, с кодом выхода 0. Перед выходом он SHALL записывать в журнал одну JSON-запись уровня info с event «Stopped API before startup» и именем сигнала в поле signal. Запись SHALL содержать timestamp, level и instance_id, как все записи журнала (service-logging).
  • Сигнал, пришедший после того, как сервер установил свои обработчики, но до конца старта, SHALL вести к штатной остановке сразу после старта. В журнале SHALL быть «Shutting down», «Stopped API» и «Finished server process», код выхода — 0.
  • docker stop стартующего контейнера SHALL завершаться не дольше чем за 1 с, а не по сроку Docker с SIGKILL.

Запуск интерпретатора до первых строк точки входа — первые десятки миллисекунд жизни процесса — это требование не покрывает. Остановка уже работающего процесса не меняется: требования выше действуют.

Scenario: docker stop во время импорта приложения

  • WHEN контейнер API остановлен docker stop в первые 0,5 с после старта, пока процесс ещё импортирует приложение (на стенде лабы запись «Started server process» появляется через ~0,7 с после старта)
  • THEN docker stop завершается не дольше чем за 1 с, код выхода контейнера 0, в журнале есть запись «Stopped API before startup» с signal SIGTERM, а записей сервера о старте нет

Scenario: Сигнал во время старта сервера

  • WHEN SIGTERM приходит после записи «Started server process» и до записи «Uvicorn running on»
  • THEN в журнале после старта идут «Shutting down», «Stopped API» и «Finished server process», docker stop завершается не дольше чем за 1 с, а код выхода 0

Scenario: Ctrl+C в консоли во время старта

  • WHEN сервер, запущенный в консоли (make run_dev или python -m src), получает SIGINT, пока импортирует приложение
  • THEN процесс завершается сразу с кодом 0 и той же записью «Stopped API before startup» с signal SIGINT, без traceback

Scenario: Работающий процесс останавливается как раньше

  • WHEN docker stop выполняется для контейнера, сервер которого уже записал «Uvicorn running on»
  • THEN в журнале «Shutting down», «Stopped API» и «Finished server process», записи «Stopped API before startup» нет, код выхода 0, а запросы в полёте получают ответ

Requirement: Остановка уборщика

По SIGTERM уборщик незавершённых загрузок (capability storage-consistency) SHALL довести текущий шаг уборки загрузки до конца или до отката и больше новых шагов не начинать. Загрузка, остановленная между шагами, остаётся в состоянии, из которого её доводит следующий проход.

Так же — во время сверки bucket и БД. Текущий вызов S3 или шаг с PostgreSQL доводится до конца или до отката. Новые страницы списка и новые действия не начинаются. Сверку, прерванную сигналом, доводит следующий проход, как прерванную отказом.

Затем сервис уборщика SHALL выйти с кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL. Разовый проход сверки, прерванный сигналом, SHALL выходить с кодом 1: проход не завершён. Сигнал во время старта процесса SHALL завершать его с кодом 0 без traceback, как у API (требование «Остановка во время старта»). Остановка SHALL быть видна в журнале записью об остановке уборщика.

Scenario: docker stop уборщика

  • WHEN выполняется docker compose stop cleaner для работающего уборщика
  • THEN команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале есть запись об остановке

Scenario: docker stop во время сверки

  • WHEN docker compose stop cleaner выполняется, пока идёт проход сверки, а вызов S3 в нём ждёт ответа
  • THEN команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале — итог сверки с причиной прерывания «остановка» и запись об остановке уборщика