Files
2026-11-07 00:02:31 +03:00

20 KiB
Raw Permalink Blame History

Отчёт по лабораторной работе №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/:

  1. d74c0ccadc85: начальные таблицы;
  2. 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) специально медленный, требует много памяти и использует случайную соль, чтобы перебор по украденной базе был дорогим. Быстрый хеш для паролей позволяет перебирать миллиарды вариантов в секунду.