17 KiB
Отчёт — лабораторная 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 . 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>|. Такой подход не допускает пропусков и дублей при вставке новых элементов во время обхода.
Кэш истории. Ключ messages:<chat_id>::, 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: ~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 в кэше позволит избежать глобальной блокировки при холодном старте.