# Отчёт по лабораторной работе №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:`, сырой токен в кэше не хранится | | 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): ```sql 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. ## Как запустить ```bash 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) специально медленный, требует много памяти и использует случайную соль, чтобы перебор по украденной базе был дорогим. Быстрый хеш для паролей позволяет перебирать миллиарды вариантов в секунду.