Files
mtusi2026lab2/openspec/specs/lab3-failover-operations/spec.md
T
ArtyomandClaude Opus 5.5 8cd30488d2 Archive the carry over of the lab 3 fixes change
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
2026-10-30 06:25:44 +03:00

12 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, 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