Files
mtusi2026lab2/REPORT.md
T
Ильяс 9ddb2244bc
Skeleton contracts / contracts (pull_request) Canceled after 0s
feat: ЛР2 - PostgreSQL, Redis сессии и keyset-пагинация
2026-10-23 12:45:58 +03:00

11 KiB
Raw Blame History

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

  • Автор, группа: Герейханов Ильяс, БВТ2301
  • Целевая оценка: 4
  • Commit/PR: ветка solution/bvt2301-Gereykhanov. PR: ЛР 2 — БВТ2301 — Герейханов — на 4
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI, Uvicorn, PostgreSQL 16, Redis 7, asyncpg, argon2-cffi, Pydantic, Pytest, Docker Compose; документация PostgreSQL, Redis, RFC 7617 (Basic Auth), RFC 6750 (Bearer Token). ИИ использовался для генерации кода тестов pytest, отладки конфигурации Docker Compose и формулирования сценариев проверки персистентности данных.

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

  1. Версии runtime и базовых образов:

    • Локальный runtime: Linux, Docker 29.9.1, Docker Compose 5.6.0
    • API контейнер: python:3.12-slim
    • PostgreSQL: postgres:16-alpine
    • Redis: redis:7-alpine
  2. Подготовка окружения и запуск стека:

    git checkout solution/bvt2301-Gereykhanov
    cp .env.example .env
    
    # Сборка и запуск всех сервисов
    make up
    
  3. Ожидание готовности и запуск тестов:

    # Проверка smoke теста
    make test
    
    # Проверка сценария сохранности данных и сессий при рестарте
    make test-persistence ACTION_SCRIPT=scripts/restart.sh
    
    # Запуск собственных расширенных тестов
    make test-student
    
  4. Остановка и удаление контейнеров:

    # Остановка контейнеров с сохранением постоянных volumes
    make down
    
    # Остановка контейнеров с удалением volumes
    docker compose down -v
    

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

  • Схема процессов и хранилищ:
    • Клиент \to HTTP REST API (FastAPI, порт 8080) \to PostgreSQL 16 (данные пользователей, чатов, сообщений) + Redis 7 (сессии пользователей).
    • Вся инфраструктура разворачивается через compose.yaml.
  • Источник истины:
    • PostgreSQL 16: постоянное хранение состояния на именованном Docker volume pg_data.
    • Redis 7: хранение токенов сессий с TTL на Docker volume redis_data с флагом --appendonly yes (AOF-журналирование обеспечивает сохранность сессий при падении или перезапуске).
  • Безопасность и аутентификация:
    • Пароли хэшируются KDF Argon2id (argon2-cffi).
    • Вход в систему выполняется через POST /api/v1/auth/sessions с заголовком Authorization: Basic <base64(username:password)>.
    • Сессионный токен генерируется с энтропией 256 бит (secrets.token_urlsafe(32)).
    • Бизнес-эндпоинты защищены через Authorization: Bearer <token>. Заголовок X-User-Id из первой лабы игнорируется и не даёт доступа.
    • Логаут (DELETE /api/v1/auth/sessions/current) отзывает токен из Redis (повторные запросы с этим токеном получают 401).
    • При ошибке 401 сервер возвращает заголовок WWW-Authenticate: для эндпоинта логина Basic realm="messenger", charset="UTF-8", для остальных эндпоинтов Bearer realm="messenger".
  • Курсорная пагинация и индексы:
    • Порядок истории строго детерминирован составным ключом (created_at, id) по возрастанию.
    • В PostgreSQL создан составной B-Tree индекс: CREATE INDEX idx_messages_cursor ON messages (chat_id, created_at ASC, id ASC);
    • Поиск страницы выполняется через SQL-условие WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at ASC, id ASC LIMIT $4. База делает Index Scan без полного перебора таблицы.
  • Транзакции и работа с БД:
    • Создание чата и добавление участников выполняется атомарно внутри транзакции async with conn.transaction():. Если хотя бы один участник не найден, происходит rollback, пустые или повреждённые чаты в базу не попадают.
    • Подключение к PostgreSQL управляется пулом asyncpg (от 2 до 20 соединений). Все запросы параметризованы через $1, $2.
  • Что изменилось относительно ЛР1:
    • Из первой лабы перенесена базовая структура роутов FastAPI, схемы Pydantic и Dockerfile.
    • Хранилище в оперативной памяти Python полностью заменено на постоянные PostgreSQL 16 и Redis 7.
    • Заголовок X-User-Id удалён и заменён на полноценную авторизацию по сессиям.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. evidence/smoke_test.log
