Files
mtusi2026lab2/REPORT.md
T

14 KiB
Raw Blame History

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

  • Автор, группа: TODO (заполняет студент)
  • Целевая оценка; выбранный трек 5, если нужен: 4 (уровень 3 + уровень 4); трек 5 не заявлен
  • Commit/PR: TODO после публикации (ветка solution/БВТ2301-Журавский)
  • Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.6, Pydantic 2.10.6, Uvicorn 0.34.0, psycopg 3.2.3 + psycopg-pool 3.2.4, argon2-cffi 23.1.0, redis-py 5.2.1 (клиент для Valkey); openapi-spec-validator и pytest только для проверок. Документация PostgreSQL (transactions, EXPLAIN), Valkey/Redis persistence, RFC 7617. Помощь ИИ: генерация каркаса и текста, проверено запуском тестов.

Запуск из чистого clone

Версии и prerequisites

Компонент Версия / образ
Runtime Python 3.11.9
API-образ python:3.11.9-slim-bookworm (пин; digest sha256:8fb099…c317)
PostgreSQL postgres:16.6-bookworm
Valkey valkey/valkey:8.0.2-alpine
Docker / Compose 26.1.4 / v2.27.1
Python-зависимости requirements.txt (пины: fastapi, pydantic, uvicorn, psycopg[binary], psycopg-pool, argon2-cffi, redis)
Стенд Windows 10 Pro 10.0.19045, Ryzen 5 3600 (6C/12T), 15.9 GiB RAM; persistence-хук выполняется в WSL Ubuntu 22.04 (Python 3.12) и на Linux-раннере

Prerequisites: Docker с Linux-контейнерами и плагином Compose. На Windows для scripts/restart.sh нужен POSIX-shell (WSL/Git Bash) либо Linux-раннер; публичный smoke и make check работают где угодно.

Создание локальных secrets (не коммитятся)

sh scripts/gen-secrets.sh
# создаёт ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url
# либо: cp secrets.example/* secrets/ и вписать свой пароль

Запуск, миграции, проверка, остановка

docker compose --env-file .env config --quiet      # 1. валидация конфигурации
docker compose --env-file .env up -d --build       # 2. сборка и запуск API+PostgreSQL+Valkey
docker compose ps                                  # 3. дождаться healthy у всех трёх

# Миграции применяются автоматически на старте API (идемпотентно, под advisory-lock);
# отдельно: docker compose exec -T api python -m src.migrate

python tests/smoke.py --base-url http://localhost:8080          # 4. публичный smoke
.venv\Scripts\python -m pytest student-tests -v                 #    свои тесты (см. ниже)

# Сохранность: перезапуск API и всех хранилищ с сохранением volumes
make test-persistence ACTION_SCRIPT=scripts/restart.sh           # выполнять в WSL/Linux

# Отказы и expiry
python scripts/check-degradation.py        # Valkey/PG down -> 200/503, восстановление
sh scripts/check-expiry.sh                 # короткий TTL -> 401

# Безопасная остановка (данные сохраняются):
docker compose stop

# Намеренное удаление учебных данных (тома):
docker compose down -v

Оператору нужно: сгенерировать secrets, выполнить шаги 1–4. Повторная сборка — docker compose up -d --build. down -v удаляет данные PostgreSQL и Valkey; обычная остановка/down (без -v) их сохраняет.

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

Схема: клиент → API (FastAPI/Uvicorn) → PostgreSQL (источник истины); Valkey — read-through кэш сессий.

  • Источник истины — PostgreSQL. Таблицы users (PK, UNIQUE(username), password_hash), chats, chat_members (FK, составной PK), messages (FK), sessions (token_hash PK, user_id, expires_at), schema_migrations.
  • Транзакционные границы. Создание чата — одна транзакция (вставить chats + всех chat_members); при невалидных участниках — rollback и 400, частичный объект не остаётся. Регистрация полагается на UNIQUE(username); гонка даёт ровно одного победителя и 409 остальным.
  • Аутентификация lab2. POST /api/v1/users требует password (12–128 code points). Пароль хранится как Argon2id (argon2-cffi), не в открытом виде. POST /api/v1/auth/sessions принимает только Authorization: Basic base64(username:password) и выдаёт opaque-токен (secrets.token_urlsafe(32), ≥256 бит). В БД хранится SHA-256 токена, не сам токен. Все бизнес-endpoint требуют Bearer; X-User-Id игнорируется. DELETE /api/v1/auth/sessions/current отзывает сессию и отдаёт 204.
  • Сессии и кэш. Сессия валидна, пока sessions.expires_at > now() (TTL = SESSION_TTL_SECONDS). Valkey кэширует session:{sha256(token)} → user_id с TTL до конца жизни сессии. Кэш не является источником истины: current_user всегда затем читает пользователя из PostgreSQL. При недоступности Valkey кэш обходится (операция ограничена таймаутом 0.5 c + mini circuit breaker, т.к. DNS остановленного контейнера может блокироваться); при недоступности PostgreSQL — ограниченный 503, анонимный пользователь не считается доверенным.
  • Индекс истории. messages(chat_id, created_at, id) под keyset-запрос WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4; пагинация не сканирует всю историю. Подтверждено EXPLAIN на ≥10 000 сообщений.
  • Пул и таймауты. psycopg_pool.ConnectionPool ограничен DB_POOL_MAX (default 10), DB_POOL_TIMEOUT (5 c); на соединении statement_timeout=DB_STATEMENT_TIMEOUT_MS (5000 мс). Все запросы параметризованы.
  • Перенос из lab1. Сохранён HTTP-каркас (маршруты, конверт ошибок, X-Request-Id, keyset-cursor), но слой данных переписан на PostgreSQL, добавлены миграции, аутентификация заменена на password + Basic/Bearer. X-User-Id удалён. In-memory store.py lab1 не переносился.

