20 KiB
Лабораторная 2. PostgreSQL, сессии и Redis/Valkey
Перенести состояние в постоянное хранилище и связать запросы с аутентифицированным пользователем. Подтверждённые сообщения и действующие сессии переживают перезапуск.
Этот форк содержит рабочую реализацию задания: API, миграции PostgreSQL, Compose-стенд и проверки. UI не обязателен.
Карта курса · Процесс fork/PR · OpenAPI · Семантика API · Проверки · Отчёт · Примеры JSON · Памятка преподавателю
Откуда начинаем
Перенесите собственный минимум lab1. Изменения API: password при регистрации, Basic для создания сессии, Bearer вместо X-User-Id для бизнес-запросов.
Архитектура: Клиент → API → PostgreSQL; на 4 появляется Redis ИЛИ Valkey для сессий/кэша.
Перенесён минимум lab1: регистрация и чтение профиля, создание/чтение чатов, сообщения и keyset-пагинация. Контракт аутентификации изменён: регистрация принимает password, Basic используется только для POST /api/v1/auth/sessions, бизнес-запросы используют Bearer-сессию. X-User-Id игнорируется и сам по себе доступ не даёт.
Модель данных и транзакционные границы
Миграция app/migrations/001_initial.sql создаёт схему с нуля; app/migrate.py применяет каждую версию один раз в общей транзакции и записывает её в schema_migrations.
| Таблица | Ключи и ограничения | Индексы и назначение |
|---|---|---|
users |
PK id; UNIQUE username; CHECK формата username и непустого display name; хранится только Argon2id hash пароля |
Уникальный индекс username создаётся ограничением |
chats |
PK id; CHECK непустого title |
PK для адресации чата |
chat_members |
Составной PK (chat_id, user_id); FK на chats с CASCADE и на users с RESTRICT |
(user_id, chat_id) для списка чатов участника |
messages |
PK id; FK чата с CASCADE и отправителя с RESTRICT; CHECK непустого текста |
(chat_id, created_at, id) обслуживает фильтрацию и keyset-страницы истории |
sessions |
PK token_hash; FK на пользователя с CASCADE; обязательный expires_at, nullable revoked_at; исходный Bearer-токен не хранится |
Частичный индекс expires_at по неотозванным сессиям |
schema_migrations |
PK version |
Уникально фиксирует применённые миграции |
Регистрация выполняет один INSERT. Создание чата проверяет участников, добавляет чат и все строки членства внутри одной транзакции: ошибка любого INSERT откатывает всю операцию. Создание и отзыв сессии также фиксируются в PostgreSQL транзакцией; logout сначала сохраняет отзыв, затем удаляет кэш. Сообщение записывается одним INSERT. История выбирает limit + 1 строку по (created_at, id) без OFFSET.
Что сделать
- Опишите таблицы, ограничения, индексы и транзакционные границы до написания запросов. Добавьте версионируемые миграции.
- Перенесите пользователей, чаты, членство и сообщения в PostgreSQL. Не используйте SQLite как замену PostgreSQL в принимаемом стенде.
- Реализуйте регистрацию с password KDF, вход через Basic, opaque Bearer-сессию, expiry и logout. Действующие сессии тоже должны сохраняться.
- Подготовьте единый локальный запуск API и БД (Compose рекомендуется уже здесь), подключите именованные volumes.
- Пройдите smoke и тест полного перезапуска. На 4 добавьте Redis/Valkey с конкретной ролью и повторите эксперимент отказа.
Оценка «3»: работающий минимум
- Минимум lab1 сохранён с объявленным переходом на новую аутентификацию. Все обязательные данные и ещё действующие сессии переживают рестарт API и хранилищ без удаления volumes.
- PostgreSQL содержит пользователей, чаты, участников и сообщения. Есть первичные/внешние ключи, уникальность username и миграции с нуля. Составная операция создания чата выполняется атомарно.
- Basic применяется только на POST /auth/sessions, остальные endpoint требуют Bearer. Есть срок жизни сессии и отзыв; X-User-Id не даёт доступ. Пароли уже хешируются password KDF.
- make test и make test-persistence ACTION_SCRIPT=scripts/restart.sh проходят. Миграции повторно запускаются без дублирования данных. Secrets/volumes не попадают в Git.
Оценка «4»: уровень стажёра/джуна
Весь уровень 3 и все пункты ниже:
- Redis ИЛИ Valkey реально используется для сессий с TTL либо осмысленного кэша. Опишите источник истины, политику expiry и инвалидации. Если это единственное хранилище сессий, включите persistence, выдерживающее проверяемый рестарт; один TTL не сохраняет данные.
- Используются параметризованные запросы/безопасный ORM, ограниченный connection pool и таймауты. Проверены гонка регистрации одинакового username и rollback составной операции.
- Индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация не использует полный scan всей истории на каждую страницу.
- Есть автоматическая проверка expiry при коротком SESSION_TTL_SECONDS, logout, неверного пароля и недоступности Redis/БД. При потере сервиса приложение возвращает ограниченную ошибку/корректно обходит кэш, не принимает запрос от анонимного пользователя как доверенный.
Оценка «5»: исследование и доказанный результат
Весь уровень 4 и один законченный трек на выбор. Приведите гипотезу, повторяемую методику, результаты и ограничения.
Трек 1. Согласованность кэша. Покажите на конкурентном сценарии stale read или cache stampede, реализуйте защиту и измерьте число SQL-запросов/latency до и после. Докажите read-after-write из контракта и восстановление после рестарта кэша; одной установки Redis недостаточно.
Трек 2. План запроса и восстановление. Исследуйте ≥100 000 сообщений с неравномерными размерами чатов, сравните ≥2 индекса/запроса и стоимость записи. Сделайте backup → восстановление в новое хранилище → сверку количества и выбранных сообщений. Обсудите время восстановления и границы потери данных.
Как начать и проверить
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test
Для трека 1 после запуска Compose-стенда выполните проверку Redis single-flight:
make test-track5-cache BASE_URL=http://localhost:8080
Проверка создаёт пользователя/сессию, очищает профиль из Redis, отправляет 16 параллельных запросов и по событиям profile_cache_fill с уникальными request ID считает фактические SQL-запросы загрузки профиля. Затем сравнивает холодный и прогретый кэш по p95 latency, перезапускает Redis, удаляет только тестовый ключ и проверяет повторную загрузку профиля из PostgreSQL. Без single-flight конкурентный cache miss мог бы вызвать до 16 запросов профиля; проверка требует ровно одного. PostgreSQL всё равно проверяет expiry/revocation каждой сессии. Тест перезапускает Redis и требует Docker Compose CLI.
.env.example, compose.example.yaml и contracts/infrastructure.json описывают настройки и роли компонентов. compose.example.yaml — список ролей с пустым services, не запускаемый стенд. Реализуйте свой compose.yaml/stack.yaml, закрепите версии образов, заполните локальный .env и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
# Compose-вариант после реализации:
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь /health/ready; затем make test.
# Локальный стенд уровня 3/4 (Docker Compose)
Стек: FastAPI/Python, PostgreSQL как источник истины, Redis для TTL-кэша профиля действующей сессии. Пароли хешируются Argon2id. Внутренние таблицы состояния из lab1 заменены реляционной схемой; клиентские операции минимума lab1 сохранены с объявленным переходом на новую аутентификацию.
Требуются Docker Compose v2 и OpenSSL. Создайте игнорируемый локальный secret и запустите стенд:
```sh
umask 077
mkdir -p secrets
openssl rand -hex 32 > secrets/database_password
chmod 600 secrets/database_password
docker compose config --quiet
docker compose up -d --build
Compose запускает миграции перед API, публикует только порт API и сохраняет состояние PostgreSQL/Redis в именованных volumes. Секрет БД монтируется как Compose secret; .env, secrets и volumes не коммитятся. Убедитесь в готовности и выполните публичный сценарий:
Если при старте миграции сообщает, что не задан DB_PASSWORD, контейнер, вероятно, запущен отдельно от Compose или без смонтированного secret. Используйте команды выше из корня проекта после создания secrets/database_password; после изменения исходников пересоберите образ. Для отдельного docker run нужно передать DB_PASSWORD_FILE=/run/secrets/database_password и смонтировать файл secret именно по этому пути. Предпочтительный способ запуска — Compose.
curl --fail http://localhost:8080/health/ready
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
Миграции версионированы и пропускают уже применённую версию. Без удаления volumes стенд останавливается командой docker compose down; для намеренного удаления учебных данных используйте docker compose down -v только после того, как сохранность данных больше не нужна.
Автоматические проверки уровня 4
make test-grade4
make test-rollback
make explain-history
test-grade4 конкурентно регистрирует одинаковый username, проверяет неверный пароль и logout, останавливает Redis (сессия должна продолжить работать через PostgreSQL), затем PostgreSQL (ready и защищённый запрос должны получить 503), после чего запускает PostgreSQL обратно. Команда временно останавливает сервисы Compose и предназначена только для локального тестового стенда.
test-rollback временно ставит тестовый триггер PostgreSQL, который заставляет вставку участника чата завершиться ошибкой после вставки строки чата; проверяет 503 и отсутствие частичного чата, затем удаляет триггер. Запускайте только на этом учебном экземпляре.
explain-history в транзакции создаёт 10 000 синтетических сообщений, запускает EXPLAIN (ANALYZE, BUFFERS) для keyset-страницы и откатывает fixture. Индекс messages_history_keyset(chat_id, created_at, id) соответствует фильтру чата и сортировке (created_at, id). Сохраните вывод плана в доказательствах после выполнения: он не предзаполнен в репозитории и не подменён ожидаемым результатом.
Проверка короткого срока сессии выполняется на отдельном запуске API:
SESSION_TTL_SECONDS=2 docker compose up -d --force-recreate api
make test-expiry
# Верните обычный TTL и пересоздайте API после проверки:
SESSION_TTL_SECONDS=3600 docker compose up -d --force-recreate api
Сессии хранятся в PostgreSQL вместе с абсолютным expires_at; Redis хранит только профиль с TTL не дольше срока сессии. Любая авторизация проверяет в PostgreSQL expiry/revocation, поэтому Redis cache miss/failure безопасно обходит кэш, а недоступность БД возвращает 503. Logout сначала фиксирует отзыв в PostgreSQL, а кэш инвалидируется best-effort; запрос не может быть принят только на основании кэшированной записи.
Примеры запросов доступны в examples/requests.http, примеры JSON — в contracts/examples.json. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по tests/README.md, остальные доказательства приведите в отчёте.
Сценарий защиты
- Применить миграции к пустому volume, создать пользователей, войти, отправить сообщение.
- Запустить persistence-сценарий: он держит токен только в памяти тестового процесса; action script перезапускает API и все используемые хранилища, сохраняя volumes.
- После готовности тот же токен читает те же данные; после logout — 401. Повторить с отдельным коротким TTL для проверки expiry.
- Для 4: показать роль Redis/Valkey, план SQL и ошибку зависимости. Для 5: выполнить выбранный эксперимент.
Что должно быть в PR
Исходники, Dockerfile, миграции, compose.yaml либо эквивалентный воспроизводимый запуск, scripts/restart.sh, собственные тесты и отчёт.
Заполните REPORT.md и шаблон PR, укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах объявленных переходов.
Вопросы на защите
- Что подтверждает COMMIT и какие гарантии зависят от настройки durability?
- Где хранятся сессии и что будет после flush/restart Redis?
- Чем аутентификация отличается от доступа к конкретному чату?
- Почему hash пароля и быстрый checksum имеют разные задачи?