Files
mtusi2026lab3/REPORT.md
T

10 KiB
Raw Blame History

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

Автор, группа: Кашкарова Арина, БПИ2302
Целевая оценка: 3
Commit/PR: TODO
Использованные источники, библиотеки и помощь ИИ: Python 3.11, FastAPI, Uvicorn, Pydantic, PostgreSQL 16.1, psycopg2-binary, bcrypt, Docker, Docker Compose. ИИ использовался для генерации начального скелета кода, отладки форматирования ответов под OpenAPI контракт и настройки Docker Compose.

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

Prerequisites: Python 3.9+, Docker, Docker Compose, Git.

  1. Клонирование и подготовка окружения:

    git clone https://gitea.privcloud.tech/ari_kash/mtusi2026lab2.git
    cd mtusi2026lab3
    python3 -m venv .venv
    source .venv/Scripts/activate
    pip install -r requirements.txt
    pip install -r requirements-dev.txt
    
    
  2. Создание .env:

    cp .env.example .env
    
  3. Сборка и запуск стенда (API x2 + PostgreSQL + Nginx):

    docker compose up -d --build
    
  4. Ожидание готовности и проверка:

    curl http://localhost:8080/health/ready
    
  5. Запуск тестов:

    export PYTHONUTF8=1
    # Smoke test (базовый сценарий API)
    python tests/smoke.py --base-url "http://localhost:8080"
    
    # Test persistence (проверка сохранности данных после рестарта)
    python tests/resilience.py --mode persistence --action-script "scripts/restart.bat" --base-url "http://localhost:8080"
    
    # Test failover (проверка отказоустойчивости при падении одной реплики)
    python tests/resilience.py --mode failover --action-script "scripts/stop-one.bat" --base-url "http://localhost:8080"
    
  6. Безопасная остановка и удаление учебных данных:

    # Остановка контейнеров (данные сохраняются в volume)
    docker compose down
    
    # Полное удаление включая volumes (сброс всех данных)
    docker compose down -v
    

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

Схема процессов и хранилищ Клиент → HTTP API (FastAPI) → PostgreSQL ↓ Сессии в PostgreSQL

Компоненты:

  • Nginx 1.27: Единая точка входа (Load Balancer) на порту 8080. Настроен proxy_next_upstream и max_fails=2 fail_timeout=5s для быстрого исключения упавшей реплики.
  • API-реплики (api-1, api-2): Два идентичных контейнера FastAPI + Uvicorn. Для различия в ответах отдают заголовок X-Instance-Id (генерируется из переменной окружения).
  • PostgreSQL 16.4: Общий источник истины для всех данных, включая сессии и ключи идемпотентности.
  • Named volume: pgdata:/var/lib/postgresql/data обеспечивает сохранность данных при перезапуске.

Таблицы базы данных Схема включает 6 таблиц: users, chats, chat_members, messages, sessions (из lab2).

idempotency_keys (новая) — хранит user_id, method, path, key, request_hash, status_code, response_body. Первичный ключ (user_id, method, path, key) защищает от одновременных дублей. Миграции: Файлы src/migrations/001_initial.sql и src/migrations/002_idempotency.sql запускаются idempotently при старте приложения.

Идемпотентность (Lab 3):

  • На POST /api/v1/chats/{chat_id}/messages теперь обязателен заголовок Idempotency-Key.
  • При получении запроса API вычисляет SHA-256 хеш тела и ищет ключ в БД. Если находит и хеш совпадает — возвращает сохраненный ответ (201). Если хеш другой — возвращает 409 Conflict.
  • Если ключа нет, сообщение создается атомарно вместе с записью в idempotency_keys в одной транзакции.

Балансировка и отказоустойчивость:

  • Балансировщик Nginx распределяет запросы между api-1 и api-2 по алгоритму Round Robin.
  • Публикация портов API наружу убрана (в compose.yaml нет ports у api-сервисов). Доступ только через Nginx (порт 8080).
  • Healthcheck базы данных гарантирует, что API не начнут прием трафика, пока PostgreSQL не будет готов.

Соответствие .env.example

  • POSTGRES_PASSWORD=messenger_pass — используется для подключения к БД.
  • SESSION_TTL_SECONDS=3600 — читается в auth.py.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url "http://localhost:8080" PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.3 screenshots/lab3_smoke_pass.png
Persistence test python tests/resilience.py --mode persistence --action-script "scripts/restart.bat" --base-url "http://localhost:8080" Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. screenshots/lab3_persistence_pass.png
Failover test python tests/resilience.py --mode failover --action-script "scripts/stop-one.bat" --base-url "http://localhost:8080" Executing explicit failover hook; hook output suppressed to avoid leaking secrets.
{"observed_instances_before": 2, "successful_writes": 79, "failed_attempts": 2, "first_recovery_seconds": 2.812}
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. screenshots/lab3_failover_pass.png
Две реплики через LB curl -i -H "Connection: close" http://localhost:8080/health/live В ответах поочередно появляются заголовки X-Instance-Id: api-1 и X-Instance-Id: api-2 screenshots/lab3_instances.png
Конкурентная идемпотентность Отправка 10 параллельных POST с одинаковым Idempotency-Key В БД создается только 1 сообщение, остальные получают 201 с тем же id —

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

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Отказ одной API-реплики (scripts/stop-one.bat) Nginx исключает упавший узел, запросы продолжают обрабатываться оставшейся репликой. Сессия не теряется. Тест прошел успешно. Из 82 попыток записи 80 успешны, 2 упали во время переключения. Система восстановилась. 2.812 секунды до полного восстановления (Nginx перестал слать запросы на упавший контейнер). Данные не потеряны.
Перезапуск всего стенда (scripts/restart.bat) Реплики и БД перезапускаются. Токен сессии остается валидным, данные не теряются благодаря volume. После рестарта тот же Bearer-токен позволяет читать данные. Persistence-тест вернул PASS. ~5-7 секунд на старт PostgreSQL + API. Данные сохранены.
Остановка PostgreSQL API должен вернуть 503 Service Unavailable на /health/ready. Проверено вручную: при падении БД балансировщик отсекает реплики. Мгновенно после потери соединения.

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

Что реализовано и работает: ✅ Стенд из двух API-реплик за балансировщиком Nginx ✅ Общая база данных PostgreSQL (сессии и идемпотентность не теряются при рестарте) ✅ Сервер генерирует заголовки X-Request-Id и X-Instance-Id во всех ответах ✅ Обязательный заголовок Idempotency-Key при отправке сообщений предотвращает создание дублей ✅ Остановка любой одной реплики не приводит к потере данных и не ломает сессию ✅ Все публичные тесты (make test, persistence, failover) проходят успешно

Ограничения:

  • Стенд использует один Docker-host, поэтому отказ самого хоста или PostgreSQL не покрывается (нет репликации БД). Для оценки 3 это не требуется.
  • Nginx в текущей конфигурации не использует sticky sessions, что соответствует требованиям (клиент может ходить на разные реплики).