Соответствие .env.example

Переменная Роль в решении
APP_HOST, APP_PORT адрес/порт Uvicorn (src/main.py); в compose 0.0.0.0:8080
APP_ENV метка в лог-строке запуска
SESSION_TTL_SECONDS срок жизни сессии (sessions.expires_at) и TTL кэша
SESSION_STORE valkey/redis — включить кэш Valkey; postgres — без кэша
DATABASE_URL_FILE файл с DSN PostgreSQL (compose secret /run/secrets/database_url)
CACHE_URL_FILE файл с URL Valkey (compose secret /run/secrets/cache_url)

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab2 public API scenario evidence/lab2-smoke.txt
Persistence: данные и сессии переживают рестарт API и хранилищ без удаления volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh (WSL) PASS: persistence preserved confirmed data and existing session; контейнеры перезапущены, volumes на месте evidence/lab2-persistence.txt
Миграции запускаются с нуля и повторно без дублирования docker compose exec -T api python -m src.migrate migrations up to date; в schema_migrations одна строка evidence/lab2-migrations.txt
PostgreSQL хранит users/chats/members/messages; PK/FK/UNIQUE; атомарное создание чата схема + test_race.py, test_negative.py rollback при неизвестном участнике; 409 при дубликате username evidence/lab2-student-tests.txt
Basic только на /auth/sessions; Bearer для остальных; TTL и отзыв; X-User-Id не даёт доступ; пароли — KDF test_auth.py 401 Basic/Bearer с корректным challenge; logout → 401 evidence/lab2-student-tests.txt
Уровень 4: Valkey реально используется с TTL, источник истины и политика описаны check-degradation.py, check-expiry.sh cache bypass при отказе Valkey; expiry → 401 evidence/lab2-degradation.txt, evidence/lab2-expiry.txt
Уровень 4: параметризованный SQL, ограниченный pool, таймауты; гонка регистрации и rollback test_race.py один 201 и четыре 409; частичный чат не создан evidence/lab2-student-tests.txt
Уровень 4: индекс обоснован EXPLAIN на ≥10 000 сообщений, пагинация без full scan EXPLAIN (ANALYZE, BUFFERS) Index Scan using messages_chat_created_id_idx, 0.113 мс, 52 буфера evidence/lab2-explain.txt
Уровень 4: expiry при коротком TTL, logout, неверный пароль, недоступность Valkey/БД check-expiry.sh, test_auth.py, check-degradation.py expiry 401; logout 401; Valkey down → 200; PG down → 503 evidence/lab2-expiry.txt, evidence/lab2-student-tests.txt, evidence/lab2-degradation.txt
Безопасность: секреты вне Git, .env/volumes не коммитятся .gitignore, secrets.example/, scripts/gen-secrets.sh git status без .env/secrets/ описание в PR

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

Гипотеза: PostgreSQL — источник истины, поэтому рестарт API и хранилищ не теряет данные и активные сессии; Valkey можно потерять без остановки API; потеря PostgreSQL даёт ограниченный 503, а не обход аутентификации. Методика: реальный compose-стенд, синтетические данные, хуки в WSL.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart api postgres valkey данные и сессия сохранены PASS: persistence preserved confirmed data and existing session рестарт ≈ секунды; потерь нет
Остановка Valkey API продолжает работать, /health/ready=200 /users/me=200, /health/ready=200 (кэш обойдён) ~0.5 c на операцию кэша, далее fast-path
Остановка PostgreSQL /health/ready=503; аноним не доверяется /health/ready=503, /users/me=503, анонимным=503 восстановление после старта PG; сессия сохранилась
Гонка регистрации одинакового username (5 потоков) ровно один победитель 1×201, 4×409 n/a
Ошибка составной операции (неизвестный участник) rollback, чат не создан 400; число чатов не изменилось n/a
Короткий SESSION_TTL_SECONDS=2 сессия истекает before=200, after=401 ~2 c

Замеры: единичный стенд на одном Docker-host (Windows/WSL2); throughput-исследование не заявлено (трек 5 не выбран). Числа latency кэша/БД — из логов и EXPLAIN.

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

  • Выдерживается: перезапуск API и хранилищ с volumes, потеря Valkey (кэш), короткий отказ PostgreSQL с восстановлением, гонки и откат составных операций, некорректный ввод.
  • Не выдерживается и не заявлено: отказ самого Docker-host, несколько API-реплик и балансировщик (lab3), вложения (lab4). Единственный инстанс PostgreSQL/Valkey не высокодоступен.
  • Учебные упрощения: HTTP без TLS (допустимо для изолированного стенда lab1–6); нет rate limiting и лимитов памяти (трек 5); хук restart.sh перезапускает сервисы, а не выполняет rolling-обновление.
  • Подтверждено измерениями: сохранность после рестарта, использование индекса (EXPLAIN), отсутствие доверия кэшу/анониму. Гипотеза на будущее: поведение при росте числа реплик и кэш-согласованности — кандидат на трек 5 следующей лабы.