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>
10 KiB
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/переходит в changegraceful-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нагрузочного стенда, поочерёдная остановка под нагрузкой — changegraceful-failover; - поочерёдная замена реплик (
scripts/rolling-update.sh) — changerolling-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-зависимостей не прибавляется.