Files
mtusi2026lab3/REPORT.md
T

102 lines
18 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; законченный трек: 1 — цена масштабирования.
- Состав реализации: API ЛР2, HAProxy, минимум две API-реплики, общие PostgreSQL и Valkey, конкурентная идемпотентность в PostgreSQL.
- Внешние источники: контракт и материалы курса. Использованы Python 3.12.8, psycopg 3.2.3, argon2-cffi 23.1.0, redis-py 5.2.1; при подготовке использовался Codex.
## Запуск
```sh
cp .env.example .env
# задайте POSTGRES_PASSWORD и CURSOR_SECRET (случайный ключ минимум 32 байта)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 180
make check
make validate
make test BASE_URL=http://127.0.0.1:8080
make test-idempotency BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080
```
Приложение слушает только внутреннюю сеть Compose. Единственный опубликованный порт — loopback порт HAProxy 8080. Миграции запускает одноразовый сервис `migrate` перед API, под advisory lock PostgreSQL. Первая схема сохраняется совместимой с базой ЛР2; миграция `002_idempotency` добавляет таблицу ключей и индекс срока хранения.
## Архитектура и решения
```text
HTTP client → HAProxy :8080 → API × 2+ → PostgreSQL (messages, sessions, idempotency)
↘ общий Valkey (TTL lookup hint; PostgreSQL остаётся источником истины)
```
HAProxy round-robin балансирует запросы между адресами DNS `api`, повторно разрешая адрес каждые 2 секунды. Проверка `GET /health/ready` выполняется раз в секунду; две ошибки исключают backend, два успеха возвращают его. Connect timeout — 1 секунда, timeout ожидания/ответа — 10 секунд. API слушает `0.0.0.0:8080` внутри сети и на SIGTERM прекращает `serve_forever`; Compose ждёт до 10 секунд для штатного завершения.
Сессия проверяется PostgreSQL на каждом запросе; значение Valkey лишь ускоряет lookup и не авторизует пользователя без живой строки в PostgreSQL. Общий `CURSOR_SECRET` нужен, чтобы cursor истории, созданный одной репликой, принимался другой. Секрет и пароль БД находятся только в локальном `.env`, игнорируемом Git и Docker build context.
Для каждого POST сообщения обязателен ключ `[A-Za-z0-9._:-]{1,128}`. Уникальная область — пользователь, метод, путь чата и ключ; body хешируется после нормализации JSON, а пропущенный `attachment_ids` равен `[]`. `pg_advisory_xact_lock` сериализует одновременные запросы одной области во всех API-процессах; PostgreSQL хранит отпечаток body и точный JSON результата вместе с сообщением в одной транзакции. Совпавший запрос возвращает тот же `201` и Message; отличающийся body — `409`; запись можно использовать заново спустя 24 часа. Ошибка/откат транзакции не оставляет частично зарегистрированный ключ. Каждый API-ответ включая ошибку содержит непустой `X-Request-Id` и идентификатор процесса в `X-Instance-Id`.
### Роли и версии
| Роль | Service | Версия | Health/volume/порты |
|---|---|---|---|
| API | `api` (Compose scale) | Python 3.12.8 slim Bookworm, pinned digest в Dockerfile | `/health/ready`, без host-порта, без локального состояния |
| Балансировщик | `haproxy` | 3.0.8 Alpine | HAProxy backend checks, единственный порт `127.0.0.1:8080` |
| База | `postgres` | 16.4 Bookworm | `pg_isready`, общий volume `postgres_data`, внутренний порт 5432 |
| Кэш сессий | `valkey` | 8.0.1 Alpine | `PING`, volume `valkey_data`, AOF `everysec`, внутренний порт 6379 |
| Миграции | `migrate` | тот же образ API | одноразовый контейнер; выполняется до запуска реплик |
CPU/RAM limits заданы в compose для API, HAProxy, PostgreSQL и Valkey. `api` не имеет `container_name`, поэтому штатное горизонтальное масштабирование поддерживается.
## Проверки уровня 3 и 4
Публичный smoke проверяет обязательный API через HAProxy. Дополнительный параллельный тест запускает 32 запроса с одним ключом и одним body одновременно; все ответы вернули один ID сообщения, наблюдались две реплики. Persistence-сценарий перезапустил API, HAProxy, PostgreSQL и Valkey без удаления volumes; тот же Bearer-токен прочитал те же данные. Три failover-прогона остановили API-реплику по очереди и повторили сценарий после восстановления. Каждый наблюдал две реплики до отказа; новые записи восстановились за 2,902 с, 1,543 с и 1,447 с; ошибок было 0 во всех трёх прогонах (113, 125 и 114 успешных записей); сообщение до отказа и все подтверждённые записи остались доступны, дубли отсутствовали. В конце теста остановленная реплика оставалась остановленной; Compose восстановил её перед следующим прогоном и после финальной проверки.
Rolling replacement под нагрузкой выполняется скриптом `scripts/rolling-update.sh`: пул сначала увеличивается до трёх, затем контейнеры заменяются по одному с сохранением активного backend. Под нагрузкой 60 секунд, concurrency 16: 50 291 успешная запись (836,949 RPS), 24 ошибки из 50 315 запросов (0,048%), p50/p95/p99 = 6,118/55,938/85,729 мс. После завершения пул восстановлен до двух здоровых реплик. Метрики сохранены в `evidence/rolling-update-load.json`; успешность запросов при замене не абсолютная, что отражено в ограничениях.
## Трек 1 — цена масштабирования
**Гипотеза.** При равном суммарном CPU/RAM перенос ресурса с одного API на несколько реплик улучшит RPS только до насыщения общей PostgreSQL или пула соединений. При фиксированной мощности на реплику добавление API в какой-то момент перестанет повышать throughput; увеличение пула сверх полезного уровня добавит конкуренцию за БД, а не пропускную способность.
**Методика.** `scripts/track1_experiment.py` пересоздаёт API при каждом профиле, ждёт readiness и 5 секунд стабилизации, затем трижды измеряет закрытый цикл POST-сообщений по 30 секунд с concurrency 16. Перед каждым sample очищаются только учебные таблицы `messages` и `idempotency_keys`, затем выполняется `ANALYZE`; порядок вариантов перемешивается детерминированным seed. Сессии/пользователи остаются в PostgreSQL. Фиксированный бюджет: 2 vCPU и 1 GiB RAM суммарно для API, разделённые между 1/2/4 репликами. Серия роста: 0,5 vCPU и 256 MiB на реплику для 1/2/4/8 реплик. Отдельное сравнение при четырёх репликах меняет `DB_POOL_MAX` 5/10/20. PostgreSQL ограничен 2 CPU и 1 GiB; HAProxy — 0,25 CPU и 128 MiB. Записываются успешные RPS, ошибки, p50/p95/p99, CPU/RAM компонентов и число сообщений. Сводки и исходные данные — `evidence/track1-results.json`, график — `evidence/track1-rps.svg`.
Чтобы определить точку насыщения, `scripts/track1_offered_load.py` подаёт фиксированный поток 250/500/750/1000 POST RPS на восемь API-реплик (0,5 CPU / 256 MiB каждая) по три раза в перемешанном порядке; HTTP-клиент переиспользуется в потоках, число in-flight ограничено, Docker stats во время нагрузочного окна не опрашивается. Throughput рассчитан по фактическому времени вместе с drain. Затем `scripts/track1_offered_scale.py` делает три парных прогона 8/12 реплик при предложенных 1000 RPS. Между повторами масштабирование возвращается к восьми репликам, чтобы освободить DB-соединения до очистки синтетических таблиц. Все исходные измерения лежат в `evidence/offered-load-results.json` и `evidence/offered-scale-results.json`; график rate sweep — `evidence/offered-load.svg`.
| Профиль | Реплики | Пул/реплика | медиана RPS (min–max) | медиана ошибок | p50/p95/p99, ms | API CPU mean/peak, % | API RAM peak, MiB |
|---|---:|---:|---:|---:|---:|---:|---:|
| fixed-1 | 1 | 10 | 418,5 (389,7–456,3) | 0,017% | 32,3/53,0/82,4 | 174,3/190,2 | 61,9 |
| fixed-2 | 2 | 10 | 698,6 (653,6–749,2) | 0% | 8,0/62,4/92,9 | 74,0/109,5 | 60,9 |
| fixed-4 | 4 | 10 | 837,7 (590,7–900,3) | 0,007% | 5,2/57,5/101,9 | 38,2/53,3 | 62,4 |
| scaled-1 | 1 | 10 | 103,7 (102,1–108,8) | 0,064% | 111,1/313,3/484,9 | 47,8/53,3 | 83,5 |
| scaled-2 | 2 | 10 | 274,6 (244,8–276,3) | 0,048% | 22,9/183,7/290,4 | 37,6/52,9 | 140,0 |
| scaled-4 | 4 | 10 | 680,7 (635,3–875,7) | 0% | 6,0/71,0/123,1 | 40,8/53,2 | 79,2 |
| scaled-8 | 8 | 10 | 764,2 (655,4–787,6) | 0% | 9,5/70,6/111,2 | 29,0/50,1 | 82,0 |
| pool-5 | 4 | 5 | 921,2 (837,9–1061,3) | 0,003% | 5,3/49,2/89,8 | 40,4/53,3 | 62,6 |
| pool-10 | 4 | 10 | 808,9 (611,5–969,2) | 0,020% | 5,5/66,7/108,3 | 38,9/51,9 | 99,5 |
| pool-20 | 4 | 20 | 951,3 (573,5–1044,2) | 0,003% | 5,4/45,3/89,2 | 41,7/52,5 | 63,1 |
Среда: macOS 26.5.1 arm64, 8 host CPU; Docker Engine 29.8.2; Docker VM 8 CPU / 4 106 605 444 байта RAM (~3 918 MiB); Python клиента 3.14.6; Python API 3.12.8; PostgreSQL 16.4. Закрытая серия длилась 30 секунд, rate-controlled серия — 15 секунд на sample. Во всех замерах JSON фиксирует размер синтетических таблиц; перед sample `messages` и `idempotency_keys` очищались, остальные пользовательские данные сохранялись. Closed-loop percentiles подвержены coordinated omission; rate-controlled серия имеет короткие окна и оценивает только эту среду. Все результаты ограничены одним Docker-host; потеря узла одновременно затрагивает API, HAProxy, PostgreSQL и локальные volumes.
| Предложено, RPS | Медиана успешных RPS (min–max) | Медиана ошибок | Медиана p95, ms |
|---:|---:|---:|---:|
| 250 | 249,6 (249,6–250,0) | 0% | 9,9 |
| 500 | 499,6 (419,6–499,9) | 0% | 41,6 |
| 750 | 745,9 (693,2–748,7) | 0,018% | 100,9 |
| 1000 | 810,1 (553,2–879,3) | 2,753% | 1 611,3 |
Парное сравнение при 1000 предложенных RPS:
| API-реплик | Успешные RPS, медиана (min–max) | p95, медиана, ms | Ошибки POST за 3 повтора | Диагностика PostgreSQL |
|---:|---:|---:|---:|---|
| 8 | 727,0 (584,4–851,5) | 1 504,7 | 874 / 45 000 | `SELECT` прошёл |
| 12 | 555,8 (546,0–774,9) | 1 986,4 | 12 / 45 000 | Все 3 запроса отклонены: `too many clients already` |
**Поиск насыщения и улучшение.** В rate-controlled серии 250 и 500 предложенных RPS полностью принимались без ошибок (медианный p95 9,9 и 41,6 мс). При 750 RPS медиана успешной пропускной способности составила 745,9 RPS, p95 — 100,9 мс. При 1000 RPS throughput вырос лишь до 810,1 RPS, медианная доля ошибок достигла 2,75%, а p95 — 1 611 мс. Это показывает knee общей цепочки между 750 и 1000 RPS; повторяемость ограничена тремя короткими прогонами, поэтому это не универсальная производственная ёмкость.
Компонентное ограничение установлено отдельной проверкой DB-пула. При `DB_POOL_MAX=10` восемь реплик могут открыть до 80 соединений, а двенадцать — до 120. Фактический `max_connections` PostgreSQL равен 100. В трёх прогонах с 12 репликами и нагрузкой 1000 RPS, помимо роста задержки, PostgreSQL трижды отказал даже в диагностическом `SELECT` с `FATAL: sorry, too many clients already`; после возврата к восьми репликам запросы к БД снова проходили. Наблюдение сохранено в `evidence/db-saturation-observation.txt`, а метрики сравнения — `evidence/offered-scale-results.json`. Таким образом, насыщение пула/БД возникает между восемью и двенадцатью репликами при текущем лимите пула; дальнейшее увеличение API без снижения размера пула или повышения DB connection budget ухудшает доступность общих соединений. 8→12 RPS-диапазоны перекрываются, поэтому причинный вывод основан на подтверждённом исчерпании connection slots, а не только на падении медианного throughput.
Подтверждённое улучшение при фиксированном суммарном бюджете 2 vCPU / 1 GiB: переход fixed-1→fixed-2 поднял медиану с 418,5 до 698,6 RPS (+66,9%); диапазоны трёх повторов не пересекаются (389,7–456,3 и 653,6–749,2 RPS). p50 снизился с 32,3 до 8,0 мс, p95 изменился с 53,0 до 62,4 мс. Серии DB_POOL_MAX=5/10/20 при низкой конкуренции и HAProxy 0,25/0,5 CPU имеют перекрывающиеся диапазоны; их эффект не заявляется как отдельное улучшение. Все измерения ограничены одной Docker VM и конкретным синтетическим профилем.
## Результаты и ограничения
Офлайн структурная проверка, API smoke, гонка идемпотентности, перезапуск и failover пройдены; подробный stdout сохранён в `evidence/lab3-checks.txt`. Полная OpenAPI/JSON Schema проверка требует `openapi-spec-validator==0.7.2` из `requirements-dev.txt`; установить зависимость в этой среде не удалось из-за недоступного DNS PyPI. HTTP используется только на loopback для синтетических данных. Эта схема выдерживает отказ одного API-процесса при работающих HAProxy, host, PostgreSQL и Valkey; она не выдерживает потерю Docker-host, HAProxy или PostgreSQL. При отказе Valkey действующие сессии проверяются по PostgreSQL. Отдельной HA базы данных и второго узла нет. Под нагрузкой при rolling replacement замерены 24 ошибки на 50 315 запросов (0,048%); для повторения именно операции создания сообщения клиент должен повторить запрос с тем же `Idempotency-Key`. Другие POST-операции не обещают прозрачную идемпотентность.