Files
mtusi2026lab2/REPORT.md
T
2026-10-30 19:37:21 +03:00

17 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: TODO (заполняется перед публикацией PR)
  • Целевая оценка; выбранный трек 5, если нужен: 4 (трек 5 не заявлен)
  • Commit/PR: TODO после публикации
  • Использованные источники, библиблиотеки и помощь ИИ: README/COURSE/CONTRIBUTING этого skeleton, contracts/README.md и tests/README.md; документация PostgreSQL (transactions, EXPLAIN), Valkey (persistence), RFC 7617 (Basic), OWASP Password Storage Cheat Sheet (Argon2id). Библиотеки: FastAPI/Starlette/uvicorn, psycopg 3 + psycopg-pool, redis-py, argon2-cffi (списки в requirements.txt).

Запуск из чистого 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 — образы закреплены по digest в compose.yaml. Аппаратура стенда: 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
docker compose --env-file .env logs api | grep migrations   # migrations_applied / migrations_up_to_date

# 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:8080                 # = make test
python3 tests/resilience.py --mode persistence \
    --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080 # = make test-persistence
sh scripts/test-ttl.sh                    # = make test-ttl (отдельный стенд на :8081, SESSION_TTL_SECONDS=2)
cd student-tests && STUDENT_DOCKER_TESTS=1 BASE_URL=http://127.0.0.1:8080 \
    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).

URL вида http://127.0.0.1:8080, а не localhost: Compose публикует только IPv4-порт, а на dual-stack хосте localhost сначала идёт в ::1 и добавляет ~2 с TCP-retry к каждому запросу (это и было причиной первоначальных «медленных» тестов).

Архитектура и решения

Процессы/хранилища. Клиент → api (FastAPI + uvicorn, один процесс) → postgres (источник истины) и valkey (кэш сессий). Сеть backend внутренняя, наружу публикуется только 127.0.0.1:${API_PUBLISH_PORT:-8080}:8080. Логика в src/, SQL-миграции в src/migrations/.

Что перенесено из lab1. Тот же контракт и та же логика keyset-пагинации, но хранилище заменено с in-memory dict на PostgreSQL; X-User-Id больше не используется нигде (входящее поле игнорируется, проверено тестом); вместо Basic-входа на каждый запрос — Basic только на POST /api/v1/auth/sessions и Bearer-токен на остальных.

Источник истины и кэш. Сессии живут в таблице sessions (хранится только SHA-256 токена). Valkey хранит тот же токен под session:<sha256> максимум CACHE_TTL_SECONDS=300 с и одновременно не дольше остатка жизни сессии. Кэш записывается при логине и при каждом cache-miss, инвалидируется логаутом через tombstone revoked (а не DEL: устаревшая запись обязана стать недействительной). Если Valkey недоступен — каждый запрос просто идёт в PostgreSQL; кэш-ошибка никогда не означает «авторизован». Плюс 5-секундный circuit breaker: после первой ошибки соединения Valkey пропускается ~5 с, чтобы отказ не стоил таймаута на каждый запрос (до внедрения breaker падение кэша стоило ~1031 мс на запрос, стало 39 мс).

Транзакционные границы. Создание чата (chats + строки chat_members) — одна транзакция: ошибка хотя бы одного участника откатывает всё (проверено: в таблицах остаётся 0 строк). Регистрация и отправка сообщения — по одной транзакции. Миграции — версионированный раннер src/migrate.py: одна транзакция + pg_advisory_xact_lock, таблица schema_migrations, повторный запуск печатает migrations_up_to_date и не дублирует данные; запуск идемпотентен и защищён от параллельных контейнеров.

Ограничения и таймауты. Пул 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, никакой конкатенации SQL). Кэш-операции ограничены 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. WWW-Authenticate различает Bearer и Basic.

Секреты. 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 → одноимённые поля Settings; DATABASE_URL_FILE/CACHE_URL_FILE → _secret(), с падением на старт-апе при нечитаемом файле; SESSION_STORE допускает только postgres (иное значение — явная ошибка конфигурации, а не тихий обход).

Доказательства критериев

