Sync the delta specs into the main specs: zones are linked by the schema and the ports main.py assembles, the event bus and the network dependencies name S3 and Valkey, an outsider does not wait for chat locks, an empty cursor is rejected, a request cancelled at shutdown gets 503 in the contract format, the body limit counts received bytes per route, logout withdraws the revocation mark on a database failure, detection runs three times, failover-each records the stopped replica, lost answers are retried on the stand, posting checks its input in a fixed order and make up waits for every replica in the balancer. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V1d3RLHNBBMA6UqBLLJv27
12 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,docker kill,docker pauseи остановки PostgreSQL записывают вevidence/detection/run<N>/*.jsonвремя обнаружения, заявленный максимум и время возврата в ротацию, и каждое время обнаружения не больше заявленного максимума плюс допуск замера 0,25 с (запуск docker CLI до сигнала и опрос статистики LB раз в 50 мс); в отчёте приводится диапазон трёх прогонов
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 фиксироваться состояние реплик после остановки (docker ps -a), интенсивность и доля ошибок нагрузки, задержки p50/p95/p99, время обнаружения, время возврата в ротацию, ошибки и время восстановления записи зонда, повторяющего неудачную запись с тем же ключом, и счётчики повторов и перенаправлений балансировщика.
Scenario: Каждая реплика по очереди
- WHEN выполняется
make failover-each - THEN
evidence/failover-each/summary.jsonсодержит запись на каждую реплику; в каждой хук завершился кодом 0, доля ошибок нагрузки не больше 1 %, запись восстановилась не позже 10 с, пока реплика была исключена, еёX-Instance-Idне встречался, а после возврата она снова обслуживает запросы; вevidence/failover-each/<hostname>/action.txtпосле хука записанdocker ps -aреплик, где остановлена именно эта реплика
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