20 KiB
Отчёт по лабораторной работе №2: PostgreSQL, сессии и Valkey
Целевая оценка
4 (уровень стажёра/джуна): весь уровень 3 плюс Valkey в роли кэша сессий, ограниченный пул и таймауты БД, проверка гонки регистрации и отказов зависимостей, обоснованный индекс истории с EXPLAIN (ANALYZE, BUFFERS) на 24 000 сообщений, собственные автотесты.
Архитектура
Клиент -> API (FastAPI, uvicorn) -> PostgreSQL 16 (источник истины)
-> Valkey 8 (кэш сессий, опциональная зависимость)
| Компонент | Выбор |
|---|---|
| API | FastAPI, SQLAlchemy 2.0 (async) + asyncpg |
| БД | PostgreSQL 16, именованный volume postgres_data |
| Миграции | Alembic, отдельный одноразовый сервис migrate в Compose |
| Хеширование паролей | Argon2id (argon2-cffi) |
| Кэш | Valkey 8 (valkey/valkey:8.0-alpine), клиент redis-py |
Состав стенда: db, valkey, migrate, app (docker-compose.yaml). Порядок запуска: db healthy -> migrate завершился с кодом 0 -> app. valkey для app мягкая зависимость: API обязан работать и без него.
Схема БД
users(id uuid PK, username UNIQUE, display_name, password_hash, created_at).sessions(id uuid PK, user_id FK -> users ON DELETE CASCADE, token UNIQUE, expires_at, created_at).chats(id uuid PK, title, created_at).chat_members(chat_id FK, user_id FK, PK(chat_id, user_id)).messages(id uuid PK, chat_id FK, sender_id FK, text, created_at), индексix_messages_chat_created_id (chat_id, created_at, id).
Миграции версионируются в alembic/versions/:
d74c0ccadc85: начальные таблицы;b7e1f3a9c2d4: составной индекс истории вместо двух одноколоночных.
alembic upgrade head разворачивает схему с нуля; повторный запуск ничего не дублирует. DATABASE_URL берётся из окружения.
Транзакционные границы. Создание чата (проверка участников, INSERT chats, INSERT chat_members) выполняется в одной транзакции: либо чат и все участники записаны, либо ничего. Регистрация и вход тоже по одной транзакции на запрос.
Аутентификация и сессии
- Регистрация:
POST /api/v1/users, пароль 12-128 символов. Хеш Argon2id, пароль в ответах не возвращается. Уникальность username обеспечивает ограничениеUNIQUE; при гонке второйINSERTполучаетIntegrityError, ответ409. - Почему не bcrypt. bcrypt учитывает только первые 72 байта пароля. Контракт допускает пароль до 128 символов (до 512 байт в UTF-8), поэтому два разных длинных пароля с общим 72-байтным префиксом считались бы одинаковыми. Argon2id учитывает весь пароль. Это проверяет тест
test_long_passwords_not_truncated. - Вход:
POST /api/v1/auth/sessions, толькоAuthorization: Basic. Ответ 201 с opaque-токеном (secrets.token_urlsafe(32), 256 бит),expires_atв UTC сZ. При неверных данных одинаковый401иWWW-Authenticate: Basic realm="messenger", charset="UTF-8". Для несуществующего пользователя выполняется проверка по фиктивному хешу, чтобы время ответа не выдавало существование логина. - Срок жизни:
SESSION_TTL_SECONDS, по умолчанию 3600. Срок не продлевается при рестарте. - Бизнес-эндпоинты: только
Authorization: Bearer. Истёкший, отозванный или неизвестный токен даёт401сWWW-Authenticate: Bearer realm="messenger".X-User-Idигнорируется. - Logout:
DELETE /api/v1/auth/sessions/currentудаляет только предъявленную сессию (остальные сессии пользователя остаются), повторный вызов с тем же токеном даёт401. - Доступ к чату: сначала аутентификация (
401), затем членство; посторонний получает404, существование чужого чата не раскрывается.
Роль Valkey
Роль: кэш сессий. Источник истины для сессий таблица sessions в PostgreSQL.
| Вопрос | Решение |
|---|---|
| Что хранится | token -> {user_id, username, display_name, created_at, expires_at} |
| Ключ | sess:<sha256(token)>, сырой токен в кэше не хранится |
| TTL записи | min(SESSION_CACHE_TTL_SECONDS (по умолчанию 30 с), остаток жизни сессии); запись не переживёт сессию |
| Инвалидация | при logout сначала DELETE в PostgreSQL (commit), затем DEL ключа в Valkey |
| Чтение | кэш -> при промахе PostgreSQL (JOIN sessions/users) -> запись в кэш |
| Persistence | не нужен: кэш не единственное хранилище, потеря кэша не теряет сессии |
| Отказ Valkey | любая ошибка кэша трактуется как промах, запрос идёт в PostgreSQL; клиентские таймауты 0,5 с |
| Анонимный запрос | при любой неисправности остаётся 401, не принимается как доверенный |
Ограничение (окно устаревания). Если DEL не прошёл (Valkey недоступен именно в момент logout), отозванный токен может приниматься до SESSION_CACHE_TTL_SECONDS (30 с). Это осознанный компромисс; окно ограничено TTL записи и логируется (cache delete failed). Похожий случай: если logout происходит между чтением сессии из PostgreSQL и записью в кэш, запись также проживёт не дольше 30 с.
Рестарт Valkey. Кэш пустой, сессии не теряются, первые запросы читают PostgreSQL и заново наполняют кэш (проверено make test-persistence и тестом test_valkey_down_falls_back_to_db).
Индекс истории и EXPLAIN
Запрос истории (то, что выполняет API):
SELECT * FROM messages
WHERE chat_id = :chat
AND (created_at, id) > (:created_at, :id) -- только при продолжении
ORDER BY created_at, id
LIMIT :limit + 1;
Было: отдельные индексы по chat_id и по created_at. Для запроса с фильтром по чату и порядком (created_at, id) ни один из них не подходит целиком: одноколоночный по chat_id требует отдельной сортировки всех сообщений чата, а по created_at не фильтрует по чату.
Стало: составной индекс ix_messages_chat_created_id (chat_id, created_at, id). Колонки идут в порядке «равенство, затем порядок сортировки», поэтому одна и та же структура и ищет границу страницы (сравнение строк), и отдаёт строки сразу в нужном порядке.
Данные для проверки воспроизводимы: scripts/seed_explain.sql создаёт 2 чата по 12 000 сообщений (24 000 всего, детерминированные UUID, повторный запуск ничего не дублирует). Снятие плана: bash scripts/explain_history.sh; результат в evidence/explain_history.txt.
Результат «после» (чат из 12 000 сообщений, EXPLAIN (ANALYZE, BUFFERS)):
| Запрос | План | Buffers | Execution time |
|---|---|---|---|
| первая страница (51 строка) | Index Scan using ix_messages_chat_created_id, Index Cond: (chat_id = ...) |
shared hit=5 | 0,032 мс |
| страница из середины (после 6 000-го сообщения) | Index Scan using ix_messages_chat_created_id, Index Cond: (chat_id = ... AND ROW(created_at, id) > ROW(...)) |
shared hit=6 | 0,052 мс |
Оба плана без шага Sort, без Seq Scan и без Bitmap Heap Scan; страница читает несколько буферов независимо от того, на каком месте истории она находится. Это подтверждает, что пагинация не сканирует всю историю на каждую страницу.
Сравнение «до»: <ВСТАВИТЬ после снятия evidence/explain_before.txt: тип плана (Sort / Bitmap / Seq Scan), Buffers и Execution time на старых индексах; если файл не снимался, удалить этот абзац>
Надёжность и таймауты
- Пул соединений:
pool_size=10,max_overflow=10,pool_timeout=3 с,pool_pre_ping,pool_recycle=1800. - Таймауты БД: подключение 2 с (
timeout), клиентский таймаут запроса 3 с (command_timeout), на сервереstatement_timeout=5000 мсиidle_in_transaction_session_timeout=10000 мс. - Общий дедлайн запроса: 8 с (
REQUEST_TIMEOUT_SECONDS), по истечении503в формате ошибки контракта. - Недоступность БД: ошибки подключения, таймауты пула и запросов отображаются в
503 unavailable, а не500и не зависание. - Параметризованные запросы: весь доступ к данным через SQLAlchemy Core/ORM, строковая конкатенация SQL не используется.
- Гонка регистрации: решается
UNIQUE (username), а не проверкой перед вставкой; из 10 параллельных запросов с одним username ровно один получает201, остальные409(test_register_race_one_winner).
Health-проверки
GET /health/live: только живость процесса.GET /health/ready:200, если из пула получено соединение и выполненSELECT 1 FROM users LIMIT 1(заодно подтверждает, что миграции накатаны). Ответ даётся не позднее чем через 2 с; при недоступной БД503.- Критичные зависимости: PostgreSQL (критична). Valkey не критичен: при его отказе API продолжает работать с обходом кэша.
Семантика пагинации и ограничения
- Курсор непрозрачный (base64 от JSON), содержит полный ключ сортировки
(created_at, id)и область (чат / пользователь). Курсор от другого чата или повреждённая строка дают400. - Порядок по возрастанию
(created_at, id)как для истории, так и для списка чатов. Последний элемент предыдущей страницы не повторяется; сообщения с одинаковым временем не пропускаются (test_pagination_with_equal_timestamps). next_cursor = null, если на момент чтения следующей записи нет.- Ограничение при конкурентных вставках.
created_atназначается приложением до коммита. Если сообщение с более раннимcreated_atбудет закоммичено позже, чем читатель уже прошёл эту позицию, при продолжении обхода оно может не попасть в выдачу. Для неизменной истории повторов и пропусков нет; snapshot-изоляция между HTTP-запросами не гарантируется (контракт этого и не требует).
Автоматические проверки
Публичные: make test (smoke) и make test-persistence ACTION_SCRIPT=scripts/restart.sh.
Собственные: make test-own (scripts/test_own.sh, tests_own/) поднимает стенд и выполняет:
| Проверка | Тест |
|---|---|
неверный пароль, 401 и WWW-Authenticate |
test_wrong_password_401 |
| длинные пароли с общим 72-байтным префиксом различаются | test_long_passwords_not_truncated |
logout отзывает только текущую сессию, повтор даёт 401 |
test_logout_revokes_only_current_session |
| logout сразу инвалидирует кэш | test_logout_invalidates_cache_immediately |
| гонка регистрации: один победитель | test_register_race_one_winner |
дубликаты / неизвестные участники / нет создателя дают 400, список чатов не изменился |
test_chat_validation_and_rollback |
повреждённый и чужой курсор дают 400 |
test_cursor_garbage_and_foreign_cursor_400 |
одинаковое created_at не теряет сообщения |
test_pagination_with_equal_timestamps |
| полный обход без повторов и в порядке отправки | test_pagination_full_walk_in_order |
Valkey остановлен: запросы с токеном работают, аноним получает 401, после старта работает снова |
test_valkey_down_falls_back_to_db |
PostgreSQL на паузе: /health/ready и бизнес-запрос дают 503, после unpause работа восстанавливается |
test_db_paused_returns_503_and_recovers |
истечение сессии при SESSION_TTL_SECONDS=2 (отдельный запуск с коротким TTL) |
test_session_expires |
Откат составной операции проверяется на уровне валидации: невалидные запросы создания чата не оставляют частично записанного состояния. Сбой внутри самой транзакции (между вставкой чата и вставкой участников) отдельно не инжектировался: атомарность в этом случае обеспечивает транзакция PostgreSQL.
Как запустить
cp .env.example .env # при необходимости задать POSTGRES_PASSWORD
docker compose up -d --build # db -> migrate -> app, плюс valkey
curl -f http://localhost:8080/health/ready
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-own # нужны pytest и httpx: pip install pytest httpx
bash scripts/explain_history.sh # EXPLAIN на 24 000 сообщений -> evidence/explain_history.txt
Параметры окружения: DATABASE_URL, REDIS_URL, SESSION_TTL_SECONDS (3600), SESSION_CACHE_TTL_SECONDS (30), DB_POOL_SIZE, DB_MAX_OVERFLOW, DB_POOL_TIMEOUT, REQUEST_TIMEOUT_SECONDS.
Секреты: пароль БД задаётся через .env (в Git не попадает); значение по умолчанию в docker-compose.yaml пригодно только для локального изолированного стенда. Basic-аутентификация и HTTP допустимы только для локальной демонстрации с синтетическими данными; при удалённом доступе нужен TLS.
Ограничения и известные компромиссы
- Окно устаревания кэша при неудачном
DEL(до 30 с), см. раздел про Valkey. - Argon2id используется с параметрами библиотеки по умолчанию, отдельной настройки под нагрузку не выполнялось.
- После перехода с bcrypt на Argon2id старые хеши несовместимы: учебный стенд пересоздаётся (
docker compose down -v). - Истёкшие строки в
sessionsфизически не удаляются фоновой задачей (проверка срока идёт при каждом запросе). - Нагрузочное и конкурентное тестирование ограничено перечисленными проверками; исследование для оценки «5» не выполнялось.
Ответы на вопросы защиты
- Что подтверждает COMMIT и какие гарантии зависят от durability? COMMIT в PostgreSQL возвращается после записи WAL-записи коммита; при
fsync=onиsynchronous_commit=on(значения по умолчанию в используемом образе) подтверждённая транзакция переживает падение процесса и перезагрузку. Приsynchronous_commit=offпоследние подтверждённые транзакции можно потерять при сбое, при этом целостность БД сохраняется. - Где хранятся сессии и что будет после flush/restart Valkey? Сессии хранятся в PostgreSQL; Valkey лишь кэширует их на короткое время. После flush или рестарта Valkey кэш пустой, сессии остаются действительными, запросы временно идут напрямую в PostgreSQL.
- Чем аутентификация отличается от доступа к конкретному чату? Аутентификация отвечает на вопрос «кто вы» (валидный Bearer-токен, иначе
401), авторизация на вопрос «можно ли вам это» (членство в чате, иначе404, чтобы не раскрывать существование чужого чата). Сначала проверяется первое, затем второе. - Почему hash пароля и быстрый checksum имеют разные задачи? Checksum (например SHA-256) должен считаться быстро и проверяет целостность данных; хеш пароля (Argon2id) специально медленный, требует много памяти и использует случайную соль, чтобы перебор по украденной базе был дорогим. Быстрый хеш для паролей позволяет перебирать миллиарды вариантов в секунду.