Files
mtusi2026lab3/openspec/changes/replicas-lb/proposal.md
T
ricoromaandClaude Opus 5.5 8e15e02898 docs: propose replicas-lb change
HAProxy as the single entry point, API replicas without published
ports, resource limits and per-service secrets, restart and stop-one
hooks, replica tests in student-tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:40:04 +03:00

10 KiB
Raw Blame History

Proposal

Why

Рубрика «3» лабы 3 (README.md) требует стенд, где клиент ходит в одну точку входа, а за ней работают не меньше двух взаимозаменяемых API-реплик с общими PostgreSQL и сессиями. Разные запросы одной сессии должны обслуживаться разными репликами, а отказ любой одной реплики — не мешать новым чтениям и записям дольше 10 с. Это проверяют make test-failover (≥2 наблюдаемых реплики, запись во время остановки одной) и make test-persistence (рестарт всего стенда с прежним токеном).

Сейчас стенд mtusi-lab3 — один контейнер api с портом на 127.0.0.1:8080 (AGENTS.md, «Переходное состояние»). X-Instance-Id и Idempotency-Key уже работают (change instance-id-idempotency), но:

  • нет балансировщика;
  • нет scripts/stop-one.sh, и make test-failover не запустить;
  • гонка одного ключа доказана только на одном процессе.

Рубрика «4» добавляет требования к стенду:

  • лимиты CPU/RAM у всех контейнеров;
  • порты API не публикуются в обход LB;
  • секреты только там, где нужны;
  • нет container_name;
  • гонка одного ключа — через разные реплики.

What Changes

  • HAProxy — единственная точка входа. Новый сервис compose haproxy: закреплённый образ, конфиг infra/haproxy/haproxy.cfg только на чтение. Наружу публикуется только он, на 127.0.0.1:${APP_OUT_PORT}.
    • Реплики находятся через DNS Docker, без списка адресов.
    • Активная проверка /health/ready с явным периодом.
    • roundrobin без sticky session.
    • Повтор запроса — только при отказе соединения.
    • Ошибки, которые создаёт сам LB, отдаются в формате ошибки контракта.
    • Статистика — только внутри сети compose.
  • api × API_REPLICAS. deploy.replicas: ${API_REPLICAS:-2}, без ports и без container_name. Новая строка API_REPLICAS=2 в .env.example. Соответствие имени skeleton — в REPORT.md.
  • BREAKING (для оператора): на APP_OUT_PORT отвечает HAProxy, а не контейнер API. Порта отдельной реплики на хосте больше нет. Запросы к реплике в обход LB — только изнутри сети compose.
  • Лимиты и секреты по сервисам. deploy.resources.limits у haproxy, api, migrate, postgres, valkey. Окружение разделено:
    • migrate получает только PostgreSQL;
    • пароль Valkey — только api и valkey;
    • LB не получает ни одного секрета.
  • Hook-скрипты.
    • scripts/restart.sh перезапускает ещё LB и все реплики API.
    • Новый scripts/stop-one.sh по scripts/stop-one.example.sh: TARGET_INSTANCE_ID → контейнер api этого проекта; режим STOP_MODE=stop|kill; возврат ≤10 с. Реплика остаётся остановленной, чужие контейнеры скрипт не трогает.
  • Свои цели Makefile:
    • replicas — вернуть остановленные реплики и выставить их число;
    • instances — распределение запросов одной сессии по X-Instance-Id;
    • lb_stats — состояние реплик глазами HAProxy.
  • Тесты реплик в student-tests/.
    • Режим стенда — EXPECT_REPLICAS: сколько реплик за BASE_URL. make student_test берёт его из API_REPLICAS, make test_isolated и драйвер скилла в консоли передают 1.
    • Распределение одной сессии по ≥2 X-Instance-Id.
    • Запись видна через другую реплику.
    • Повтор с тем же ключом через другую реплику.
    • Гонка одного ключа с ответами ≥2 реплик, пересекающимися по времени.
    • Против одного процесса тесты реплик пропускаются с явной причиной. Если реплик за LB меньше ожидаемого — падают.
    • Тест «Одно значение на процесс» переписан под несколько реплик.
  • Совместимость своих стендов.
    • make test_isolated и make failure_checks по-прежнему поднимают свои одиночные API из определения сервиса api.
    • Стенд bench/ остаётся с одним API: override задаёт одну реплику и лимиты в форме deploy.resources.
    • На HAProxy и N реплик bench/ переходит в change graceful-failover.
  • Скилл run-mtusi-messenger — раздел «контейнер» под LB и реплики, команда instances драйвера.
  • Документы. Правила balancer.md, docker.md, run-modes.md, student-tests.md — под решения design. AGENTS.md — «Переходное состояние» и карта кода. REPORT.md:
    • архитектура, выбор HAProxy;
    • соответствие API_REPLICAS, лимиты и расчёт соединений;
    • строки доказательств;
    • ответы на вопросы защиты.

