forked from mtusi2026/mtusi2026lab2
174 lines
20 KiB
Markdown
174 lines
20 KiB
Markdown
# Отчёт по лабораторной работе №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) специально медленный, требует много памяти и использует случайную соль, чтобы перебор по украденной базе был дорогим. Быстрый хеш для паролей позволяет перебирать миллиарды вариантов в секунду.
|