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
created: 2026-10-28
archived: 2026-10-28
lab: 3
@@ -79,7 +79,7 @@
### 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: Остановка укладывается в срок
@@ -87,6 +87,11 @@
- **THEN** процесс завершается не позднее чем через 10 секунд и раньше `stop_grace_period`
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
#### Scenario: Сначала вывод из ротации
- **WHEN** процессу сервера послан `SIGTERM`
- **THEN** в течение окна `DRAIN_SECONDS` `/health/ready` отвечает `503` в общем формате ошибки, `/health/live` — `200`, соединения ещё принимаются, а после окна порт закрыт и процесс завершается с кодом 0 не позднее `SHUTDOWN_TIMEOUT_SECONDS`
#### Scenario: Принятый запрос дорабатывается
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
@@ -5,18 +5,24 @@
## Requirements
### 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 остановлен
- **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: Неизвестный токен при остановленной БД
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
- **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
После возвращения 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`