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

166 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-зависимостей не прибавляется.