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>
482 lines
34 KiB
Markdown
482 lines
34 KiB
Markdown
# 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).
|