Files
mtusi2026lab3/openspec/changes/graceful-failover/proposal.md
T
ricoromaandClaude Opus 5.5 459f84c75c feat: coordinate timeout chain and add failover load profile
HAProxy checks get fastinter 500ms and timeout check 2.5s (hung replica
detected within 6.5 s), http-reuse never with uvicorn keep-alive 60 s so
the LB closes idle replica connections, and app connections set
idle_in_transaction_session_timeout so a frozen replica releases its
idempotency key. The bench stand runs behind HAProxy with N replicas and
gains the failover profile (make bench_failover / bench_failover_quick):
constant-rate writes with a key and reads while each replica is stopped,
killed or paused, with per-second timeline, detection and recovery time
and write reconciliation. Driver commands idle-conns and hang-key check
the keep-alive and hung-transaction decisions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 23:21:12 +03:00

8.8 KiB
Raw Blame History

Proposal

Why

Рубрика «4» лабы 3 (README.md) требует трёх вещей, которых после change replicas-lb ещё нет:

  • согласованные health/readiness, таймауты и прекращение приёма при SIGTERM, LB исключает недоступный backend, а период проверок и максимальное время обнаружения отказа названы;
  • поочерёдная остановка каждой API-реплики с восстановлением предыдущей: RPS, ошибки и время восстановления;
  • те же числа под нагрузкой, а не на тестовом клиенте раз в 0,1 с.

Сейчас цепочка таймаутов задана, но не замерена (AGENTS.md, «Переходное состояние»). Verify replicas-lb оставил открытыми:

  • Мало запаса у зависшей реплики. LB исключает её за `fall × (inter
    • timeout check)` = 8 с, замер — 7,3–7,7 с при пределе 10 с.
  • Гонка keep-alive не проверена. uvicorn закрывает простаивающее соединение через 5 с, а HAProxy держит такие соединения в пуле и может отправить запрос в закрывающееся. Разведка на рабочем стенде (2026-10-10, design, «Context») показала: пул LB опустел ровно через ~5 с после всплеска, то есть первым закрывает uvicorn.
  • Блокировка ключа у зависшей реплики. Замороженный процесс держит открытую транзакцию с ключом идемпотентности бесконечно. Повтор того же ключа через другую реплику ждёт до statement_timeout и получает 503 снова и снова (REPORT.md, «Ограничения»).
  • Стенд bench/ — один API без LB. На нём нельзя ни измерить отказ реплики под нагрузкой, ни начать серии трека 1 (PLAN.md, «Трек 5 → Методика»).

What Changes

  • Цепочка таймаутов. Каждое звено обосновано и записано в design, REPORT.md и комментариях конфигов:

    • HAProxy: fastinter 500ms, timeout check 2,5 с вместо 3 с. Худшее обнаружение зависшей реплики — 6,5 с вместо 8 с, вернувшаяся реплика включается быстрее;
    • uvicorn: timeout_keep_alive из новой настройки [app] keep_alive_seconds (60 с) вместо неявных 5 с, HAProxy: http-reuse never. Простаивающее соединение LB → реплика живёт не дольше сеанса клиента (10 с) и закрывает его LB, а не реплика;
    • PostgreSQL: idle_in_transaction_session_timeout на соединениях приложения из новой настройки [database] idle_in_transaction_timeout_ms (10 с). Транзакция замороженной реплики снимается, ключ освобождается.
  • Замер обнаружения отказа для stop, kill и зависшей реплики (pause): действие → DOWN в LB → первые успешные ответы → восстановление доли успеха ≥ 99 %. Формула сверяется с замером.

  • Стенд bench/ на HAProxy + N реплик. Тот же haproxy.cfg, число реплик и лимиты LB — поля Profile. k6 ходит через LB. При N = 1 профили лабы 2 (full, quick, restore, restore_quick) работают как раньше. CPU и память приложения в метриках — сумма по репликам.

  • Профиль failover — make bench_failover и быстрый make bench_failover_quick:

    • две реплики с лимитами рабочего стенда;
    • k6 с постоянной интенсивностью: запись с Idempotency-Key и чтение истории;
    • по очереди каждая реплика в каждом режиме: остановка посреди нагрузки, восстановление, следующая;
    • режимы stop и kill, в полном профиле ещё pause;
    • посекундные успешные RPS и ошибки по кодам, распределение по X-Instance-Id, время обнаружения и восстановления;
    • после каждой фазы неподтверждённые записи повторяются с тем же ключом, и число сообщений сверяется: без потерь и дублей.

    Результаты — в evidence/failover/<метка>/.

  • Документы. Правила balancer.md, bench.md, run-modes.md, infra.md — под решения design. AGENTS.md — «Переходное состояние», карта кода, команды. REPORT.md:

    • таблица цепочки таймаутов;
    • замер обнаружения;
    • строки доказательств уровня «4»;
    • «Эксперименты и отказы»;
    • ответ на вопрос защиты «отказ процесса и отказ узла».

Вне этого change:

  • поочерёдная замена реплик на новый образ под нагрузкой — change rolling-update;
  • открытая модель ступенями до SLO, серии A и B, метрики LB и PostgreSQL по репликам — change scaling-bench. Здесь стенд только получает LB и N реплик.

Capabilities

New Capabilities

Нет.

Modified Capabilities

  • graceful-shutdown: остановка реплики за балансировщиком. Закрытый сокет даёт отказ соединения, LB перенаправляет запрос, и при stop под нагрузкой ошибок клиента нет. Простаивающие соединения LB → реплика первым закрывает LB.
  • load-balancing:
    • быстрые повторные проверки (fastinter), формула и замер времени обнаружения по режимам stop, kill, pause;
    • транзакции зависшей реплики снимает PostgreSQL, повтор того же ключа через другую реплику завершается;
    • поочерёдная остановка каждой реплики под постоянной нагрузкой.
  • load-benchmark:
    • стенд — HAProxy и N реплик, генератор ходит через LB;
    • метрики приложения — по всем репликам;
    • новый профиль failover с посекундной шкалой, временем обнаружения и восстановления, сверкой записей.
  • service-configuration: новые параметры [app] keep_alive_seconds и [database] idle_in_transaction_timeout_ms.

Impact

  • Конфигурация стенда: infra/haproxy/haproxy.cfg (проверки, комментарии цепочки), config_example.toml.

  • Код приложения:

    • src/config/settings.py — два поля;
    • src/main.py — timeout_keep_alive у uvicorn;
    • src/infra/db/engine.py — серверная настройка idle_in_transaction_session_timeout.

    Поведение HTTP API не меняется.

  • Стенд bench/:

    • bench.compose.yml, bench.env;
    • run.py — реплики, LB, профиль failover;
    • новые failover.py (разбор шкалы, событий LB и docker) и k6/failover.js, k6/retry.js;
    • k6/lib.js — адрес LB, ключ отправки задаётся.
  • Makefile: цели bench_failover, bench_failover_quick. .gitignore — пробные метки evidence/failover/quick-*.

  • Документы:

    • .claude/rules/ (balancer.md, bench.md, run-modes.md, infra.md);
    • AGENTS.md, REPORT.md;
    • evidence/failover/, evidence/tests/.
  • Зависимости не прибавляются: k6 и HAProxy — те же образы.