Files
mtusi2026lab3/REPORT.md
T

14 KiB
Raw Blame History

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

  • Автор, группа: Кропивка Виктория, БВТ2303
  • Целевая оценка: 4 (уровень 3 + уровень 4)
  • Commit/PR: ветка solution/БВТ-23-Кропивка
  • Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.0, Uvicorn 0.30.6, Pydantic 2.9.2, psycopg 3.2.3, psycopg-pool 3.2.3, Alembic 1.13.3, argon2-cffi 23.1.0, redis 5.1.1, PostgreSQL 16.4-alpine, Valkey 8.0.1-alpine, HAProxy 3.0-alpine, python:3.12-slim. При подготовке решения использовался ассистент (LLM) для генерации черновика кода и объяснения контракта; итоговый код проверен публичным smoke, тестами failover/persistence/parallel idempotency и вручную.

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

Prerequisites:

  • Docker 29.2.1 (Docker Desktop для Windows + WSL2)
  • Python 3.9+ (только для тестов)
  • Git

Шаги:

  1. Клонировать репозиторий, создать .env из примера:

    cp .env.example .env
    

    Заполнить значениями:

    APP_HOST=0.0.0.0
    APP_PORT=8080
    APP_ENV=lab
    SESSION_TTL_SECONDS=3600
    POSTGRES_USER=messenger
    POSTGRES_PASSWORD=changeme_local_only
    POSTGRES_DB=messenger
    DATABASE_URL=postgresql://messenger:changeme_local_only@postgres:5432/messenger
    CACHE_URL=redis://cache:6379/0
    API_REPLICAS=2
    IDEMPOTENCY_TTL_SECONDS=86400
    
  2. Запустить стенд:

    docker compose --env-file .env up -d --build
    

    Compose:

    • postgres — 16.4-alpine, named volume, только внутренняя сеть.
    • cache — Valkey 8.0.1-alpine, named volume, только внутренняя сеть.
    • migrate — запускает alembic upgrade head однократно, завершается.
    • api — 2 реплики (deploy.replicas: 2), без публикации портов.
    • lb — HAProxy 3.0-alpine, публикует 127.0.0.1:8080.
  3. Дождаться готовности:

    docker compose ps
    

    Ожидаемо: postgres, cache, api-1, api-2 — healthy, lb — up, migrate — Exited (0).

  4. Прогнать тесты:

    make test BASE_URL=http://localhost:8080
    make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
    make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:8080
    
  5. Остановить:

    docker compose --env-file .env down
    

    Данные сохраняются в named volumes mtusi_lab3_postgres_data, mtusi_lab3_cache_data.

    Намеренное удаление:

    docker compose --env-file .env down -v
    

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

  • Топология. Клиент → HAProxy (LB, порт 8080) → 2 API-реплики (внутренняя сеть, порт 8080) → общие Postgres и Valkey.
  • Балансировка. HAProxy roundrobin, healthcheck GET /health/ready каждые 2 секунды, fall 2 rise 2. Отказ реплики обнаруживается за ~4 секунды.
  • Динамическое обнаружение реплик. HAProxy резолвит api через Docker DNS 127.0.0.11, server-template api 1-10. Если реплика добавилась или упала — HAProxy видит изменения.
  • X-Instance-Id. Генерируется в src/instance.py из hostname контейнера (или UUID, если hostname недоступен). Добавляется в каждый ответ middleware RequestIdMiddleware. Стабилен в жизни процесса.
  • Идемпотентность. Таблица idempotency_keys (PK: user_id + method + path + key). Логика:
    1. SELECT — если ключ уже есть и body совпадает → возвращаем сохранённый ответ.
    2. Если body другой → 409.
    3. INSERT резервирования (response_status=0), при UniqueViolation → перечитываем, ждём или возвращаем 409.
    4. Создаём сообщение, UPDATE результата.
  • Источник истины — Postgres. Valkey используется как deny-list отозванных сессий (не кэш валидных).
  • Сессии. Bearer-токен, SHA-256-хеш в sessions, logout добавляет в deny-list.
  • Пароли. Argon2id.
  • Миграции. Alembic, отдельный сервис migrate, запускается один раз, API ждёт service_completed_successfully.
  • CPU/RAM-лимиты на всех сервисах (deploy.resources.limits).
  • API не публикуют порты — только LB.

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

Уровень 3

Критерий Команда/сценарий Результат
Публичный smoke make test BASE_URL=http://localhost:8080 PASS: lab3 public API scenario
≥2 API-реплики docker compose ps mtusi2026lab3-api-1, -api-2 Up
Разные реплики обслуживают for i in 1..6; do curl .../health/live | grep x-instance-id; done чередование 5fff16304a90 / 8a77b9d87d21
LB — единая точка входа curl http://localhost:8080/health/live ответ приходит от одной из реплик, порт публикует только LB
Остановка одной реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh {"observed_instances_before": 2, "successful_writes": 106, "failed_attempts": 1, "first_recovery_seconds": 2.718} → PASS
Идемпотентность smoke: повтор POST с тем же ключом возвращает тот же Message PASS
make test-persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS

Уровень 4

Критерий Команда/сценарий Результат
LB исключает недоступный backend make test-failover восстановление за 2.7 секунды, вторая реплика продолжает обслуживать
Последовательная остановка каждой реплики make test-failover дважды прогон 1: recovery 2.718s, прогон 2: recovery 2.488s; оба PASS
Параллельная идемпотентность python3 student_tests/test_parallel_idempotency.py Status codes: {409: 9, 201: 1}, Messages in history: 1
CPU/RAM-лимиты grep -A5 "deploy:" compose.yaml cpus/memory на всех сервисах
API не публикуют порты docker compose ps у api нет 0.0.0.0:8080, порт только у lb
Нет container_name grep container_name compose.yaml пусто
Rolling update под нагрузкой load.py --duration 60 + параллельно docker restart api-1 && docker restart api-2 3197 успешных, 9 ошибок (0.28%), 53.2 RPS, p50=25ms, p95=183ms, p99=272ms
Миграции однократно сервис migrate в docker compose ps Exited (0)

