Files
2026-11-10 23:47:45 +03:00

171 lines
19 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, сессии и 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/)