21 KiB
Отчёт — лабораторная 3
- Автор, группа: Тимофей Александров, БВТ2301
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 1 «Цена масштабирования»
- Commit/PR: подготовлен к публикации
- Использованные источники, библиотеки и помощь ИИ: README/COURSE/CONTRIBUTING этого skeleton,
contracts/README.mdиtests/README.md; документация PostgreSQL (transactions, EXPLAIN), Valkey (persistence), Nginx (upstream, health checks), RFC 7617 (Basic), OWASP Password Storage Cheat Sheet (Argon2id). Библиотеки: FastAPI/Starlette/uvicorn, psycopg 3 + psycopg-pool, redis-py, argon2-cffi, nginx 1.27. Лабораторная 3 построена на кодовой базе лабораторной 2.
Запуск из чистого clone
Версии, на которых всё воспроизведено: Docker Engine 29.9.2, Docker Compose v5.6.1, на хосте Python 3.11.5 (нужен только для скриптов и тестов), внутри контейнера Python 3.12.7 (python:3.12.7-slim-bookworm), PostgreSQL 17.6, Valkey 8.1.3, Nginx 1.27-alpine — образы закреплены (postgres и valkey по digest, nginx без digest). Аппаратура стенда: Intel Pentium Silver N5030 @ 1.10 GHz, 4 логических ядра, ~7.6 GiB RAM, лимитов CPU/RAM для контейнеров не задано.
Нужны: Git с POSIX-shell (на Windows — Git Bash, скрипты scripts/*.sh) и Docker с Compose. make в этой среде отсутствует, поэтому ниже приведены те же команды напрямую (сам Makefile сохранён и использует те же пути).
# 1) секреты и .env: генерирует ./secrets (mode 0600, в .gitignore) и копирует .env
sh scripts/bootstrap-secrets.sh # на Windows: sh из Git Bash
# 2) проверка конфигурации и подъём стенда (миграции применяет entrypoint контейнера api)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180
docker compose --env-file .env ps
# 3) проверки
python3 scripts/check_contract.py # = make check
python3 scripts/validate_openapi.py # = make validate (нужен requirements-dev.txt)
python3 tests/smoke.py --base-url http://127.0.0.1:8081 # = make test (порт 8081)
python3 tests/resilience.py --mode persistence \
--action-script scripts/restart.sh --base-url http://127.0.0.1:8081 # = make test-persistence
python3 tests/resilience.py --mode failover \
--action-script scripts/stop-one.sh --base-url http://127.0.0.1:8081 # = make test-failover
TARGET_INSTANCE_ID=api-1 sh scripts/stop-one.sh # остановить одну реплику
cd student-tests && BASE_URL=http://127.0.0.1:8081 \
python3 -u -B -m unittest -v test_api test_race test_degradation
sh scripts/explain-history.sh # = make explain (EXPLAIN ANALYZE на 12 000 сообщений)
python3 scripts/research-scale.py --base-url http://127.0.0.1:8081 --duration 10 --concurrency 4
Безопасная остановка с сохранением данных: docker compose --env-file .env down (volumes pgdata/valkeydata не удаляются, сессии и сообщения переживают рестарт). Намеренное удаление учебных данных: docker compose --env-file .env down -v. На Windows эквивалент restart-hook для tests/resilience.py — scripts/restart.cmd (тот же сценарий, что и scripts/restart.sh: down без -v, затем up -d --wait; Python не умеет запускать .sh напрямую, ошибка WinError 193). Аналогично для failover — scripts/stop-one.cmd.
URL вида http://127.0.0.1:8081, а не localhost: Compose публикует только IPv4-порт, а на dual-stack хосте localhost сначала идёт в ::1 и добавляет ~2 с TCP-retry к каждому запросу.
Архитектура и решения
Процессы/хранилища. Клиент → nginx (load balancer, публичный entrypoint) → api-1 / api-2 (FastAPI + uvicorn, два процесса) → postgres (источник истины) и valkey (кэш сессий). Сеть backend внутренняя, наружу публикуется только 127.0.0.1:${API_PUBLISH_PORT:-8081}:8080 через nginx. Логика в src/, SQL-миграции в src/migrations/.
Что перенесено из lab2. Тот же контракт и та же логика keyset-пагинации, но хранилище заменено с in-memory dict на PostgreSQL; X-User-Id больше не используется нигде (входящее поле игнорируется, проверено тестом); вместо Basic-входа на каждый запрос — Basic только на POST /api/v1/auth/sessions и Bearer-токен на остальных. Добавлены: X-Instance-Id в каждом ответе (идентификация реплики), /version и /info эндпоинты, housekeeping-loop (очистка истёкших сессий и idempotency-ключей), таблица idempotency_keys с миграцией 004 и индексами миграции 005.
Балансировка и отказ API-реплики (новое в lab3). Два API-инстанса (api-1, api-2) с разными INSTANCE_ID. Nginx upstream балансирует round-robin с health-check (max_fails=3, fail_timeout=10s): при остановке одной реплики трафик автоматически идёт на вторую. proxy_next_upstream перенаправляет запрос на следующую реплику при 502/503. Порты API-реплик не публикуются наружу — только через LB. Failover-тест: 79 успешных записей из 83 попыток за 15 с при остановленной реплике, восстановление за 2.6 с.
Источник истины и кэш. Сессии живут в таблице sessions (хранится только SHA-256 токена). Valkey хранит публичный снимок пользователя под session:<sha256> максимум CACHE_TTL_SECONDS=300 с и одновременно не дольше остатка жизни сессии. Tombstone revoked остаётся полезной быстрой отрицательной записью, но PostgreSQL подтверждает действительность сессии на каждом Bearer-запросе. Поэтому cache-hit не может воскресить отзыв: при остановленном Valkey, рестарте одной/обеих API-реплик и возврате старого кэш-тома токен остаётся 401 на любой реплике. Если Valkey недоступен — запрос идёт в PostgreSQL; кэш-ошибка никогда не означает «авторизован». Плюс 5-секундный circuit breaker.
Транзакционные границы. Создание чата (chats + строки chat_members) — одна транзакция. Регистрация и отправка сообщения — по одной транзакции. Миграции — версионированный раннер src/migrate.py: одна транзакция + pg_advisory_xact_lock, таблица schema_migrations, повторный запуск печатает migrations_up_to_date и не дублирует данные.
Idempotency-Key (новое в lab3). Ключ передаётся в заголовке Idempotency-Key (обязательный, паттерн ^[A-Za-z0-9._:-]{1,128}$). Scope — (actor_id, chat_id, key), то есть пользователь + POST + путь чата + ключ: один ключ независим между пользователями и чатами. Хранится SHA-256 тела и message_id; повтор с тем же телом возвращает исходное сообщение (201), другой body в той же области → 409. Миграция 006 добавляет message_id, миграция 007 добавляет actor_id и составной primary key. Резервирование ключа использует INSERT ... ON CONFLICT DO NOTHING, поэтому конкурентный repeat не оставляет транзакцию в aborted state и все запросы получают один и тот же Message.
Ограничения и таймауты. Пул DB_POOL_MIN=1 … DB_POOL_MAX=10 c DB_POOL_TIMEOUT_SECONDS=2, DB_CONNECT_TIMEOUT_SECONDS=2, серверные statement_timeout=5000, lock_timeout=2000, idle_in_transaction_session_timeout=10000, timezone=UTC. Все запросы параметризованные (psycopg3). Кэш-операции ограничены CACHE_TIMEOUT_SECONDS=0.5.
Аутентификация. Пароли — Argon2id через argon2-cffi (19 MiB, 2 итерации, 1 lane; для неизвестного пользователя проверяется dummy-hash). Токен — secrets.token_urlsafe(48) = 384 бита, в БД только его SHA-256. SESSION_TTL_SECONDS (3600 по умолчанию), отзыв через DELETE /api/v1/auth/sessions/current.
Секреты. scripts/bootstrap-secrets.sh генерирует ./secrets/* (mode 0600, каталог в .gitignore), compose монтирует их как файлы (DATABASE_URL_FILE, POSTGRES_PASSWORD_FILE, …), значения не попадают в compose.yaml, docker inspect, логи или отчёт.
Соответствие .env.example ↔ src/config.py. APP_HOST/APP_PORT → load_address(); SESSION_TTL_SECONDS, CACHE_TTL_SECONDS, DB_POOL_*, DB_*_TIMEOUT*, CACHE_TIMEOUT_SECONDS, IDEMPOTENCY_TTL_SECONDS → одноимённые поля Settings; DATABASE_URL_FILE/CACHE_URL_FILE → _secret(), с падением на старт-апе при нечитаемом файле; SESSION_STORE допускает только postgres; INSTANCE_ID → settings.instance_id.
Доказательства критериев
Все выводы сохранены в evidence/ (без токенов и секретов); файлы сгенерированы 2026-10-30.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python3 tests/smoke.py --base-url http://127.0.0.1:8081 |
PASS: lab3 public API scenario |
evidence/smoke.txt |
| make check: структура/контракт | python3 scripts/check_contract.py |
PASS: offline skeleton structure, local refs and Python syntax |
строка в PR |
| Полная валидация OpenAPI | python3 scripts/validate_openapi.py |
PASS: full OpenAPI 3.1 and JSON Schema validation |
строка в PR |
| Уровень 3: рестарт сохраняет данные и сессию | python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh … |
PASS: persistence preserved confirmed data and existing session |
evidence/persistence.txt |
| Уровень 3: failover — остановка одной реплики | python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh … |
PASS: failover preserved confirmed data and existing session; 79 успешных записей из 83, восстановление за 2.6 с |
evidence/failover.txt |
| Миграции, транзакции, гонка username, откат создания чата | python3 -m unittest -v test_api test_race |
26/26 OK, включая duplicate_username_race (ровно 1 пользователь) и chat_creation_rolls_back_on_unknown_member |
evidence/student-tests.txt |
| Ограниченный пул и параллельные чтения | там же, bounded_pool_serves_parallel_reads |
OK; 100 записей от 10 клиентов за 2.50 с, ровно 100 строк | evidence/student-tests.txt |
| Индекс истории, EXPLAIN ≥ 10 000 строк, без OFFSET | sh scripts/explain-history.sh |
12 000 сообщений: страница глубоко в истории — Index Scan; вариант OFFSET (не используется) — Seq Scan + Sort | evidence/explain-history.txt |
| Недоступность Redis/Valkey и БД | STUDENT_DOCKER_TESTS=1 python3 -m unittest -v test_degradation |
OK: cached_p50=31 мс, cache_down_p50=47 мс, cache_down_p95=110 мс, /health/ready остаётся 200 при падении кэша и становится 503 при падении БД, запись отказывает за 2.05 с, восстановление за 1.97 с |
evidence/test-degradation.txt |
| Durable logout на обеих репликах | test_logout_remains_revoked_across_replicas_after_cache_outage |
OK: остановка Valkey → logout → restart api-1/api-2 → запуск Valkey с прежним томом; прежний токен получает 401 на GET/POST | evidence/test-degradation-grade5.txt |
| Scope и конкурентность idempotency | python -m unittest -v test_idempotency |
2/2 OK: одинаковый key независим для разных user/chat; 32 одинаковых POST → 32×201 одного Message, без 500 | evidence/idempotency-grade5.txt |
| Трек 5: 1/2/4 API-реплики | python scripts/research-scale.py --duration 10 --concurrency 4 |
fixed total saturation: 36.9 / 49.4 / 36.2 RPS; growing resources: 42.4 / 45.2 / 57.0 RPS | evidence/scale-summary.json, evidence/scale-*.json |
| Нагрузочный прогон | python3 tests/load.py … |
результаты в evidence/load.json | evidence/load.json |
Дополнительно: docker compose --env-file .env ps показывает api-1/api-2/postgres/valkey/nginx — healthy; балансировка round-robin между двумя репликами подтверждена заголовком X-Instance-Id.
Эксперименты и отказы
Методика: закрытый цикл POST /api/v1/chats/{id}/messages, 4 потока, 20 с, без ретраев, клиент — tests/load.py; латентность считается только по успешным запросам. Хост: Intel Pentium Silver N5030 @ 1.10 GHz, 4 логических ядра, ~7.6 GiB RAM; Docker Desktop, контейнеры без CPU/RAM-лимитов.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose stop api-1 (одна реплика) |
LB перенаправляет трафик на api-2, API продолжает работать | 79 успешных записей из 83 попыток за 15 с, 4 неудачных (во время переключения), восстановление за 2.6 с; целевая реплика больше не обслуживает запросы | восстановление docker compose start api-1 — ~30 с до healthy; данных не теряется |
docker compose stop valkey |
api продолжает работать через PostgreSQL, readiness 200 |
после breaker-а p50 47 мс, 60 из 60 запросов 200 | восстановление compose start valkey — 0.6–3 с; данных не теряется |
docker compose stop postgres |
ограниченная ошибка, никогда 200 | /health/ready → 503 unavailable, запись → 503 за 2.05 с, в ответе нет ни psycopg, ни postgresql://, ни Traceback |
compose start postgres → ready 200 за 1.97 с, объём не тронут (volumes) |
Полный рестарт стека (down + up -d --wait) |
сессия и данные те же, volumes сохраняются | PASS: persistence preserved confirmed data and existing session |
~20 с, потеря данных: 0 |
| Гонка 20 параллельных регистраций одного username | ровно один INSERT, остальные 409 |
1 пользователь в БД, ответы 201/409 | не применимо |
| Регистрация чата с неизвестным участником | откат всей операции | в chats/chat_members 0 строк |
не применимо |
Трек 5 — Цена масштабирования
Гипотеза. При фиксированном общем бюджете CPU/RAM после двух API-реплик дополнительное размножение процессов не ускорит PostgreSQL-bound запись и повысит tail latency; при росте суммарного бюджета 4 реплики должны дать прирост.
Методика. scripts/research-scale.py использует один closed-loop профиль POST messages (tests/load.py, 4 клиента, 10 секунд, без retry) и сохраняет raw JSON для каждой точки. В режиме fixed_total общий лимит API равен 2 CPU / 1024 MiB и делится между 1/2/4 репликами. В режиме growing_total каждая реплика получает 1 CPU / 512 MiB. Overlay compose.scale.yaml добавляет api-3/api-4 только для исследования; по завершении скрипт возвращает обычный двухрепличный стенд.
Результат. При фиксированном бюджете: 1 → 36.921 RPS (p95 172 мс), 2 → 49.412 RPS (p95 172 мс), 4 → 36.171 RPS (p95 281 мс). Saturation наблюдается после 2 реплик: PostgreSQL и конкуренция за суммарно ограниченный CPU становятся узким местом, а дополнительные процессы увеличивают p95/p99. При росте ресурсов: 1 → 42.374 RPS, 2 → 45.174 RPS, 4 → 57.007 RPS; p95 у 4 реплик 125 мс. Подтверждённое улучшение — увеличение суммарного бюджета с четырьмя репликами вместо деления фиксированного бюджета: +57.6% RPS против fixed-total 4.
Ограничения. Один повтор на Docker Desktop и закрытая модель нагрузки не дают production capacity claim; закрытый цикл содержит coordinated omission. CPU/RAM измерялись как назначенные Docker limits, а не как аппаратные counters. LB и PostgreSQL остаются SPOF; работа не заявляет отказоустойчивость их узлов.
Ограничения и следующие шаги
- Выдерживается: отказ одной API-реплики (LB перенаправляет на вторую), отказ Valkey (полный обход кэша), кратковременный отказ PostgreSQL (ограниченная ошибка и быстрый возврат), рестарт всего стека с сохранением данных. Не выдерживается: одновременный выход обоих хранилищ из-под
up --wait(стенд перестаёт готовиться — это ожидаемо), потеря PostgreSQL-тома вместе с контейнером. - Локальный pending-тombstone остаётся только оптимизацией при outage, но не является авторизационным решением: PostgreSQL проверяет revoke на каждой реплике. Поэтому отсутствие общего local cache не может воскресить токен.
- Нагрузочный тест закрытого цикла содержит coordinated omission и накладные издержки клиента; это не доказательство ёмкости. Повторов и замера CPU/RAM не делалось.
makeв среде отсутствует, поэтому все команды выполнялись напрямую;Makefileсохранён для Linux/CI.- На Windows
.sh-скрипты не запускаются напрямую (WinError 193); созданы эквиваленты.cmd(restart.cmd,stop-one.cmd). На Linux grading-стенде используются.sh.