Все выводы сохранены в evidence/ (без токенов и секретов); файлы сгенерированы 2026-10-30, commit указывается в PR.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python3 tests/smoke.py --base-url http://127.0.0.1:8080 PASS: lab2 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.cmd … PASS: persistence preserved confirmed data and existing session evidence/persistence.txt
Миграции, транзакции, гонка username, откат создания чата python3 -m unittest -v test_api test_race 26/26 OK, 14.8 с, включая duplicate_username_race (ровно 1 пользователь) и chat_creation_rolls_back_on_unknown_member evidence/student-tests.txt
Ограниченный пул и параллельные чтения там же, bounded_pool_serves_parallel_reads OK; 100 записей от 10 клиентов за 3.08 с, ровно 100 строк evidence/student-tests.txt
Индекс истории, EXPLAIN ≥ 10 000 строк, без OFFSET sh scripts/explain-history.sh 12 000 сообщений: страница глубоко в истории — Index Scan, 4 буфера, 0.208 мс; вариант OFFSET (не используется) — Seq Scan + Sort, 205 буферов, 14.0 мс evidence/explain-history.txt
Автопроверка expiry при коротком TTL, logout, неверный пароль sh scripts/test-ttl.sh (стенд SESSION_TTL_SECONDS=2, :8081) 4/4 OK, 6.1 с; кэш не продлевает жизнь токену, logout мгновенен и при закэшированной сессии evidence/test-ttl.txt
Недоступность Redis/Valkey и БД STUDENT_DOCKER_TESTS=1 python3 -m unittest -v test_degradation OK, 21.4 с: cached_p50=16 мс, cache_down_p50=39 мс, cache_down_p95=78 мс, /health/ready остаётся 200 при падении кэша и становится 503 unavailable при падении БД, запись отказывает за 2.05 с, восстановление 0.58 с, после восстановления та же сессия и те же сообщения evidence/test-degradation.txt
Нагрузочный прогон (не оценочный критерий) python3 tests/load.py … --duration 20 --concurrency 4 25.5 успешных req/s, 523 запроса, 0 ошибок, p50 125 мс, p95 328 мс, p99 484 мс evidence/load.json, evidence/load.txt

Дополнительно: docker compose --env-file .env ps показывает api/postgres/valkey — healthy; на стенде 204 пользователя, 68 чатов, 13 286 сообщений, 174 сессии (синтетические).

Эксперименты и отказы

Методика: закрытый цикл 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-лимитов. Прогрев — один smoke-проход и два чтения /users/me перед замером. Результаты одного прогона, повторов не делалось (см. ограничения).

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose stop valkey api продолжает работать через PostgreSQL, readiness 200, ошибка кэша не считается успехом авторизации после breaker-а p50 39 мс (без него — 1031 мс: две попытки подключения на запрос), 60 из 60 запросов 200 восстановление compose start valkey — 0.6–3 с; данных не теряется
docker compose stop postgres ограниченная ошибка, никогда 200 и никогда сырая 500 /health/ready → 503 unavailable, запись → 503 за 2.05 с, в ответе нет ни psycopg, ни postgresql://, ни Traceback; неизвестный токен — 401/503, но не 200 compose start postgres → ready 200 за 0.58–1.75 с, объём не тронут (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 строк не применимо
Создание записи в chats/messages с обычной нагрузкой закрытый цикл выдерживает 25.5 rps, p95 328 мс, 0 ошибок за 20 с не применимо

Сиреневой AOF (--appendfsync everysec) в Valkey: потеря до ~1 с кэша при жёстком выключении ВМ не критична, так как PostgreSQL — источник истины.

Ограничения и следующие шаги

  • Выдерживается: отказ Valkey (полный обход кэша), кратковременный отказ PostgreSQL (ограниченная ошибка и быстрый возврат), рестарт всего стека с сохранением данных. Не выдерживается: одновременный выход обоих хранилищ из-под up --wait (стенд перестаёт готовиться — это ожидаемо), потеря PostgreSQL-тома вместе с контейнером.
  • Один процесс api: локальный кэш отозванных токенов и circuit breaker не разделяются между репликами. Для уровня 3 с несколькими репликами (X-Instance-Id, failover) нужно вынести отзов в общее хранилище и согласовать поведение между инстансами.
  • Нагрузочный тест закрытого цикла содержит coordinated omission и накладные издержки клиента; это не доказательство ёмкости. Повторов и замера CPU/RAM не делалось — цифры выше относятся к одному прогону.
  • EXPLAIN снят на 12 000 сообщений (требование ≥10 000 выполнено), но без неравномерного распределения по чатам и без backup/restore — это уже трек 5, который не заявлен.
  • Кэш-запись — best effort: при недоступном Valkey запись пропускается, а не блокирует ответ (источник истины не затронут).
  • make в среде отсутствует, поэтому все команды выполнялись напрямую; Makefile сохранён для Linux/CI.