# 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-зависимостей не прибавляется.