Files
mtusi2026lab3/openspec/changes/replicas-lb/design.md
T
ricoromaandClaude Opus 5.5 4e0cc4e965 fix: start DNS-resolved replicas down until checks pass
Without init-state down HAProxy marked a slot UP as soon as Docker DNS
returned the container address, before uvicorn listened, so requests
after LB restart or scale-up hit a replica that was not ready.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 18:08:50 +03:00

482 lines
34 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.
# Design
## Context
Мотивация — `proposal.md`, «Why». Требования — дельты в `specs/`.
Правила стенда уже описывают целевое состояние лабы 3 (`balancer.md`,
`docker.md`, `run-modes.md`, `settings.md`, `student-tests.md`). Выбор
HAProxy и Compose без Swarm подтверждён пользователем 2026-10-07
(`PLAN.md`, «Ключевые решения», п. 1). Design выбирает то, что правила
и план оставили открытым, и сверяет стартовые значения плана с
соотношениями правил.
Текущее состояние (commit `b5ae252`):
- `docker-compose.yml`, проект `mtusi-lab3`. Сервисы:
- `postgres` и `valkey` — с портами на `127.0.0.1`;
- одноразовый `migrate`;
- один `api` с портом `127.0.0.1:${APP_OUT_PORT}:${APP__PORT}`.
Окружение `api` и `migrate` — общий якорь `x-app-env`, в нём и
пароль Valkey. Лимитов нет ни у одного сервиса.
- `X-Instance-Id` = hostname процесса, в compose — короткий ID
контейнера (12 hex). Сессии и ключи идемпотентности — в PostgreSQL,
Valkey — общий кэш неизменяемых карточек. Код приложения к нескольким
репликам готов: change `instance-id-idempotency`, решение 7;
`PLAN.md`, п. 4.
- `/health/ready` — `SELECT 1` с таймаутом
`READINESS_DB_TIMEOUT_SECONDS` = 2 с. Healthcheck образа — каждые
10 с, `[app] graceful_shutdown_seconds` = 8, `stop_grace_period` = 10 с.
- Пул на процесс — 10 + 5 соединений, `max_connections` PostgreSQL —
100 (по умолчанию).
- Свои стенды берут `docker-compose.yml` за основу:
- `make test_isolated` и `make failure_checks` создают отдельные
контейнеры API через `docker compose run ... api` с `-p`;
- `bench/` — через override `bench/bench.compose.yml`, где у `api`
есть `container_name` и лимиты в форме `cpus` / `mem_limit`.
- Проверено до design на Docker 29.8.1 и Compose 5.5.1:
- `docker kill` контейнера с `restart: unless-stopped` не
перезапускает его: 6 с после kill — `exited`, `RestartCount` 0;
- `container_name` вместе с `deploy.replicas` > 1 — ошибка
проекта compose;
- `mem_limit` в override при `deploy.resources.limits.memory` в
основном файле — ошибка `can't set distinct values`;
- черновик `haproxy.cfg` проходит `haproxy -c` на 3.4.6.
Одинаковые имена у frontend и backend с 3.3 запрещены. В образе
есть `bash`, `head`, `grep`, процесс работает от UID 99.
## Goals / Non-Goals
**Goals:**
- Каждое число цепочки таймаутов удовлетворяет соотношениям
`balancer.md`. Где стартовое значение `PLAN.md` их нарушает, число
меняется здесь, с объяснением.
- Остановленная реплика не обслуживает запросы ни через LB, ни после
политики перезапуска. Восстановление — одной командой.
- Свои стенды (`test_isolated`, `failure_checks`, `bench`) работают
без правок методики. Метки `bench` до и после change сравнимы: лимиты
те же, меняется только форма записи.
- Тесты реплик не выдают пропуск за успех. Режим стенда задан явно,
а не угадан по ответам.
**Non-Goals:**
- Замер времени обнаружения отказа, профиль `failover` нагрузочного
стенда, перевод `bench/` на HAProxy + N реплик — change
`graceful-failover`. Здесь числа цепочки задаются и проверяются
`make test-failover`, но не замеряются посекундно.
- `idle_in_transaction_session_timeout`, тюнинг пула под 8 реплик —
`graceful-failover` и трек 1.
- `scripts/rolling-update.sh` — change `rolling-update`.
- Изменения кода `src/`: не нужны (Context).
## Decisions
### 1. HAProxy 3.4.6 LTS, конфиг `infra/haproxy/haproxy.cfg`
- Образ — `haproxy:3.4.6-trixie@sha256:e2739156…` (digest индекса из
`docker buildx imagetools inspect`). 3.4 — текущая LTS, `trixie` — та
же база, что у остальных образов стенда.
- Конфиг монтируется только на чтение длинной записью с
`create_host_path: false`, в `/usr/local/etc/haproxy/haproxy.cfg`.
- Секций прокси четыре:
| Секция | Что делает |
|---|---|
| `resolvers docker` | DNS Docker `127.0.0.11:53` |
| `frontend entry` | приём клиентов на `APP__PORT` |
| `backend api` | реплики, проверки, балансировка |
| `frontend monitor` | `:8404`, `monitor-uri` и статистика |
- Внутренний порт LB — тот же `APP__PORT`, что у API. Строка
публикации `"127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"`
переезжает с `api` на `haproxy` без изменений, как в `docker.md`.
В конфиг порт приходит переменной окружения `API_PORT` (HAProxy
раскрывает `"${API_PORT}"` в кавычках). Это не секрет.
- Журнал — `log stdout format raw`, `option httplog` +
`option dontlog-normal`. Обычные успешные запросы не пишутся.
Пишутся ошибки, таймауты, повторы и перенаправления, смена состояния
реплик. Так журнал LB — доказательство failover и не шумит под
нагрузкой трека 1.
- `nbthread 1` при лимите 1 CPU. Без него HAProxy создал бы поток на
каждый из 12 CPU ВМ и делил бы между ними одну квоту. Пересмотр — в
треке 1, если упрёмся в LB.
**Альтернативы** — `PLAN.md`, таблица п. 1 (Nginx, Traefik, Swarm).
Выбор подтверждён. Обоснование переносится в `REPORT.md`.
### 2. Реплики через DNS Docker: `server-template api- 8`
```
default-server check inter 1s fall 2 rise 2 resolvers docker init-addr none init-state down resolve-prefer ipv4
server-template api- 8 "api:${API_PORT}"
```
- DNS Docker отвечает на имя сервиса `api` адресами всех работающих
реплик. HAProxy раскладывает их по 8 слотам, лишние слоты в `MAINT`.
`init-addr none` позволяет LB стартовать без реплик.
- **`init-state down`** (добавлено в apply). Без него слот, получивший
адрес из DNS, сразу считается `UP` («UP/READY (resolves again)» в
журнале), до первой проверки. Docker регистрирует адрес контейнера
при старте, раньше, чем uvicorn открыл порт. Поэтому после рестарта
LB, `make replicas` и масштабирования запросы шли на неслушающую
реплику: отказ соединения, повторы, а когда обе реплики ещё не
слушали — 503 от LB (видно на `scripts/restart.sh`). С `init-state
down` слот начинает `DOWN` и получает запросы только после `rise`
успешных проверок `/health/ready`. Новая реплика при `make replicas
API_REPLICAS=3` вошла в распределение через 4 с.
- `resolvers docker`: `timeout resolve 1s`, `hold valid 1s`,
`hold obsolete 1s`, `hold nx 1s`, `accepted_payload_size 8192`.
Пропавший адрес уходит из слота за 1–2 с, новый появляется за то же
время, без перезагрузки LB.
- 8 слотов — максимум серии B трека 1 (`PLAN.md`). Реплики сверх 8 LB
не увидит. Ограничение — в `REPORT.md`.
**Альтернатива — список `server api-1 …` по именам контейнеров.**
Имена зависят от индекса compose. После `--scale` пришлось бы править
конфиг и перезагружать LB, а рубрика «4» требует масштабирования одного
сервиса.
### 3. Проверки и цепочка таймаутов
| Параметр | Значение | Соотношение (`balancer.md`) |
|---|---|---|
| `inter` / `fall` / `rise` | 1 с / 2 / 2 | обнаружение ≈ `inter × fall + timeout check` = 1 × 2 + 3 = 5 с ≤ 10 с |
| `timeout check` | 3 с | > `READINESS_DB_TIMEOUT_SECONDS` = 2 с внутри `/health/ready` |
| `timeout connect` | 500 мс | `timeout connect × (retries + 1)` = 0,5 × 3 = 1,5 с < 2 с (таймаут клиента `tests/resilience.py`) |
| `retries` | 2 | с `option redispatch 1` каждый повтор идёт на другую реплику |
| `timeout server` | 10 с | > `[database] request_timeout_seconds` (6 с) + KDF входа |
| `timeout client` / `http-request` / `http-keep-alive` | 30 с / 10 с / 10 с | соединения тестов и k6 живут между запросами |
| `graceful_shutdown_seconds` / `stop_grace_period` | 8 с / 10 с | без изменений (`run-modes.md`) |
Отличия от стартовых значений `PLAN.md`, п. 6:
- **`timeout check` 3 с вместо 1 с.** При 1 с проверка обрывалась бы
раньше собственного таймаута `/health/ready` (2 с). Медленный, но
живой PostgreSQL выглядел бы как мёртвая реплика, а это нарушает
`infra.md`. Уменьшать таймаут готовности в коде этот change не будет
(Non-Goals). Цена — худшее обнаружение «зависшей» реплики 5 с вместо
3 с. Остановленную или убитую реплику проверка не ждёт: соединение
отвергается сразу (`stop`) или ограничено `timeout connect`
(адрес пропал). Пересмотр — `graceful-failover`.
- **`timeout connect` 500 мс вместо 1 с и `option redispatch 1`.** При
1 с и `retries 2` худший путь — 3 с, больше 2-секундного таймаута
клиента. `redispatch 1` уводит уже первый повтор на другую реплику, а
не на ту же. Внутри одной сети Docker соединение с живой репликой
устанавливается за доли миллисекунды, так что 500 мс — большой запас.
### 4. Повторы и ответы самого LB
- Повтор — только `retry-on conn-failure`, `retries 2`,
`option redispatch 1`. `empty-response`, `response-timeout`,
`junk-response`, `5xx` не включены. Почему — спек `load-balancing`,
«Повтор только при отказе соединения».
- Ответы LB 502 / 503 / 504 — через `http-error status … content-type
application/json lf-string …` в `defaults`. Тело — формат ошибки
контракта с `code` `unavailable`: в перечислении `Error.code`
контракта нет кодов для 502 и 504, ближайший по смыслу —
`unavailable`.
- `request_id` — `%[unique-id]` (`unique-id-format` в `defaults`), он
же в заголовке `X-Request-Id` (`hdr`). Тело остаётся в форме
контракта: `request_id` совпадает с заголовком. `X-Instance-Id` у
таких ответов нет — контракт это допускает.
- Запросу к реплике `unique-id` не передаётся. `X-Request-Id`
генерирует API (`api-layer.md`), LB его не переписывает.
### 5. Мониторинг LB, его healthcheck и `make lb_stats`
- `frontend monitor` на `:8404`, в сети compose, наружу не
публикуется:
- `monitor-uri /lb/ready` с `monitor fail if { nbsrv(api) lt 1 }` —
200, пока есть хотя бы одна готовая реплика, иначе 503;
- `stats uri /stats` — страница и CSV (`/stats;csv`) по каждому
слоту: `status`, `check_status`, `scur`, `stot`, `qcur`, `wretr`,
`wredis`. Это метрики трека 1.
- Healthcheck сервиса `haproxy` в compose: `bash` открывает
`/dev/tcp/127.0.0.1/8404`, шлёт `GET /lb/ready` и ждёт ` 200 ` в
первой строке. curl в образе нет, а `bash` есть. Значит, `healthy`
у LB — «через LB можно обслужить запрос».
- `make lb_stats` — тот же приём через `docker compose exec haproxy
bash`: читает `/stats;csv` и печатает слоты с адресом.
Пустые слоты в `MAINT` без адреса не печатаются. Контейнер LB
работает всегда, поэтому `exec` не зависит от того, какая реплика
остановлена.
**Альтернатива — stats-сокет.** В образе нет `socat`, читать его
пришлось бы другим контейнером. HTTP-статистика внутри сети
доступна и стенду `bench/` (k6 и python в сети compose).
### 6. Compose: реплики, лимиты, окружение по сервисам
- `api`: `deploy.replicas: ${API_REPLICAS:-2}`, без `ports` и
`container_name`. `restart: unless-stopped`, `stop_grace_period:
10s`, healthcheck из образа — как было. `make logs` по-прежнему
показывает журнал сервиса `api`, то есть всех реплик, без префикса:
реплику называет поле `instance_id` каждой строки.
- `haproxy`:
- `depends_on: api` (`service_started`): `make stop` гасит LB раньше
реплик, `make run_docker` поднимает его после них;
- `restart: unless-stopped`;
- окружение — только `API_PORT`.
- Лимиты (`deploy.resources.limits`):
| Сервис | CPU | Память | Почему так |
|---|---|---|---|
| `api` (на реплику) | 1.0 | 512M | один процесс — один event loop, больше 1 CPU не использует; Argon2id 4 × 64 MiB + интерпретатор ≈ 350 МБ |
| `postgres` | 2.0 | 1G | `shared_buffers` по умолчанию 128 МБ, запас на соединения реплик |
| `valkey` | 0.5 | 128M | `maxmemory 64mb` + накладные |
| `haproxy` | 1.0 | 256M | `nbthread 1` (решение 1) |
| `migrate` | 0.5 | 256M | один прогон alembic |
Сумма при двух репликах — 6 CPU и 2,6 ГБ из 12 CPU и 7,7 ГиБ ВМ
Docker.
- Соединения PostgreSQL: `API_REPLICAS × (pool_size + max_overflow)` +
`migrate`. 2 × 15 + 1 = 31; 6 × 15 + 1 = 91 ≤ 100; при 7 репликах —
106 > 100. Граница пула — гипотеза 3 трека 1. Расчёт — в `REPORT.md`.
- Окружение — якоря вместо одного `x-app-env`:
- `x-db-env`: `APP__RUN_MODE`, `DATABASE__*`;
- `x-cache-env`: `CACHE__*`, в том числе пароль Valkey;
- `migrate` — только `x-db-env`;
- `api` — `x-db-env`, `x-cache-env` и `APP__PORT`;
- `haproxy` — `API_PORT`.
`<<` с несколькими якорями compose поддерживает.
- `.env.example`: строка `API_REPLICAS=2` с комментарием. Её читают
compose и Makefile, приложение — нет (`settings.md`).
- В рабочий `.env` строка не переносится: без неё действует 2 и в
compose (`${API_REPLICAS:-2}`), и в Makefile (`API_REPLICAS ?= 2`).
### 7. `scripts/stop-one.sh`
```
TARGET_INSTANCE_ID → проверка формата: [0-9a-f]{12,64}
→ docker compose ps -q api (работающие реплики, полные ID)
→ ровно один ID с этим префиксом, иначе выход 3
STOP_MODE=stop → docker stop --timeout 9 <id>
STOP_MODE=kill → docker kill <id>
STOP_ONE_LOG=файл → строка «время, TARGET_INSTANCE_ID, полный ID, режим» в файл
```
- `cd` в корень репозитория, как `restart.sh`. Проект — из
`docker-compose.yml`, без `-p`: hook работает с рабочим стендом
`mtusi-lab3`.
- Формат — только hex: hostname в compose — начало ID контейнера.
Пустое и иное значение — выход 2 до вызова docker. ID PostgreSQL,
Valkey и LB не попадут в `ps -q api`, контейнеры других проектов — тем
более.
- `--timeout 9`: uvicorn сам завершается не позже 8 с
(`graceful_shutdown_seconds`), а 9 с гарантируют возврат hook раньше
10 с даже для зависшего процесса. `stop_grace_period` (10 с) для
`make stop` не меняется.
- `kill` политику перезапуска не включает (Context, проверено).
Поэтому `docker stop -t 0` вместо `kill`, оговорённый в `PLAN.md`
(«Риски»), не нужен. Проверка повторяется на стенде (сценарий
«Реплика не поднимается сама»).
- **`STOP_ONE_LOG`** — необязательный журнал для доказательства.
`tests/resilience.py` скрывает вывод hook, но передаёт ему своё
окружение целиком. Запуск `STOP_ONE_LOG=… make test-failover …`
оставляет строку с `TARGET_INSTANCE_ID`, который выбрал тест, и
полным ID остановленного контейнера. Секретов в строке нет. Так
evidence показывает «ID остановленного = `TARGET_INSTANCE_ID`»
прямо, а не по косвенным признакам (`balancer.md`).
- Вывод в stderr — одна строка «stopped api container <id12> (mode)».
Окружение и секреты не печатаются.
**Восстановление** — цель `make replicas` (решение 9): `up -d
--no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api`. Она
запускает остановленные контейнеры с теми же ID и доводит число реплик
до `API_REPLICAS`.
### 8. `scripts/restart.sh`
Порядок по `docker.md`:
1. `docker compose stop haproxy api`;
2. `docker compose restart postgres valkey`;
3. `docker compose up -d --wait postgres valkey`;
4. `docker compose start api haproxy`.
- `start` поднимает те же контейнеры всех реплик, число не меняется.
`start api` запускает и зависимость `migrate`, повторный прогон —
no-op.
- LB гасится первым и поднимается последним: тест сохранности ждёт
`/health/ready` через LB, и 503 от LB в окне рестарта для него —
обычная неготовность.
- Если перед рестартом одна реплика была остановлена (`stop-one.sh`),
`start api` поднимет и её. Это возврат к штатному стенду, а не
изменение числа реплик.
### 9. Свои цели Makefile
Новая секция «Реплики за балансировщиком» ниже целей skeleton:
- `API_REPLICAS ?= 2` и `EXPECT_REPLICAS ?= $(API_REPLICAS)` после
`-include .env`;
- `replicas` — решение 7: восстановить и выставить число. Разовая
подмена — `make replicas API_REPLICAS=3`. Следующий `make run_docker`
вернёт число из `.env`;
- `instances` — `driver.py --port $(APP_OUT_PORT) instances`
(решение 11): вход одним синтетическим пользователем, 12 запросов
`GET /users/me` с одним токеном, `X-Instance-Id` каждого ответа и
итог по репликам. Это шаг 1 сценария защиты (`README.md`);
- `lb_stats` — решение 5;
- `student_test` передаёт `EXPECT_REPLICAS` (решение 10).
`make run_docker` не меняется: `up -d` поднимает и LB. Готовность
стенда — `healthy` у `haproxy` (решение 5).
### 10. Тесты реплик: режим `EXPECT_REPLICAS`
- **`conftest.py`.** `EXPECT_REPLICAS` — сколько реплик за `BASE_URL`;
без переменной — 2, как у стенда по умолчанию. Фикстура `replicas`:
- при значении < 2 — `pytest.skip` с причиной «один процесс API
(EXPECT_REPLICAS=1): нужен стенд с балансировщиком»;
- иначе — число.
- **`contract.py`.** Помощник `assert_replicas(values)`: не меньше
двух разных `X-Instance-Id`. Иначе — падение с числом увиденных
значений и подсказкой про `EXPECT_REPLICAS=1`.
- **Почему не угадывать по ответам.** Если считать «одно значение —
значит один процесс», сломанный LB (одна живая реплика, sticky)
давал бы пропуск вместо падения. Явный режим отличает «стенд одного
процесса» от «стенд с LB, который не распределяет».
- **Кто передаёт 1:**
- `run_isolated.py` — аргумент `EXPECT_REPLICAS=1` у `make
student_test`;
- драйвер скилла — когда на порту его собственный процесс (есть
pid-файл).
`make failure_checks` гоняет только тесты `fault`, им режим не нужен.
- **Новые и изменённые тесты:**
- `test_load_balancing.py`:
- «Одна сессия на разных репликах» — 20 × `GET /users/me` с одним
токеном;
- «Запись видна через другую реплику» — отправка, затем
`2 × EXPECT_REPLICAS + 2` чтений истории, и среди них есть чтение
с другим `X-Instance-Id`.
Capability `load-balancing` вне сверки покрытия (proposal). Поэтому
сценарий назван в докстринге, как у тестов `student-tests`.
- `test_idempotency.py`, «Повтор через другую реплику»: отправка с K,
затем повторы, пока ответ не придёт с другим `X-Instance-Id`
(не больше `2 × EXPECT_REPLICAS` попыток). Тот же JSON; другое
тело с K — 409 от ≥2 реплик.
- `test_race.py`, «Гонка одного ключа через реплики»: тот же
`run_together`, что у «Гонки одного ключа». Ответы проверяются так
же, плюс должна найтись пара пересекающихся по времени запросов с
разными `X-Instance-Id`. Именно это «одновременно через разные
реплики», а не просто «разные реплики за весь прогон». Прежний тест
«Гонка одного ключа» остаётся для любого стенда.
- `test_api_conventions.py`, «Одно значение на процесс»: две
одинаковые серии. Каждая — `business_responses` и три раза
`service_responses`, 18 запросов. При `EXPECT_REPLICAS` = 1 —
одно значение на всё. Иначе каждое значение встречается больше
одного раза, и вторая серия не приносит новых.
Round-robin по ≤8 репликам за 18 запросов показывает каждую
реплику хотя бы дважды. Значение «новое на каждый запрос» не
прошло бы ни одну проверку. Тест не пропускается ни в одном режиме.
- **`spec_coverage.py`**: новые сценарии `idempotency` покрыты
маркерами. Исключений не прибавляется.
### 11. Драйвер и скилл `run-mtusi-messenger`
- Команда `instances [--count N]`, работает против любого порта:
1. регистрация синтетического пользователя и вход;
2. N × `GET /api/v1/users/me` с одним токеном;
3. по строке на ответ (номер, статус, `X-Instance-Id`) и итог
`Counter`. Токен не печатается.
- `student` передаёт `EXPECT_REPLICAS=1`, если на порту процесс самого
драйвера (есть pid-файл).
- `SKILL.md`:
- описание — уже не «один API без балансировщика»;
- раздел «Run: контейнер» — LB, реплики, `make replicas`,
`instances`, `lb_stats`, `stop-one.sh`, `make test-failover`;
- Gotchas — `docker compose logs api` по всем репликам, `exec api`
берёт первую реплику, порт реплики на хосте не опубликован.
### 12. Свои стенды
- **`student-tests/failures.compose.yml`.** `!reset []` для портов
`haproxy`: LB стенда отказов не запускается, но порт `APP_OUT_PORT`
не должен быть занят даже по ошибке. Сброс портов `api` убирается:
их больше нет.
- **`run_isolated.py` и `run_failures.py`.** `docker compose run
--no-deps … api` создаёт отдельный контейнер вне `deploy.replicas`,
с лимитами сервиса. Меняется только `EXPECT_REPLICAS=1` у `make
student_test` в `run_isolated.py`.
- **`bench/bench.compose.yml`.** Стенд остаётся с одним API до
`graceful-failover`:
- `api`: `deploy.replicas: 1` (рядом с `container_name`);
- лимиты `api`, `postgres`, `valkey` — в форме
`deploy.resources.limits` с теми же переменными `BENCH_*`.
`memswap_limit` остаётся на уровне сервиса, у него нет формы в
`deploy`;
- `migrate` получает лимиты основного файла;
- `haproxy` стенд не запускает: `up -d --no-deps api`.
`NanoCpus` и `Memory` контейнеров те же, что раньше, поэтому паспорт
и сравнимость меток не меняются. Проверка — `make bench_quick` и
`make bench_restore_quick` без ошибок.
### 13. Evidence
| Файл | Что показывает |
|---|---|
| `evidence/replicas/stand.md` | `docker compose ps` — порт хоста только у `haproxy`, `postgres`, `valkey`, все на `127.0.0.1`. У `api` нет портов и `container_name`. Лимиты всех контейнеров из `docker inspect`. Имена переменных окружения по сервисам — без значений. Один прогон `migrate` |
| `evidence/replicas/distribution.md` | `make instances` (≥2 значения, одна сессия), `make lb_stats`. `make replicas API_REPLICAS=3` → три значения, обратно → два |
| `evidence/replicas/lb-errors.md` | все реплики остановлены — 503 JSON от LB, `request_id` = `X-Request-Id`; healthcheck LB `unhealthy`; восстановление |
| `evidence/replicas/test-persistence.md` | `make test-persistence` через LB, `StartedAt` всех контейнеров до и после, те же ID |
| `evidence/failover/test-failover.md` | `make test-failover` (`STOP_MODE=stop`) для каждой реплики по очереди. `docker compose ps -a` и `StartedAt` до и после. `STOP_ONE_LOG`: `TARGET_INSTANCE_ID` = ID остановленного. `lb_stats` и журнал LB (перенаправления). `make replicas` между прогонами |
| `evidence/failover/test-failover-kill.md` | то же с `STOP_MODE=kill`. Контейнер `exited` 137 и через 15 с не поднят; журнал LB: оборванный ответ без повтора |
| `evidence/failover/stop-one-refusals.md` | пустой, не-hex, ID PostgreSQL / Valkey / LB, неизвестный ID — ненулевой код, `StartedAt` всех контейнеров прежний |
| `evidence/tests/student-test-lb.md` | `make student_test` через LB: тесты реплик выполнены и прошли |
| `evidence/tests/test-isolated.md`, `failure-checks.md` | новые прогоны: тесты реплик пропущены с причиной; проверки отказов прошли |
| `evidence/tests/bench-self-checks.md` | `make bench_quick` и `make bench_restore_quick` на новом compose — код 0 (самопроверки, не замеры) |
Все снимаются с закоммиченного кода, в шапке — спеки, change, дата,
commit, стенд, хост.
## Risks / Trade-offs
- **[HAProxy держит keep-alive к реплике, и uvicorn закрывает его при
SIGTERM ровно в момент повторного использования]** → запрос получит
502 от LB (`empty-response` не повторяется намеренно). Клиент
`make test-failover` повторяет с тем же ключом. Частоту видно в
журнале LB, замер — `graceful-failover`.
- **[`timeout check` 3 с медленнее плана]** → худшее обнаружение
зависшей реплики 5 с. Укладывается в 10 с. Пересмотр вместе с
таймаутом готовности — `graceful-failover`.
- **[`server-template` на 8 слотов]** → девятая реплика не получит
трафик. Это максимум серий трека 1. Ограничение — в `REPORT.md` и в
комментарии конфига.
- **[При 7+ репликах пул превышает `max_connections`]** → расчёт в
`REPORT.md`. Это гипотеза 3 трека 1, а не дефект этого change.
- **[Make-цель `instances` зовёт драйвер скилла из `.claude/`]** →
драйвер переносится между лабами вместе с `.claude/`
(AGENTS.md, «Переход в следующую лабу»), только stdlib. Отдельный
скрипт в `scripts/` смешался бы с файлами skeleton.
- **[Тест «Одно значение на процесс» полагается на round-robin]** →
при `leastconn` или весах набор мог бы не увидеть реплику в первой
серии. Балансировка задана в решении 2. Смена алгоритма — повод
пересмотреть тест.
- **[`make student_test` против консольного процесса на 8080 без
`EXPECT_REPLICAS=1`]** → тесты реплик падают с подсказкой. Это
намеренно: пропуск по догадке скрыл бы сломанный LB.
- **[`docker compose run` для `test_isolated` и `failure_checks`
наследует лимиты `api` (1 CPU, 512M)]** → для функциональных
проверок достаточно. Тест «100 сообщений» и KDF укладываются, это
проверяется прогоном.
## Migration Plan
1. `make down` старого стенда не нужен. `docker compose up -d` по
новому файлу:
- пересоздаёт `api` без порта и добавляет вторую реплику;
- создаёт `haproxy` на освободившемся `APP_OUT_PORT`;
- volume PostgreSQL не трогает.
2. Откат: прежний `docker-compose.yml` и `docker compose up -d
--remove-orphans`. Контейнер `haproxy` удаляется, `api` снова
получает порт. Данные те же: схема не менялась.
3. В рабочий `.env` ничего переносить не нужно (решение 6).