Files
mtusi2026lab2/REPORT.md

10 KiB
Raw Permalink Blame History

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

  • Автор, группа: Яковлев Матвей Дмитриевич, БПИ2304
  • Целевая оценка; выбранный трек 5, если нужен: 3
  • Commit/PR: ветка: (solution/BPI2304-Yakovlev); MR: (mtusi2026/mtusi2026lab2#189)
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.135.3, Uvicorn 0.44.0, psycopg 3.3.3, PostgreSQL 16-alpine, Dockerfile из репозитория; версии закреплены в requirements.txt, compose.yaml и Dockerfile. При подготовке использовалась помощь Claude.

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

Требуется Docker с Compose. Секреты создаются локально и в Git не попадают (.env игнорируется).

git clone <url-вашего-fork> && cd <каталог>
cp .env.example .env
# В .env задайте синтетические локальные POSTGRES_USER / POSTGRES_PASSWORD /
# POSTGRES_DB / DATABASE_URL. Пример: postgresql://messenger:<password>@db:5432/messenger
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -i http://localhost:8080/health/ready      # 200 {"status":"ok"}
python tests/smoke.py --base-url http://localhost:8080

Без Docker (для отладки): задайте DATABASE_URL на доступный PostgreSQL, создайте БД. python -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python -m app. Миграции применяются при старте приложения; повторный запуск ничего не дублирует (schema_migrations хранит список применённых файлов).

Остановка и безопасная работа с данными:

docker compose --env-file .env stop api db      # данные остаются в volume pgdata
docker compose --env-file .env start api db
# Явное намеренное удаление учебных данных (не используется в тестах):
docker compose --env-file .env down -v

Проверка сохранности (перезапуск API и PostgreSQL с сохранением volume):

# Linux/macOS:
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Windows (локально):
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080

Полный вывод команд — evidence/lifecycle.txt.

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

Клиент → FastAPI/Uvicorn (один процесс, один worker) → PostgreSQL 16.

  • Источник истины — PostgreSQL. Все обязательные данные (пользователи, чаты, участники, сообщения, сессии) хранятся в таблицах; процесс не держит их копию. Приложение использует небольшой пул соединений (DB_POOL_MAX, по умолчанию 8) с таймаутом подключения 3 с.
  • migrations/001_init.sql — версионируемая схема: PK/FK, UNIQUE(username), CHECK-ограничения длины/формата, индексы ix_chat_members_user, ix_messages_history (chat_id, created_at, id), ix_sessions_expiry. Применяется один раз, фиксируется в schema_migrations.
  • Транзакции: регистрация пользователя, создание чата (проверка участников + chat
    • все membership-строки) и отправка сообщения выполняются в одной транзакции; при ошибке — rollback. Уникальность username и включение вызывающего в member_ids проверяются до вставки.
  • Аутентификация lab2: POST /auth/sessions принимает только Basic; пароль проверяется библиотечным KDF hashlib.scrypt (n=2^14, r=8, p=1, соль 16 байт, 256-битный вывод) — не SHA-256 и не plaintext. Сессия — непрозрачный токен (256 бит entropy, urlsafe_b64encode(os.urandom(32))); в БД хранится только SHA-256 хэш токена, expires_at и user_id. TTL задаётся SESSION_TTL_SECONDS (по умолчанию 3600). Бизнес-endpoint'ы принимают только Bearer; X-User-Id игнорируется. Logout удаляет строку сессии. Basic на бизнес-endpoint и неверный Bearer получают 401 с корректным WWW-Authenticate.
  • Пагинация — keyset по (created_at, id); курсор — base64url JSON с привязкой к типу ресурса и ID чата/пользователя, поэтому курсор другого чата даёт 400. Индекс ix_messages_history позволяет читать одну страницу без полного scan истории.
  • Отказы: /health/ready делает SELECT 1 и возвращает 503 в общем формате ошибки, если БД недоступна. X-Request-Id есть в каждом ответе; X-Instance-Id стабилен для процесса. POST /users с занятым username → 409, чужой чат и несуществующий чат → одинаковый 404.
  • Соответствие .env.example: переменные DATABASE_URL / DATABASE_URL_FILE и SESSION_TTL_SECONDS; SESSION_STORE=postgres — level 3, Redis/Valkey не используется (уровень 4 не заявляется).

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 PASS: lab2 public API scenario... evidence/lifecycle.txt, раздел 4
Данные и сессии переживают рестарт API+БД make test-persistence ACTION_SCRIPT=scripts/restart.sh (на Windows — scripts/restart.cmd) PASS: persistence preserved confirmed data and existing session; старый Bearer-токен читает те же данные; счётчики строк до/после рестарта, schema_migrations без повторов evidence/lifecycle.txt, разделы 3, 6, 7
PostgreSQL, FK/PK/UNIQUE, миграции с нуля docker compose up -d --build; psql ... SELECT две таблицы миграций/данных созданы с чистого volume; 001_init.sql применён один раз evidence/lifecycle.txt, разделы 1, 3
Basic только на /auth/sessions, Bearer на остальных, expiry и logout публичный smoke: 401 на Basic для /users/me, 401 на X-User-Id, проверка X-User-Id поверх Bearer, logout → 401 PASS evidence/lifecycle.txt, раздел 4
Пароли хешируются password KDF python -m unittest discover -s student-tests 9 тестов OK: scrypt, соли, UTF-8 пароль с : evidence/lifecycle.txt, раздел 8
Атомарное создание чата, rollback и курсор smoke + собственные юнит-тесты PASS; курсор привязан к чату, мусор отклоняется evidence/lifecycle.txt, разделы 4, 8

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

Не проводились (целевая оценка 3). Для уровня 5 потребовались бы отдельные исследования согласованности кэша или плана запросов — в этой работе не заявлены.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Перезапуск API и PostgreSQL с сохранением pgdata пользователи, чаты, сообщения и действующая сессия остаются; токен работает подтверждённые данные и тот же Bearer-токен прочитаны после рестарта; schema_migrations без повторов автоматический hook + ожидание готовности; потеря данных — 0

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

  • Уровень 4 не реализован: Redis/Valkey не подключается (SESSION_STORE=postgres), нет отдельного теста expiry при коротком TTL и автоматической проверки отказа БД — эти пункты требует оценка 4.
  • Один процесс API: created_at назначается сервером, порядок страниц определяется (created_at, id); при параллельной вставке возможны одинаковые метки времени, но детерминированный second key (id) исключает потери/дубли при обходе неизменной истории.
  • Хранение сессий в PostgreSQL означает, что рестарт БД сохраняет сессии только вместе с volume pgdata; down -v удаляет их намеренно.
  • Для удалённой демонстрации нужен TLS: HTTP допускается только для локального изолированного стенда с синтетическими данными.