Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 4 specs and the
archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5
continues the same spec history instead of starting from scratch. The
files come from the lab 4 solution commit d2744bc.
Rewrite AGENTS.md and the openspec context and rules for lab 5: upload
answers 202 queued after the original is in a private staging prefix
and the attachment, the job and the outbox row are committed in one
transaction, a separate relay publishes the outbox to RabbitMQ with
publisher confirms, a separate worker built from the same image
consumes the queue through FastStream with a manual ack after the
result commit, PostgreSQL stays the source of truth for job states,
Out of scope moves to labs 6-7, track 1 and broker HA, and the rules
add the failure windows between PostgreSQL and the broker, the effect
key and the lease to specs and designs.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
11 KiB
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