Files
mtusi2026lab2/REPORT.md
T
kuruoni ae11723671
Skeleton contracts / contracts (pull_request) Canceled after 0s
report change
2026-11-14 05:07:17 +03:00

10 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Свидерский К.Ю., БПИ2301
  • Целевая оценка; выбранный трек 5, если нужен: 3 (трек не нужен)
  • Commit/PR: #182
  • Использованные источники, библиотеки и помощь ИИ: README лабораторной, contracts/openapi.json, contracts/README.md, документация Python, FastAPI, asyncpg, PostgreSQL 16, Docker Compose и bcrypt. ИИ использовался для диагностики ошибок подключения к БД, пути миграции, формата UTC-времени, контрактных проверок и запуска Bash-скрипта в Windows.

Запуск из чистого clone

Требования: Docker Desktop с Docker Compose, Python с зависимостями тестового клиента, Bash/Linux-окружение для scripts/restart.sh (например, WSL Ubuntu). Проект реализован на Python 3.11 и FastAPI.

В корне склонированного репозитория

docker compose up -d --build

Проверка готовности API

curl http://127.0.0.1:8080/health/ready

Публичный тест API

python tests/smoke.py

Проверка сохранения данных после рестарта (из Linux/WSL)

python3 tests/resilience.py --mode persistence --action-script scripts/restart.cmd

Docker Compose запускает сервисы postgres (postgres:16-alpine) и api (образ из локального Dockerfile). API доступен на порту 8080, PostgreSQL — на 5432. При первом запуске должна выполняться миграция api/migrations/001_init_db.sql через init_db(); вызов этой функции из точки входа приложения следует проверить. В db.py путь должен совпадать с фактическим именем файла миграции. В настройках приложения применяется DATABASE_URL=postgresql://messenger:…@postgres:5432/messenger_db (пароль в отчёте не раскрывается).

Архитектура и решения

Схема процессов: клиент / тестовый Python-клиент → FastAPI (Uvicorn, порт 8080) → asyncpg → PostgreSQL 16. В Dockerfile используется базовый образ python:3.11.8-slim, рабочая директория /app, непривилегированный пользователь appuser и проверка /health/ready.

Хранение данных: PostgreSQL с именованным томом postgres_data, который сохраняется при docker compose restart. Миграция api/migrations/001_init_db.sql создаёт таблицы users, sessions, chats, chat_members, messages. Для идентификаторов используются UUID; связи между сессиями, чатами, участниками и сообщениями задаются внешними ключами, при удалении связанных записей применяется ON DELETE CASCADE. Имя пользователя уникально; есть индекс idx_messages_chat_cursor по (chat_id, created_at, id).

Миграции: db.py создаёт пул соединений asyncpg (минимум 2, максимум 10) и выполняет SQL из api/migrations/001_init_db.sql. Операторы CREATE TABLE IF NOT EXISTS и CREATE INDEX IF NOT EXISTS допускают повторное исполнение на уже созданной схеме. Это не полноценная система версионирования миграций; новые изменения схемы требуют отдельного контроля.

Пользователи: POST /api/v1/users проверяет имя и отображаемое имя, хеширует пароль с помощью bcrypt, создаёт UUID и сохраняет created_at в UTC. Ответ регистрации использует то же значение времени, что записано в БД. GET /api/v1/users/me возвращает данные авторизованного пользователя из PostgreSQL. Модель CreateUserRequest требует username, display_name и password длиной 12–128 символов.

Аутентификация и сессии: POST /api/v1/auth/sessions использует HTTP Basic для входа, а полученный токен передаётся клиентом как Bearer. Сессии хранятся в таблице sessions (token, user_id, expires_at, revoked); в Compose задан SESSION_TTL_SECONDS=3600. Точные правила проверки срока действия и отзыва токена определяются реализацией authenticate_user и маршрута сессий и требуют отдельной проверки.

Чаты: POST /api/v1/chats проверяет название, уникальность member_ids, наличие автора среди участников и существование каждого пользователя. Добавление чата и его участников выполняется в одной транзакции asyncpg; при ошибке транзакция откатывается. GET /api/v1/chats возвращает items и next_cursor, GET /api/v1/chats/{chat_id} проверяет принадлежность пользователя к чату.

Сообщения: POST /api/v1/chats/{chat_id}/messages разрешён только участнику чата, проверяет непустой текст длиной не более 4000 символов, сохраняет sender_id, chat_id и время создания. GET /api/v1/chats/{chat_id}/messages принимает limit и опциональный cursor; контракт предусматривает items и next_cursor. Полную корректность курсорной пагинации необходимо подтвердить тестом.

Формат времени: поля created_at и expires_at сериализуются в UTC по ISO 8601 с завершающим Z через format_iso(). Все значения времени для создания записей должны быть согласованы между SQL и JSON-ответами.

Отличия от лабораторной 1: обязательный пароль при регистрации, bcrypt-хеширование, отдельный вход через Basic, сессии с Bearer-токеном, хранение пользователей и сообщений в PostgreSQL, проверка сохранности данных при перезапуске контейнеров.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke pytthon tests/smoke.py PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. evidence/tests.txt
make check (offline-структура) python scripts/check_contract.py PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. evidence/check.txt
Данные и активные сессии переживают рестарт API и БД python tests/resilience.py --mode persistence --action-script scripts/restart.cmd PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. evidence/persistence.txt
Составная операция создания чата атомарна POST /chats с несуществующим member_id → 400, затем SELECT count(*) FROM chats новая запись не появилась evidence/rollback.txt

Эксперименты и отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose --env-file .env restart (API + PostgreSQL, volumes сохранены) через scripts/restart.sh Тот же Bearer-токен работает; подтверждённые сообщения и чат на месте; сессия не инвалидируется PASS: persistence preserved confirmed data and existing session; /health/ready → {"status":"ok"} Восстановление ≈ 10–15 с; потерь данных не

Ограничения и следующие шаги

  1. Ограничения текущей реализации. В create_chat() существование каждого участника проверяется отдельным SQL-запросом; можно заменить пакетной проверкой при дальнейшей оптимизации. Нагрузочные тесты, анализ SQL через EXPLAIN (ANALYZE, BUFFERS) и реальный failover не подтверждены.

Вывод: реализован backend мессенджера на FastAPI, asyncpg и PostgreSQL с регистрацией, сессиями, чатами, сообщениями и сохранением данных в Docker volume. В ходе отладки устранены ошибки пути миграции, пароля подключения, формата времени и обработки списка участников. Часть HTTP-сценариев подтверждена логами; окончательное соответствие лабораторной №2 необходимо зафиксировать успешными smoke- и persistence-тестами.