Files
mtusi2026lab3/REPORT.md
T

1492 lines
160 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.
# Отчёт — лабораторная 3
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
- Целевая оценка 5; выбранный трек 5: трек 1 «Цена масштабирования» (серии сняты, change `scaling-bench`; подтверждённое улучшение — change `scaling-improvement`, впереди)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Запуск из чистого clone
TODO (этап 7, `PLAN.md`): версии runtime/образов и prerequisites одним
списком, повторная проверка из настоящего `git clone` на стенде с LB.
Стенд с балансировщиком (change `replicas-lb`):
```sh
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml из шаблонов; существующие не трогает
make run_docker # docker compose build + up -d: postgres, valkey → migrate → api × API_REPLICAS (2) → haproxy
docker compose ps # готовность — haproxy (healthy): через LB можно обслужить запрос
make test # публичный smoke через LB на http://localhost:8080
make student_test # свой набор через LB, тесты реплик выполняются (EXPECT_REPLICAS = API_REPLICAS)
make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 сценария защиты)
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make replicas # вернуть остановленную реплику (те же ID) перед следующим прогоном failover
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин; полный — make bench_failover
make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной реплике с выводом из LB
make bench_rollout_quick # то же под нагрузкой на своём стенде с образа прежнего commit, ~2 мин; полный — make bench_rollout
make stop # остановить; make down — удалить контейнеры, volume с данными остаётся
make wipe_data # намеренно удалить учебные данные: только после ввода yes, только проект mtusi-lab3
```
Порт API на хосте один — у HAProxy (`127.0.0.1:${APP_OUT_PORT}`, 8080).
Число реплик — `API_REPLICAS` в `.env` (по умолчанию 2), разово —
`make replicas API_REPLICAS=N`. В консоли (`make run_dev`) — один
процесс без LB; свой набор против него — `make student_test
EXPECT_REPLICAS=1`.
Проверено на одном API без балансировщика (change
`instance-id-idempotency`): в настоящем `git clone` `docker build -t
mtusi-messenger:lab3 .` проходит без `.env` и `config.toml`; после
`make env_setup` на этом образе проходит smoke
(`evidence/tests/clean-clone.md`). Стенд с LB из настоящего `git clone`
(change `replicas-lb`): `make run_docker` сам создаёт `.env` и
`config.toml` и поднимает две реплики за HAProxy; на нестандартных
`APP_OUT_PORT`, `APP__PORT` и портах Postgres и Valkey проходят `make
test` и `make student_test` (`evidence/replicas/clean-clone-ports.md`). Удаление учебных данных — `make
wipe_data` с вводом `yes`, трогает только проект `mtusi-lab3`
(`evidence/tests/stand-lab3.md`).
## Архитектура и решения
TODO (этап 7): что перенесено из lab2 одним списком, транзакционные
границы сводно.
```
клиент → 127.0.0.1:APP_OUT_PORT → haproxy ──→ api (реплика 1) ──→ postgres (данные, сессии, ключи идемпотентности; volume)
└─→ api (реплика 2) ──→ valkey (кэш неизменяемых карточек чатов)
migrate (один раз на каждый up, до реплик) ──→ postgres
```
Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии и
ключи идемпотентности. Valkey — общий кэш, его отказ — обход в
Postgres. Реплики `api` одинаковы и взаимозаменяемы, порта на хосте у
них нет; единственная точка входа — HAProxy.
### Балансировщик и реплики (change `replicas-lb`)
**Почему Compose + HAProxy** (выбор подтверждён 2026-10-07, `PLAN.md`):
| Критерий | HAProxy | Nginx (бесплатный) | Traefik | Swarm |
|---|---|---|---|---|
| Активная проверка `/health/ready` с периодом | есть (`inter`/`fall`/`rise`) | нет: пассивная по живым запросам, активная — только в NGINX Plus | есть (healthcheck в labels) | healthcheck контейнера, грубее (`interval × retries`) |
| Новые реплики после `--scale` без правки конфига | DNS Docker (`server-template` + `resolvers`) | `server ... resolve` с 1.27.3 | через docker socket | встроено |
| Повтор только недошедшего запроса | `retry-on conn-failure` | по умолчанию POST не повторяется, если уже отправлен | retry middleware, семантику для POST надо проверять | повторов нет |
| Статистика по репликам (трек 1) | встроена (`/stats;csv`) | только общие счётчики | метрики Prometheus | нет |
| Лишние привилегии | нет | нет | docker socket — почти root на хосте | — |
| Переделка стенда лабы 2 | добавить сервис | добавить сервис | сервис и labels | `build` и `depends_on` не работают в `stack deploy`, migrate как job, образ доступен узлам |
Swarm на одном хосте ничего не даёт, а сборку образа и его доступность
узлам пришлось бы описывать отдельно. Цена HAProxy — свой язык
конфигурации и фиксированное число слотов `server-template` (8).
**Как устроено** (`infra/haproxy/haproxy.cfg`, HAProxy 3.4 LTS):
- реплики находятся через DNS Docker: имя сервиса `api` отвечает
адресами всех работающих реплик, HAProxy раскладывает их по 8 слотам.
Новая и пропавшая реплика видны за 1–2 с без перезагрузки LB;
- активная проверка `GET /health/ready` (200 — Postgres отвечает) раз в
секунду, `fall 2`, `rise 2`. Слот, получивший адрес из DNS, начинает
в `DOWN` (`init-state down`) и получает запросы только после
проверок: Docker регистрирует адрес при старте контейнера, раньше,
чем uvicorn слушает порт;
- `balance roundrobin`, без cookie и stick-table: запросы одной сессии
чередуются между репликами (`evidence/replicas/distribution.md`);
- повтор в LB — только `retry-on conn-failure`, `retries 2`,
`option redispatch 1` (каждый повтор — на другую реплику): запрос до
реплики не дошёл, повтор безопасен для любого метода. Оборванный или
долгий ответ не повторяется;
- ответы самого LB (502/503/504) — в формате ошибки контракта с `code`
`unavailable`, `request_id` = `X-Request-Id`, без `X-Instance-Id`
(`evidence/replicas/lb-errors.md`);
- статистика и `/lb/ready` — `frontend monitor` на `:8404`, только
внутри сети compose; оператору — `make lb_stats`. Healthcheck
контейнера LB — `/lb/ready`: 200, пока есть готовая реплика.
**Цепочка таймаутов** (change `graceful-failover`, design, решение 1;
числа — в `infra/haproxy/haproxy.cfg`, `config_example.toml`,
`docker-compose.yml`, `src/utils/constants.py`). От клиента к
PostgreSQL; «было» — до change:
| Звено | Значение | Было | Соотношение и почему |
|---|---|---|---|
| Клиент `tests/resilience.py` | 2 с | — | задан skeleton; всё, что LB делает при отказе соединения, укладывается раньше |
| Клиент k6 профиля `failover` | 15 с | — | > `timeout server`: клиент видит 504 от LB, а не свой таймаут |
| HAProxy `timeout client` / `http-request` | 30 / 10 с | — | соединения клиентов; на отказ реплики не влияют |
| HAProxy `timeout http-keep-alive` | 10 с | — | простаивающий сеанс клиента, а с `http-reuse never` — и его соединения с репликами; < keep-alive реплики (60 с) |
| HAProxy `http-reuse` | `never` | `safe` | соединение с репликой живёт не дольше сеанса клиента и не уходит в общий пул: простаивающее соединение закрывает LB, а не реплика (`evidence/failover/keep-alive.md`) |
| HAProxy `timeout connect`, `retries`, `redispatch` | 500 мс, 2, каждый повтор | — | 0,5 × 3 = 1,5 с < 2 с клиента. Живая реплика в сети Docker принимает соединение за доли миллисекунды; 500 мс ограничивают ожидание пропавшего адреса |
| HAProxy `timeout server` | 10 с | — | > `[database] request_timeout_seconds` (6 с) + KDF входа под лимитом 1 CPU (до 1,6 с) |
| HAProxy `inter` / `downinter` | 1 с / = `inter` | — | период проверок `/health/ready`, в том числе исключённой реплики |
| HAProxy `fastinter` | 500 мс | = `inter` | повторная проверка после первой неудачи и до возврата |
| HAProxy `fall` / `rise` | 2 / 2 | — | одна неудача — ещё не отказ; возврат — после двух успехов подряд |
| HAProxy `timeout check` | 2,5 с | 3 с | > таймаута `SELECT 1` внутри `/health/ready` (2 с) на 0,5 с: медленный PostgreSQL даёт 503 от реплики, а не таймаут проверки |
| Таймаут соединения проверки | 0,5 с | — | min(`timeout connect`, `inter`), правило HAProxy |
| `resolvers docker` `hold` | 1 с | — | пропавший адрес уходит из слота за 1–2 с |
| uvicorn `timeout_keep_alive` (`[app] keep_alive_seconds`) | 60 с | 5 с | > `timeout http-keep-alive` LB (10 с) |
| `/health/ready`: `SELECT 1` | 2 с | — | < `timeout check`; не меньше: проверка берёт соединение из общего пула, и заминка PostgreSQL вывела бы из LB все реплики разом |
| Пул: `pool_timeout` / `connect_timeout` | 5 / 3 с | — | < `request_timeout_seconds` |
| PostgreSQL `statement_timeout` | 5 с | — | < `request_timeout_seconds`: сервер прерывает долгую команду раньше, чем приложение рвёт соединение |
| Работа запроса с БД (`request_timeout_seconds`) | 6 с | — | < `timeout server` 10 с |
| PostgreSQL `idle_in_transaction_session_timeout` (`[database] idle_in_transaction_timeout_ms`) | 10 с | нет | > `request_timeout_seconds`: транзакция живого запроса дольше не живёт. Прерывает транзакцию замороженной реплики и снимает блокировку её ключа идемпотентности (`evidence/failover/hung-key.md`) |
| uvicorn `[app] graceful_shutdown_seconds` | 8 с | — | < `stop_grace_period` 10 с; запросы в полёте дорабатывают |
| `scripts/stop-one.sh` | `docker stop --timeout 9` | — | возврат hook < 10 с |
| compose `stop_grace_period` | 10 с | — | SIGKILL после graceful |
**Период проверок и время обнаружения.** Проверка `/health/ready`
раз в секунду. Следующая начинается через интервал после конца
предыдущей, а после первой неудачи — через `fastinter`. Худшее время
по проверкам:
| Режим | Как выглядит для проверки | Формула | Было | Стало |
|---|---|---|---|---|
| зависшая реплика (`docker pause`) | соединение принято, ответа нет | `inter` + `timeout check` + (`fall` − 1) × (`fastinter` + `timeout check`) | 8 с | **6,5 с** |
| адрес пропал (`docker stop` после выхода, `docker kill`) | таймаут соединения 0,5 с | `inter` + 0,5 + (`fall` − 1) × (`fastinter` + 0,5) | 3 с | **2,5 с** |
| сокет закрыт, адрес жив (окно graceful) | отказ соединения | `inter` + (`fall` − 1) × `fastinter` | 2 с | 1,5 с |
Остановленный контейнер ещё и пропадает из DNS Docker: слот уходит в
обслуживание за `hold` 1–2 с, действует то, что раньше. Возврат —
≤ `downinter` + `fastinter` = 1,5 с после готовности реплики. Замер
под нагрузкой по режимам — раздел «Эксперименты и отказы».
Остановленная реплика (`docker stop`) сразу закрывает приёмный сокет:
LB получает отказ соединения и перенаправляет запрос, клиент ошибок от
недоступности не видит. Убитая (`docker kill`) рвёт запросы в полёте:
LB отвечает 502, клиент повторяет с тем же ключом. Зависшая
(соединение есть, ответа нет) исключается проверками за ≤ 6,5 с, а
запрос, уже ушедший на неё, получает 504 через `timeout server` 10 с.
**Роли и сервисы** (`infra/README.md`):
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Порт на хосте | Credentials |
|---|---|---|---|---|---|---|
| load_balancer | `haproxy` | `haproxy:3.4.6-trixie@sha256:e2739156…` | `/lb/ready` (есть готовая реплика) | — | `127.0.0.1:${APP_OUT_PORT}` (8080) | нет |
| api × `API_REPLICAS` | `api` | образ из `Dockerfile` (`mtusi-messenger:lab3`) | `/health/ready` (healthcheck образа и проверки LB) | — | нет | `environment`: пароли Postgres и Valkey мостами из `.env` |
| миграции | `migrate` | тот же образ, `alembic upgrade head` | код выхода 0 | — | нет | пароль Postgres |
| postgres | `postgres` | `postgres:18.6-trixie@sha256:5a5a84b1…` | `pg_isready` по TCP | `postgres_data` | `127.0.0.1:${POSTGRES_OUT_PORT}` (консоль) | `POSTGRES_*` из `.env` |
| кэш | `valkey` | `valkey/valkey:9.1.2-trixie@sha256:418652cf…` | `valkey-cli ping` с паролем | нет (persistence выключен) | `127.0.0.1:${VALKEY_OUT_PORT}` (консоль) | `VALKEY_PASSWORD` из `.env` |
**Лимиты и соединения** (`deploy.resources.limits`, `evidence/replicas/stand.md`):
| Сервис | CPU | Память |
|---|---|---|
| `api` (на реплику) | 1.0 | 512M |
| `postgres` | 2.0 | 1G |
| `valkey` | 0.5 | 128M |
| `haproxy` (`nbthread 1`) | 1.0 | 256M |
| `migrate` | 0.5 | 256M |
При двух репликах — 6 CPU и 2,6 GiB из 12 CPU и 7,7 GiB ВМ Docker.
Соединения Postgres: `API_REPLICAS × (pool_size + max_overflow)` +
`migrate` = 2 × (10 + 5) + 1 = 31 ≤ `max_connections` 100; при 6
репликах — 91, при 7 — 106 > 100. Граница пула — гипотеза 3 трека 1.
На время поочерёдной замены реплик на одну больше (`API_REPLICAS` + 1):
3 × 15 + 1 = 46 соединений, 7 CPU и 3,1 GiB лимитов.
**Секреты по сервисам.** Пароль Postgres — `postgres`, `api`,
`migrate`; пароль Valkey — `valkey` и `api`; у `haproxy` секретов нет
(окружение — только `API_PORT`). Окружение собрано из якорей
`x-db-env` / `x-cache-env` в `docker-compose.yml`.
**Состояние процесса.** Просмотр `src/` (уровень модулей): в памяти
процесса только пул соединений Postgres, клиент Valkey с отметкой
«пропускать кэш после отказа» (`retry_after_seconds`), лимитер и
фиктивный хэш KDF, `instance_id` и логгер. От них не зависит
корректность ответа: сессии, данные и ключи идемпотентности — в
Postgres, карточки чатов неизменны, поэтому общий кэш не требует
инвалидации между репликами.
**Восстановление реплики** после `scripts/stop-one.sh`: `make replicas`
(`docker compose up -d --no-deps --no-recreate --wait --scale
api=$(API_REPLICAS) api`) — тот же контейнер запускается снова, LB
включает его после проверок.
### Обновление без простоя и миграции (change `rolling-update`)
Compose сам rolling update не делает (это `update_config` Swarm),
поэтому замена — свой скрипт `scripts/rolling-update.sh`, цель `make
rolling_update`. Сторонний плагин не используется: это была бы ещё одна
незакреплённая зависимость. Порядок (design `rolling-update`, решения
1–5):
0. **Предусловия** — ничего не меняют, иначе код 2 и подсказка `make
replicas`:
- работает ровно `API_REPLICAS` реплик, остановленных нет;
- все `UP` в LB;
- для ещё одной реплики есть слот (≤ 8);
- канал управления LB отвечает;
- нет слотов в ручном `drain` / `maint`, оставленных прерванной
заменой (их не видно в `make lb_stats`, скрипт читает `show servers
state`); иначе он печатает команду, которая вернёт слот в `ready`.
1. **Сборка образа** из рабочего дерева. `COMMIT=<commit>` — из файлов
commit через `git archive <commit> | docker build`, рабочее дерево не
трогается.
2. **Миграции — один раз**, в контейнере сервиса `migrate`, на новом
образе, до первой новой реплики. Ошибка (в том числе `lock_timeout`)
— код 1, реплики не тронуты.
3. **Одна новая реплика** рядом со старыми: `up -d --no-deps
--no-recreate --scale api=N+1 api`.
4. **Ожидание готовности новой:** `healthy` **и** `UP` в статистике LB
по её адресу. Слот получает адрес из DNS и начинает в `DOWN`, в
распределение попадает через ≤ 1,5 с проверок. Вывести старую по
одному `healthy` — значит на эти 1,5 с остаться с N − 1 репликами.
5. **Вывод старой из LB и удаление:**
- runtime API HAProxy: `drain` — новых запросов нет, начатые
дорабатывают;
- ожидание, пока запросов в полёте не станет 0 (≤ 12 с, больше
`timeout server`);
- `maint`, `docker stop` (graceful, ≤ 10 с; код выхода — в строке
скрипта), `docker rm`;
- когда адрес ушёл из слота — `ready`.
6. Шаги 3–5 для каждой старой реплики. В конце `API_REPLICAS` реплик
нового образа, все `UP`.
**Канал управления LB** — `stats socket ipv4@127.0.0.1:9999 level admin`
в `haproxy.cfg`. Он слушает только loopback контейнера LB. Из сети
compose и с хоста его не достать (`evidence/rollout/script-failures.md`,
случай 6), команды идут через `docker compose exec haproxy`. Страница
статистики `:8404` с `stats admin` не годится: она открыта всей сети
compose. Альтернатива — readiness 503 по SIGTERM — отвергнута:
- она меняет поведение остановки, после SIGTERM реплика ещё ≥ 1,5 с
принимала бы запросы;
- остановка удлиняется до 1,5 + 8 с — впритык к `stop_grace_period`;
- ломается срок `stop-one.sh`.
**Почему слот возвращается в `ready`.** Ручное состояние — свойство
слота, а не реплики. IPAM Docker сразу отдаёт адрес удалённой реплики
следующей, и DNS кладёт её в тот же слот. Это видно в замере: новая
реплика второго шага получила адрес и слот только что удалённой. Слот,
оставленный в `maint`, не пустил бы к ней ни одного запроса.
**Дренаж убирает одиночный 502** гонки keep-alive. Слот выведен, и LB
не отправляет запросов в соединения, которые uvicorn закрывает по
SIGTERM. Профиль `rollout` под 200 запросами в секунду — 0 ошибок
(раздел «Эксперименты и отказы»). `scripts/stop-one.sh` и профиль
`failover` дренаж не делают намеренно: они имитируют отказ, а не
плановую остановку.
**Сбой на середине.** Новая реплика не стала `UP` за срок или замену
прервали, пока она стартует (в том числе внутри `up --scale`, когда её
ID скрипту ещё не известен), — она удаляется. Её слот, если DNS уже
отдал его, сначала уходит в `maint`. Новая уже `UP` (в том числе при
Ctrl+C) — вывод текущей старой доводится до удаления. В любом исходе работает `API_REPLICAS` готовых
реплик, слоты без ручного состояния, повторный запуск доводит замену
(`evidence/rollout/script-failures.md`). Автоматического отката нет.
Откат — та же замена на образ прежнего commit без миграций: `make
rolling_update COMMIT=<commit> MIGRATE=0`.
**Миграции однократны и совместимы с работающей версией** (expand /
contract):
- ревизия только расширяет схему: новая таблица, колонка с NULL или
значением по умолчанию, индекс;
- удаление и переименование — отдельной поставкой, когда прежнего кода
не осталось.
Демонстрация — колонка `messages.instance_id` (`text NULL`, ревизия
`e656d6bbe1a4`): реплика, записавшая сообщение. Наружу она не
отдаётся, контракт не меняется:
- новый код её пишет, без неё упал бы, поэтому миграция обязана идти
до новых реплик;
- прежний код её не знает: вставляет свои колонки (NULL), читает свои.
Первой строкой ревизии — `SET LOCAL lock_timeout = '2s'`. `ADD COLUMN`
берёт `ACCESS EXCLUSIVE` на миллисекунды, но, пока ждёт блокировку, за
ним в очереди стоят все запросы к `messages`. Чужая долгая транзакция
без срока остановила бы запись всех реплик. Со сроком миграция падает
без изменений, замена не начинается, повтор проходит. Срок меньше
`statement_timeout` приложения (5 с): запросы из очереди дожидаются
отказа миграции и выполняются. В apply срок был 5 с, равный
`statement_timeout`, и verify поймал цену: под нагрузкой все 6 запросов,
вставших в очередь, получили 503 вместе с отказом миграции; с 2 с — 0
ошибок, задержка до 2 с (`evidence/rollout/script-failures.md`).
Проверено на рабочем стенде с итогового commit `84161c0`
(`evidence/rollout/compatibility.md`):
- реплики образа `c50b721` (до change) на схеме после новой миграции
проходят `make test` и `make student_test` (131 passed);
- `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0` и снова
вперёд — под `tests/load.py`, 0 неуспешных запросов из 16–21 тысячи на
каждый прогон; старые реплики после дренажа завершаются за 0,1 с с
кодом 0;
- по колонке видно, какая версия записала каждое сообщение;
- после замен (реплики `api-7`, `api-8` и дальше) работают `make
instances`, `make test-failover` в режимах `stop` и `kill`, `make
replicas`, `make test-persistence`, `make run_docker` поверх
заменённых реплик и `make down` + `make run_docker`; две замены подряд
не оставляют слотов LB с ручным состоянием, свободных слотов — те же
6 из 8.
**`make run_docker` и пересборка.** Пункт `KNOWN_ISSUES.md` «не
пересоздаёт работающие `api`» не воспроизвёлся
(`evidence/rollout/compatibility.md`, шаг B и шаг 6 жизненного цикла):
- compose пересоздаёт реплики, у которых изменилось содержимое образа,
— все разом, с простоем;
- пересборка без изменений кода реплики не трогает.
Хранилище образов Docker Desktop — containerd, и `docker ps`
показывает у реплик digest конфигурации образа, а не имя тега. Отсюда
была ошибка диагностики. Обновление без простоя — `make rolling_update`.
### Стенд лабы 3
Проект compose — `mtusi-lab3`, образ — `mtusi-messenger:lab3`. Имя
проекта задаёт имена volumes: с именем второй лабы стенд подключился бы
к её базе. Данные второй лабы не переносились (они синтетические), volume
`mtusi-lab2_postgres_data` не затронут, в том числе `make wipe_data`
этого стенда (`evidence/tests/stand-lab3.md`).
### `X-Instance-Id`
- Значение — `[app] instance_id`. Пусто (по умолчанию) — hostname
процесса, определённый один раз при загрузке настроек; в compose это
короткий ID контейнера, то есть то, что показывает
`docker compose ps -q api`. По нему `scripts/stop-one.sh` найдёт
контейнер без таблицы соответствия.
- Значение не задаётся ни в `config.toml`, ни в `.env`, ни в compose
(`environment`, `hostname:`): эти источники общие у реплик, а значение
должно различаться. В консоли его можно заменить `APP__INSTANCE_ID`.
Формат проверяется при старте (`[A-Za-z0-9._-]{1,64}`): с `api a`
сервис не стартует (`evidence/idempotency/config-checks.md`).
- Заголовок ставит то же ASGI-middleware, что `X-Request-Id`; ответ 500
собирает `ServerErrorMiddleware` снаружи него, поэтому обработчик
`Exception` ставит оба заголовка сам. То же значение — поле
`instance_id` в каждой записи журнала, включая старт и shutdown
(`evidence/idempotency/instance-id.md`).
- `docker restart` сохраняет hostname, и значение остаётся прежним;
новый контейнер — новое значение. В лабе 7 поле получит непрозрачный
alias вместо hostname.
### Идемпотентность отправки сообщения
Таблица `idempotency_keys` (миграция `7652184b7016`, только добавляет
таблицу): первичный ключ `(user_id, chat_id, key)` — область ключа
контракта «пользователь + метод + путь чата + ключ», ключ принимает одна
ручка; внешний ключ `(chat_id, user_id) → chat_members`; `message_id →
messages` с проверкой на commit (`DEFERRABLE INITIALLY DEFERRED`);
SHA-256 тела; `created_at` с индексом; `CHECK` формата и длины ключа.
Отправка (`MessageService.send_message`) — одна транзакция:
1. Сессию проверила зависимость (401), сервис проверяет членство (404) —
и при повторе тоже.
2. Захват ключа одним выражением: `INSERT … ON CONFLICT (user_id,
chat_id, key) DO UPDATE … WHERE created_at < now − ttl RETURNING`.
Строка вернулась — ключ свободен (новый или просроченный, заменён тем
же выражением): вставка сообщения, `commit()`.
3. Ключ занят — чтение сохранённого хэша и сообщения, `commit()` (снять
блокировку строки). Хэш совпал — тот же 201 и то же `Message` из БД;
не совпал — 409 `conflict`.
Почему это корректно, в том числе между репликами (READ COMMITTED):
одновременная вставка того же ключа ждёт commit или отката чужой
транзакции на уникальном индексе. После commit — конфликт и сохранённый
результат, после отката — вставка проходит, то есть транзиентная ошибка
результатом не фиксируется. Ключ вставляется раньше сообщения, поэтому
повтор не пишет и не откатывает сообщение. Любая ошибка до commit
откатывает и ключ, и сообщение (`evidence/tests/failure-checks.md`:
сбой вставки сообщения, остановка Postgres).
«То же тело» — SHA-256 канонического JSON, собранного из разобранного
тела (сортированные ключи, значения по умолчанию подставлены): пробелы,
`\u`-экранирование и порядок полей на сравнение не влияют, другой текст
— другой хэш. В журнале ключа нет: повтор виден по `"replayed": true` и
тому же `message_id`.
Порядок кодов при нескольких ошибках — 401 → 400 → 404 → 409.
`Idempotency-Key` объявлен параметром ручки (есть в `/openapi.json`),
а FastAPI проверяет параметры после зависимостей: без сессии — 401,
затем нет ключа или неверное тело — 400, затем не участник — 404,
затем другое тело — 409. Битый JSON — 400 раньше 401. Это то самое
расхождение порядка кодов FastAPI, согласованное с преподавателем
2026-09-26 (AGENTS.md, «Согласования с преподавателем»); smoke его не
затрагивает, порядок закреплён тестами `test_idempotency.py`.
### Соответствие переменных `.env.example`
| Имя skeleton | Где у нас | Почему так |
|---|---|---|
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | значение читает только приложение; как `SESSION_TTL_SECONDS` (`.claude/rules/settings.md`). Срок меньше 86400 нарушает контракт и применяется только в проверках (2 с у «тесного» API стенда отказов) |
| `API_REPLICAS` | `API_REPLICAS` в `.env` (шаблон — 2), `deploy.replicas: ${API_REPLICAS:-2}` сервиса `api`; Makefile — `API_REPLICAS ?= 2` (`make replicas`, `EXPECT_REPLICAS` тестов). Разово — `make replicas API_REPLICAS=N` | приложение его не читает, поэтому имя без секции; без строки в `.env` действует 2 (`.claude/rules/settings.md`) |
TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` через LB на стенде `make run_docker`; `make test_isolated` (образ из `a4ca9ef`, временная база, один контейнер): `make test` + `make student_test EXPECT_REPLICAS=1`; `make test` через LB стенда из настоящего `git clone` на нестандартных портах | `PASS: lab3 public API scenario` во всех трёх; в изоляции 127 passed, 4 теста реплик пропущены с причиной «one API process»; сверка покрытия: 135 сценариев, 123 тестом, 12 исключений | `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated.md`, `evidence/replicas/clean-clone-ports.md` |
| «3»: стенд одной командой, ≥2 API, одна точка входа, общие БД и сессии | `make run_docker` (рабочий стенд и настоящий `git clone`); `docker compose ps`, `docker port`, `docker compose config` | `haproxy` — единственный порт API на хосте (`127.0.0.1:8080`), `api` × 2 без портов и `container_name`; общие Postgres (сессии, данные, ключи) и Valkey; миграции — один прогон `migrate` на каждый up, в журналах реплик `alembic` нет; из клона стенд поднимается одной командой, `.env` и `config.toml` создаются сами | `evidence/replicas/stand.md`, `evidence/replicas/clean-clone-ports.md` |
| «3»: разные запросы одного пользователя — разными репликами без повторного входа | `make instances` (один вход, 12 × `GET /users/me` с одним токеном); `test_load_balancing.py` | ответы чередуются `3681880fc55f` / `8100f940a5fa` по 6; 20 запросов сессии — по 10; запись через одну реплику видна в чтениях через другую | `evidence/replicas/distribution.md`, `evidence/tests/student-test-lb.md` |
| «3»: отказ любой одной реплики — ≤10 с до новых чтений и записей; `make test-failover` | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для каждой реплики, `make replicas` и сдвиг очереди round-robin одним запросом между прогонами; `STOP_ONE_LOG` — какой `TARGET_INSTANCE_ID` выбрал тест; `docker compose ps -a` и `StartedAt` до и после | 2 × `PASS`: остановлены `8100f940a5fa`, затем `3681880fc55f`; первая запись через 1,10–1,11 с, 0 неудачных попыток, по 2 запроса перенаправлены LB; ID остановленного контейнера = `TARGET_INSTANCE_ID`, остальные контейнеры с прежним `StartedAt`; через 20 с реплика всё ещё `exited`. С цепочкой таймаутов `graceful-failover` (commit `459f84c`) — снова `PASS` для каждой реплики: `stop` — 0 неудачных попыток, первая запись через 1,62 с; `kill` — 1 неудачная попытка (запрос в полёте), повторена с тем же ключом, первая запись через 0,23 с | `evidence/failover/test-failover.md`, `evidence/tests/graceful-failover-checks.md` |
| «3»: отказ процесса без graceful, реплика остаётся остановленной | `STOP_MODE=kill make test-failover …`; через 15 с `docker inspect`; `driver.py --port 8080 kill-inflight` (kill во время входов по Basic) | `PASS`, первая запись через 0,74 с; контейнер `exited` 137, `RestartCount` 0 через 15 с (`restart: unless-stopped` его не поднял); 3 входа в полёте — 502 от LB в формате контракта без повтора (`SH--`, повторов 0), 2 в момент kill — перенаправлены | `evidence/failover/test-failover-kill.md` |
| «3»: `make test-persistence` с LB | `make test-persistence ACTION_SCRIPT=scripts/restart.sh`; `StartedAt` до и после | `PASS` за 6,4 с; перезапущены LB, обе реплики, Postgres и Valkey (те же ID, новый `StartedAt`), volume с прежней датой создания | `evidence/replicas/test-persistence.md` |
| «3»: повтор `POST` с тем же ключом при переключении реплики | `test_idempotency.py::test_replay_on_other_replica` через LB | отправка через `8100f940a5fa`, повтор через `3681880fc55f` — тот же JSON; другое тело — 409 от обеих реплик | `evidence/tests/student-test-lb.md` |
| Failover hook не трогает чужое | `scripts/stop-one.sh` с пустым, не-hex, коротким ID, ID Postgres / Valkey / LB / `migrate`, несуществующим, контейнером `mtusi-lab2`, `STOP_MODE=pause` | код 2 (неверное значение или режим, до вызова docker) или 3 (нет такой работающей реплики); состояние и `StartedAt` всех контейнеров не изменились | `evidence/failover/stop-one-refusals.md` |
| «4»: лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name` | `docker inspect` (`NanoCpus`, `Memory`), `docker port`, имена переменных из `docker compose config` | лимиты у всех 6 контейнеров; порт API только у LB; пароль Valkey только у `valkey` и `api`, у LB секретов нет; `container_name` нет. Цена лимита 1 CPU для Argon2id измерена (раздел «Ограничения») | `evidence/replicas/stand.md` |
| «4» (часть): LB исключает недоступный backend; период проверок | `make lb_stats`, `docker compose logs -t haproxy`; все реплики остановлены; одна реплика заморожена `docker pause`; PostgreSQL остановлен | период 1 с, `fall 2`, `rise 2`, `timeout check` 3 с; остановленные реплики `DOWN` / в обслуживании, вернувшиеся — после проверки; зависшая — `DOWN` через 7,7 с (формула худшего случая — 8 с), запрос в полёте — 504 в формате контракта; без PostgreSQL обе реплики отвечают на проверку 503 и исключаются за 1,2–1,8 с; без реплик LB отвечает 503 в формате контракта, healthcheck LB `unhealthy`. Замер обнаружения по режимам под нагрузкой — строка ниже (change `graceful-failover`; `timeout check` с тех пор 2,5 с и `fastinter 500ms`) | `evidence/replicas/lb-errors.md`, `evidence/failover/test-failover.md` |
| «4»: health/readiness, таймауты и прекращение приёма при SIGTERM согласованы; период проверок и максимальное время обнаружения | таблица цепочки таймаутов (раздел «Балансировщик и реплики»); `make bench_failover FAILOVER_LABEL=baseline` (commit `459f84c`, хост проверен); `driver.py --port 8080 idle-conns`; `driver.py --port 8080 hang-key`; запуск с неверными сроками | проверка раз в 1 с, `fastinter` 0,5 с, `fall 2`, `rise 2`, `timeout check` 2,5 с > 2 с готовности; худшее обнаружение — 2,5 с для остановленной и убитой реплики, 6,5 с для зависшей (было 8 с). Замер под нагрузкой: `stop` и `kill` — 0,79–1,81 с, `pause` — 5,83–6,00 с; возврат в LB — 1,2–1,8 с. Простаивающие соединения с репликами закрывает LB через 10,1 с (keep-alive реплики 60 с > `timeout http-keep-alive` 10 с, `http-reuse never`). Отвергнутый вариант — пул LB (`http-reuse safe`) при том же keep-alive 60 с — переснят на закоммиченном коде временным вторым HAProxy с одной изменённой строкой: последнее соединение закрыла реплика через 60,4 с. Транзакцию замороженной реплики PostgreSQL прерывает через 10 с простоя: повтор того же ключа — 201, одно сообщение; временный триггер сценария удаляется и при Ctrl+C или SIGTERM. Неверные сроки — сервис не стартует | `evidence/failover/detection.md`, `evidence/failover/keep-alive.md`, `evidence/failover/hung-key.md`, `evidence/failover/baseline/` |
| «4»: последовательная остановка каждой реплики с восстановлением предыдущей: RPS, ошибки, время восстановления | `make bench_failover FAILOVER_LABEL=baseline`: 100 записей с ключом и 100 чтений в секунду, каждая из двух реплик в режимах `stop`, `kill`, `pause`, возврат через 20 с | 6 фаз. `stop` и `kill`: ~200 успешных ответов в секунду всё время, 0 ошибок, восстановление 0 с, всплеск p95 до 505 мс в секунду действия. `pause`: 602 и 584 ответа 504 (половина запросов ~6 с до исключения), доля успешных 0,5, восстановление 6 с. После возврата ошибок нет. Неуспешные записи повторены с тем же ключом: сообщений 30 005 = ключей 30 005, одинаковых текстов нет | `evidence/failover/baseline/summary.md`, `evidence/failover/detection.md` |
| Регрессия на итоговом commit `graceful-failover` | `make test`, `make student_test` через LB, `make test-persistence`, `make test-failover` (`stop` и `kill`), `make test_isolated`, `make failure_checks`, `make bench_quick`, `make bench_restore_quick`, `make bench_failover_quick` | всё код 0: 131 passed через LB; 127 passed и 4 пропуска с причиной в изоляции; 15 проверок отказов; профили лабы 2 на стенде с HAProxy и одной репликой; быстрый профиль отказа — 4 фазы, сверка сошлась | `evidence/tests/graceful-failover-checks.md` |
| Масштабирование без правки LB | `make replicas API_REPLICAS=3`, затем `make replicas` | третья реплика в распределении через 2 с без правки `haproxy.cfg`; обратно — две | `evidence/replicas/distribution.md` |
| Порты из `.env` со стендом за LB | настоящий `git clone`, `make run_docker` во временном проекте с `APP_OUT_PORT=18090`, `APP__PORT=9090`, портами Postgres и Valkey 5544 / 15545 и 6390 / 16391 | реплики слушают 9090, LB проверяет их на 9090 (`L7OK`), API на хосте — только через LB на 18090; `make test` и `make student_test` (131 passed) через LB | `evidence/replicas/clean-clone-ports.md` |
| Тесты реплик не выдают пропуск за успех | `make student_test` против одного процесса без `EXPECT_REPLICAS=1` | 4 теста реплик падают с `saw 1 X-Instance-Id … EXPECT_REPLICAS=2`, остальные 127 проходят | `evidence/tests/student-test-lb.md` |
| Свои стенды на новом compose | `make test_isolated`, `make failure_checks`, `make bench_quick`, `make bench_restore_quick` | все код 0; рабочий стенд не тронут; лимиты в паспорте `bench` те же, что до change | `evidence/tests/test-isolated.md`, `evidence/tests/failure-checks.md`, `evidence/tests/bench-self-checks.md` |
| «3»: повтор `POST` с тем же `Idempotency-Key` не создаёт дубль | разовый HTTP-скрипт: отправка, повтор, повтор в `\u`-записи | все 201 с одинаковым JSON, в истории одно сообщение | `evidence/idempotency/replay.md` |
| «3»: другое тело с тем же ключом, нет и неверный ключ | тот же скрипт | 409 `conflict`; 400 без ключа и с `a b`, значение ключа в ответ не попадает; постороннему — 404, ключ у другого пользователя — новое сообщение | `evidence/idempotency/replay.md` |
| «3»: повтор через другой процесс API | отправка, `docker compose up -d --force-recreate api`, повтор с тем же ключом и токеном | новый контейнер и `X-Instance-Id`, тот же `Message` (тот же `id` и `created_at`) | `evidence/idempotency/replay-after-restart.md` |
| «3»: ключ переживает рестарт API и хранилищ | отправка, `scripts/restart.sh` (api, Postgres, Valkey без удаления volumes), повтор с тем же ключом и токеном | новый `StartedAt` у всех трёх; повтор — 201 и тот же `Message`, другое тело — 409, в чате одно сообщение | `evidence/idempotency/replay-after-storage-restart.md` |
| «3»: неподтверждённую запись можно повторить; сбой не занимает ключ | `make failure_checks`: триггер роняет вставку сообщения после вставки ключа; остановка Postgres | 500 / 503, затем повтор с тем же ключом — 201, ровно одно сообщение | `evidence/tests/failure-checks.md` |
| Срок ключа | `make failure_checks`, «тесный» API с `IDEMPOTENCY__TTL_SECONDS=2` | в пределах срока другое тело — 409, после срока — 201 и новое сообщение | `evidence/tests/failure-checks.md` |
| Настройки `instance_id` и срока ключа | API в консоли с `APP__INSTANCE_ID=api-a`; запуск с `APP__INSTANCE_ID="api a"`, `IDEMPOTENCY__TTL_SECONDS=abc` и `0` | `X-Instance-Id: api-a` и `instance_id` = `api-a` во всех 14 записях журнала; недопустимые значения — код 1 до старта, ошибка называет поле | `evidence/idempotency/config-checks.md` |
| «4»: идемпотентность под параллельными запросами с одним ключом | `test_race.py::test_same_key_through_replicas` через LB: 10 клиентов за `threading.Barrier`, одно тело и один ключ | 10 × 201 с одним `Message`, одно сообщение в истории; ответы обеих реплик (5 + 5), есть пара пересекающихся по времени запросов разных реплик; то же на стенде из клона. Против одного процесса — `test_same_key_at_once` | `evidence/tests/student-test-lb.md`, `evidence/replicas/clean-clone-ports.md`, `evidence/idempotency/keys-table.md` |
| `X-Instance-Id` на каждом ответе, `instance_id` в журнале | тесты `api-conventions`, `curl`, `docker compose logs api` | заголовок у 2xx, 4xx, health, 404, 405, 500; значение = короткий ID контейнера; 85 из 85 записей журнала с `instance_id`, включая старт и shutdown; ключей и текста в журнале нет | `evidence/idempotency/instance-id.md` |
| Стенд лабы 3 не трогает данные лабы 2 | `make run_docker`, `make wipe_data`, снова `make run_docker`; `docker volume inspect` до и после | `wipe_data` удалил только контейнеры, сеть и volume `mtusi-lab3`; `mtusi-lab2_postgres_data` с прежней датой создания | `evidence/tests/stand-lab3.md` |
| Сборка из чистого clone | `git clone`, `docker build -t mtusi-messenger:lab3 .` до `make env_setup`; стенд на этом образе, `make test` | сборка без `.env` и `config.toml`, в образе их нет, процесс от UID 10001; `PASS: lab3 public API scenario` | `evidence/tests/clean-clone.md` |
| Стенд `bench/`: отправки с ключом при восстановлении | `make bench_restore_quick` (самопроверка, не замер) | 1000 отправок во время backup на каждом размере, 0 неудачных; сообщений в исходной базе = подтверждённых отправок; сверка баз прошла | `evidence/tests/bench-restore-quick.md` |
| «4»: rolling update (поочерёдная замена) проверен под нагрузкой | `make bench_rollout ROLLOUT_LABEL=baseline` (commit `9dcea0b`, код `de654a1`, хост проверен, рабочий стенд остановлен): 100 записей с ключом и 100 чтений в секунду, две реплики образа `c50b721` заменяются на образ текущего checkout тем же `scripts/rolling-update.sh`; на рабочем стенде (итоговый код `84161c0`) — `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0`, снова вперёд и две замены подряд под `tests/load.py`; быстрый профиль `make bench_rollout_quick` на `84161c0` | замена 8,9 с; **0 ошибок** из 24 002 запросов, доля успешных 1,0 в каждой секунде, p95 5 → макс. 11 мс; по шагам: новая `UP` в LB через 2,0–2,1 с после старта, дренаж старой 0,14–0,16 с, остановка 0,3–0,4 с; после вывода из LB старая не получила ни одного запроса; сообщений 12 001 = ключей 12 001. Рабочий стенд: 0 неуспешных из 21 043 / 16 687 / 18 480 / 27 278 запросов `tests/load.py`; старые реплики завершаются за 0,1 с с кодом 0 («Finished server process»); контейнеров прежних реплик после замены нет. Быстрый профиль на итоговом коде: замена 8,1 с, 0 ошибок, 7 301 = 7 301 | `evidence/rollout/baseline/summary.md`, `evidence/rollout/compatibility.md`, `evidence/tests/rolling-update-checks.md` |
| «4»: миграции однократно и совместимы с работающей версией | реплики образа `c50b721` + миграция нового образа в контейнере сервиса `migrate` (команда скрипта), без замены; `make test`, `make student_test`; замена; `SELECT instance_id, count(*)` по сообщениям; миграция под чужой блокировкой и нагрузкой | новая ревизия `e656d6bbe1a4` (колонка `messages.instance_id`, NULL) при прежних репликах: `PASS`, 131 passed; запись прежней версии — NULL, новой — её `X-Instance-Id`; при замене одна миграция в контейнере `migrate` до первой новой реплики, в журналах реплик alembic нет; повторный запуск — no-op; откат кода без отката схемы (после отката `migrate` прежнего образа падает на новой ревизии — ограничение, описано); под чужой транзакцией `lock_timeout` 2 с → миграция падает с кодом 1, схема и реплики не тронуты, 6 запросов из очереди за ней — успешны за 2,0 с (с 5 с в apply — все 6 получили 503), повтор проходит | `evidence/rollout/compatibility.md`, `evidence/rollout/script-failures.md` |
| Замена при сбое и неготовом стенде | остановленная реплика, `API_REPLICAS=3`, слоты в ручном `maint` / `drain`, `ROLLOUT_READY_TIMEOUT=1`, настоящий Ctrl+C (^C в псевдотерминал под `make`) во время дренажа и внутри `up --scale` под нагрузкой, порт 9999 LB из сети и с хоста | код 2 до сборки (для слотов — с командой возврата в `ready`); неготовая новая реплика удалена, работают 2 реплики `UP`; Ctrl+C во время дренажа — вывод старой доведён до удаления, внутри `up --scale` — новая реплика найдена и удалена (до исправления в verify оставалась третья реплика), 0 неуспешных запросов, повтор довёл замену; слоты LB без ручного состояния; канал управления LB из сети и с хоста — отказ соединения | `evidence/rollout/script-failures.md` |
| `make run_docker` после пересборки | реплики на образе прежнего commit, `docker compose build api`, `docker compose --dry-run up -d`; `make run_docker` поверх заменённых реплик | compose пересоздаёт реплики с изменившимся образом, без изменений — не трогает (те же ID); пункт `KNOWN_ISSUES.md` не воспроизвёлся и закрыт | `evidence/rollout/compatibility.md` |
| Регрессия на итоговом коде `rolling-update` (`84161c0`) | `make test`, `make student_test`, `make instances`, `make test-failover` (`stop` и `kill`, обе реплики), `make replicas`, `make test-persistence`, `make run_docker`, `make down` + `make run_docker`, две замены подряд — на репликах после замены; `make test_isolated`, `make failure_checks`, `make bench_failover_quick`, `make bench_rollout_quick` | всё код 0 (131 passed через LB, 127 + 4 пропуска в изоляции, 15 проверок отказов, быстрые профили на чистом дереве); apply нашёл дефект шага миграций (контейнер `migrate` прежнего образа ломал `restart.sh`, исправлен в `de654a1`), verify — уборку при Ctrl+C внутри `up --scale` и `lock_timeout`, равный `statement_timeout` (`5e102e6`, `84161c0`) | `evidence/tests/rolling-update-checks.md`, `evidence/rollout/compatibility.md` |
| Выбранный трек 5, если заявлен | трек 1 «Цена масштабирования»: `make bench_scaling SERIES=a\|b\|pool\|ab` (`bench/run.py`, профили `scaling_*`), методика и гипотезы — раздел «Цена масштабирования (трек 1)» | гипотезы H1–H3 закоммичены до первой серии (`02fd3d8` старше меток); 4 метки на коде `712d245`, хост проверен, брака генератора нет | `evidence/bench/scaling-*/`, `evidence/plots/scaling/`, `evidence/tests/scaling-bench-checks.md` |
| «5», трек 1: 1/2/4 реплики при фиксированном суммарном CPU/RAM | `make bench_scaling SERIES=a`: 4 CPU / 2 ГиБ на приложение — 1 × 4, 2 × 2, 4 × 1, по 3 повтора на свежем стенде, открытая модель 70/20/10, поиск R* по SLO (p95 ≤ 200 мс, ошибок ≤ 1 %) | R* 630 (630–704), 1 101 (1 041–1 164), 1 819 (1 539–1 819) запросов/с; 1 × 4 ≈ 1 × 1 (0,95): один процесс занимает ≤ 1,00 ядра из 4 (посекундный максимум за серию), троттлинг 0 | `evidence/bench/scaling-a/summary.md`, `samples.csv` |
| «5», трек 1: серия с ростом ресурсов | `make bench_scaling SERIES=b`: 1…6 реплик по 1 CPU / 512 МиБ, PostgreSQL 2 CPU / 1 ГиБ, 3 повтора | R* 666 → 1 164 → 1 539 → 1 819 → 2 034 → 2 034; эффективность 1,00 → 0,51 | `evidence/bench/scaling-b/summary.md`, `evidence/plots/scaling/rstar-by-replicas.svg` |
| «5», трек 1: точка насыщения и почему рост реплик перестаёт помогать | `make bench_plots LABELS="scaling-a scaling-b"`; метрики ступени R*: CPU каждого контейнера и ВМ, PSI, PostgreSQL (`pg_stat_activity` по `wait_event`, commit, WAL), HAProxy | k_sat = 5 по правилу (R*(6) < 1,1 × R*(5)), но на границе разрешения сетки: в её пределах k_sat ∈ {4, 5}. Общий ресурс стенда не насыщен: PostgreSQL — 1,1 ядра из 2, ожидания WAL — 22 % активных (порог 30 %), блокировок нет; HAProxy — 0,25 ядра из 1, очередь 0; отказов пула нет, признак `pool` не сработал, но пул каждой реплики на R* заполнен до 15. Растёт цена запроса в CPU у всех компонентов вместе с занятыми ядрами ВМ (реплики ×1,91, PostgreSQL ×2,03, HAProxy ×2,24, k6 ×1,56 от k = 1 к 6; `host_cost` 2,12): предел задаёт хост, механизм удорожания этим замером не разделён | `evidence/plots/scaling/summary.md` (разделы «Точка насыщения», «Цена запроса и общие ресурсы на R*»), `evidence/bench/scaling-b/runs.csv` |
| «5», трек 1: граница пула | `make bench_scaling SERIES=pool`: 4 × 1 при `max_connections` 100 и 50 (пул 10 + 5 на реплику) | при 50 — «too many clients» в журнале PostgreSQL с 1 455/с, R* 1 539 (1 539–1 627) против 1 819 (1 720–1 819), разбросы не пересекаются; клиенту — **500** на измеренном коде `712d245` (серия снята до правки 53300); при 100 отказов нет, а за R* реплики отдают 503 после 5 с ожидания пула | `evidence/bench/scaling-pool/summary.md`, `raw/*-errors.log` |
| «5», трек 1: точка насыщения БД | `make bench_scaling SERIES=db`: 1, 2, 4 реплики по 1 CPU при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU, 3 повтора, код `95539a1`, хост проверен; лимит — по калибровке `db_quick` (design) | R* 630 → 1 101 → **931**: от 2 к 4 репликам R* падает на 15 %; на 984/с у 4 реплик PostgreSQL выбирает квоту (троттлинг 68 %, до 100 % выше), CPU на запрос 279 → 441 мкс, признаки `db_cpu` и `db_wal`; контроль при 2 CPU — 1 627. Рубрика: БД и пул — управляемыми опытами, LB не насыщен (≤ 0,30 ядра из 1), на дефолтах рост останавливает хост | `evidence/bench/scaling-db/summary.md`, `evidence/plots/scaling-db/` |
| Отказ PostgreSQL «too many clients» (53300) — 503, а не 500 | правка `68edc66` (`53300` в `UNAVAILABLE_SQLSTATES`); `make failure_checks`: hook `fill-connections` занимает все слоты `max_connections` и обрывает соединения API; проба тем же способом через LB на рабочем стенде | без правки — 500 `internal_error` (тест красный); с правкой — 503 `unavailable` в формате контракта с `X-Instance-Id` реплики за 3–4 мс, без `Retry-After` (в контракте он только у 429), в журнале API — `warning` «Database is unavailable»; после освобождения слотов — 200 без рестарта; 16 проверок отказов прошли | `evidence/storage/too-many-clients.md`, `evidence/tests/scaling-bench-checks.md` |
| «5», трек 1: исходные данные и графики | `make bench_plots`; таблицы меток | R* от числа реплик, p95 от интенсивности (лог. шкала, линия SLO), CPU по компонентам на R*; строка на ступень, на ячейку и посекундные отсчёты | `evidence/plots/scaling/*.svg`, `evidence/bench/scaling-*/runs.csv`, `searches.csv`, `samples.csv` |
| «5», трек 1: уровень шума для улучшения | `make bench_scaling SERIES=ab SCALING_LABEL=scaling-aa`; `make bench_compare BEFORE=scaling-b AFTER=scaling-aa`, `BEFORE=scaling-b AFTER=scaling-a` | шум между сессиями (B → A/A, тот же код `712d245`): 1 × 1 666 (666–704) → 704 (666–704), +5,7 % — одна ступень деления; 6 × 1 2 034 (1 923–2 034) → 2 034 (2 034–2 034), Δ в пределах одной ступени (< 5,7 %); разбросы пересекаются. Согласованность серий: 4 × 1 серии `a` и k = 4 серии `b` — 1 819 и 1 819. Для `scaling-improvement` `scaling-aa` как `AA` не годится: код после правки 53300 другой, A/A снимается заново | `evidence/compare/scaling-b__scaling-aa.md`, `evidence/compare/scaling-b__scaling-a.md` |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker stop` одной из двух реплик (`stop-one.sh`) во время записи раз в 0,1 с | закрытый сокет → отказ соединения → LB перенаправляет, ошибок нет | 0 неудачных попыток в 2 прогонах (по одному на реплику); по 2 отправки перенаправлены (`+1` в журнале LB), одна — через `timeout connect` 500 мс к пропавшему адресу | первая запись 1,10–1,11 с от старта hook; потерь и дублей нет (`evidence/failover/test-failover.md`) |
| `docker kill` реплики | запросы в полёте рвутся, LB их не повторяет; клиент повторяет с тем же ключом | при записи раз в 0,1 с в полёте не оказалось ни одной (0 ошибок); при входах по Basic (`driver.py kill-inflight`) 3 оборванных → 502 без повтора, 2 перенаправлены | первая запись 0,74 с; дублей нет; реплика не поднимается сама (`evidence/failover/test-failover-kill.md`) |
| `docker pause` одной реплики (зависла), до `graceful-failover` | проверка ждёт `timeout check` и исключает реплику не позже 8 с; запрос в полёте — 504 | `DOWN` через 7,7 с; запрос на ней — 504 в формате контракта через 10 с (`timeout server`), без повтора; после разморозки — `UP` через 1,1 с | 7,7 с до исключения; второй запрос сразу ушёл на живую реплику (`evidence/replicas/lb-errors.md`). С `graceful-failover` граница 6,5 с, замер — таблица ниже |
| реплика заморожена посреди отправки с ключом (`driver.py hang-key`) | ключ занят её транзакцией; PostgreSQL прерывает транзакцию через 10 с простоя, повтор того же ключа проходит | повтор через живую реплику — 503 по `statement_timeout` (ждёт блокировку), через замороженную — 504; через 12,1 с PostgreSQL прервал простаивающую транзакцию, следующий повтор — 201 | одно сообщение в чате, ключ и сообщение замороженной транзакции откатились (`evidence/failover/hung-key.md`) |
| остановка PostgreSQL | реплики отвечают 503 на `/health/ready`, LB исключает обе и отвечает 503 сам | первые ~2 с — 503 от API, затем 503 от LB на всё, включая `/health/live`; после запуска PostgreSQL обе реплики `UP` | 1,2–1,6 с после запуска PostgreSQL, без рестарта реплик и LB (`evidence/replicas/lb-errors.md`) |
| остановка всех реплик | LB отвечает 503 в формате контракта, healthcheck LB — `unhealthy` | так и есть; после `make replicas` — 200 через ~3 с | данные в Postgres не затронуты (`evidence/replicas/lb-errors.md`) |
| `scripts/restart.sh`: LB, обе реплики, Postgres, Valkey | данные и токен переживают рестарт | `PASS`; до прохождения проверок LB отвечал 503, реплики начинают в `DOWN` | 6,4 с на тест целиком; кэш пуст, данные целы (`evidence/replicas/test-persistence.md`) |
| `make rolling_update` под `tests/load.py` (4 клиента): вперёд, откат на `c50b721`, снова вперёд | новая реплика в LB до вывода старой, старая выводится из LB до SIGTERM — ошибок нет | 0 неуспешных из 21 043, 16 687 и 18 480 запросов (`84161c0`); замена 10–12 с; новая миграция при прежних репликах — `make test` и `make student_test` проходят | простоя нет; по `messages.instance_id` видно, какая версия что записала (`evidence/rollout/compatibility.md`) |
| миграция ждёт блокировку `messages` за чужой 20-секундной транзакцией, через LB идут запись и чтение | миграция сдаётся по `lock_timeout`, запросы в очереди за ней выполняются | `lock_timeout` 5 с (apply): все 6 запросов из очереди — 503 через 5,03 с (`statement_timeout` приложения 5 с истёк вместе с ним); 2 с (`84161c0`): 0 ошибок, те же 6 запросов — 2,01–2,02 с | схема и реплики не тронуты, повтор после конца транзакции прошёл (`evidence/rollout/script-failures.md`, случай 7) |
### Отказ каждой реплики под нагрузкой (change `graceful-failover`)
**Гипотеза** (design `graceful-failover`, решения 1–3):
- `docker stop` реплики не даёт ошибок от её недоступности: закрытый
сокет и пропавший адрес — отказ соединения, LB перенаправляет запрос;
- `docker kill` — то же, кроме запросов в полёте на убитой реплике: 502
без повтора LB;
- зависшую реплику (`docker pause`) LB исключает не позже 6,5 с, а до
этого половина запросов ждёт `timeout server` и получает 504;
- время восстановления до ≥ 99 % успешных в секунде — не больше
времени исключения, то есть ≤ 10 с во всех режимах;
- после повтора неуспешных записей с тем же ключом нет ни потерь, ни
дублей.
**Методика.** `make bench_failover FAILOVER_LABEL=baseline`
(`bench/run.py`, профиль `failover`; правила — `.claude/rules/bench.md`):
- стенд `mtusi-bench`: HAProxy 3.4.6 с тем же `haproxy.cfg`, две
реплики API по 1 CPU / 512 МиБ, PostgreSQL 2 CPU / 1 ГиБ, Valkey
0,5 CPU / 128 МиБ — лимиты рабочего стенда;
- k6 2.3.0 в сети стенда, через LB, открытая модель с постоянной
интенсивностью: 100 записей сообщения с `Idempotency-Key` и
100 чтений страницы истории (50 сообщений, чат из 1 000) в секунду;
- фаза — одна реплика в одном режиме: 15 с нагрузки, действие, 20 с,
возврат (`docker start` того же контейнера или `docker unpause`),
15 с. Порядок: `stop` реплики 1, 2, `kill` 1, 2, `pause` 1, 2;
- время — часы ВМ Docker: действие — событие Docker, исключение и
возврат — журнал HAProxy, запросы — отметки k6 при отправке; секунда
запроса — по отправке;
- после фазы неуспешные записи повторяются с тем же ключом до 201, затем
сверка в PostgreSQL: сообщений в чате записи = отправленных ключей,
разных текстов столько же.
Commit `459f84c`, чистое рабочее дерево. Хост: Docker Desktop 29.8.2,
macOS arm64, ВМ 12 CPU / 7,7 GiB; питание от сети, свободной памяти
56 %, посторонних контейнеров нет (рабочий стенд остановлен), выгрузки
в swap за прогон не было (`Swapouts` до и после одинаковы). Один прогон
на фазу: замер показывает поведение, а не распределение.
**Результат** (`evidence/failover/baseline/summary.md`,
`evidence/failover/detection.md`):
| Фаза | Исключение LB, с (граница) | Успешных в секунду в окне отказа, мин. | Ошибки в окне отказа | Мин. доля успешных в секунде | Восстановление ≥ 99 %, с | p95 успешных: до / макс. в окне, мс | Возврат в LB, с | Ошибки после возврата | Сверка: сообщений = ключей |
|---|---|---|---|---|---|---|---|---|---|
| `stop`, реплика 1 | 1,06 (2,5), DNS | 200 | 0 | 1 | 0 | 5 / 505 | 1,73 | 0 | 5 001 = 5 001 |
| `stop`, реплика 2 | 1,01 (2,5), DNS | 200 | 0 | 1 | 0 | 4 / 505 | 1,21 | 0 | 10 002 = 10 002 |
| `kill`, реплика 1 | 1,81 (2,5), DNS | 199 | 0 | 1 | 0 | 4 / 505 | 1,16 | 0 | 15 002 = 15 002 |
| `kill`, реплика 2 | 0,79 (2,5), DNS | 200 | 0 | 1 | 0 | 5 / 505 | 1,75 | 0 | 20 003 = 20 003 |
| `pause`, реплика 1 | 6,00 (6,5), проверки | 99 | 602 × 504 | 0,5 | 6 | 5 / 104 | 1,53 | 0 | 25 004 = 25 004 |
| `pause`, реплика 2 | 5,83 (6,5), проверки | 100 | 584 × 504 | 0,5 | 6 | 4 / 150 | 1,53 | 0 | 30 005 = 30 005 |
**Итог по гипотезе:**
- `stop` и `kill` — подтверждено, ошибок 0. Остановленную и убитую
реплику LB убирал по DNS через 0,79–1,81 с, раньше проверок. Цена —
задержка: запросы, назначенные на пропавший адрес, ждали `timeout
connect` 0,5 с и уходили на другую реплику (p95 505 мс в секунду
действия). Запросов в полёте на убитой реплике в этих двух фазах не
оказалось (p50 запроса — 3 мс). В самопроверках быстрого профиля —
1–2 ответа 502 на фазу `kill` и одиночный 502 в части фаз `stop`
(гонка keep-alive при SIGTERM, `evidence/failover/keep-alive.md`);
доля успешных и там не ниже 99 %.
- `pause` — подтверждено с ценой: 5,83–6,00 с до исключения при
границе 6,5 с, всё это время половина запросов получала 504 через
10 с, восстановление — 6 с. Во второй фазе все записи этих секунд
попали на замороженную реплику (записи и чтения идут вперемешку
поровну, round-robin чередует реплики). Зависшая реплика — самый
дорогой отказ: её не видно, пока не провалятся две проверки по 2,5 с.
- Возврат реплики — 1,2–1,8 с до `UP`, ошибок после возврата нет
(`init-state down`, два успеха проверки).
- Потерь и дублей нет: 240 и 584 неуспешные записи фаз `pause`
повторены с тем же ключом — 201, сообщений столько же, сколько ключей.
**Ограничения замера.** Один хост: генератор, LB, реплики и
PostgreSQL делят ВМ Docker. Один прогон на фазу. Интенсивность — около
половины потолка одной реплики, чтобы после отказа оставшаяся
держала всю нагрузку; на пределе мощности одной реплики отказ дал бы
ещё и ошибки перегрузки. Отказ узла, LB и PostgreSQL не воспроизводится
(«Ограничения»).
### Поочерёдная замена под нагрузкой (change `rolling-update`)
**Гипотеза** (design `rolling-update`, решения 2–4):
- клиент не видит ни одной ошибки, в том числе 502 гонки keep-alive из
профиля `failover`:
- новая реплика получает запросы только после `UP` в LB;
- старая выводится из LB раньше SIGTERM;
- в каждой секунде отвечают только реплики, которые сейчас в LB;
- после вывода старая не получает ни одного запроса;
- записи не теряются и не дублируются.
**Методика.** `make bench_rollout ROLLOUT_LABEL=baseline` (`bench/run.py`,
профиль `rollout`; `.claude/rules/bench.md`):
- стенд `mtusi-bench` с лимитами рабочего стенда, как у профиля
`failover`;
- реплики стартуют на образе `c50b721` (`git archive`, схема
`7652184b7016`);
- k6 — постоянная интенсивность, 100 записей с `Idempotency-Key` и
100 чтений истории в секунду;
- через 15 с — `scripts/rolling-update.sh` против проекта стенда: сборка
текущего checkout, миграция `e656d6bbe1a4`, замена обеих реплик;
- ещё ≥ 15 с нагрузки после замены;
- время — часы ВМ Docker: события контейнеров проекта (поток `docker
events`), журнал HAProxy, отметки k6;
- после прогона неуспешные записи повторяются с тем же ключом, затем
сверка в PostgreSQL.
Commit `9dcea0b` (код `de654a1`), чистое дерево. Хост: Docker Desktop
29.8.2, ВМ 12 CPU / 7,7 GiB, питание от сети, свободной памяти 52–53 %,
swap занят 920 МиБ, но выгрузки за прогон не было (`Swapouts` до и
после одинаковы). Посторонних контейнеров нет, рабочий стенд
остановлен. Один прогон.
Итоговый код change — `84161c0`: после замера verify поменял пути сбоя
скрипта (уборка при Ctrl+C, предусловие о слотах, код выхода в строке) и
`lock_timeout` миграции (2 с вместо 5 с). Порядок замены и то, что видит
клиент, они не меняют: `lock_timeout` действует только при чужой
блокировке, а в замере миграция получает её за миллисекунды. Поэтому
полный замер не переснимался; быстрый профиль на `84161c0` — замена
8,1 с, 0 ошибок, сверка 7 301 = 7 301
(`evidence/tests/rolling-update-checks.md`).
**Результат** (`evidence/rollout/baseline/summary.md`):
| Шаг | Новая: старт → `UP` в LB, с | Дренаж старой, с | Остановка старой, с | Шаг целиком, с | Ошибок | Запросов старой после дренажа |
|---|---|---|---|---|---|---|
| 1 | 2,08 | 0,16 | 0,42 | 3,21 | 0 | 0 |
| 2 | 2,03 | 0,14 | 0,33 | 3,13 | 0 | 0 |
- Замена целиком (от создания контейнера миграции до удаления последней
старой) — 8,9 с; сборка из кэша 0 с, миграция 2 с.
- Ошибок нет ни до, ни во время, ни после замены: 0 из 24 002
запросов. В каждой секунде 200 успешных, доля 1,0. p95 — 5 мс до
замены, максимум 11 мс во время.
- Ответы по версиям: первый ответ новой реплики — через 4,05 с,
последний ответ старой — 8,3 с. В секунду 4 — 114 старых и 86
новых, в секунду 8 — 20 и 180, с секунды 9 — только новые.
- Сверка: сообщений 12 001 = ключей 12 001, одинаковых текстов нет,
повторять было нечего.
**Итог по гипотезе:** подтверждено. В профиле `failover` `docker stop`
под той же нагрузкой давал одиночный 502 в части фаз. При плановой
замене с дренажём 502 нет ни одного: запрос в слот, выведенный в
`drain`/`maint`, LB не отправляет. Новая реплика вступает в работу через
~2 с после старта (`init-state down`, `rise 2`). Число реплик в LB не
опускается ниже двух.
**Ограничения замера.** Один хост, один прогон: замер показывает
поведение, а не распределение. Нагрузка — около половины потолка одной
реплики. Под нагрузкой выше потолка двух реплик третья на время замены
добавила бы CPU-конкуренцию. Сборка образа шла из кэша. Холодная сборка
займёт больше времени, но на шаги замены не влияет: она идёт до
миграции.
### Цена масштабирования (трек 1, change `scaling-bench`)
Уровень «5», трек 1 `README.md`. Гипотезы записаны и закоммичены до
первой серии (design `scaling-bench`, решение 10); результат каждой —
ниже, как получился.
**Гипотезы.**
- **H1. Фиксированный бюджет** (серия `a`, опора R*(1 × 1) — из серии
`b`: в серии `a` конфигурации 1 × 1 нет). При бюджете приложения
4 CPU / 2 ГиБ одна реплика 1 × 4 использует около одного ядра: один
процесс uvicorn, один поток event loop, GIL не даёт распараллелить
Python-код и в потоках executor. Поэтому R*(1 × 4) ≈ R*(1 × 1), а 2 × 2
и 4 × 1 растут почти пропорционально числу процессов, пока не упрёмся
в PostgreSQL, LB или хост.
- Предсказание: R*(1 × 1) ≈ 550–700/с; R*(1 × 4) / R*(1 × 1) — 0,9–1,15;
R*(2 × 2) ≥ 1,7 × R*(1 × 1); R*(4 × 1) ≥ 3 × R*(1 × 1) или признак
общего ресурса на 4 × 1.
- Механизм: CPU контейнера 1 × 4 по секундам на ступенях R* и выше —
около 1,0–1,2 ядра (`samples.csv`), троттлинг 1 × 4 около 0.
- Подтвердит — всё вместе: отношение в [0,9; 1,15]; посекундный
максимум CPU 1 × 4 ≤ 1,3 ядра, среднее на перегрузке ≤ 1,2; 2 × 2 ≥
1,7 × R*(1 × 1); 4 × 1 ≥ 3 × R*(1 × 1) или сработал признак `db_*` /
`pool` / `lb` / `host` / `host_cost`.
- Опровергнет — хотя бы одно: R*(1 × 4) ≥ 1,25 × R*(1 × 1) или CPU
1 × 4 ≥ 1,5 ядра на перегрузке (процесс параллелится, и `workers` —
не единственный способ занять бюджет); R*(2 × 2) < 1,5 × R*(1 × 1)
без признака общего ресурса.
- **H1б. Троттлинг 1 × 1.** p99 у 1 × 1 хуже, чем у 1 × 4, из-за
троттлинга CFS (квота 100 мс на период 100 мс). Наш разбор до
прогона: один поток не выбирает больше 100 мс за период, троттлинг
требует второго потока (executor, время ядра на сеть) или работы у
самой квоты. Вероятный исход — на 250 и 500/с троттлинг < 1 % периодов
(H1б опровергнется), на ступени R* — заметный.
- Подтвердит: на 500/с троттлинг 1 × 1 ≥ 1 % периодов и p99 1 × 1 >
p99 1 × 4, разбросы не пересекаются. Опровергнет: троттлинг < 1 %
или разбросы p99 пересекаются.
- **H2. Рост ресурсов** (серия `b`, k = 1…6 по 1 CPU, PostgreSQL 2 CPU /
1 ГиБ фиксирован). R*(k) растёт почти линейно, пока каждая реплика
упирается в свой CPU; рост останавливается, когда PostgreSQL выходит
на свой лимит CPU или на запись WAL и commit. Арифметика до прогона:
PostgreSQL тратит 0,3–0,45 мс CPU на запрос (калибровка `bench_quick`),
2 ядра кончатся около 4 500–6 500/с, то есть при k ≈ 7–9, а
производительных ядер у хоста 6. Поэтому сильна **конкурирующая
гипотеза H2-хост**: рост остановит хост раньше PostgreSQL (признак
`host_cost` — CPU реплики на запрос растёт при той же нагрузке на
реплику; `host` — задачи ВМ ждут CPU).
- Предсказание: эффективность R*(k) / (k × R*(1)) ≥ 0,85 при k ≤ 3;
k_sat ∈ {4, 5}; на k_sat + 1 — `host_cost` (или `host`) либо `db_cpu`,
вероятнее `host_cost`.
- H2 подтвердит: на k_sat + 1 (или k = 6 без k_sat) срабатывает
`db_cpu` или `db_wal`, а CPU реплики падает ниже 0,9 — реплики ждут
базу.
- H2 опровергнет: на k_sat + 1 CPU PostgreSQL < 1,4 ядра и нет `db_wal`
/ `db_lock` — причину называет другой признак (`host_cost`, `host`,
`lb`, `pool`); либо k_sat нет, и эффективность при k = 6 ≥ 0,8.
- **H3. Граница пула** (серия `pool`). Пул приложения — 10 + 5 = 15 на
реплику, пользователь приложения — суперпользователь (резерв
`superuser_reserved_connections` его не держит), сэмплер занимает 1
соединение. На дефолтах граница — k = 7, вне серии `b`; опыт — 4
реплики при `max_connections` 100 (61 ≤ 100) и 50 (61 > 50).
- Предсказание: при 100 отказов «too many clients» нет, на R* и выше
`pool_busy_share` > 0, `db_conn_replica_max` доходит до 15; при 50,
когда пулы вместе вырастают за 49 соединений, — отказы в журнале
PostgreSQL и 5xx клиенту, R*(50) < R*(100), разбросы не пересекаются.
По коду отказ даст 500 `internal`, а не 503: SQLSTATE 53300 нет в
`UNAVAILABLE_SQLSTATES` (`src/infra/db/errors.py`), а спек
`data-storage` требует 503.
- Подтвердит: при 50 есть отказы и ошибки ≥ 1 % на уровне, который при
100 проходит; R*(50) < R*(100) без пересечения; при 100 отказов нет.
- Опровергнет: при 50 отказов нет ни на одном уровне до нарушения SLO
— реплики упираются в CPU раньше, чем копятся соединения.
**H4. Пул без переполнения** (change `scaling-improvement`, design
решение 5). Записана после серий `scaling-bench` и до замеров «до/после»
этого change: коммит с H4 старше меток `scaling-db-aa`,
`scaling-db-before`, `scaling-db-nooverflow`.
- **Утверждение.** У насыщенного PostgreSQL рост реплик вредит из-за
переполнения пула (10 + 5). Под нагрузкой реплики открывают
соединения сверх 10, а каждое новое стоит PostgreSQL ~2,4 мс CPU и
реплике ~11 мс. База раньше уходит в троттлинг. Пул без переполнения
(10 + 0, дефолт `[database] max_overflow` 5 → 0) отодвигает этот
излом.
- **Механизм — откуда гипотеза** (пробы при выборе на `bbd6f65`, не
замер для отчёта; пробные метки в git не идут):
- исходники SQLAlchemy (`QueuePool._do_return_conn`): возвращённое
соединение закрывается, если в очереди пула уже `pool_size`
простаивающих. Соединения сверх 10 живут, только пока заняты, и при
спросе около 10 открываются снова и снова;
- `db_sessions_new` серий — прирост `pg_stat_database.sessions` за окно
20 с: на 250 и 500/с у k ≥ 2 — 3–4 (фон); на R* `scaling-b` — от 103
(k = 1) до 283 (k = 6); у 4 × 1 при 0,5 CPU (`scaling-db`) на R*
931/с — 12–24, на 984/с — 79–144, там же соединений 60 и CPU
PostgreSQL на запрос 412–496 мкс против 278–292 на 931/с;
- микропроба цены соединения (рабочий стенд, PostgreSQL 2 CPU, реплика
1 CPU, итерация — проверка сессии и страница истории через функции
repo): из пула с пингом при выдаче — 552–590 мкс CPU реплики и
130–138 мкс PostgreSQL; новое соединение на итерацию — 11 225–11 318
и 2 378–2 386 мкс. Почти вся цена реплики — SCRAM-SHA-256: asyncpg
считает PBKDF2 на 4 096 итераций циклом `hmac.new()` в потоке event
loop;
- проба основной ячейки 4 × 1 при 0,5 CPU (один повтор, пул задан
окружением): 10 + 5 — R* 931, на 1 041/с CPU PostgreSQL 482 мкс на
запрос и 51 новая сессия за окно; 10 + 0 — R* 1 164, ~300 мкс до
1 164/с и 3–4 новые сессии на всех ступенях; 15 + 0 — R* 1 041.
- **Предсказание для `4x1-pg0.5`** (основная ячейка):
- медиана R* 931 → 1 101–1 301 (+18…+40 %), не меньше двух ступеней
сетки (≥ 1 041);
- новых сессий за окно «после» — не больше 10 и на R*, и на первой
нарушившей ступени; «до» на первой нарушившей — не меньше 40;
- соединений на R* «после» — не больше 40;
- CPU PostgreSQL на запрос на R* «после» — не больше 330 мкс.
- **Предсказание для контроля `4x1-pg2`:** |Δ R*| меньше двух ступеней;
CPU реплик на запрос на 500/с у `4x1-pg0.5` и `4x1-pg2` — в пределах
±5 % (переоткрытия там нет и до изменения).
- **Какие ячейки снимаются.** Только основная `4x1-pg0.5` и контрольная
`4x1-pg2`, по 3 повтора, профиль `scaling_db4` (`SERIES=db4`; те же
поля, что у серии `db`) — у меток A/A, «до» и «после» одинаково.
`1x1-pg0.5` и `2x1-pg0.5` не снимаются: пользователь решил сократить
замеры (около 25 мин на метку вместо 50). Поэтому R*(4 × 1) «после»
сравнивается с R*(2 × 1) = 1 101 из `scaling-db` только как справка
(другая сессия), а не как критерий.
- **Порог — две ступени сетки:** R* «после» / R* «до» ≥ √1,25 ≈ 1,118
(шаг сетки после двух делений 1,25^¼ ≈ 5,7 %; 931 → 1 041 — ровно две
ступени).
- **Подтверждено**, если выполнено всё:
1. у `4x1-pg0.5` вывод `make bench_compare … AA=scaling-db-aa` —
«эффект», и медиана «после» ≥ медиана «до» × 1,118;
2. механизм по таблице «PostgreSQL на R* и первой нарушившей
ступени»: «после» новых сессий за окно ≤ 10 на обеих ступенях,
соединений на R* ≤ 40; «до» на первой нарушившей — ≥ 40 новых
сессий;
3. дрейфа сессии нет: CPU реплик на запрос на 500/с в пределах ±5 % у
`4x1-pg0.5` и `4x1-pg2`; шум A/A меньше двух ступеней.
Если контроль сдвинулся на две ступени и больше, а пункт 3 выполнен,
эффект основной ячейки засчитывается, а предсказание для контроля
опровергнуто. Пункт 3 не выполнен — дрейф сессии хоста, не
засчитывается ничего.
- **Опровергнет** — хотя бы одно: у `4x1-pg0.5` разбросы пересекаются,
Δ не больше шума A/A или меньше двух ступеней; переоткрытие «после»
не исчезло (механизм не тот).
**Методика** (`make bench_scaling SERIES=…`, `bench/run.py` профили
`scaling_*`, правила — `.claude/rules/bench.md`, раздел «Серии трека 1»):
- Хост: Apple M3 Pro, 6 производительных и 6 энергоэффективных ядер,
18 ГиБ; ВМ Docker — 12 vCPU, 7,75 GiB. CFS-лимиты к ядрам не
привязаны: при занятых больше 6 vCPU часть работы идёт на
энергоэффективных ядрах.
- Бюджет (сумма CPU стенда и генератора не больше CPU ВМ, иначе отказ
до стенда):
| Контейнер | CPU | Память |
|---|---|---|
| PostgreSQL | 2 | 1 ГиБ |
| HAProxy | 1 | 256 МиБ |
| Valkey | 0,5 | 128 МиБ |
| k6 | 2 | 1 ГиБ |
| сэмплер | 0,25 | 128 МиБ |
| **без реплик** | **5,75** | **2,5 ГиБ** |
| Серия | Конфигурации | Σ CPU |
|---|---|---|
| `a` | 1 × 4 / 2 ГиБ, 2 × 2 / 1 ГиБ, 4 × 1 / 512 МиБ | 9,75 |
| `b` | k × 1 / 512 МиБ, k = 1…6 | 6,75…11,75 |
| `pool` | 4 × 1 / 512 МиБ при `max_connections` 100 и 50 | 9,75 |
| `ab` | 1 × 1 и 6 × 1 (как в `b`) | 6,75 и 11,75 |
Серия `b` — до 6 реплик: при 7 сумма лимитов 12,75 CPU > 12 vCPU, и
лимит перестал бы быть гарантией.
- Профиль — открытая модель k6 (`k6/mixed.js`): 70 % — страница истории
(`limit=50`, курсор из пула) читаемого чата из 10 000 сообщений, 20 % —
отправка с новым `Idempotency-Key` в один из 10 чатов записи, 10 % —
`GET /users/me`. Вход по Basic — до ступеней.
- Ступень — один запуск k6: прогрев (15 с с нуля у первой ступени и
после паузы, иначе 5 с подъёма от прежнего уровня) и окно 20 с.
Сначала 250 и 500 запросов/с, затем поиск: начало — ступенька
`100 × 1,25^i` ≥ max(300 × реплик, пройденный фиксированный); подъём
до первой нарушившей (если нарушена первая — спуск), затем два деления
по среднему геометрическому. Разрешение — не грубее 6 %.
- SLO ступени: p95 успешных ≤ 200 мс и (ошибки + неполные страницы +
недосланные генератором) / запланированные ≤ 1 %. R* — наибольший
прошедший уровень поиска.
- Ячейка — конфигурация × повтор, 3 повтора, каждая на свежем стенде;
порядок — круги с перемешиванием (зерно 20261011). В отчёт — медиана
и min–max.
- Метрики ступени — посекундный сэмплер (cgroup каждого контейнера:
CPU, троттлинг, память; загрузка и PSI ВМ; статистика HAProxy;
PostgreSQL: соединения по репликам и `wait_event`, commit/s, WAL),
итог k6 по окну и распределение по `X-Instance-Id`. Узкое место
называется признаками с порогами, заданными до прогонов
(`THRESHOLDS` в `bench/scaling.py`): `app`, `db_cpu`, `db_wal`,
`db_lock`, `pool`, `lb`, `host`, `host_cost`, `generator`. После
коммита гипотез, но до первой серии, на самопроверках уточнены два
определения (design, «Найдено в apply»): `host_cost` — по наклону CPU
реплик от запросов в секунду, а не по CPU на запрос на 500/с, и
минимум 1 активного соединения для признаков ожиданий
(`db_active_min`). По исходному определению `host_cost` (CPU на запрос
на 500/с, `runs.csv`) отношения к 1 × 1 — 1,00 / 1,07 / 1,16 / 1,23 /
1,29 / 1,41 для k = 1…6: признак тоже растёт с k, вывод тот же.
- Точка насыщения k_sat серии `b` — наименьшее k ≤ 5, при котором
медиана R*(k + 1) < 1,1 × R*(k); причина — признак общего ресурса на
k_sat + 1, не сработавший на k_sat − 1.
**Метки и графики.** Серии сняты на commit с кодом приложения
`712d245` (метки — на последующих commit документов, `dirty: false`),
хост проверен перед каждой серией: питание от сети, свободно 49–55 %
памяти (паспорта, `host_state` в начале и в конце), посторонних контейнеров нет, рабочий стенд остановлен,
выгрузок в swap за серии 0 (`evidence/tests/scaling-bench-checks.md`,
раздел «Проверки хоста перед сериями»). Брака генератора нет ни в
одной ячейке: CPU k6 на вершине серии B — 0,7–0,8 ядра из 2, троттлинг
0.
| Метка | Серия | Ячеек | Время | Файлы |
|---|---|---|---|---|
| `scaling-a` | бюджет 4 CPU | 9 | 37 мин | `evidence/bench/scaling-a/` |
| `scaling-b` | рост 1…6 | 18 | 74 мин | `evidence/bench/scaling-b/` |
| `scaling-pool` | граница пула | 6 | 24 мин | `evidence/bench/scaling-pool/` |
| `scaling-aa` | A/A (1 × 1 и 6 × 1) | 6 | 21 мин | `evidence/bench/scaling-aa/` |
Сводная таблица и графики — `make bench_plots LABELS="scaling-a
scaling-b" PLOTS=scaling` → `evidence/plots/scaling/`:
`summary.md`, [R* от числа реплик](evidence/plots/scaling/rstar-by-replicas.svg),
[p95 от интенсивности, серия a](evidence/plots/scaling/p95-by-rate-a.svg),
[серия b](evidence/plots/scaling/p95-by-rate-b.svg),
[CPU по компонентам на R*](evidence/plots/scaling/cpu-by-component.svg).
Исходные данные — `runs.csv` (строка на ступень), `searches.csv`
(строка на ячейку), `samples.csv` (посекундные CPU, троттлинг и память
каждого контейнера и загрузка ВМ) и итоги k6 в `raw/` каждой метки.
**Результат: R* по конфигурациям** (медиана (min–max) трёх повторов,
`evidence/plots/scaling/summary.md`):
| Серия | Конфигурация | R*, запросов/с | R* / (k × R*(1 × 1)) | p95 / p99 на 500/с, мс | Предельный CPU реплик на запрос, мкс | host_cost |
|---|---|---|---|---|---|---|
| a | 1 × 4 | 630 (630–704) | 0,95 | 62,0 / 91,8 | 1 436 | 1,05 |
| a | 2 × 2 | 1 101 (1 041–1 164) | 0,83 | 3,2 / 5,5 | 1 766 | 1,29 |
| a | 4 × 1 | 1 819 (1 539–1 819) | 0,68 | 2,9 / 4,3 | 2 166 | 1,58 |
| b | 1 × 1 | 666 (666–704) | 1,00 | 54,1 / 87,7 | 1 370 | 1,00 |
| b | 2 × 1 | 1 164 (1 164–1 231) | 0,87 | 2,8 / 5,0 | 1 644 | 1,20 |
| b | 3 × 1 | 1 539 (1 539–1 539) | 0,77 | 2,7 / 4,1 | 1 918 | 1,40 |
| b | 4 × 1 | 1 819 (1 819–1 819) | 0,68 | 2,9 / 4,1 | 2 168 | 1,58 |
| b | 5 × 1 | 2 034 (1 923–2 034) | 0,61 | 2,9 / 4,2 | 2 463 | 1,80 |
| b | 6 × 1 | 2 034 (1 923–2 034) | 0,51 | 3,0 / 4,2 | 2 906 | 2,12 |
| pool | 4 × 1, `max_connections` 100 | 1 819 (1 720–1 819) | — | 2,9 / 4,2 | 2 198 | — |
| pool | 4 × 1, `max_connections` 50 | 1 539 (1 539–1 627) | — | 2,9 / 4,2 | 2 243 | — |
Предельный CPU на запрос — наклон CPU реплик от успешных запросов в
секунду по ступеням ячейки, прошедшим SLO (без постоянных расходов
реплики: проверки LB, простой event loop); host_cost — он же
относительно 1 × 1 серии `b`.
**Точка насыщения — k_sat = 5 по правилу решения 9** (R*(6) = 2 034 <
1,1 × R*(5) = 2 237), но на границе разрешения сетки. Прирост на
реплику: +75 %, +32 %, +18 %, +12 %, +0 %; эффективность падает с
первой же добавленной реплики (0,87 при k = 2). Разрешение поиска после
двух делений — шаг ≈ 5,7 %: истинный R*(4) лежит в [1 819; 1 923), R*(5)
— в [2 034; 2 151), и прирост 4 → 5 — от +6 до +18 % при пороге 10 %.
Один повтор 5 × 1 из трёх дал 1 923; будь таких два, правило дало бы
k_sat = 4. Поэтому в пределах разрешения **k_sat ∈ {4, 5}**. «+0 %»
между 5 и 6 значит |Δ| < 5,7 %: у k = 5 и k = 6 одно дерево поиска (L0 =
1 819, затем 2 274 нарушена, деления 2 034 и 2 151), и оба R* — в одной
ступени. Порог k_sat устойчиво не пройден только парой 5 → 6.
Предсказание H2 (k_sat ∈ {4, 5}) от этого не меняется.
Узкое место — по метрикам ступени R*: таблица ниже — раздел «Цена
запроса и общие ресурсы на R*» в `evidence/plots/scaling/summary.md`
(`make bench_plots`, медианы по повторам серии `b`; рост — к k = 1):
| k | CPU реплик на R*, ядер на реплику | CPU на успешный запрос на R*, мкс: реплики / PostgreSQL / HAProxy / k6 | Рост к k = 1 | Занято ядер ВМ | PSI CPU ВМ | CPU PostgreSQL, ядер из 2 | Соединений PostgreSQL | Ожидания WAL, доля активных |
|---|---|---|---|---|---|---|---|---|
| 1 | 0,97 | 1 440 / 266 / 55 / 219 | — | 1,8 | 0,4 % | 0,18 | 15 | 0 % |
| 2 | 0,97 | 1 654 / 324 / 60 / 229 | ×1,15 / ×1,22 / ×1,08 / ×1,05 | 3,3 | 0,9 % | 0,38 | 30 | 0 % |
| 3 | 0,97 | 1 886 / 390 / 69 / 247 | ×1,31 / ×1,47 / ×1,24 / ×1,13 | 4,6 | 1,7 % | 0,60 | 45 | 0 % |
| 4 | 0,96 | 2 106 / 432 / 81 / 272 | ×1,46 / ×1,62 / ×1,47 / ×1,24 | 5,8 | 3,4 % | 0,79 | 60 | 5 % |
| 5 | 0,95 | 2 332 / 495 / 97 / 310 | ×1,62 / ×1,86 / ×1,75 / ×1,42 | 7,1 | 6,6 % | 1,01 | 73 | 18 % |
| 6 | 0,93 | 2 754 / 540 / 124 / 342 | ×1,91 / ×2,03 / ×2,24 / ×1,56 | 8,1 | 11,6 % | 1,10 | 89 | 22 % |
**Почему рост реплик перестаёт помогать.** Каждая реплика на R* занята
своим процессом почти полностью (0,93–0,97 ядра, признак `app` у всех
конфигураций), а общий ресурс стенда — PostgreSQL, LB, пул — не
насыщен:
- PostgreSQL на k = 6 занимает 1,1 ядра из 2. Ожидания WAL — 15–28 %
активных соединений по повторам (медиана 22 %, порог признака 30 %),
блокировок нет. Крупнейший класс — прочие ожидания (`other`: Client,
IPC, Timeout и остальное; 0,35–0,9 соединения), их состав не
записывался: в `runs.csv` только сумма класса;
- HAProxy — 0,25 ядра из 1, очередь 0, ошибок соединения и ответа нет;
- пул: отказов нет, признак `pool` не сработал (`pool_busy_share`
≤ 0,1), но пул каждой реплики на R* заполнен до 15 соединений, а за
R* запросы ждут его до 5 с и получают 503 (серия `pool`, ниже).
Растёт другое: **цена того же запроса в CPU у всех компонентов сразу**.
От k = 1 к k = 6 запрос стоит репликам ×1,91, PostgreSQL ×2,03, HAProxy
×2,24, генератору ×1,56 CPU-времени, а на 250 и 500/с, где ВМ занята на
0,8–1,7 ядра, цена запроса у PostgreSQL от k не зависит (230–300 мкс).
HAProxy и k6 от кода приложения не зависят, а дорожают тоже. Значит,
дорожает не код и не база, а **секунда CPU хоста под нагрузкой**: чем
больше vCPU ВМ занято (1,8 → 8,1 из 12), тем меньше работы она даёт.
Механизм этим замером не разделяется. Один и тот же признак — рост CPU
на запрос с числом занятых vCPU — дают:
- vCPU на энергоэффективных ядрах M3 Pro (6 P + 6 E);
- снижение частоты производительных ядер под многоядерной нагрузкой;
- накладные расходы гипервизора и сетевого стека ВМ, учтённые в cgroup;
- конкуренция за кэш и память;
- у k6 — ещё и рост числа занятых VU (66 → 309).
Ни одна метрика не показывает, на каких физических ядрах шла работа.
Проверено и исключено: генератор (≤ 0,88 ядра из 2 посекундно,
троттлинг 0, недосланных на ступенях R* нет), HAProxy (≤ 0,30 ядра из
1, очередь 0) и переоткрытие соединений LB → реплика (проба verify:
keep-alive-сессия держит своё соединение к каждой реплике, 200
запросов — 2 новых соединения и 198 повторных использований).
Это признак `host_cost` (сработал уже с k = 2, 1,20 → 2,12), а не
`host`: очереди к vCPU внутри ВМ почти нет (PSI ≤ 12 %, порог 20 %).
Проверка порядка величины (арифметика над числами сводки, не таблица
команды): R*(k) ≈ k × CPU реплики / предельный CPU на запрос; для k = 6
— 6 × 0,93 / 2 906 мкс ≈ 1 920/с при измеренных 1 923–2 034. Прирост числа реплик
съедается ростом цены запроса, и после k = 5 R* стоит.
Итог: **на этом стенде с дефолтными лимитами точку насыщения задаёт
хост** — общий CPU ноутбука для реплик, PostgreSQL, LB и генератора, а
не БД, LB или пул; каким механизмом секунда CPU дешевеет, замер не
разделяет. Границы пула и БД достижимы управляемыми опытами (серии
`pool` и `db`, ниже): на дефолтах граница пула — k = 7, за пределом
бюджета ВМ, а PostgreSQL 2 CPU занят на 1,1 ядра.
Память нигде не была узким местом (раздел «Память» той же сводки,
пики за серию): RSS процесса реплики — 106–135 МиБ при лимите 512 МиБ
(у 1 × 4 — 106 МиБ из 2 ГиБ), PostgreSQL — до 411 МиБ из 1 ГиБ, k6 — до
253 МиБ из 1 ГиБ.
**Граница пула** (`scaling-pool`, 4 × 1, пул 10 + 5 на реплику):
- `max_connections` 100: соединений не больше 60 (15 на реплику), отказов
«too many clients» 0 на всех 20 ступенях (7 + 6 + 7). 5xx — только 503
от самих реплик на перегрузке (1–11 за окно на 2 034/с, 17–27 на
2 274/с): запрос ждал свободное соединение пула дольше `pool_timeout`
5 с (строки API `"status": 503` с `duration_ms` ≈ 5 010 и строки LB
`api/api-N 0/0/0/50xx/50xx 503` в `raw/*-errors.log`); LB реплики не
исключал (`lb_chkdown` 0). Тот же механизм — у 503 серий `a` (4 × 1,
1–11 за окно) и `b` (2 × 1 — 1, 3 × 1 — 1–6, 4 × 1 — 1–8) за R*.
- `max_connections` 50: пулы упираются в 49 соединений (50 − 1 слот
сэмплера). Отказы начинаются уже на 1 455/с — 10–200 за окно при
ошибках 0,03–0,7 % (ступень проходит SLO), на 1 627/с — 314–785
(0,97–2,4 %, в двух повторах из трёх — нарушение), на 1 819/с — 4 514–5
060 (24–29 %). R* = 1 539 (1 539–1 627) против
1 819 (1 720–1 819) при 100, разбросы не пересекаются, причина первого
нарушения — `errors`.
- **Код ответа на отказ — 500, а не 503.** Число ответов 500 в окне
почти равно числу отказов в журнале PostgreSQL (25 и 25, 5 060 и
5 071). В журнале API — «Exception in ASGI application»,
`asyncpg.exceptions.TooManyConnectionsError` → `sqlalchemy.exc.DBAPIError`:
SQLSTATE 53300 нет в `UNAVAILABLE_SQLSTATES`
(`src/infra/db/errors.py`), и `get_db_session` не переводит отказ в
503. Так ведёт себя измеренный commit `712d245`: серия `pool` снята до
правки, спек `data-storage` требует 503. Доказательства окна — строки
PostgreSQL, API и LB в `evidence/bench/scaling-pool/raw/*-errors.log`.
**Исправлено после серий** в `68edc66`: `53300` добавлен в
`UNAVAILABLE_SQLSTATES`. Проба тем же отказом (все слоты
`max_connections` заняты, соединения пула оборваны) даёт 503
`unavailable` в формате контракта с `X-Instance-Id` реплики — тест
`make failure_checks` (`test_connection_limit_reached`, без правки он
красный: 500) и запрос через LB на рабочем стенде
(`evidence/storage/too-many-clients.md`). Серия `pool` не
перемерялась: правка меняет код ответа, а не число отказов, и R*(50)
определяется ошибками ≥ 1 % при любом коде.
**Насыщение PostgreSQL** (`scaling-db`, управляемый опыт после verify,
решение пользователя): на дефолтах PostgreSQL не насыщался, поэтому его
лимит CPU сужен до 0,5 при 1, 2 и 4 репликах по 1 CPU; контроль — 4 × 1
при прежних 2 CPU. 4 конфигурации × 3 повтора в одной метке, перемешанным
порядком, на коде `95539a1` (после правки 53300, поэтому с метками `b` и
`pool` не сравнивается: контроль снят заново). Лимит 0,5 выбран
калибровкой `db_quick` и записан в design до серии (`46e8f75`): при нём
БД упирается около 1 000–1 160/с — раньше потолка 4 реплик и около
потолка 2. Ожидание до серии: R*(4) ≈ R*(2). Хост проверен, выгрузок в
swap 0, брака генератора нет (`evidence/tests/scaling-bench-checks.md`,
раздел 10).
| Конфигурация | R*, запросов/с | Признаки на R* / на первой нарушившей | CPU PostgreSQL на R* (доля лимита) | Троттлинг PostgreSQL на первой нарушившей | CPU PostgreSQL на запрос: R* → первая нарушившая, мкс | Соединений |
|---|---|---|---|---|---|---|
| 1 × 1, PostgreSQL 0,5 | 630 (630–630) | `app` / `app` | 0,19 (0,38) | 0 | 298 → 284 | 15 |
| 2 × 1, PostgreSQL 0,5 | 1 101 (1 101–1 101) | `app` / `app` | 0,38 (0,77) | 4,8 % | 348 → 349 | 30 |
| 4 × 1, PostgreSQL 0,5 | **931 (931–931)** | — / **`db_cpu` `db_wal` `host`** | 0,26 (0,52) | **68 %** | 279 → **441** | 41 → 60 |
| 4 × 1, PostgreSQL 2 (контроль) | 1 627 (1 627–1 627) | `app` `host_cost` / `app` `host_cost` | 0,76 (0,38) | 0 | 468 → 492 | 60 |
Таблица — разделы «PostgreSQL на R*» `evidence/bench/scaling-db/summary.md`
и «Насыщение PostgreSQL» `evidence/plots/scaling-db/summary.md`
(`make bench_plots LABELS="scaling-db" PLOTS=scaling-db`), график —
[R* от числа реплик](evidence/plots/scaling-db/rstar-by-replicas.svg).
- **Точка насыщения БД** при 0,5 CPU — около 950–1 000 запросов/с при
4 репликах: на 931/с PostgreSQL занят на 0,26 ядра и p95 3,8 мс, а уже
на 984/с (+5,7 %, следующая ступень) он выбирает квоту — 0,43 ядра,
троттлинг 68 % периодов (на 1 041–1 455/с — 0,48–0,50 ядра и до 100 %),
p95 244 мс, срабатывают `db_cpu` и `db_wal`. CPU реплик при этом —
2,2–2,4 ядра из 4: реплики ждут базу.
- **Рост реплик перестаёт помогать — и вредит.** 1 → 2 реплики: R*
растёт (630 → 1 101), узкое место — CPU реплик, PostgreSQL на 77 %
лимита. 2 → 4: R* **падает на 15 %** (1 101 → 931), разбросы не
пересекаются (во всех повторах одно и то же значение). Ожидание «почти
не растёт» подтвердилось сильнее, чем предполагали: у 4 реплик вдвое
больше соединений (до 60 против 30), и у насыщенного PostgreSQL CPU на
запрос растёт с 279 до 441 мкс — квоту делят больше backend-процессов,
растут ожидания WAL. Тот же лимит при 2 репликах держит 1 101/с при
348 мкс на запрос.
- **Контроль:** 4 × 1 при 2 CPU PostgreSQL — 1 627/с, PostgreSQL на 38 %
лимита, узкое место — реплики и хост, как в серии `b`. С `scaling-b`
(1 819) не сравнивается: другая сессия и другой код.
**Saturation point БД / LB / пула** (рубрика «5», трек 1):
- **БД** — показана управляемым опытом `scaling-db`: при 0,5 CPU
PostgreSQL насыщается около 950–1 000/с, добавление реплик с 2 до 4
снижает R* на 15 %. На дефолтах (2 CPU) в пределах бюджета ВМ БД не
насыщается: 1,1 ядра из 2 при 6 репликах.
- **Пул** — показан управляемым опытом `scaling-pool`: при
`max_connections` 50 отказы «too many clients» с 1 455/с и R* 1 539
против 1 819; на дефолтах граница — k = 7, за бюджетом ВМ. За R* реплики
ждут свободное соединение пула до 5 с (503).
- **LB** — не насыщен ни в одной серии: HAProxy ≤ 0,30 ядра из 1,
очередь 0, ошибок соединения нет.
- **Хост** — на дефолтах именно он останавливает рост реплик (k_sat ∈
{4, 5}, `host_cost`), механизм не разделён.
**Итог по гипотезам.**
- **H1 — по заранее записанным критериям не подтверждена целиком.**
«Подтвердит» требовало выполнения всех условий, и одно не выполнено.
- Механизм подтверждён: R*(1 × 4) / R*(1 × 1) = 630 / 666 = **0,95** ∈
[0,9; 1,15]; посекундный максимум CPU реплики 1 × 4 за всю серию —
**1,00 ядра**, среднее на ступенях перегрузки — 1,00 ядра (пороги
1,3 и 1,2), троттлинг 1 × 4 — 0. Один процесс uvicorn из 4 ядер
лимита занимает одно, и бюджет занимают только процессы: 4 × 1 =
1 819 (2,73 × R*(1 × 1), сработал `host_cost` 1,58 — условие для
4 × 1 выполнено).
- Не выполнено условие «2 × 2 ≥ 1,7 × R*(1 × 1)»: 2 × 2 = 1 101, то
есть **1,65 ×** — на один шаг сетки ниже порога (1 101 → 1 164 —
+5,7 %).
- Опровержение тоже не наступило: 2 × 2 < 1,5 × R*(1 × 1) нет, и на
2 × 2 сработал признак общего ресурса `host_cost` (1,29).
- Чувствительность к опоре: с R*(1 × 1) из A/A (704) 2 × 2 — 1,56 ×,
а 1 × 4 / 1 × 1 — 0,89, то есть ниже 0,9; по медиане шести повторов
1 × 1 (685) — 1,61 и 0,92.
4 × 1 серии `a` и k = 4 серии `b` совпали (1 819, ниже — сравнение).
- **H1б — опровергнута на фиксированных уровнях, как и ожидал наш
разбор.** На 500/с троттлинг 1 × 1 — медиана 0 (0–1,1 % периодов), p99
1 × 1 87,7 (86,3–87,8) мс против 1 × 4 91,8 (86,6–102,5) — разбросы
пересекаются. На ступени R* троттлинг 1 × 1 заметен — 2,1 (1,1–6,9) %
периодов (1 × 4 — 0), на нарушивших ступенях до 21 %, но p99 на R*
(183–262 мс у 1 × 1 и 203–234 мс у 1 × 4) не разделяются (таблица
троттлинга в `evidence/plots/scaling/summary.md`, раздел
«Фиксированный бюджет»).
- **H2 — опровергнута; подтвердилась конкурирующая H2-хост.** k_sat = 5
∈ {4, 5}, как предсказано (в пределах разрешения сетки — тоже {4, 5}),
но на k_sat + 1 = 6 CPU PostgreSQL — 1,10
ядра (< 1,4), признаков `db_cpu`, `db_wal`, `db_lock` нет; CPU реплики
не падает (0,93 ядра) — реплики не ждут базу. Причину называет
`host_cost`: цена запроса растёт у всех компонентов вместе с занятыми
ядрами хоста. Предсказание эффективности ≥ 0,85 при k ≤ 3 тоже не
выполнено (0,87 и 0,77): дорожание начинается сразу. Строгое правило
причины решения 9 («сработал на k_sat + 1 и не срабатывал на k_sat −
1») ни один признак не выполняет: `host_cost` нарастает постепенно с
k = 2 — насыщение плавное, а не ступенька.
- **H3 — подтверждена.** При `max_connections` 50 отказы «too many
clients» и ошибки ≥ 1 % на 1 627–1 819/с, где при 100 ошибок меньше
0,1 % и ступени проходят SLO (кроме одной 1 819/с по p95); R*(50) <
R*(100) без пересечения разбросов; при 100 отказов нет. Первая часть
предсказания — «до границы растёт ожидание свободного соединения» —
тоже видна: при 100 на R* пул каждой реплики заполнен до 15 во всех
повторах, а за R* ожидание пула доходит до `pool_timeout` 5 с, и
реплика отвечает 503. Код ответа на отказ — **500 на измеренном commit
`712d245`** (серия `pool` снята до правки), как и предсказывал разбор
кода; **после правки `68edc66` — 503 `unavailable`** (тест `make
failure_checks` и проба через LB, `evidence/storage/too-many-clients.md`).
**Уровень шума и согласованность серий** (`make bench_compare`):
- A/A — метка `scaling-aa` (профиль `scaling_ab`: 1 × 1 и 6 × 1 серии
`b`, тот же код, другая сессия): 1 × 1 — 666 (666–704) → 704 (666–704),
+5,7 %; 6 × 1 — 2 034 (1 923–2 034) → 2 034 (2 034–2 034), Δ медиан 0,
то есть |Δ| < 5,7 % (одна ступень сетки). CPU на запрос — в пределах
1 %; p95 — до 3,3 % (6 × 1 на 500/с 3,0 → 3,1 мс), p99 на 250/с — до 7 % (1 × 1 5,6 → 6,0 мс, 6 × 1
4,3 → 4,1 мс; `evidence/compare/scaling-b__scaling-aa.md`). Шум R* ≈
5,4–5,7 % (5,4 % — `compare.py` с `AA`, Δ относительно A/A; 5,7 % —
b → aa) — одна ступень деления. Оценён по двум конфигурациям × 3
повтора. Сдвиг на одну ступень при непересекающихся разбросах команда
назовёт эффектом, но он в пределах разрешения: эффект R* засчитывается
при сдвиге не меньше двух ступеней (≥ 12 %) или с оговоркой
(`bench.md`). Для `scaling-improvement` `scaling-aa` как `AA` не
годится: правка 53300 (`68edc66`) изменила код приложения после неё,
поэтому A/A снимается заново на коде «до» (design, «Найдено в
verify»).
- 4 × 1 серии `a` против k = 4 серии `b` (одна конфигурация в разных
сериях и сессиях): 1 819 (1 539–1 819) и 1 819 (1 819–1 819), Δ 0 %
(`evidence/compare/scaling-b__scaling-a.md`).
**Почему не `workers`.** Масштабирование числом процессов внутри одного
контейнера (`uvicorn --workers`) не используется: LB должен видеть
каждый процесс отдельной репликой со своим `X-Instance-Id`, проверкой
готовности и пулом соединений, а failover hook — останавливать
процесс, а не контейнер с несколькими; поэтому 1 × 4 здесь — честный
«один процесс с четырьмя ядрами», и бюджет занимают 2 × 2 и 4 × 1.
**Ограничения замеров.**
- Один хост: генератор, LB, реплики и PostgreSQL делят ВМ Docker и CPU
ноутбука; Docker Desktop — ВМ. Числа относятся к этому ноутбуку и
профилю.
- Разнородные ядра M3 Pro (6 производительных + 6 энергоэффективных):
vCPU ВМ к ним не привязаны, «1 CPU» лимита при занятом хосте даёт
меньше работы. Это одно из объяснений найденной точки насыщения, но
не единственное (частота ядер, гипервизор, кэш и память — раздел
«Почему рост реплик перестаёт помогать»). На хосте с однородными
ядрами и свободным CPU насыщение, вероятно, наступило бы позже; это
не проверялось.
- Серия `b` — до 6 реплик: при 7 сумма лимитов (12,75 CPU) больше 12
vCPU ВМ. Граница пула на дефолтах (k = 7) показана управляемым
опытом (`max_connections` 50 при 4 репликах), а не ростом реплик.
- Насыщение БД показано управляемым опытом: лимит PostgreSQL 0,5 CPU
вместо 2 (серия `db`). Эффект соединений у насыщенной базы (CPU на
запрос 279 → 441 мкс) измерен только при этом лимите и 2 / 4
репликах; гипотез для серии `db` в коммите до серий не было — она
добавлена после verify, ожидание и лимит записаны в design перед её
прогоном. Серия снята в другой сессии и на другом коде, чем `a`, `b`,
`pool`: её контроль 4 × 1 при 2 CPU (1 627) с `scaling-b` (1 819) не
сравнивается.
- Окно 20 с и разрешение поиска ~6 %: превышение потолка на ~1 % окно
не ловит; разброс R* между повторами — одна-две ступени деления
(до 18 % у 4 × 1 серии `a`). Решения у порогов держатся на одном шаге
сетки: k_sat = 5 — в пределах разрешения k_sat ∈ {4, 5} (прирост
4 → 5 — от +6 до +18 % при пороге 10 %); «+0 %» между k = 5 и 6 —
|Δ| < 5,7 %; 2 × 2 = 1,65 × R*(1 × 1) — на шаг ниже порога H1 1,7.
- Шум A/A (5,4–5,7 %, одна ступень сетки) оценён по двум конфигурациям
× 3 повтора.
- Первая ячейка серии `a` (4x1-r1, сразу после остановки рабочего
стенда) дала R* 1 539 против 1 819 у двух других повторов. Возможен
прогрев хоста в начале сессии; в других сериях первая ячейка в норме,
доказательства слабые. Для будущих серий — отбрасываемая ячейка
прогрева.
- `lb_qtime_ms` … `lb_ttime_ms` — скользящее среднее HAProxy по
последним 1 024 запросам на конце окна (около 0,5 с при 2 000/с), а
не среднее окна: для разбора задержек не используются.
- Признаки и пороги — до прогонов, но определения `host_cost` и
`db_active_min` уточнены на самопроверках после коммита гипотез
(методика выше).
- Автоочистка и контрольные точки PostgreSQL внутри ячейки одинаковы
для всех конфигураций по времени, но не исключены.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Идемпотентность:
- **Таблица ключей растёт.** Строка на каждое сообщение, фоновой
уборки нет до worker лабы 5. Просроченный ключ заменяется только при
следующей отправке с ним же. Ручная очистка — по индексу `created_at`:
```sh
docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-c "DELETE FROM idempotency_keys WHERE created_at < now() - interval '"'"'24 hours'"'"'"'
```
Удаляются только ключи, сообщения остаются.
- **Замороженная реплика держит ключ до 10 с.** Если процесс заморожен
(`docker pause`) между захватом ключа и commit, повторы того же ключа
на других репликах ждут его блокировку до `statement_timeout` (5 с)
и получают 503. Через 10 с простоя PostgreSQL прерывает такую
транзакцию (`idle_in_transaction_session_timeout` с change
`graceful-failover`), и следующий повтор проходит: 201 через ~12 с
после начала транзакции (`evidence/failover/hung-key.md`). Раньше
ключ оставался занят до разморозки.
- **Каждая запись дороже на одну вставку** и проверку отложенного
внешнего ключа. Это цена контракта; её измеряет трек 1, там же
кандидат «ключ и сообщение одним SQL-выражением» (`PLAN.md`).
- **После 24 ч** повтор того же тела с тем же ключом создаст новое
сообщение: контракт гарантирует повтор только в пределах срока.
- **В консоли `X-Instance-Id` — имя машины разработчика**; для локальной
разработки это допустимо, `APP__INSTANCE_ID` его заменяет.
Балансировщик и реплики:
- **Что стенд выдерживает и что нет.** Один Docker-host, один HAProxy,
одна PostgreSQL, один Valkey. Выдерживается отказ процесса API —
любой одной реплики при второй живой. Не выдерживается отказ хоста,
LB и PostgreSQL: это единые точки отказа, устойчивость к ним не
заявляется. Отказ Valkey — деградация до Postgres, не отказ.
- **8 слотов `server-template`.** Девятую реплику LB не увидит; 8 —
максимум серий трека 1. Число меняется в `haproxy.cfg`.
- **Граница пула Postgres.** С пулом 10 + 5 на реплику при 7 репликах
соединений больше `max_connections` (106 > 100). Проверено серией
`pool` трека 1 при 50: под нагрузкой — отказы «too many clients», и
клиент получает 500 вместо 503 (`KNOWN_ISSUES.md`, исправление — этап
fixes change `scaling-bench`).
- **Зависшую реплику LB исключает за 6,5 с, а не мгновенно.**
`timeout check` 2,5 с, а не 1 с, как в плане: проверка не должна
обрываться раньше таймаута готовности внутри API (2 с). Уменьшать и
его нельзя: `/health/ready` берёт соединение из общего пула, и
заминка PostgreSQL на 1–2 с вывела бы из LB все реплики разом.
Худшее обнаружение зависшей реплики — `inter` + `timeout check` +
`fastinter` + `timeout check` = 6,5 с (замер под нагрузкой — 5,8–6,0 с),
всё это время половина запросов получает 504 через 10 с. Остановленную
и убитую реплику LB исключает за 0,8–1,8 с (DNS, граница проверок
2,5 с). Пассивная проверка по ошибкам живого трафика зависшую реплику
не ускорила бы: соединение с ней устанавливается, а ответ 504 приходит
только через `timeout server` (design `graceful-failover`, решение 2).
- **Оборванный ответ при `kill`.** Запросы в полёте на убитой реплике
получают 502 от LB, LB их не повторяет (они уже дошли). Отправку
сообщения клиент повторяет с тем же ключом; другие `POST` — на
усмотрение клиента, прозрачных повторов контракт не допускает.
Воспроизводится командой `driver.py --port 8080 kill-inflight`.
- **Отказ PostgreSQL выводит из LB все реплики сразу.** `/health/ready`
проверяет PostgreSQL, поэтому через 1–2 с после его отказа на всё,
включая `/health/live`, отвечает сам HAProxy: 503 `unavailable` в
формате контракта — тот же код, что отдал бы API. Liveness процесса
без LB проверяет `make failure_checks`.
- **Выбор реплики в `make test-failover`.** Тест останавливает
реплику, ответившую на его первую отправку; число запросов до неё
постоянно, и при round-robin по двум репликам после `make replicas`
тест снова выбирает ту же. Для второй реплики очередь сдвигается
одним запросом до теста (`evidence/failover/test-failover.md`).
- **Argon2id под лимитом 1 CPU.** Один процесс API — один event loop,
он больше 1 CPU не использует, а Argon2id (`p=4`) считает хэш в
четырёх потоках. Под лимитом реплики проверка пароля подряд идёт
около 0,14 с вместо 0,025 с, четыре одновременных — 0,8–1,6 с;
одиночный вход через LB — около 50 мс. Пока на реплике идёт вход, её
остальные запросы делят с ним квоту: при 8 потоках входа `GET
/users/me` — медиана 46 мс вместо 2 мс, p95 101 мс
(`evidence/replicas/stand.md`). `make test_isolated` (около 190
регистраций и 190 входов на одной реплике) идёт около минуты вместо
21 с. Лимит оставлен осознанно: вход редок, в замеры трека 1 не
входит, серия B считает реплику в 1 CPU.
- **Одиночный 502 при `docker stop` под нагрузкой.** Простаивающее
соединение LB → реплика теперь закрывает LB (`http-reuse never`,
`timeout http-keep-alive` 10 с < keep-alive реплики 60 с,
`evidence/failover/keep-alive.md`). Но при SIGTERM uvicorn сразу
закрывает простаивающие соединения, и запрос, который LB в тот же
миг отправил в такое соединение, получает 502 без повтора. Под
нагрузкой 200 запросов в секунду на закоммиченном коде — одиночный 502
в 1 из 4 фаз `stop` (регрессия и замер `baseline`), доля успешных в
секунде не ниже 99 %. С пулом (`safe`) гонка та же: в разведке на
рабочем дереве — 1 из 9 фаз против 2 из 10 с `never`, разница в
пределах случайности (это история поиска, не доказательство,
`evidence/failover/keep-alive.md`). Клиенты с новым соединением на
запрос (`make test-failover`) его не встречают; отправку сообщения
клиент повторяет с тем же ключом. README допускает краткие ошибки во
время обнаружения отказа, если они измерены. Плановая остановка
(`make rolling_update`, change `rolling-update`) сначала выводит
реплику из LB через его runtime API и только потом шлёт SIGTERM.
Под той же нагрузкой это 0 ошибок (профиль `rollout`). Одиночный 502
остаётся только у остановки без дренажа, то есть у имитации отказа
(`stop-one.sh`, профиль `failover`).
Цена масштабирования (трек 1):
- **Один ноутбук и ВМ Docker.** Генератор k6, LB, реплики и PostgreSQL
делят 12 vCPU ВМ и CPU M3 Pro; числа — для этого хоста и профиля
70/20/10. Генератор ограничен 2 CPU и следит за собой (брак — нижняя
граница R*), но работает на том же хосте.
- **Разнородные ядра и общий CPU хоста.** 6 производительных и 6
энергоэффективных ядер, vCPU к ним не привязаны: при занятых больше
~6 vCPU «1 CPU» лимита делает меньше работы. Рост остановил хост
(`host_cost`), но механизм не разделён: энергоэффективные ядра,
частота ядер под многоядерной нагрузкой, гипервизор и сетевой стек ВМ,
кэш и память дают один и тот же признак. На хосте с однородными
ядрами и свободным CPU насыщение, вероятно, наступило бы позже, а
какой общий ресурс стал бы первым (PostgreSQL занят на 1,1 ядра из 2
на k = 6), не проверялось. Причинная проба — 1 × 1 на 666/с с
контейнером-«грелкой» на 6 vCPU и без него (verify W4) — не
снималась.
- **Серия `b` — до 6 реплик** (бюджет ВМ, 11,75 CPU лимитов); граница
пула на дефолтах (k = 7) показана управляемым опытом
`max_connections` 50, а не ростом реплик.
- **Окно 20 с, разрешение поиска ~6 %**, 3 повтора: разброс R* — одна-две
ступени деления; уровень шума между сессиями — A/A `scaling-aa`
(5,4–5,7 %, одна ступень). Для улучшения A/A снимается заново: код
приложения после `scaling-aa` изменён правкой 53300.
- **Улучшение по найденному узкому месту** — следующий change
`scaling-improvement`. На этом хосте R* сдвигает прежде всего
удешевление запроса в CPU приложения (оно занимает 5,6 из 8,1 ядра ВМ
на k = 6). На дефолтах PostgreSQL и PgBouncer узким местом не были.
Кандидат по пулу — не размер, а переполнение: на R* при k ≥ 2
PostgreSQL открывает 168–298 новых соединений за окно 20 с
(`db_sessions_new`), вероятно, соединения сверх `pool_size` 10
закрываются при возврате и открываются заново (процесс PostgreSQL и
SCRAM на каждое). Серия `db` добавляет довод за меньшее число
соединений: у насыщенной базы 60 соединений 4 реплик дают на 15 %
меньше, чем 30 у двух. Сравнение — пул без переполнения (например,
10 + 0 или 15 + 0) против 10 + 5 на 6 × 1 и на 4 × 1 при PostgreSQL
0,5 CPU.
Поочерёдная замена и миграции:
- **Автоматического отката нет.** Сбой на середине оставляет
`API_REPLICAS` готовых реплик, возможно, разных версий. Миграция
только расширяет схему, так что обе версии работают; повторный запуск
доводит замену. Откат — `make rolling_update COMMIT=<прежний>
MIGRATE=0`: его миграции не знают новой ревизии, поэтому шаг
пропускается явно, а схема остаётся новой. После отката тег
`mtusi-messenger:lab3` указывает на прежний образ: `docker compose up`
без сборки пересоздал бы на нём `migrate`, и тот упал бы на новой
ревизии. Вперёд — снова `make rolling_update` или `make run_docker`
(`evidence/rollout/compatibility.md`, шаг E).
- **Contract-миграции нет в этой поставке.** Удалить или переименовать
колонку можно только отдельной миграцией, когда кода, который её
пишет, не осталось. `downgrade` новой ревизии удаляет колонку и
допустим только тогда же.
- **`lock_timeout` 2 с.** Под тяжёлой записью или во время `pg_dump`
(он держит `ACCESS SHARE` на все таблицы до конца) миграция может не
дождаться блокировки и упасть. Тогда замена не начинается, повтор
проходит. Это осознанный выбор: иначе очередь всех записей ждала бы
за миграцией. Пока миграция ждёт, запросы к `messages` стоят в
очереди до 2 с.
- **Сборка образа идёт на том же хосте, под нагрузкой.** Из кэша слоёв
— секунды CPU ВМ Docker.
- **SIGTERM во время старта реплики теряется** (процесс с PID 1 до
установки обработчиков uvicorn, `KNOWN_ISSUES.md`). Скрипт обходит это
для неготовой новой реплики: слот в `maint`, затем `docker rm -f`.
Штатные остановки касаются уже запущенных процессов.
- **Замена только на одном хосте** и только для `api`. LB, PostgreSQL и
Valkey обновляются с простоем.
- **Профиль отказа — один прогон на фазу, один хост.** Замер показывает
поведение и порядок величин, а не распределение. Генератор, LB,
реплики и PostgreSQL делят ВМ Docker (`evidence/failover/baseline/`).
## Ответы на вопросы защиты
**Чем отказ процесса отличается от отказа узла?** Отказ процесса —
остановлена, убита или зависла одна реплика API, а хост, сеть, LB и
хранилища живы. Его стенд переживает, и это измерено под нагрузкой
200 запросов в секунду (`evidence/failover/detection.md`):
- `docker stop` (SIGTERM) — процесс дорабатывает запросы в полёте и
закрывает сокет; LB получает отказ соединения и перенаправляет
запрос, через 1,0–1,1 с убирает реплику из распределения. Ошибок 0,
только задержка до 0,5 с у запросов, попавших на пропавший адрес;
- `docker kill` (SIGKILL) — то же, но запросы в полёте рвутся: 502 от
LB без повтора, клиент повторяет отправку с тем же ключом. Исключение
— 0,8–1,8 с;
- зависание (`docker pause`) — процесс жив для сети, но не отвечает.
Его видно только по проверкам: 5,8–6,0 с (граница 6,5 с), и всё это
время половина запросов получает 504. Его открытую транзакцию
PostgreSQL прерывает через 10 с простоя, ключ освобождается.
Вторая реплика обслуживает те же сессии и данные из PostgreSQL,
подтверждённые сообщения не теряются, повтор с тем же ключом не даёт
дублей. Отказ узла — пропал весь хост: вместе с ним LB, PostgreSQL,
Valkey и все реплики, и переключаться некуда. Причём для остальных
узлов отказ узла выглядит как зависание или пропавший адрес, а не как
аккуратный отказ соединения: соединения висят до таймаутов. На одном
хосте его не пережить, это трек 2, который мы не выбрали. Здесь хост,
LB и PostgreSQL честно названы единой точкой отказа.
**Почему `depends_on` и healthcheck сами по себе не являются
балансировщиком?** `depends_on` лишь упорядочивает старт контейнеров
(postgres → migrate → api), а healthcheck только меняет статус
контейнера на `unhealthy`: Docker Compose не перестаёт слать ему
запросы и не распределяет их. Распределять некому: без LB клиент
ходит на один опубликованный порт одного контейнера. Нужен отдельный
процесс, который принимает соединения, выбирает готовую реплику,
исключает неготовую по своей проверке и повторяет недошедший запрос —
здесь это HAProxy с проверкой `/health/ready` раз в секунду.
Healthcheck контейнера остаётся для `make replicas --wait` и
`docker compose ps`. При поочерёдной замене видно, что одного
`healthy` мало: реплика попадает в распределение LB только после его
собственных проверок, через ≤ 1,5 с. Поэтому `make rolling_update` ждёт
состояния `UP` в статистике HAProxy, а старую реплику выводит из LB
явно, до остановки.
**Дополнительно (уровень «4»): как обновить API без простоя и почему
миграция не ломает работающие реплики?** `make rolling_update` меняет
реплики по одной:
1. одна новая рядом со старыми;
2. ожидание её `UP` в LB;
3. старая выводится из LB (`drain`), дорабатывает запросы,
останавливается и удаляется.
Реплик всё время не меньше `API_REPLICAS`, клиент ошибок не видит:
профиль `rollout` под 200 запросами в секунду и публичный
`tests/load.py` — 0 неуспешных. Миграция выполняется один раз, до
первой новой реплики, и только расширяет схему (expand/contract).
Старые реплики работают на новой схеме: это проверено `make test` и
`make student_test` на образе прежнего commit после новой миграции.
Откат кода не требует отката схемы. Удаление и переименование —
отдельной поставкой, когда прежнего кода не осталось
(`evidence/rollout/compatibility.md`).
**Какие POST можно повторять после timeout и что защищает
`Idempotency-Key`?** После таймаута клиент не знает, выполнен ли
запрос. Безопасно повторять только `POST
/api/v1/chats/{chat_id}/messages` с тем же ключом и телом: ключ и
сообщение пишутся одной транзакцией, повтор через любую реплику вернёт
тот же 201 и то же `Message`, другое тело — 409, одновременные повторы
дают одно сообщение. Регистрация, создание чата и вход ключа не имеют:
повтор создаст второго пользователя (или 409), второй чат, вторую
сессию. Поэтому и LB повторяет запрос сам только при отказе
соединения, когда запрос до реплики точно не дошёл (`retry-on
conn-failure`), а не по таймауту или обрыву ответа
(`evidence/failover/test-failover-kill.md`).
**Что сломается при увеличении числа API, если сессии находятся в
локальной памяти?** Токен, выданный одной репликой, другая не знает:
round-robin отправит следующий запрос на другую реплику — 401, хотя
пользователь вошёл. Logout отзовёт сессию только на одной реплике, и
токен продолжит работать на остальных. Рестарт или отказ реплики
стирает её сессии, `make test-persistence` и `make test-failover`
упали бы. Sticky session это лишь маскирует и запрещена заданием.
Поэтому сессии в Postgres (общие для реплик, переживают рестарт), как
и ключи идемпотентности; в памяти процесса нет ничего, от чего зависит
корректность (раздел «Балансировщик и реплики»).
**Дополнительно (уровень «5», трек 1): почему одна реплика с 4 CPU не
быстрее реплики с 1 CPU?** Процесс uvicorn — один поток event loop, и
GIL не даёт выполнять Python-код параллельно даже в потоках executor.
Серия `a`: реплика с лимитом 4 CPU за всю серию не взяла больше 1,00
ядра в секунду, и её R* — 630/с против 666/с у 1 × 1. Бюджет 4 CPU
занимают только процессы: 2 × 2 — 1 101/с, 4 × 1 — 1 819/с. Поэтому
масштабирование — числом реплик за LB, а не лимитом CPU одной.
**Почему рост реплик перестаёт помогать и где точка насыщения?** Серия
`b`: R* растёт до k = 5 (2 034/с) и дальше не растёт (k_sat = 5 по
правилу, в пределах разрешения сетки — 4 или 5). Каждая реплика на R*
занята почти на ядро, а PostgreSQL — только на 1,1 ядра из 2: ожидания
WAL — около 22 % активных соединений (порог признака 30 %), блокировок
нет. LB — 0,25 ядра из 1, очереди нет. Пул не отказывает, но на R*
заполнен до 15 соединений на реплику, а за R* запросы ждут его до 5 с и
получают 503. Растёт цена запроса в CPU у всех компонентов сразу —
реплик, PostgreSQL, HAProxy, генератора — примерно вдвое от k = 1 к
k = 6, вместе с числом занятых ядер хоста. Добавленная реплика делит
тот же хост, и её вклад съедается удорожанием каждого запроса. На этом
стенде с дефолтными лимитами предел задаёт хост, а не БД, LB или пул.
Почему секунда CPU даёт меньше работы — энергоэффективные ядра M3 Pro,
частота ядер, гипервизор или кэш и память, — замер не разделяет.
Границы БД и пула показаны управляемыми опытами. Серия `db`: при
PostgreSQL 0,5 CPU база насыщается около 950–1 000/с (троттлинг до
100 %, `db_cpu`), и 4 реплики дают R* на 15 % меньше, чем 2 (931 против
1 101): лишние реплики только добавляют соединения, и запрос в
насыщенной базе дорожает с 279 до 441 мкс CPU. Серия `pool`: при
`max_connections` 50 — отказы и падение R* на 15 % (после правки 53300
отказ — 503). LB не насыщался нигде: ≤ 0,30 ядра из 1.
**Почему открытая модель нагрузки, а не фиксированное число клиентов?**
В закрытой модели клиент ждёт ответа перед следующим запросом: когда
стенд замедляется, клиенты сами снижают интенсивность, и очередь не
видна (coordinated omission). В открытой модели k6 отправляет запросы с
заданной интенсивностью, а неотправленные из-за занятых VU считаются
ошибками. Поэтому R* — максимальная интенсивность, которую стенд держит
с p95 ≤ 200 мс и ошибками ≤ 1 %, а не число, подогнанное
под скорость ответов.