Files
mtusi2026lab2/REPORT.md
T

194 lines
17 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.
Отчёт — лабораторная 2
Автор, группа: Кузнецова Марина, БВТ2304
Целевая оценка; выбранный трек 5. Трек 1 — согласованность кэша
Commit/PR: пока пусто
Использованные источники, библиотеки и помощь ИИ: официальная документация FastAPI, asyncpg, redis-py, PostgreSQL EXPLAIN, Docker Compose. ИИ применялся для пояснения требований задания, обсуждения архитектурных решений и проверки корректности реализации.
Запуск из чистого clone
Требования к окружению:
Python 3.13.15
Docker 26.1.1
git
Подготовка и запуск через Docker Compose:
cp .env.example .env
docker compose --env-file .env up -d --build
Ожидаемый признак готовности: ответ {"status":"ok"} на http://localhost:8080/health/ready. В логах api должны появиться строки applied migration: 001_users.sql ... 005_sessions.sql и Application startup complete.
Проверка публичным smoke-тестом (в отдельном терминале, при запущенном стенде):
python tests/smoke.py --base-url http://localhost:8080
Проверка собственными тестами:
pytest student-tests/ -v
Проверка сохранности (перезапуск API и PostgreSQL с сохранением volumes):
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080
Безопасная остановка:
docker compose down — остановка без потери данных.
docker compose down -v — удаление volumes, все данные пропадут. Использовать только для чистого повтора.
Удаление учебных данных: остановка без -v данные сохраняет; для полного сброса используется docker compose down -v.
Секреты: в .env.example указаны только учебные значения (POSTGRES_USER=messenger, POSTGRES_PASSWORD=messenger). Файл .env создаётся локально из .env.example и не коммитится.
Архитектура и решения
Схема:
Client → HTTP (FastAPI + Uvicorn) → PostgreSQL (users/chats/messages/sessions)
→ Valkey (sessions + cache)
Компоненты:
app/main.py — создание приложения FastAPI, lifespan (подключение к БД, применение миграций, создание Storage, SessionStore и Cache), middleware для X-Request-Id, обработчики ошибок, подключение роутеров.
app/config.py — конфигурация из переменных окружения: DATABASE_URL, SESSION_TTL_SECONDS, SESSION_STORE, CACHE_URL.
app/db.py — асинхронный пул соединений asyncpg (min_size=1, max_size=10, command_timeout=5, timeout=5).
app/migrations.py — простой раннер миграций: читает SQL-файлы из migrations/, применяет ещё не применённые, ведёт таблицу applied_migrations.
app/models.py — Pydantic-модели, включая новое поле password в CreateUser и модель Session.
app/security.py — Argon2id для паролей, генерация токенов, парсинг Basic и Bearer, извлечение пользователя из сессии.
app/storage.py — работа с PostgreSQL: пользователи, чаты, участники, сообщения. Параметризованные запросы, транзакции для составных операций.
app/session_store.py — два backend для сессий: PostgreSQL и Redis/Valkey. Выбор через SESSION_STORE.
app/cache.py — кэш истории сообщений и single-flight через Redis SET NX.
app/api/health.py — liveness и readiness. Readiness проверяет PostgreSQL и Valkey через asyncio.wait_for с таймаутом 2 секунды.
app/api/users.py, app/api/auth.py, app/api/chats.py — обработчики эндпоинтов.
migrations/*.sql — 5 миграций с нуля: users, chats, chat_members, messages, sessions.
compose.yaml — три сервиса: postgres, valkey, api.
Источник истины: PostgreSQL для пользователей, чатов, участников, сообщений и метаданных. Сессии — в Valkey с TTL 3600 секунд. Кэш истории — в Valkey с TTL 30 секунд. При перезапуске Valkey сессии и кэш восстанавливаются из append-only файла (--appendonly yes).
Транзакционные границы: операции с пользователями и сообщениями выполняются в одном SQL-запросе; создание чата вместе со всеми участниками — в одной транзакции asyncpg (BEGIN/COMMIT). Уникальность username гарантируется UNIQUE-констрейнтом в БД, а не проверкой в коде. При конфликте asyncpg бросает UniqueViolationError, который превращается в 409 conflict.
Идентификация и сессии. С lab2 применяется схема Basic → Bearer. POST /api/v1/auth/sessions принимает только Authorization: Basic base64(username:password), возвращает 201 с токеном (secrets.token_urlsafe(48), ~256 бит энтропии) и сроком действия. Все бизнес-эндпоинты требуют Authorization: Bearer <token>. X-User-Id с lab2 игнорируется: заголовок не меняет владельца сессии и сам по себе не даёт доступ. DELETE /api/v1/auth/sessions/current отзывает текущую сессию и возвращает 204 без тела. Истёкший, отозванный или неизвестный токен даёт 401 с WWW-Authenticate: Bearer realm="messenger".
Пароли хешируются Argon2id (argon2-cffi). Пароль и хеш никогда не возвращаются в API.
Обработка ошибок: единый формат {"error": {"code", "message", "request_id"}}. Заголовок X-Request-Id устанавливается на всех ответах через middleware. Если клиент прислал свой, возвращается он же, иначе генерируется новый. При недоступности PostgreSQL или Valkey /health/ready возвращает 503 unavailable без деталей.
Пагинация: keyset-cursor по паре (created_at, id). Вместо offset используется пара значений последнего элемента предыдущей страницы. Cursor непрозрачен для клиента, внутри это строка <created_at>|<id>. Такой подход не допускает пропусков и дублей при вставке новых элементов во время обхода.
Кэш истории. Ключ messages:<chat_id>:<limit>:<cursor>, TTL 30 секунд. При вставке нового сообщения add_message инвалидирует все ключи messages:<chat_id>:* — это обеспечивает read-after-write из контракта. Защита от cache stampede — single-flight через try_lock (SET NX EX 5): только один запрос получает lock и идёт в БД, остальные ждут в цикле, проверяя кэш.
Соответствие переменных .env.example:
APP_HOST / APP_PORT — задаются в compose.yaml как environment api.
SESSION_TTL_SECONDS — срок жизни сессии, по умолчанию 3600.
DATABASE_URL — строка подключения к PostgreSQL.
SESSION_STORE — postgres или redis. Для «4» установлено значение redis.
CACHE_URL — redis://valkey:6379/0.
Доказательства критериев «3»
Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Минимум lab1 с новой аутентификацией python tests/smoke.py --base-url http://localhost:8080 PASS: lab2 public API scenario лог терминала
Persistence python tests/resilience.py --mode persistence --action-script scripts/restart.cmd PASS: persistence preserved confirmed data and existing session лог терминала
Свои тесты pytest student-tests/ -v 15 passed (без test_cache) лог pytest
Basic только на /auth/sessions test_basic_on_business_endpoint_returns_401 PASS лог pytest
Bearer на бизнес-эндпоинтах test_x_user_id_ignored_with_bearer PASS лог pytest
Logout отзывает токен test_logout_invalidates_token PASS лог pytest
Неверный пароль test_wrong_password_returns_401 PASS лог pytest
Пароли хешируются Argon2id, PasswordHasher.hash — код
Доказательства критериев «4»
Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Redis/Valkey для сессий с TTL docker compose exec valkey valkey-cli TTL session:<token> ~3600 вывод команды
Persistence Valkey docker compose restart valkey + valkey-cli KEYS "session:*" ключи сохранились вывод команды
Ограниченный connection pool asyncpg.create_pool(min_size=1, max_size=10, command_timeout=5, timeout=5) — код
Гонка регистрации username test_race_duplicate_username_only_one_wins PASS лог pytest
Rollback составной операции test_rollback_chat_with_unknown_member PASS лог pytest
Index + EXPLAIN на 10000 сообщениях docker compose exec postgres psql + EXPLAIN (ANALYZE, BUFFERS) Index Scan, 29× быстрее evidence/explain.txt
Проверка expiry test_expiry_invalidates_session PASS лог pytest
Redis unavailable → 503 test_redis_unavailable_returns_503 PASS лог pytest
PostgreSQL unavailable → 503 test_postgres_unavailable_returns_503 PASS лог pytest
Трек 1: согласованность кэша
Гипотеза: без кэша и защиты от cache stampede каждый параллельный GET /messages идёт в БД. При 50 параллельных клиентах и холодном кэше в БД уйдёт 50 запросов. Если добавить кэш истории и single-flight через Redis SET NX, число SQL-запросов к таблице messages должно упасть до 1.
Условия измерения:
Стенд: Docker 26.1.1, три контейнера (postgres, valkey, api) на localhost:8080.
Клиент: Windows 11, Python 3.13.15, httpx, ThreadPoolExecutor.
Сервер: python:3.12-slim.
Нагрузка: 50 параллельных GET /api/v1/chats/{id}/messages?limit=50 на один чат с 100 сообщениями.
Метрики: SQL-запросы к таблице messages (через pg_stat_statements), p50/p95/p99 latency.
Сырые результаты: evidence/cache_experiment.json.
Результаты:
Baseline (без кэша, без single-flight):
concurrency ok errors sql_calls p50 ms p95 ms p99 ms
50 50 0 50 2048 2109 2130
После single-flight:
concurrency ok errors sql_calls p50 ms p95 ms p99 ms
50 50 0 1 2052 2207 2297
Изменение:
Добавлен кэш истории сообщений в app/cache.py. В app/storage.py метод list_messages:
Проверяет кэш по ключу messages:<chat_id>:<limit>:<cursor>.
При промахе пытается захватить lock:<cache_key> через Redis SET NX EX 5.
Захвативший lock идёт в БД, кладёт результат в кэш с TTL 30 секунд, отпускает lock.
Не захватившие lock ждут до 5 секунд, проверяя кэш. Если значение появилось, возвращают его.
В add_message после вставки сообщения вызывается инвалидация кэша: удаляются все ключи messages:<chat_id>:*.
Анализ:
SQL-запросы к таблице messages: 50 → 1. Это главный результат: cache stampede предотвращён. БД получает один запрос вместо N.
p50/p95 latency: без изменений. Параллельные клиенты всё равно ждут лидера, который идёт в БД. Основной выигрыш — снижение нагрузки на БД, а не latency одного запроса.
Read-after-write: после POST сообщения следующий GET видит его. Это доказано тестом test_read_after_write_sees_new_message. Кэш инвалидируется при вставке.
Восстановление после рестарта Valkey: после docker compose restart valkey API продолжает отдавать те же данные. Доказано тестом test_cache_recovers_after_valkey_restart.
Ограничения измерения:
50 клиентов — небольшое число. При 500+ выигрыш в latency тоже станет заметным.
Closed-loop нагрузка: клиент ждёт ответа, поэтому coordinated omission.
Один Docker-хост.
TTL кэша 30 секунд. Если данные меняются в обход API (напрямую в БД), возможен stale read, потому что кэш об этом не узнает.
Ограничения и следующие шаги
Что выдерживается:
Перезапуск API и БД с сохранением volumes: подтверждённые данные и активные сессии не теряются.
Перезапуск Valkey: сессии и кэш восстанавливаются из AOF.
Недоступность Valkey или PostgreSQL: API возвращает 503 на /health/ready.
Истечение сессии по TTL: токен перестаёт работать.
Гонка регистрации одинакового username: проходит только один запрос.
Откат транзакции при ошибке вставки участника чата.
Что не выдерживается:
Потеря хоста с данными PostgreSQL и Valkey одновременно.
Согласованность кэша при изменении данных в обход API (прямо в БД).
Балансировка нагрузки между репликами: одна реплика API.
Учебные упрощения:
Одна реплика API вместо нескольких с LB.
Хранение сессий и кэша в одной базе Valkey (db 0) с разными префиксами ключей.
HTTP без TLS.
SESSION_TTL_SECONDS по умолчанию 3600, в обычном smoke не менее 300.
Подтверждённое улучшение:
Cache stampede предотвращён. При 50 параллельных GET число SQL-запросов к таблице messages снизилось с 50 до 1.
Гипотезы, не проверенные в lab2:
Разделение Valkey на две базы git add .для сессий и кэша упростит policy expiry.
Более длинный TTL кэша увеличит hit rate, но повысит риск stale read при прямых изменениях в БД.
Разбиение per-chat lock в кэше позволит избежать глобальной блокировки при холодном старте.