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

174 lines
20 KiB
Markdown
Raw Permalink 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: 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):
```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) специально медленный, требует много памяти и использует случайную соль, чтобы перебор по украденной базе был дорогим. Быстрый хеш для паролей позволяет перебирать миллиарды вариантов в секунду.