Метрики failover

Прогон 1:

{"observed_instances_before": 2, "successful_writes": 106, "failed_attempts": 1, "first_recovery_seconds": 2.718}

Прогон 2:

{"observed_instances_before": 2, "successful_writes": 105, "failed_attempts": 1, "first_recovery_seconds": 2.488}

Интерпретация:

  • observed_instances_before: 2 — балансировка работала до отказа.
  • successful_writes: ~105 — вторая реплика продолжала обрабатывать трафик.
  • failed_attempts: 1 — только один запрос попал в момент обнаружения отказа (HAProxy inter 2s × fall 2 = ~4s).
  • first_recovery_seconds: ~2.5s — укладывается в требование lab3 «≤10 секунд».

Метрики rolling update

{
  "requested_duration_seconds": 60.0,
  "successful_requests": 3197,
  "failed_requests": 9,
  "error_ratio": 0.002807,
  "successful_rps": 53.216,
  "successful_latency_ms": {
    "p50": 24.915,
    "p95": 182.695,
    "p99": 271.553
  }
}

Интерпретация: во время 60-секундной нагрузки обе реплики были поочерёдно перезапущены. 9 ошибок (0.28%) — это те запросы, которые попали в момент grace period реплики. Все остальные обработаны второй репликой.

Параллельная идемпотентность

Results: 10 responses
Status codes: {409: 9, 201: 1}
Messages in history: 1
PASS: parallel idempotency — exactly one message created

10 потоков одновременно послали POST с одним Idempotency-Key и разными body. Один получил 201, остальные — 409 conflict. В истории одно сообщение.

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

Воздействие Ожидаем Наблюдали Восстановление
Остановка реплики api-1 Вторая продолжает 105 успешных записей, 1 фейл ~2.5 секунды
Остановка реплики api-2 Вторая продолжает 106 успешных, 1 фейл ~2.7 секунды
Перезапуск всего стека с volumes Данные и сессия выживают PASS persistence ~5 секунд
Параллельные POST с одним ключом Одно сообщение 1 сообщение в истории —
Rolling update под нагрузкой ≤ нескольких % ошибок 0.28% (9 из 3206) мгновенно

Исправления по замечаниям ревью

Уровень 3

  1. Небезопасный повтор после обрыва POST. Ключ резервировался со status=0 до создания сообщения — при падении ключ залипал. Исправлено: INSERT idempotency_keys и INSERT messages в одной транзакции, response_status=201 сразу. При падении — ROLLBACK откатывает всё.

  2. Конкурентная идемпотентность. В except UniqueViolation возвращался 409 вместо перечитывания. Исправлено: retry loop (5 попыток по 50 мс). При одинаковых запросах все потоки получают тот же 201 и то же тело.

    Проверка: test_parallel_idempotency.py, 10 потоков → Status codes: {201: 10}, Unique response bodies: 1, Messages in history: 1.

  3. ACL при повторе. Проверка ключа шла до проверки доступа → посторонний видел 409. Исправлено: проверка chat_members первой; посторонний всегда получает 404.

  4. X-Instance-Id: unknown. В compose.yaml было INSTANCE_ID: ${HOSTNAME:-unknown} — переменная WSL, не контейнера. Исправлено: строка удалена, src/instance.py использует socket.gethostname() — у каждой реплики уникальный ID.

  5. Ошибки контракта.

    • Неверный UUID → 400: функция valid_uuid в main.py, применяется в роутах с {chat_id}.
    • 500 без заголовков: все обработчики ошибок добавляют X-Request-Id и X-Instance-Id через _with_headers.
    • Readiness с неправильным request_id: берётся из _rid(request), совпадает с заголовком.

Уровень 4

  1. Конкурентная идемпотентность — см. п. 2 выше.
  2. Migrate без лимитов — добавлен deploy.resources.limits (cpus: 0.5, memory: 256M).
  3. Healthcheck в отчёте. Синхронизировано:
    • postgres — pg_isready каждые 5s.
    • cache — valkey-cli ping каждые 5s.
    • api — urllib /health/live каждые 5s, start_period: 15s.
    • migrate — healthcheck нет (разовый сервис).
    • lb — healthcheck нет в Compose; HAProxy проверяет бэкенды через option httpchk GET /health/ready (inter 2s fall 2 rise 2) в haproxy.cfg.

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

  • SPOF: LB (HAProxy) и Postgres — единственные экземпляры. Падение LB → сервис недоступен. Падение Postgres → 503. Это осознанное ограничение lab3: HA для БД и LB — тема lab5+ или трека «Отказ узла».
  • HAProxy на одном узле: на Docker Desktop не проверяется перенос между физическими узлами. Это lab3 трек 2.
  • Valkey не персистентный: deny-list теряется при рестарте. Это безопасно — Postgres источник истины.
  • Идемпотентные ключи хранятся вечно — cleanup по IDEMPOTENCY_TTL_SECONDS не реализован. Для lab3 приемлемо.
  • Параллельный POST в момент рестарта реплики: если реплика упала между INSERT idempotency_keys (status=0) и UPDATE, ключ останется «в процессе» до TTL. Клиент получит 409. Для lab3 приемлемо, для продакшена — нужен cleanup-job.

Следующий шаг (если делать «5»):

  • Трек 1: цена масштабирования (1/2/4 реплики под нагрузкой, saturation point).
  • Трек 2: отказ узла (несколько физических хостов, Swarm).