Корректное завершение backend-процессов¶
Требования этого документа применяются к долгоживущим backend-процессам:
API, worker-, consumer-процессам и data pipelines. Уровни обязательности
определены в корневом README.md.
BE-SHUT-001. Единая процедура завершения¶
Уровень: MUST
Применяется к: штатному сигналу остановки процесса
Получение штатного сигнала остановки среды выполнения должно запускать одну процедуру завершения. Повторный или конкурентный сигнал не должен повторно закрывать ресурс, запускать конкурентное завершение той же операции или увеличивать срок ожидания.
Процесс не должен начинать штатное завершение по ошибке одной бизнес-операции.
Обоснование¶
Единая идемпотентная процедура предотвращает гонки, повреждение ресурсов и непредсказуемое завершение при повторной доставке сигнала.
Проверка¶
- integration-тест одного, повторного и конкурентных сигналов остановки;
- проверка единственного запуска каждого этапа завершения;
- тест изоляции ошибки бизнес-операции от жизненного цикла процесса.
Исключения¶
Нештатный сигнал принудительного завершения может остановить процесс без выполнения процедуры, если среда выполнения не позволяет его обработать.
BE-SHUT-002. Прекращение допуска новой работы¶
Уровень: MUST
Применяется к: началу штатного завершения
При начале завершения экземпляр должен перевести /healthz/ready в неуспешное
состояние согласно BE-HLTH-005 и прекратить допуск новой работы.
API должен прекратить принимать новые соединения и запросы после прекращения
маршрутизации на экземпляр. Worker и consumer должны прекратить резервировать
новые job и сообщения. Работа, уже допущенная к выполнению, должна перейти к
дренированию по BE-SHUT-003.
Параметры развёртывания должны предоставлять балансировщику или брокеру время наблюдать неготовность экземпляра до принудительного закрытия канала приёма.
Обоснование¶
Удаление экземпляра из маршрутизации до дренирования ограничивает гонку между новой работой и закрытием её зависимостей.
Проверка¶
- integration-тест изменения readiness и прекращения допуска новой работы;
- тест запроса, соединения и сообщения, поступивших во время завершения;
- review согласованности таймингов приложения, probe и среды оркестрации.
Исключения¶
Для процесса без входящей работы применима только смена readiness.
BE-SHUT-003. Дренирование выполняемой работы¶
Уровень: MUST
Применяется к: операциям, начатым до прекращения допуска новой работы
Процесс должен предоставить выполняемым запросам, job и обработчикам сообщений возможность завершиться в пределах общего срока завершения. Начатая операция не должна считаться успешно завершённой до фиксации всех обязательных результатов и побочных эффектов.
Если операция не завершилась в срок, процесс должен отменить её через поддерживаемый механизм отмены. Незавершённое сообщение не должно подтверждаться; оно должно оставаться доступным для повторной доставки. Повторное выполнение должно соблюдать проектный контракт идемпотентности.
Обоснование¶
Дренирование уменьшает число оборванных операций, а отказ от ложного подтверждения предотвращает незаметную потерю работы.
Проверка¶
- integration-тест долгого запроса, job и обработки сообщения;
- тест истечения срока, отмены и повторной доставки сообщения;
- проверка отсутствия успешного ответа или подтверждения до фиксации результата.
Исключения¶
Операция, для которой проектный контракт явно требует немедленной отмены, может не дренироваться; поведение восстановления должно быть определено этим контрактом.
BE-SHUT-004. Ограниченный срок завершения¶
Уровень: MUST
Применяется к: всей процедуре штатного завершения
Проект должен задавать конечный общий срок завершения в управляемой конфигурации. Этот срок должен быть меньше срока до принудительного завершения процесса средой исполнения и оставлять ненулевой резерв для закрытия ресурсов и сброса телеметрии.
Каждое ожидание внутри процедуры должно быть ограничено общим оставшимся сроком. Истечение срока не должно запускать неограниченные повторы или продлевать общий срок.
Обоснование¶
Согласованный временной бюджет позволяет приложению закончить процедуру до принудительной остановки и делает длительность развёртывания предсказуемой.
Проверка¶
- автоматическая проверка конфигурации приложения и среды исполнения;
- тест зависшей операции и недоступной зависимости;
- измерение фактического времени до выхода процесса.
Исключения¶
Конкретное значение срока определяется проектом по максимальному допустимому времени операции и фиксируется в конфигурации поставки.
BE-SHUT-005. Порядок закрытия ресурсов¶
Уровень: MUST
Применяется к: сетевым серверам, исполнителям и внешним ресурсам процесса
Процесс должен закрывать ресурсы в порядке, сохраняющем зависимости выполняемой работы:
- прекратить допуск новой работы;
- дождаться или отменить выполняемую работу;
- закрыть все внешние ресурсы, которыми владеет процесс;
- сбросить ограниченные буферы телеметрии;
- завершить процесс.
Ресурс не должен закрываться, пока незавершённая операция может штатно использовать его, кроме случая истечения общего срока.
Обоснование¶
Преждевременное закрытие общей зависимости превращает управляемое дренирование в каскад искусственных ошибок.
Проверка¶
- integration-тест порядка событий жизненного цикла;
- тест использования базы данных, broker и внешнего клиента текущей операцией;
- review единой точки владения каждым закрываемым ресурсом.
Исключения¶
Ресурс, необходимый только для допуска новой работы, может закрываться на первом этапе.
BE-SHUT-006. Завершение телеметрии¶
Уровень: MUST
Применяется к: логгеру, OpenTelemetry SDK и Sentry SDK процесса
Процесс должен предоставить каждому буферизованному каналу телеметрии конечную часть общего срока для сброса данных. Недоступность Vector, OpenTelemetry Collector, OpenObserve или GlitchTip не должна задерживать выход за пределами общего срока.
Сбой сброса не должен запускать рекурсивную телеметрию или изменять результат уже завершённой бизнес-операции.
Обоснование¶
Ограниченный сброс сохраняет диагностические данные о завершении, не превращая наблюдаемость в блокирующую зависимость.
Проверка¶
- тест завершения с заполненными буферами;
- тест недоступного и медленного получателя каждого канала;
- проверка соблюдения общего срока завершения.
Исключения¶
Не допускаются.
BE-SHUT-007. Результат и наблюдаемость завершения¶
Уровень: MUST
Применяется к: результату штатной процедуры завершения
Успешное штатное завершение должно приводить к коду выхода 0. Неустранимая
ошибка процедуры или истечение общего срока должны приводить к ненулевому коду
выхода, если процесс ещё может управлять своим выходом.
Процесс должен записать по одному структурированному событию
shutdown.started и shutdown.completed. Завершающее событие должно содержать
результат success, timeout или failure и фактическую длительность.
События должны соблюдать требования документа logging.md и не содержать
идентификаторы отдельных запросов при отсутствии соответствующего контекста.
Обоснование¶
Код выхода и ограниченные события жизненного цикла отличают управляемое развёртывание от crash и позволяют расследовать превышение срока.
Проверка¶
- integration-тест успешного, ошибочного и просроченного завершения;
- проверка кода выхода и единственности событий;
- проверка схемы и длительности завершающего события.
Исключения¶
При принудительном завершении среда выполнения может определить код выхода и не позволить записать завершающее событие.