10 KiB
Отчёт — лабораторная 2
- Автор, группа: Свидерский К.Ю., БПИ2301
- Целевая оценка; выбранный трек 5, если нужен: 3 (трек не нужен)
- Commit/PR: mtusi2026/mtusi2026lab2#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 с; потерь данных не |
Ограничения и следующие шаги
- Ограничения текущей реализации. В create_chat() существование каждого участника проверяется отдельным SQL-запросом; можно заменить пакетной проверкой при дальнейшей оптимизации. Нагрузочные тесты, анализ SQL через EXPLAIN (ANALYZE, BUFFERS) и реальный failover не подтверждены.
Вывод: реализован backend мессенджера на FastAPI, asyncpg и PostgreSQL с регистрацией, сессиями, чатами, сообщениями и сохранением данных в Docker volume. В ходе отладки устранены ошибки пути миграции, пароля подключения, формата времени и обработки списка участников. Часть HTTP-сценариев подтверждена логами; окончательное соответствие лабораторной №2 необходимо зафиксировать успешными smoke- и persistence-тестами.