forked from mtusi2026/mtusi2026lab2
Restore lab assignment README and report PR status
This commit is contained in:
@@ -1,92 +1,105 @@
|
||||
# Лабораторная 2. PostgreSQL, сессии и Redis
|
||||
# Лабораторная 2. PostgreSQL, сессии и Redis/Valkey
|
||||
|
||||
Переносит мессенджер Lab 1 на PostgreSQL и меняет учебную идентификацию на пароль и Bearer-сессию. PostgreSQL хранит пользователей, чаты, членство и сообщения. Redis хранит сессии с TTL и AOF persistence.
|
||||
Перенести состояние в постоянное хранилище и связать запросы с аутентифицированным пользователем. Подтверждённые сообщения и действующие сессии переживают перезапуск.
|
||||
|
||||
## Запуск локального стенда
|
||||
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
|
||||
|
||||
Требуются Docker Engine с Compose v2 и PowerShell 7 либо совместимый PowerShell. Стенд использует Python 3.12.6, PostgreSQL 16.4 и Redis 7.4.1; теги образов закреплены. Все порты хранилищ доступны только во внутренней сети Compose, API опубликован на `127.0.0.1:8080`.
|
||||
[Карта курса](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)
|
||||
|
||||
В корне проекта:
|
||||
## Откуда начинаем
|
||||
|
||||
```powershell
|
||||
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
|
||||
./scripts/create-secrets.ps1
|
||||
docker compose --env-file .env config --quiet
|
||||
docker compose --env-file .env up -d --build
|
||||
```
|
||||
Перенесите собственный минимум lab1. Изменения API: password при регистрации, Basic для создания сессии, Bearer вместо X-User-Id для бизнес-запросов.
|
||||
|
||||
Миграция `001_initial.sql` запускается одноразовой службой `migrate` до API. Дождитесь готовности и выполните публичный smoke:
|
||||
**Архитектура:** Клиент → API → PostgreSQL; на 4 появляется Redis ИЛИ Valkey для сессий/кэша.
|
||||
|
||||
```powershell
|
||||
docker compose ps
|
||||
python tests/smoke.py --base-url http://localhost:8080
|
||||
```
|
||||
## Что сделать
|
||||
|
||||
Или `make test`. Smoke создаёт синтетических пользователей, чат и сообщения; API не имеет endpoint для их удаления. Повторяйте проверки на отдельном учебном volume, если нужен чистый набор данных.
|
||||
1. Опишите таблицы, ограничения, индексы и транзакционные границы до написания запросов. Добавьте версионируемые миграции.
|
||||
2. Перенесите пользователей, чаты, членство и сообщения в PostgreSQL. Не используйте SQLite как замену PostgreSQL в принимаемом стенде.
|
||||
3. Реализуйте регистрацию с password KDF, вход через Basic, opaque Bearer-сессию, expiry и logout. Действующие сессии тоже должны сохраняться.
|
||||
4. Подготовьте единый локальный запуск API и БД (Compose рекомендуется уже здесь), подключите именованные volumes.
|
||||
5. Пройдите smoke и тест полного перезапуска. На 4 добавьте Redis/Valkey с конкретной ролью и повторите эксперимент отказа.
|
||||
|
||||
## Проверки для оценки 4
|
||||
## Оценка «3»: работающий минимум
|
||||
|
||||
Для короткого срока сессии переопределите значение при создании контейнеров. Десять секунд достаточно для проверки expiry, оставаясь безопасным для самого сценария:
|
||||
- Минимум 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.
|
||||
|
||||
```powershell
|
||||
$env:SESSION_TTL_SECONDS = '10'
|
||||
docker compose --env-file .env up -d --build --force-recreate
|
||||
python tests/grade4.py --base-url http://localhost:8080
|
||||
Remove-Item Env:SESSION_TTL_SECONDS
|
||||
docker compose --env-file .env up -d --force-recreate
|
||||
```
|
||||
## Оценка «4»: уровень стажёра/джуна
|
||||
|
||||
`tests/grade4.py` проверяет ошибочный пароль, expiry, logout, гонку регистрации одинакового username, отсутствие частичного чата при ошибке и контролируемые `503` при остановке Redis или PostgreSQL. Скрипт останавливает и снова запускает сервисы, но не удаляет volumes. Сначала запустите публичный smoke с обычным TTL; тест сохранности сессии требует TTL не менее 300 секунд.
|
||||
Весь уровень 3 **и все** пункты ниже:
|
||||
|
||||
План запроса истории можно воспроизвести отдельно. Скрипт добавляет 10 000 временных сообщений в одной транзакции, фиксирует `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`, проверяет использование `messages_history_idx` и откатывает fixtures:
|
||||
- Redis ИЛИ Valkey реально используется для сессий с TTL либо осмысленного кэша. Опишите источник истины, политику expiry и инвалидации. Если это единственное хранилище сессий, включите persistence, выдерживающее проверяемый рестарт; один TTL не сохраняет данные.
|
||||
- Используются параметризованные запросы/безопасный ORM, ограниченный connection pool и таймауты. Проверены гонка регистрации одинакового username и rollback составной операции.
|
||||
- Индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация не использует полный scan всей истории на каждую страницу.
|
||||
- Есть автоматическая проверка expiry при коротком SESSION_TTL_SECONDS, logout, неверного пароля и недоступности Redis/БД. При потере сервиса приложение возвращает ограниченную ошибку/корректно обходит кэш, не принимает запрос от анонимного пользователя как доверенный.
|
||||
|
||||
```powershell
|
||||
docker compose exec -T api python -m src.app.explain_history | Set-Content -Encoding utf8 evidence/query-plan.json
|
||||
```
|
||||
## Оценка «5»: исследование и доказанный результат
|
||||
|
||||
Повторное применение миграций не меняет данные:
|
||||
Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения.
|
||||
|
||||
```powershell
|
||||
docker compose run --rm migrate
|
||||
```
|
||||
**Трек 1. Согласованность кэша.** Покажите на конкурентном сценарии stale read или cache stampede, реализуйте защиту и измерьте число SQL-запросов/latency до и после. Докажите read-after-write из контракта и восстановление после рестарта кэша; одной установки Redis недостаточно.
|
||||
|
||||
Сценарий полного перезапуска API и обоих хранилищ с сохранением volumes:
|
||||
**Трек 2. План запроса и восстановление.** Исследуйте ≥100 000 сообщений с неравномерными размерами чатов, сравните ≥2 индекса/запроса и стоимость записи. Сделайте backup → восстановление в новое хранилище → сверку количества и выбранных сообщений. Обсудите время восстановления и границы потери данных.
|
||||
|
||||
## Как начать и проверить
|
||||
|
||||
```sh
|
||||
chmod +x scripts/restart.sh
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
|
||||
make check
|
||||
|
||||
# После реализации запустите свой сервер/стенд по REPORT.md.
|
||||
# По умолчанию тест использует http://localhost:8080.
|
||||
make test
|
||||
```
|
||||
|
||||
Запускайте этот сценарий из Linux, WSL или Git Bash, где доступны Docker Compose и исполняемые shell-скрипты. Проверка держит токен только в памяти и использует тот же токен после перезапуска.
|
||||
`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
|
||||
|
||||
## Остановка и удаление учебных данных
|
||||
|
||||
Безопасно остановить контейнеры можно `docker compose stop` или удалить контейнеры и сеть командой `docker compose down`; именованные volumes сохраняются. Осознанно удалить все локальные данные можно только отдельной командой:
|
||||
|
||||
```powershell
|
||||
docker compose down --volumes
|
||||
```sh
|
||||
# Compose-вариант после реализации:
|
||||
docker compose --env-file .env config --quiet
|
||||
docker compose --env-file .env up -d --build
|
||||
# Дождитесь /health/ready; затем make test.
|
||||
# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md.
|
||||
```
|
||||
|
||||
Не используйте её во время тестов persistence.
|
||||
|
||||
## Архитектура и границы
|
||||
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
|
||||
|
||||
- `users`, `chats`, `chat_members` и `messages` находятся в PostgreSQL. FK гарантируют членство отправителя в чате, уникальный индекс разрешает гонки username, а создание чата и участников выполняется одной транзакцией.
|
||||
- `messages_history_idx(chat_id, created_at, id)` соответствует keyset-пагинации и сортировке истории. Курсор содержит чат, время и UUID; сортировка по тройке остаётся однозначной при совпавших временных метках.
|
||||
- Пароли хешируются библиотекой Argon2id. Basic принимается только на `POST /api/v1/auth/sessions`; токен содержит 256 случайных бит, а Redis хранит запись под SHA-256 ключом с TTL. Ответы и логи не содержат пароль или токен.
|
||||
- Redis является источником истины для сессий. AOF с `appendfsync everysec`, RDB snapshot и именованный volume сохраняют действующие сессии при контролируемом рестарте. При аварийном отключении Redis возможна потеря примерно последней секунды записей; API закрывает доступ и возвращает `503`, если Redis недоступен.
|
||||
- SQLAlchemy Core/ORM использует параметризованные выражения, пул ограничен 5 соединениями + 5 overflow, acquisition timeout — 3 секунды, connect timeout — 3 секунды, statement timeout — 5 секунд. Ошибки хранилищ не раскрывают SQL или credentials.
|
||||
- PostgreSQL — источник истины сообщений и профилей. Приложение не кэширует сообщения, поэтому после записи чтение идёт из БД и не может вернуть историю из устаревшего кэша.
|
||||
|
||||
HTTP и Basic предназначены только для localhost со synthetic-данными. Удалённую демонстрацию проводите через TLS termination.
|
||||
|
||||
## Команды разработки
|
||||
|
||||
```powershell
|
||||
python scripts/check_contract.py
|
||||
python -m compileall -q src tests scripts
|
||||
python -m pip install -r requirements-dev.txt
|
||||
python scripts/validate_openapi.py
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||||
make validate PYTHON=.venv/bin/python
|
||||
```
|
||||
|
||||
`make check` проверяет контрактные файлы; `make test` выполняет публичный API smoke; `make test-grade4` запускает негативные и отказные проверки; `make explain-history` печатает план в терминал. Публичный smoke сам по себе не доказывает grading evidence: сохраните результат проверки, план запроса и фактическое состояние контейнеров в `REPORT.md`/`evidence/`.
|
||||
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/)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- Автор, группа: Бадрадин Али, БВТ-2302
|
||||
- Целевая оценка: 4; трек 5 не заявлен
|
||||
- Commit/PR: коммит будет опубликован в личный fork `Badradine/mtusi2026lab2`
|
||||
- Commit/PR: черновик PR #84 — https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/84
|
||||
- Источники и помощь: контракт этого репозитория; документация FastAPI, SQLAlchemy, PostgreSQL, Redis и Argon2. ИИ использован для реализации и ревью.
|
||||
|
||||
## Запуск из чистого clone
|
||||
@@ -40,12 +40,13 @@ python tests/smoke.py --base-url http://localhost:8080
|
||||
| Конфигурация Compose и secrets | `docker compose config --quiet` | PASS; secrets и `.env` созданы локально и игнорируются Git | exit code 0 |
|
||||
| In-process HTTP, ошибки и базовые проверки | `fastapi.testclient.TestClient` с нерабочими локальными адресами хранилищ | PASS: health, request ID, игнорирование `X-User-Id`, пустое тело сессии, ошибки валидации/malformed JSON, Argon2id, Basic parsing и cursor codec | вывод `PASS` в терминале |
|
||||
| Недоступная PostgreSQL | `GET /health/ready` при закрытом localhost-порту | PASS: контролируемый `503 unavailable`, request ID совпадает | вывод `PASS` в терминале |
|
||||
| README задания | `README.md` сохранён из исходного репозитория задания | PASS | `README.md`; инструкция запуска решения находится в этом отчёте |
|
||||
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | PASS | вывод пользователя: `PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.` |
|
||||
| Пароль, expiry, logout, гонка регистрации, rollback чата | `$env:SESSION_TTL_SECONDS='10'; python tests/grade4.py --base-url http://localhost:8080` | PASS: все 8 сценариев | вывод пользователя от 2026-10-22; `tests/grade4.py` |
|
||||
| Отказ Redis и PostgreSQL | часть `tests/grade4.py` | PASS: оба отказа возвращают ограниченный `503`; API и хранилища восстановлены | вывод пользователя от 2026-10-22 |
|
||||
| Полный перезапуск сессии и данных | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Ещё не проверен; нужен TTL ≥300 секунд и запуск из WSL/Git Bash | `scripts/restart.sh` |
|
||||
| История ≥10 000 сообщений | `docker compose --env-file .env exec -T api python -m src.app.explain_history` | PASS: `Index Scan` использует `messages_history_idx`; Execution Time 0,108 мс | `evidence/query-plan.json`; 3 shared hit blocks в узле Index Scan |
|
||||
| Повторное применение миграций | `docker compose run --rm migrate` | Ещё не проверено; команда указана в README | вывод команды после запуска |
|
||||
| Повторное применение миграций | `docker compose --env-file .env run --rm migrate` | Ещё не проверено; запустить из локального PowerShell с доступным Docker Engine | вывод команды после запуска |
|
||||
|
||||
Локальный HTTP-прогон использовал установленное в рабочей среде FastAPI 0.139.0, Pydantic 2.13.4, SQLAlchemy 2.0.51 и Redis client 8.0.1; контейнер фиксирует версии из `requirements.txt`. Публичный smoke и полная suite grade4 подтверждены пользователем на Docker Compose 2026-10-22. План запроса истории снят в Docker: `Index Scan` по `messages_history_idx`, 0,108 мс на синтетическом наборе.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user