# Лабораторная 2. PostgreSQL, сессии и Redis/Valkey Перенести состояние в постоянное хранилище и связать запросы с аутентифицированным пользователем. Подтверждённые сообщения и действующие сессии переживают перезапуск. Этот форк содержит рабочую реализацию задания: API, миграции PostgreSQL, Compose-стенд и проверки. UI не обязателен. [Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md) ## Откуда начинаем Перенесите собственный минимум 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. ## Что сделать 1. Опишите таблицы, ограничения, индексы и транзакционные границы до написания запросов. Добавьте версионируемые миграции. 2. Перенесите пользователей, чаты, членство и сообщения в PostgreSQL. Не используйте SQLite как замену PostgreSQL в принимаемом стенде. 3. Реализуйте регистрацию с password KDF, вход через Basic, opaque Bearer-сессию, expiry и logout. Действующие сессии тоже должны сохраняться. 4. Подготовьте единый локальный запуск API и БД (Compose рекомендуется уже здесь), подключите именованные volumes. 5. Пройдите 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 → восстановление в новое хранилище → сверку количества и выбранных сообщений. Обсудите время восстановления и границы потери данных. ## Как начать и проверить ```sh # Работает прямо в skeleton, Python 3.9+; приложение не запускается: make check # После реализации запустите свой сервер/стенд по REPORT.md. # По умолчанию тест использует http://localhost:8080. make test ``` `.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость. ```sh # 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. ```sh 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 ```sh 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: ```sh 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 делает её автоматически): ```sh python3 -m venv .venv .venv/bin/python -m pip install -r requirements-dev.txt make validate PYTHON=.venv/bin/python ``` Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте. ## Сценарий защиты 1. Применить миграции к пустому volume, создать пользователей, войти, отправить сообщение. 2. Запустить persistence-сценарий: он держит токен только в памяти тестового процесса; action script перезапускает API и все используемые хранилища, сохраняя volumes. 3. После готовности тот же токен читает те же данные; после logout — 401. Повторить с отдельным коротким TTL для проверки expiry. 4. Для 4: показать роль Redis/Valkey, план SQL и ошибку зависимости. Для 5: выполнить выбранный эксперимент. ## Что должно быть в PR Исходники, Dockerfile, миграции, compose.yaml либо эквивалентный воспроизводимый запуск, scripts/restart.sh, собственные тесты и отчёт. Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md). ## Вопросы на защите - Что подтверждает COMMIT и какие гарантии зависят от настройки durability? - Где хранятся сессии и что будет после flush/restart Redis? - Чем аутентификация отличается от доступа к конкретному чату? - Почему hash пароля и быстрый checksum имеют разные задачи? ## Первичные материалы - [PostgreSQL transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html) - [PostgreSQL EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html) - [Valkey persistence](https://valkey.io/topics/persistence/) - [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) - [Basic authentication](https://www.rfc-editor.org/info/rfc7617/)