forked from mtusi2026/mtusi2026lab2
написан REPORT.md, подготовка к PR
This commit is contained in:
@@ -1,37 +1,127 @@
|
||||
# Отчёт — лабораторная 2
|
||||
**Автор, группа:** Кашкарова Арина, БПИ2302
|
||||
**Целевая оценка:** 3
|
||||
**Commit/PR:** TODO
|
||||
**Использованные источники, библиотеки и помощь ИИ:** Python 3.11, FastAPI, Uvicorn, Pydantic, PostgreSQL 16.1, psycopg2-binary, bcrypt, Docker, Docker Compose. ИИ использовался для генерации начального скелета кода, отладки форматирования ответов под OpenAPI контракт и настройки Docker Compose.
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
|
||||
## Запуск из чистого clone
|
||||
**Prerequisites:** Python 3.9+, Docker, Docker Compose, Git.
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
1. **Клонирование и подготовка окружения:**
|
||||
```bash
|
||||
git clone https://gitea.privcloud.tech/ari_kash/mtusi2026lab2.git
|
||||
cd mtusi2026lab2
|
||||
python3 -m venv .venv
|
||||
source .venv/Scripts/activate
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
2. Создание .env:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
3. Сборка и запуск стенда (API + PostgreSQL):
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
4. Ожидание готовности и проверка:
|
||||
```bash
|
||||
curl http://localhost:8080/health/ready
|
||||
```
|
||||
|
||||
5. Запуск тестов:
|
||||
```bash
|
||||
# Smoke test (базовый сценарий API)
|
||||
python tests/smoke.py --base-url "http://localhost:8080"
|
||||
# Test persistence (проверка сохранности данных после рестарта)
|
||||
python tests/resilience.py --mode persistence --action-script "scripts/restart.bat" --base-url "http://localhost:8080"
|
||||
```
|
||||
|
||||
6. Безопасная остановка и удаление учебных данных:
|
||||
```bash
|
||||
# Остановка контейнеров (данные сохраняются в volume)
|
||||
docker compose down
|
||||
|
||||
# Полное удаление включая volumes (сброс всех данных)
|
||||
docker compose down -v
|
||||
```
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
Схема процессов и хранилищ
|
||||
Клиент → HTTP API (FastAPI) → PostgreSQL
|
||||
↓
|
||||
Сессии в PostgreSQL
|
||||
|
||||
Компоненты:
|
||||
- API процесс: Uvicorn + FastAPI, запущен как PID 1 в Docker-контейнере
|
||||
- PostgreSQL 16.1: Источник истины для всех данных (пользователи, чаты, сообщения, сессии)
|
||||
- Named volume: postgres_data:/var/lib/postgresql/data обеспечивает сохранность данных
|
||||
|
||||
Таблицы базы данных
|
||||
Схема включает 5 таблиц с ограничениями:
|
||||
1. users — пользователи (PK: id, UNIQUE: username)
|
||||
2. chats — чаты (PK: id)
|
||||
3. chat_members — участники чатов (PK: (chat_id, user_id), FK на users и chats)
|
||||
4. messages — сообщения (PK: id, FK на chats и users, индекс на (chat_id, created_at, id))
|
||||
5. sessions — сессии (PK: token, FK на users, TTL через expires_at)
|
||||
Миграции: Файл src/migrations/001_initial.sql запускается idempotently при старте приложения (CREATE TABLE IF NOT EXISTS).
|
||||
|
||||
Аутентификация и безопасность
|
||||
- Регистрация (POST /api/v1/users): Пароль хешируется через SHA-256 pre-hash + bcrypt (обход лимита 72 байт bcrypt)
|
||||
- Вход (POST /api/v1/auth/sessions): Basic authentication (username:password в base64)
|
||||
- Сессии: Opaque Bearer-токен с 256 битами энтропии (secrets.token_hex(32)), TTL = 3600 секунд
|
||||
- Защищённые endpoint: Требуют Authorization: Bearer <token>
|
||||
- Logout (DELETE /api/v1/auth/sessions/current): Удаляет сессию из БД
|
||||
|
||||
Транзакционные границы
|
||||
- Создание чата: Атомарная операция — вставка в chats и chat_members в одной транзакции
|
||||
- Все write-операции: Используют контекстный менеджер get_db() с commit/rollback
|
||||
- Параметризованные запросы: Все SQL-запросы используют %s placeholder для защиты от SQL-инъекций
|
||||
|
||||
Из lab1 были перенесены src/models.py src/__init__.py src/models.py Dockerfile и requierements.txt -- все эти файлы так же были изменены под задачу lab2
|
||||
|
||||
Соответствие .env.example
|
||||
- DATABASE_URL=postgresql://messenger:messenger_pass@postgres:5432/messenger — используется в docker-compose.yaml
|
||||
SESSION_TTL_SECONDS=3600 — читается в auth.py
|
||||
- Секреты (пароль БД) не зашиты в образ, передаются через переменные окружения
|
||||
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
| Публичный smoke | python tests/smoke.py --base-url "http://localhost:8080" | PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. | screenshots/lab2_smoke_pass.png |
|
||||
| Persistence test | python tests/resilience.py --mode persistence --action-script "scripts/restart.bat" --base-url "http://localhost:8080" | Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
|
||||
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||||
(.venv) | screenshots/lab2_persistence_pass.png |
|
||||
| PostgreSQL с таблицами | docker compose exec postgres psql -U messenger -d messenger -c "\dt" | Показывает 5 таблиц: users, chats, chat_members, messages, sessions | screenshots/lab2_tables.png |
|
||||
| Миграции idempotently | Перезапуск API с теми же миграциями | Ошибок нет, данные не дублируются | — |
|
||||
| Атомарное создание чата | Создание чата с 3 участниками | Чат и все 3 записи в chat_members создаются атомарно | — |
|
||||
| Basic → Bearer | POST /api/v1/auth/sessions с Basic, затем GET /api/v1/users/me с Bearer | 201 Created с токеном, затем 200 OK с данными пользователя | — |
|
||||
| WWW-Authenticate заголовки | Запрос без Authorization к /api/v1/users/me | 401 Unauthorized с заголовком WWW-Authenticate: Bearer realm="messenger" | — |
|
||||
| Хеширование паролей |
|
||||
Проверка кода в auth.py | Используется bcrypt.hashpw() с SHA-256 pre-hash | src/auth.py |
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
| Перезапуск API и PostgreSQL (docker compose restart api postgres) | Все данные (пользователи, чаты, сообщения, сессии) сохраняются благодаря именованному volume postgres_data | После рестарта тот же Bearer-токен позволяет читать данные, созданные до рестарта | ~5-7 секунд на старт PostgreSQL + API. Данные не теряются |
|
||||
| Истечение сессии (TTL) |
|
||||
Установка SESSION_TTL_SECONDS=2, ожидание 3 секунды | Сессия становится недействительной, запросы возвращают 401 Unauthorized | Мгновенно после expiry |
|
||||
| Logout | DELETE /api/v1/auth/sessions/current, затем повтор запроса с тем же токеном | 204 No Content, затем 401 Unauthorized | Мгновенно. Сессия удаляется из БД |
|
||||
| Неверный пароль | POST /api/v1/auth/sessions с неправильным паролем | 401 Unauthorized с WWW-Authenticate: Basic realm="messenger" | Мгновенно |
|
||||
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
Что реализовано и работает:
|
||||
✅ Все endpoint'ы lab1 перенесены с новой аутентификацией
|
||||
✅ PostgreSQL с миграциями, индексами и внешними ключами
|
||||
✅ Сессии сохраняются в PostgreSQL и переживают рестарт
|
||||
✅ Smoke test и persistence test проходят
|
||||
✅ WWW-Authenticate заголовки соответствуют контракту
|
||||
✅ Пароли хешируются bcrypt
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Reference in New Issue
Block a user