Вне этого change:

  • обоснование и замер времени обнаружения отказа, профиль failover нагрузочного стенда, поочерёдная остановка под нагрузкой — change graceful-failover;
  • поочерёдная замена реплик (scripts/rolling-update.sh) — change rolling-update;
  • серии трека 1 — changes scaling-bench, scaling-improvement.

Capabilities

New Capabilities

  • load-balancing: работа API за балансировщиком:
    • одна точка входа, ≥2 взаимозаменяемых реплики, число реплик без правки конфигурации LB;
    • распределение без sticky session;
    • активная проверка готовности, исключение и возврат реплики;
    • повтор только при отказе соединения;
    • ошибки самого LB в формате контракта;
    • отказ одной реплики: ≤10 с до новых чтений и записей;
    • failover hook scripts/stop-one.sh, восстановление реплик;
    • статистика LB внутри сети.

Modified Capabilities

  • container-run:

    • make run_docker поднимает HAProxy и API_REPLICAS реплик;
    • APP_OUT_PORT — порт LB;
    • на localhost публикуются только LB, PostgreSQL и Valkey;
    • scripts/restart.sh перезапускает и LB, и все реплики;
    • новое требование: лимиты CPU/RAM у всех сервисов и секреты только там, где нужны.
  • api-conventions: сценарий «Одно значение на процесс» проверяется и через балансировщик.

  • idempotency: новые сценарии «Гонка одного ключа через реплики» и «Повтор через другую реплику».

  • student-tests:

    • тесты реплик и режим EXPECT_REPLICAS;
    • make test_isolated — в режиме одного процесса;
    • вывод прогона через LB — отдельный файл evidence.

    load-balancing, как и container-run, в сверку покрытия не входит: почти все его сценарии требуют действий над контейнерами и доказываются evidence. Два сценария, которые проверяются по HTTP, тесты называют в докстринге.

Impact

  • Стенд: docker-compose.yml (сервис haproxy, реплики, лимиты, окружение по сервисам), новый infra/haproxy/haproxy.cfg, .env.example.
  • Скрипты и цели: scripts/restart.sh, новый scripts/stop-one.sh, свои цели в Makefile (replicas, instances, lb_stats, EXPECT_REPLICAS у student_test).
  • Свои стенды: student-tests/run_isolated.py, student-tests/failures.compose.yml, bench/bench.compose.yml.
  • Тесты: student-tests/conftest.py, test_api_conventions.py, test_race.py, test_idempotency.py, новый test_load_balancing.py, spec_coverage.py.
  • Скилл: .claude/skills/run-mtusi-messenger/SKILL.md и driver.py.
  • Код приложения (src/) не меняется: X-Instance-Id, идемпотентность и состояние вне процесса уже есть.
  • Документы: .claude/rules/ (balancer.md, docker.md, run-modes.md, student-tests.md), AGENTS.md, PLAN.md, REPORT.md, evidence/replicas/, evidence/failover/, evidence/tests/.
  • Зависимости: новый образ haproxy:3.4.6-trixie (LTS), тег и digest индекса. Python-зависимостей не прибавляется.