- 2 API-реплики (api-1, api-2) с уникальным INSTANCE_ID - Nginx load balancer с health-check и failover - PostgreSQL источник истины, Valkey кэш сессий - Idempotency-Key в заголовке, replay возвращает исходное сообщение - X-Instance-Id в каждом ответе для идентификации реплики - /version и /info эндпоинты - Housekeeping-loop для очистки истёкших сессий и ключей - stop-one.sh/cmd для failover-теста, restart.sh/cmd для persistence - Исправлены импорты config/models/api/store/sessions - Добавлены миграции 004 (idempotency), 005 (indexes), 006 (message_id) - Отчёт с доказательствами критериев уровня 3 и 4 - Все тесты проходят: smoke, 26 student tests, failover, persistence, degradation
17 KiB
Отчёт — лабораторная 3
- Автор, группа: Тимофей Александров, БВТ2301
- Целевая оценка; выбранный трек 5, если нужен: 4 (трек 5 не заявлен)
- 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 сообщений)
Безопасная остановка с сохранением данных: 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 с и одновременно не дольше остатка жизни сессии. Кэш записывается при логине и при каждом cache-miss, инвалидируется логаутом через tombstone revoked (а не DEL: устаревшая запись обязана стать недействительной). Если 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}$). Хранится в таблице idempotency_keys вместе с SHA-256 тела запроса и message_id. Повтор с тем же ключом и тем же телом возвращает исходное сообщение (201); другой body → 409. Миграция 006 добавляет message_id для возврата оригинального сообщения при replay.
Ограничения и таймауты. Пул 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 |
| Нагрузочный прогон | 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 строк |
не применимо |
Ограничения и следующие шаги
- Выдерживается: отказ одной API-реплики (LB перенаправляет на вторую), отказ Valkey (полный обход кэша), кратковременный отказ PostgreSQL (ограниченная ошибка и быстрый возврат), рестарт всего стека с сохранением данных. Не выдерживается: одновременный выход обоих хранилищ из-под
up --wait(стенд перестаёт готовиться — это ожидаемо), потеря PostgreSQL-тома вместе с контейнером. - Локальный кэш отозванных токенов и circuit breaker не разделяются между репликами. Для уровня 5 с несколькими репликами нужно вынести отзыв в общее хранилище.
- Нагрузочный тест закрытого цикла содержит coordinated omission и накладные издержки клиента; это не доказательство ёмкости. Повторов и замера CPU/RAM не делалось.
makeв среде отсутствует, поэтому все команды выполнялись напрямую;Makefileсохранён для Linux/CI.- На Windows
.sh-скрипты не запускаются напрямую (WinError 193); созданы эквиваленты.cmd(restart.cmd,stop-one.cmd). На Linux grading-стенде используются.sh.