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