Archive the failover operations change

Grade 4 of lab 3 is closed. A replica on SIGTERM first answers 503 on
readiness for a two second window, longer than the 1.5 s worst
detection, and only then closes its listener and finishes accepted
requests within five seconds; the balancer lets a replica back only
after two passed checks. A test pins the timeout chain to compose,
HAProxy and the stop hook. make detection measured 0.71 s for SIGTERM
(before the process exited at 2.49 s), 0.67 s for a killed process,
2.76 s for a hung one and 1.23 s until no replica was left with
PostgreSQL down. make failover-each stopped and restored each replica
under k6 at 100 rps with no errors and no balancer retries, make
lb-check ran 20 same-key races of 8, make limits checks limits and
isolation against a policy, and make rolling-update replaced the
level 3 image with the current one under load with capacity kept at
two and no errors, migrate running once. The new
lab3-failover-operations spec is synced, and the lab 1 operability
and lab 2 dependency failure specs carry their deltas.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Artyom
2026-10-28 20:08:15 +03:00
co-authored by Claude Opus 5.5
parent a9aab2727f
commit 61c0c28a43
10 changed files with 101 additions and 3 deletions
@@ -1,2 +1,4 @@
schema: spec-driven schema: spec-driven
created: 2026-10-28 created: 2026-10-28
archived: 2026-10-28
lab: 3
@@ -79,7 +79,7 @@
### Requirement: Корректное завершение по сигналу ### Requirement: Корректное завершение по сигналу
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд; срок мягкой остановки сервера SHALL быть меньше `stop_grace_period` контейнера, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую. По получении `SIGTERM` сервис SHALL сначала выйти из ротации: на время окна `DRAIN_SECONDS` (по умолчанию 2 с, больше максимального времени обнаружения балансировщиком) `/health/ready` SHALL отвечать `503 unavailable`, а принятые и новые запросы SHALL обслуживаться как обычно. После окна сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс; весь срок, включая окно, SHALL укладываться в `SHUTDOWN_TIMEOUT_SECONDS` (по умолчанию 5 с), который меньше таймаута хука остановки, `stop_grace_period` контейнера и 10 секунд, чтобы контейнер не убивался по таймауту. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
#### Scenario: Остановка укладывается в срок #### Scenario: Остановка укладывается в срок
@@ -87,6 +87,11 @@
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period` - **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту - **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
#### Scenario: Сначала вывод из ротации
- **WHEN** процессу сервера послан `SIGTERM`
- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS`
#### Scenario: Принятый запрос дорабатывается #### Scenario: Принятый запрос дорабатывается
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса - **WHEN** `SIGTERM` приходит во время обработки принятого запроса
@@ -5,18 +5,24 @@
## Requirements ## Requirements
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку ### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
При недоступном PostgreSQL защищённые endpoint и `/health/ready` SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` SHALL отвечать `200`. При недоступном PostgreSQL защищённые endpoint и `/health/ready` каждой реплики SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` реплики SHALL отвечать `200`. Балансировщик SHALL исключить все реплики из ротации не позднее чем через 1,5 с после отказа и SHALL сам отвечать на любой запрос `503` в общем формате ошибки с `request_id`, равным `X-Request-Id`; после возвращения PostgreSQL реплики SHALL вернуться в ротацию без перезапуска.
#### Scenario: PostgreSQL остановлен #### Scenario: PostgreSQL остановлен
- **WHEN** сервис `postgres` остановлен - **WHEN** сервис `postgres` остановлен
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` отвечают `503 unavailable` быстрее 2 с, `GET /health/live` — `200`, ни один ответ не `500` - **THEN** `GET /health/ready` и `GET /api/v1/users/me` через LB отвечают `503 unavailable` быстрее 2 с, `GET /health/live` внутри реплики — `200`, ни один ответ не `500`
#### Scenario: Неизвестный токен при остановленной БД #### Scenario: Неизвестный токен при остановленной БД
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном - **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
- **THEN** ответ `503`, а не `200` - **THEN** ответ `503`, а не `200`
#### Scenario: Балансировщик исключает все реплики
- **WHEN** PostgreSQL остановлен дольше времени обнаружения
- **THEN** статистика LB показывает 0 готовых реплик, а запрос через LB, включая `GET /health/live`, получает `503 {"error":{"code":"unavailable",...}}` без `X-Instance-Id`
- **AND** после запуска PostgreSQL все реплики снова готовы в LB без перезапуска своих процессов
### Requirement: Восстановление без рестарта API ### Requirement: Восстановление без рестарта API
После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула. После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
@@ -0,0 +1,85 @@
# lab3-failover-operations Specification
## Purpose
Определяет эксплуатационные гарантии реплицированного стенда: за какое время балансировщик исключает отказавшую реплику, как переживается поочерёдный отказ и плановая замена реплик под нагрузкой, как проверяется общая идемпотентность параллельными запросами и как ограничены ресурсы, порты, секреты и хранилища.
## Requirements
### Requirement: Согласованные проверки, таймауты и остановка
Балансировщик SHALL проверять каждую реплику `GET /health/ready` с периодом 1 с, после первого провала — каждые 0,5 с, исключать её после 2 провалов подряд и возвращать после 2 успехов. Реплика, которая появилась или вернулась через DNS (запуск, `restore.sh`, новая реплика rolling update), SHALL получать запросы только после 2 успешных проверок, а не сразу после появления адреса. Максимальное время обнаружения SHALL составлять 1,5 с для реплики, которая отвечает `503` или отказывает в соединении, и 3,5 с для зависшей реплики (с таймаутом проверки 1 с). Readiness реплики SHALL отвечать быстрее таймаута проверки. Цепочка таймаутов SHALL убывать от внешнего звена к внутреннему: ожидание ответа балансировщиком > таймаут запроса в приложении > таймаут оператора и ожидания соединения с БД. Срок остановки реплики SHALL укладываться в таймаут хука остановки, а тот — в `stop_grace_period` и в 10 с.
#### Scenario: Конфигурация согласована
- **WHEN** выполняется `make student-test`
- **THEN** тест цепочки таймаутов по `compose.yaml`, `infra/haproxy/haproxy.cfg` и `scripts/stop-one.sh` проходит: окно вывода из ротации больше максимума обнаружения, срок остановки меньше таймаута хука, таймаут хука меньше `stop_grace_period` и 10 с, `timeout server` балансировщика больше `REQUEST_TIMEOUT_SECONDS`, а тот больше суммы таймаутов БД
#### Scenario: Обнаружение измерено по каждому виду отказа
- **WHEN** выполняется `make detection`
- **THEN** для `SIGTERM` через `scripts/stop-one.sh`, `docker kill`, `docker pause` и остановки PostgreSQL в `evidence/detection/*.json` записаны время обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума
#### Scenario: Остановка по сигналу не теряет запросы
- **WHEN** реплике посылается `SIGTERM` через `scripts/stop-one.sh`
- **THEN** балансировщик исключает её раньше, чем хук завершился, а реплика закрывает приём соединений только после этого
#### Scenario: Возврат реплики без преждевременного трафика
- **WHEN** остановленная реплика запускается снова под нагрузкой
- **THEN** балансировщик не направляет на неё запросы, пока она не прошла 2 проверки готовности: счётчики повторов и перенаправлений LB (`wretr`, `wredis`) за прогон равны 0
#### Scenario: Зависшая реплика
- **WHEN** процесс реплики приостановлен (`docker pause`) и не отвечает на проверки
- **THEN** балансировщик исключает её не позднее чем через 3,5 с, а после `docker unpause` возвращает в ротацию
### Requirement: Поочерёдный отказ под нагрузкой
Оператор SHALL одной командой останавливать каждую реплику по очереди под открытой нагрузкой (постоянная интенсивность запросов, 80 % отправок сообщений и 20 % чтений истории) и возвращать её до остановки следующей. Для каждой реплики SHALL фиксироваться интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика.
#### Scenario: Каждая реплика по очереди
- **WHEN** выполняется `make failover-each`
- **THEN** `evidence/failover-each/summary.json` содержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, её `X-Instance-Id` не встречался, а после возврата она снова обслуживает запросы
### Requirement: Общая идемпотентность под параллельными запросами
Параллельные `POST /api/v1/chats/{chat_id}/messages` с одним `Idempotency-Key` и одним телом, распределённые балансировщиком по разным репликам, SHALL создавать ровно одно сообщение и SHALL получать одинаковые ответы `201`; тот же ключ с другим телом SHALL получать `409`.
#### Scenario: Серия гонок через LB
- **WHEN** выполняется `make lb-check` (20 раундов по 8 параллельных запросов с одним ключом на раунд)
- **THEN** все 160 ответов `201`, их обслужили не менее двух реплик, в каждом раунде тела ответов совпадают, в истории ровно одна копия, а другой body получает `409`
### Requirement: Лимиты и изоляция
Каждый сервис стенда, включая генератор нагрузки, SHALL иметь лимиты CPU и памяти. Ни один сервис SHALL NOT задавать `container_name`. Опубликованные порты SHALL быть только у балансировщика и только на `127.0.0.1`. Секреты SHALL монтироваться только сервисам, которые ими пользуются; volumes данных SHALL принадлежать только своему хранилищу; реплики API SHALL работать с корневой файловой системой только для чтения; внутренняя сеть SHALL быть недоступна снаружи, а генератор нагрузки SHALL видеть только балансировщик.
#### Scenario: Проверка лимитов и изоляции
- **WHEN** выполняется `make limits`
- **THEN** проверка по `docker compose config` и `docker inspect` запущенных контейнеров печатает таблицу сервисов с лимитами, портами, секретами, volumes и сетями в `evidence/limits.txt` и завершается `PASS`; ни у одного контейнера `api` нет опубликованных портов
#### Scenario: Нарушение политики
- **WHEN** сервису без необходимости добавлен секрет, порт или `container_name`, либо снят лимит
- **THEN** `make limits` перечисляет нарушение и завершается ненулевым кодом
### Requirement: Поочерёдная замена под нагрузкой и однократные миграции
Оператор SHALL одной командой заменять реплики новой версией образа по одной: сначала миграции применяются один раз отдельным процессом, затем на каждую старую реплику запускается новая, и старая останавливается только после того, как балансировщик видит новую готовой. Число готовых реплик в балансировщике SHALL NOT опускаться ниже исходного. Миграции SHALL быть совместимы с работающей предыдущей версией (только добавление объектов схемы) либо ограничение SHALL быть описано в `REPORT.md`.
#### Scenario: Замена под нагрузкой
- **WHEN** выполняется `make rolling-update`
- **THEN** `evidence/rolling/result.json` показывает, что балансировщик ни разу не видел меньше исходного числа готовых реплик, доля ошибок нагрузки не больше 1 %, зонд не потерял записей, а после замены запросы обслуживают только новые контейнеры
#### Scenario: Обновление с прежней версии
- **WHEN** выполняется `make rolling-update FROM_REV=<коммит>`
- **THEN** стенд сначала поднимается на образе, собранном из этого коммита, а затем заменяется текущей версией с теми же гарантиями; журнал замены называет старый и новый образ каждой реплики
#### Scenario: Миграции один раз
- **WHEN** идёт поочерёдная замена
- **THEN** `migrate` запускается один раз до замены первой реплики, реплики схему не меняют, а повторный запуск сообщает `up to date`