Files
mtusi2026lab6/openspec/specs/graceful-shutdown/spec.md
T
2026-11-11 21:04:40 +03:00

24 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 доводится до конца или до отката. Новые страницы списка и новые действия не начинаются. Ожидание из-за предела скорости сверки (capability storage-consistency, «Скорость сверки») сигнал прерывает сразу: остановка не ждёт конца паузы. Сверку, прерванную сигналом, доводит следующий проход, как прерванную отказом.

Затем сервис уборщика 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, а в журнале — итог сверки с причиной прерывания «остановка» и запись об остановке уборщика

Scenario: docker stop во время паузы предела скорости

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

Requirement: Остановка worker

По SIGTERM worker (capability attachment-processing) SHALL перестать принимать новые сообщения и дать начатым заданиям завершиться, но не дольше [worker] graceful_shutdown_seconds. Задание, которое не успело, SHALL оставаться неподтверждённым: брокер доставит его снова (attachment-processing, «Доставка at least once»), а его процесс обработки SHALL быть убит. Затем worker SHALL выйти с кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL, в том числе если декодирование ещё идёт.

Значение graceful_shutdown_seconds MUST быть не больше 8: вместе с закрытием клиентов остановка в худшем случае укладывается в 9,5 с. Сигнал во время старта процесса SHALL завершать его с кодом 0 без traceback, как у API (требование «Остановка во время старта»). Остановка SHALL быть видна в журнале записью об остановке worker.

Ограничение называется в REPORT.md. Задание, прерванное остановкой, считается начатой попыткой: следующую она получит, когда истечёт срок её аренды.

Scenario: docker stop простаивающего worker

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

Scenario: docker stop во время обработки

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

Scenario: docker stop во время декодирования

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

Scenario: docker stop во время старта worker

  • WHEN контейнер worker остановлен в первые доли секунды после старта, пока процесс ещё импортирует приложение
  • THEN docker stop завершается не дольше чем за 1 с, код выхода контейнера 0, а в журнале есть запись об остановке worker до старта

Requirement: Остановка relay

По SIGTERM relay (capability job-outbox) SHALL довести текущий проход до фиксации или отката и выйти с кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL. Новые проходы не начинаются, а паузу между проходами сигнал прерывает сразу. Незаписанное время подтверждения ничего не теряет: следующий запуск опубликует задание снова. Сигнал во время старта процесса SHALL завершать его с кодом 0 без traceback. Остановка SHALL быть видна в журнале.

Scenario: docker stop relay

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

Scenario: docker stop во время старта relay

  • WHEN контейнер relay остановлен в первые доли секунды после старта
  • THEN docker stop завершается не дольше чем за 1 с, код выхода контейнера 0, а в журнале есть запись об остановке relay до старта

Requirement: Остановка при недоступном Collector

С включённой телеметрией (capability observability) реплика API, worker и relay SHALL останавливаться по SIGTERM в прежние сроки: API — требования «Завершение за заявленный срок» и «Остановка видна в журнале», worker — «Остановка worker», relay — «Остановка relay», в том числе когда Collector остановлен или заморожен. Отправка накопленной телеметрии при остановке SHALL ограничиваться своим сроком внутри этого бюджета; что не ушло за срок, теряется, а процесс MUST NOT ждать Collector дольше. Запись об остановке процесса SHALL быть в stdout при любом состоянии Collector.

Срок отправки при остановке SHALL входить в тот же бюджет, а не прибавляться к нему: у API с включённой телеметрией [app] graceful_shutdown_seconds вместе со сроком закрытия SDK MUST NOT превышать 9 с (требование «Завершение за заявленный срок»), иначе запуск SHALL останавливаться ошибкой проверки настроек с именем поля app.graceful_shutdown_seconds; без телеметрии допустимы прежние 9 с. У worker и relay закрытие SDK SHALL идти внутри окна закрытия клиентов, и худший случай остаётся прежним (требования «Остановка worker» и «Остановка relay»).

Scenario: docker stop при остановленном Collector

  • WHEN Collector остановлен, реплика API только что обслуживала запросы, relay только что опубликовал задание, и выполняется docker stop этой реплики, а затем docker compose stop worker и docker compose stop relay
  • THEN все три команды завершаются быстрее 10 с, коды выхода контейнеров 0, а в stdout есть «Stopped API», «Stopped worker» и «Stopped relay»

Scenario: docker stop при замороженном Collector

  • WHEN контейнер Collector заморожен (docker pause), и выполняются те же остановки
  • THEN все три команды завершаются быстрее 10 с, коды выхода 0, а в stdout есть записи об остановке

Scenario: Срок остановки API не оставляет места закрытию SDK

  • WHEN API запускается с включённой телеметрией и APP__GRACEFUL_SHUTDOWN_SECONDS=9
  • THEN запуск останавливается ошибкой проверки настроек, которая называет поле app.graceful_shutdown_seconds и допустимый предел, а с выключенной телеметрией то же значение принимается