diff --git a/REPORT.md b/REPORT.md index e42f2b05..30f87207 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 +- 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 diff --git a/screenshots/lab2_persistence_pass.png b/screenshots/lab2_persistence_pass.png new file mode 100644 index 00000000..9a23fe2c Binary files /dev/null and b/screenshots/lab2_persistence_pass.png differ diff --git a/screenshots/lab2_smoke_pass.png b/screenshots/lab2_smoke_pass.png new file mode 100644 index 00000000..a8086386 Binary files /dev/null and b/screenshots/lab2_smoke_pass.png differ diff --git a/screenshots/lab2_tables.png b/screenshots/lab2_tables.png new file mode 100644 index 00000000..949d14da Binary files /dev/null and b/screenshots/lab2_tables.png differ