Files
mtusi2026lab3/openspec/specs/lab3-failover-operations/spec.md
T
ArtyomandClaude Opus 5.5 61c0c28a43 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>
2026-10-28 20:08:15 +03:00

11 KiB
Raw Blame History

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