Files
mtusi2026lab2/REPORT.md
T

8.9 KiB
Raw Blame History

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

  • Автор, группа: Мякишев Владислав, БПИ2302
  • Целевая оценка: 3
  • Commit/PR: TODO после публикации
  • Источники и библиотеки: FastAPI, SQLAlchemy 2.1 (ORM), Alembic, psycopg 3, argon2-cffi, PyJWT; документация PostgreSQL, Alembic, RFC 7617. При разработке использовался ИИ-ассистент (Claude).

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

Нужно: Docker с Compose v2, Python 3.9+ (для тестов). Образы: postgres:17.10-alpine, python:3.14.3-slim (закреплены digest в compose.yaml/Dockerfile).

sh scripts/init-secrets.sh                 # Windows: powershell -File scripts\init-secrets.ps1
docker compose up -d --build --wait        # postgres (healthy) -> migrate (exit 0) -> api (healthy)
make test                                  # публичный smoke
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
  • init-secrets создаёт secrets/postgres_password, secrets/jwt_secret (случайные, не выводятся, вне Git) и .env из .env.example.
  • Миграции применяет разовый сервис migrate (alembic upgrade head) при каждом up; повторный запуск ничего не меняет.
  • Остановка без потери данных: docker compose down. Намеренное удаление учебных данных: docker compose down -v.
  • Свои тесты (нужен запущенный postgres, используют отдельную базу messenger_test): python -m venv .venv && .venv/bin/pip install -r requirements-test.txt && .venv/bin/python -m pytest
  • На Windows тест сохранности: python tests/resilience.py --mode persistence --action-script scripts/restart.cmd (restart.cmd — те же команды, что restart.sh).

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

Клиент → API (FastAPI, api) → PostgreSQL 17 (postgres, volume postgres_data). PostgreSQL — источник истины для пользователей, чатов, участников, сообщений и сессий (SESSION_STORE=postgres).

Роль Сервис Готовность Хранилище Порт Credentials
база postgres pg_isready volume postgres_data 127.0.0.1:5432 secret postgres_password
миграции migrate exit 0 — — secret postgres_password
API api /health/live (Docker), /health/ready (проверяет БД) нет 127.0.0.1:8080 secrets postgres_password, jwt_secret
  • Схема (миграция 0001): users (UNIQUE username, CHECK формата), sessions (PK = SHA-256 токена, expires_at), chats, chat_members (PK (chat_id, user_id)), messages (составной FK (chat_id, sender_id) → chat_members, индекс (chat_id, created_at, id) для keyset-пагинации).
  • Транзакции: создание чата — одна транзакция (чат + все участники); 201 возвращается только после COMMIT. Дубль username отсекается ограничением users_username_key → 409.
  • Аутентификация: регистрация с паролем (Argon2id). POST /auth/sessions принимает только Basic и выдаёт JWT (HS256, sub/iat/exp/jti, jti — 256 бит случайности). На сервере хранится сессия (хеш токена + срок). Bearer проверяется по подписи, exp и наличию сессии в БД; logout удаляет сессию. X-User-Id не читается.
  • Из lab1 перенесено: весь API, формат ошибок, X-Request-Id, cursor-пагинация, Dockerfile. Изменено: хранилище в памяти → PostgreSQL (app/models, app/database_functions), X-User-Id → Basic/Bearer, добавлены Compose и миграции.
  • Переменные (.env.example курса → наши): APP_HOST/APP_PORT → APP_CONFIG__RUN__HOST/PORT; DATABASE_URL_FILE → APP_CONFIG__DB__HOST/PORT/NAME/USER + APP_CONFIG__DB__PASSWORD_FILE; SESSION_TTL_SECONDS → APP_CONFIG__JWT__SESSION_TTL_SECONDS (3600).

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test против стенда в Compose PASS: lab2 public API scenario вывод команды
Данные и действующие сессии переживают рестарт API и БД без удаления volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh (на Windows — restart.cmd) PASS: persistence preserved confirmed data and existing session; у api и postgres новый StartedAt при тех же id контейнеров и том же volume evidence/persistence.txt
Таблицы, PK/FK, UNIQUE username, миграции с нуля alembic downgrade base → alembic upgrade head; alembic check схема создаётся заново; No new upgrade operations detected app/migrations/versions/0001_initial_schema.py
Повторные миграции без дублей docker compose up при существующей схеме migrate завершается с кодом 0 без Running upgrade, данные не меняются docker compose logs migrate
Атомарное создание чата pytest student-tests/test_chats_api.py при неизвестном участнике — 400 и 0 строк в chats/chat_members student-tests/test_chats_api.py
Basic только на входе, Bearer, expiry, logout, X-User-Id не работает pytest student-tests/test_auth_api.py + smoke 401 с корректным WWW-Authenticate; токен после logout и после TTL → 401 student-tests/test_auth_api.py
Пароли — password KDF pytest student-tests/test_users_api.py в БД $argon2id$…, в ответах пароля нет student-tests/test_users_api.py
Секреты/volumes вне Git git status --ignored .env, secrets/ в игноре .gitignore
Свои тесты python -m pytest 30 passed student-tests/

Проверка истечения на стенде: APP_CONFIG__JWT__SESSION_TTL_SECONDS=2 docker compose up -d --wait api → войти, подождать 3 с → запрос с токеном даёт 401. Вернуть: docker compose up -d --wait api.

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

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh: stop + up API и PostgreSQL данные и сессии сохраняются test-persistence PASS, тот же токен работает ~22 с на весь сценарий; потерь нет
docker compose stop postgres при работающем API /health/ready → 503, бизнес-запросы → 503 без деталей 503 через ~3 с (connect_timeout); после start — 200 без рестарта API (pool_pre_ping) несколько секунд; потерь нет
SIGTERM API (docker compose stop api) корректное завершение Shutting down → Соединения с базой данных закрыты → Finished server process —

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

  • Один экземпляр API и одна PostgreSQL без реплик и бэкапов: потеря volume = потеря данных.
  • Токен — JWT: payload (UUID пользователя, время) читается клиентом, секретов в нём нет; отзыв обеспечивается серверной сессией.
  • При одновременной записи курсор может пропустить сообщение, чьё created_at меньше уже выданного (окно — время между INSERT и COMMIT); повторное чтение с начала его показывает. Время назначает PostgreSQL.
  • Истёкшие сессии из таблицы не удаляются автоматически (индекс по expires_at есть).
  • Не сделано (уровень 4): Redis/Valkey, EXPLAIN на ≥10 000 сообщений, тест гонки регистрации.