Сохранение данных и сессий при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session. evidence/persistence_test.log
Негативные тесты make test-student 16 тестов проходят: пустые сообщения, пароли из пробелов, запрет тела в auth sessions, Basic Auth битый base64, чужой курсор 400, дубликаты, чужой чат 404, неверный пароль, отзыв сессии, гонка 100 сообщений evidence/student_tests.log
B-Tree Index Scan на 17 000+ сообщениях EXPLAIN (ANALYZE, BUFFERS) в PostgreSQL Index Scan using idx_messages_cursor on messages. Execution Time: 0.109 ms, без Seq Scan evidence/explain_index.log
Redis сессии с AOF-персистентностью docker exec highload-redis-lab2 redis-cli config get appendonly Сессии сохраняются на redis_data volume и выдерживают рестарт контейнеров evidence/docker_services.log
Защита от гонок: 100 сообщений от 10 клиентов pytest tests_student/ -k test_concurrency_race_condition Все 100 сообщений успешно записаны и прочитаны, 100 уникальных ID, строгий порядок evidence/student_tests.log

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

  • Профиль нагрузки: скрипт tests/load.py, закрытый цикл параллельных POST-запросов отправки сообщений.
  • Параметры: длительность 30 секунд, 4 параллельных потока
  • Результаты нагрузки:
    {
      "lab": 2,
      "workload": "closed-loop POST messages; no automatic retries",
      "requested_duration_seconds": 30,
      "elapsed_seconds": 30.008,
      "concurrency": 4,
      "successful_requests": 17657,
      "failed_requests": 0,
      "error_ratio": 0.0,
      "successful_rps": 588.401,
      "successful_latency_ms": {
        "p50": 6.535,
        "p95": 8.599,
        "p99": 10.335
      }
    }
    
Воздействие Что ожидаем Что наблюдали Время восстановления
Рестарт стека docker compose restart во время активной сессии Сохранение подтверждённых данных в Postgres и токенов сессий в Redis; восстановление API \le 90 сек Контейнеры перезапустились за 2.3 сек, токен юзера сохранил валидность, история сообщений не повреждена Восстановление за 2.3 сек, потеря подтверждённых данных: 0
Обращение с отозванным токеном после logout HTTP 401 с заголовком WWW-Authenticate: Bearer 401 Unauthorized Потеря данных отсутствует, токен недействителен
Неверный пароль при входе HTTP 401 с заголовком WWW-Authenticate: Basic 401 Unauthorized, токен не выпускается Безопасность соблюдена

Ограничения

  • Какие отказы выдерживаются и какие нет:
    1. Выдерживаются: перезапуск любого или всех контейнеров (docker compose restart). Все подтверждённые данные в Postgres и токены сессий в Redis выживают благодаря томам pg_data и redis_data. Конкурентная нагрузка и параллельная запись сообщений без гонок.
    2. Не выдерживаются: удаление Docker volumes через docker compose down -v, физический выход диска из строя, падение хоста во время активной записи без репликации.
  • Учебные упрощения:
    1. Одиночные инстансы: Postgres, Redis и API запущены в одном экземпляре без репликации и кластеризации.
    2. Конфигурация: учетные данные базы зафиксированы в compose.yaml для простоты воспроизведения проверки.