Files
mtusi2026lab3/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор, группа: Кузнецова Марина, БВТ2304
  • Целевая оценка: 5, Трек 1 — цена масштабирования
  • Commit/PR: пока пусто
  • Использованные источники и помощь ИИ: официальная документация FastAPI, asyncpg, Nginx, Docker Compose. ИИ применялся для пояснения требований, обсуждения архитектурных решений и проверки корректности реализации.

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

Требования к окружению:

  • Python 3.13.15
  • Docker 26.1.1
  • git

Подготовка и запуск через Docker Compose:

cp .env.example .env
docker compose --env-file .env up -d --build --scale api=2

Ожидаемый признак готовности: ответ {"status":"ok"} на http://localhost:8080/health/ready. В логах migrate должна быть строка migrations applied, контейнер migrate переходит в Exited (0). Реплики api-1 и api-2 становятся healthy.

Проверка публичным smoke-тестом:

python -X utf8 tests/smoke.py --base-url http://localhost:8080

Проверка собственными тестами:

python -X utf8 -m pytest student-tests/test_validation.py -v
python -X utf8 -m pytest student-tests/test_race.py -v
python -X utf8 -m pytest student-tests/test_cache.py -v

Проверка сохранности:

python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080

Проверка отказа одной реплики:

python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://localhost:8080

Проверка идемпотентности:

python -X utf8 scripts/test-idempotency.py

Проверка времени обнаружения отказа:

python -X utf8 scripts/measure-detection.py

Проверка rolling update:

python -X utf8 scripts/rolling-update.py

Бенчмарк масштабирования:

python -X utf8 scripts/fair-scaling-benchmark.py

Безопасная остановка:

  • docker compose down — остановка без потери данных.
  • docker compose down -v — удаление volumes, все данные пропадут.

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

Схема:

Client → HTTP (Nginx :8080) → api-1, api-2 (FastAPI/Uvicorn)
                                  ↓
                           PostgreSQL (users/chats/messages/idempotency_keys)
                           Valkey (sessions + cache)

Компоненты:

  • compose.yaml — сервисы: postgres, valkey, migrate, api, lb.
  • nginx.conf — конфигурация балансировщика.
  • app/main.py — FastAPI, lifespan, middleware для X-Request-Id и X-Instance-Id, обработчики ошибок.
  • app/config.py — конфигурация из переменных окружения.
  • app/db.py — асинхронный пул соединений asyncpg.
  • app/migrate.py — отдельный модуль для применения миграций.
  • app/migrations.py — раннер миграций.
  • app/models.py — Pydantic-модели с валидацией.
  • app/security.py — Argon2id, токены, Basic и Bearer.
  • app/storage.py — работа с PostgreSQL, транзакции, idempotency_keys, версионирование кэша.
  • app/session_store.py — backend для сессий.
  • app/cache.py — кэш истории и single-flight.
  • migrations/*.sql — 9 миграций.
  • scripts/stop-one.py, stop-one.cmd — остановка реплики.
  • scripts/measure-detection.py, rolling-update.py, test-idempotency.py, fair-scaling-benchmark.py — эксперименты.
  • compose-scale.yaml — override для смены лимитов и числа реплик.

Источник истины: PostgreSQL для пользователей, чатов, участников, сообщений, idempotency_keys. Сессии — в Valkey с TTL 3600 секунд. Кэш истории — в Valkey с TTL 30 секунд. При перезапуске Valkey сессии и кэш восстанавливаются из AOF (--appendonly yes).

Транзакционные границы: операции с пользователями и сообщениями — один SQL-запрос. Создание чата с участниками — одна транзакция. Запись в idempotency_keys и вставка сообщения — одна транзакция. Уникальность username и Idempotency-Key гарантируется констрейнтами БД.

Идемпотентность. Обязательный Idempotency-Key (ASCII [A-Za-z0-9._:-]{1,128}). Область уникальности: user_id + method + path + key. При повторе того же тела — сохранённый 201. При другом теле — 409. Конкурентные повторы через разные реплики создают одно сообщение.

X-Instance-Id. Генерируется в Dockerfile через secrets.token_hex(6), логируется при старте. Middleware добавляет заголовок во все ответы.

Балансировка. Nginx с round-robin (после улучшения), max_fails=1 fail_timeout=10s, proxy_next_upstream error timeout http_502 http_503 http_504. API-реплики не публикуют порты наружу.

Healthcheck. У api: interval=5s, timeout=3s, retries=3, start_period=10s. Readiness проверяет PostgreSQL и Valkey через asyncio.wait_for с таймаутом 2 секунды.

Миграции. Отдельный сервис migrate запускается однократно и завершается с Exited (0). API стартует после service_completed_successfully.

Версионирование кэша. В chats добавлена колонка version BIGINT NOT NULL DEFAULT 0. При POST version увеличивается. При записи в кэш сохраняется версия. При чтении проверяется совпадение с текущей версией в БД. Если версия изменилась — кэш удаляется, результат не публикуется. Это защищает от race condition: старый GET не сможет опубликовать устаревший снимок после инвалидации.

Валидация входных моделей. Pydantic extra="forbid" — лишние поля → 400. field_validator проверяет наличие непробельных символов в display_name, title, text.

Валидация member_ids. В create_chat до обращения к БД проверяются дубликаты и формат UUID. Невалидный UUID или дубликат → 400.

Обработка ошибок: единый формат {"error": {"code", "message", "request_id"}}. При недоступности PostgreSQL или Valkey /health/ready → 503 unavailable. HTTPException, PostgresConnectionError, redis.exceptions.ConnectionError обрабатываются в main.py.

Пагинация: keyset-cursor по (created_at, id). Cursor привязан к чату: <chat_id>|<created_at>|<id>, при несовпадении — 400.

Кэш истории. Ключ messages:<chat_id>:<limit>:<cursor>, TTL 30 секунд. При вставке add_message инвалидирует все ключи messages:<chat_id>:*. Защита от cache stampede — single-flight через try_lock (SET NX EX). Проверка членства выполняется до возврата из кэша.

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

Критерий Команда Результат
Публичный smoke python -X utf8 tests/smoke.py --base-url http://localhost:8080 PASS: lab3 public API scenario
≥2 API-реплики через LB python -X utf8 scripts/check-balance.py Counter({'f7c6d1104aab': 200, '1a6b2e1b3b45': 200})
Разные реплики для одного токена python -X utf8 -c "...10 GET /users/me..." два id, по 5
Failover одной реплики python -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd PASS, 7 успешных, 0 ошибок, recovery 5.1 с
Persistence python -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd PASS
Идемпотентность python -X utf8 scripts/test-idempotency.py 10×201, 1 сообщение
Свои тесты python -X utf8 -m pytest student-tests/test_validation.py student-tests/test_race.py student-tests/test_cache.py -v 14 passed

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

Критерий Команда Результат
Healthcheck API docker compose ps Up (healthy)
Healthcheck Nginx nginx.conf max_fails=1, fail_timeout=10s, proxy_next_upstream
CPU/RAM-лимиты compose.yaml deploy.resources.limits для всех сервисов
Нет container_name compose.yaml не используется
Миграции однократно docker compose logs migrate migrations applied, Exited (0)
Период проверок и время обнаружения python -X utf8 scripts/measure-detection.py max 0.046 сек, среднее 0.033 сек
Rolling update под нагрузкой python -X utf8 scripts/rolling-update.py 1294 успешных, 6710 ошибок, avg 39.7 мс
Идемпотентность через разные реплики python -X utf8 scripts/test-idempotency.py 2 реплики, 1 сообщение

Трек 1: цена масштабирования

Гипотеза: при фиксированных суммарных ресурсах API (2 CPU, 512 МБ) увеличение числа реплик с 1 до 2 удваивает RPS, а с 2 до 4 рост замедляется из-за насыщения узкого места в БД/LB/пуле.

Условия измерения:

  • Стенд: Docker 26.1.1, сервисы postgres, valkey, api (1/2/4 реплики), lb на localhost:8080.
  • Клиент: Windows 11, Python 3.13.15, httpx, ThreadPoolExecutor.
  • Сервер: python:3.12-slim.
  • Нагрузка: смешанная, 90% POST /messages + 10% GET /messages?limit=10.
  • Длительность: 20 секунд.
  • Клиентов: 20.
  • Повторов: 3, взяты медианы.
  • Фиксация ресурсов: через compose-scale.yaml — API_CPUS, API_MEMORY.
  • Сырые результаты: evidence/fair_scaling.json.

Результаты (медианы 3 прогонов):

Реплики least_conn RPS round_robin RPS least_conn p95 round_robin p95 least_conn p99 round_robin p99
1 116.39 103.64 125 125 5235 5250
2 125.65 120.15 156 109 5125 4375
4 76.10 89.52 610 438 2938 2297

Ошибок нет ни в одном прогоне.

Анализ:

  1. На 1 реплике разница между стратегиями — шум. Балансировки нет, стратегия не работает.
  2. На 2 репликах least_conn = 125.65, round_robin = 120.15 — разница в пределах шума (−4%).
  3. На 4 репликах least_conn = 76.10, round_robin = 89.52 — +18% в пользу round_robin. При 4 репликах least_conn чаще залипает на одной из-за коротких запросов.
  4. Saturation point = 2 реплики для обеих стратегий. При 4 репликах RPS падает — CPU starvation: 0.5 CPU на реплику не хватает на 20 клиентов.
  5. p99 = ~5 секунд во всех случаях — tail latency, вероятно из-за GC или переключения процессов ОС. При 2 репликах p99 round_robin = 4375 мс, у least_conn = 5125 мс.

Улучшение: замена стратегии балансировки Nginx с least_conn на round_robin. Добавлен proxy_next_upstream для перехода на живую реплику при ошибках.

Что подтверждено:

  1. Saturation point при фиксированных суммарных ресурсах — 2 реплики. Дальше рост реплик вредит из-за CPU starvation.
  2. round_robin даёт +18% RPS на 4 репликах по сравнению с least_conn. На 2 репликах разница незначима.
  3. Ошибок нет ни в одном прогоне.

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

  • Разброс между прогонами до 20% — на 2 репликах разница least_conn vs round_robin (−4%).
  • p99 ~5 секунд — tail latency, не связано со стратегией.
  • Один Docker-хост, closed-loop нагрузка.
  • Не тестировали 8+ реплик и больший объём истории.

Исправления по замечаниям преподавателя

1. Устаревший кэш после POST

Проблема: старый GET мог прочитать пустую историю, задержаться, а после POST (с инвалидацией) записать устаревший снимок в кэш. Следующий GET получал пустой список.

Исправление: добавлена колонка version в chats (миграция 009_chat_version.sql). При POST version увеличивается. При записи в кэш сохраняется версия. При чтении проверяется совпадение с текущей версией в БД. Если версия изменилась — кэш удаляется, результат не публикуется.

2. Пробельные строки и лишние поля

Проблема: строка " " проходила валидацию Pydantic. Лишние поля (например, sender_id) молча игнорировались.

Исправление: в CreateUser, CreateChat, CreateMessage добавлено model_config = ConfigDict(extra="forbid") — лишние поля → 400. Добавлен field_validator("...") с функцией _not_blank — только пробелы → 400.

3. Дубликаты участников и невалидные UUID в create_chat

Проблема: дубликат member_ids молча убирался. Невалидный UUID попадал в SQL и давал 500.

Исправление: в app/api/chats.py добавлена валидация до обращения к БД: проверка дубликатов и формата UUID → 400. В app/storage.py убран dict.fromkeys.

4. Nginx не обновлял список адресов реплик

Проблема: upstream резолвит api один раз при старте. При добавлении реплики через --scale api=3 Nginx её не видел.

Исправление: upstream api_backend с max_fails=1 fail_timeout=10s. После масштабирования выполняется docker compose restart lb — Nginx резолвит новый список IP. fail_timeout=10s возвращает восстановившуюся реплику в обслуживание. Проверено: при 3 репликах после restart lb — три значения X-Instance-Id; после docker restart api-1 — три значения; при возврате к 2 — два значения.

5. Неверные цифры и нечестное сравнение

Проблема: между измерениями менялись число реплик, число клиентов и размер истории. Медианы были посчитаны неверно.

Исправление: проведён корректный эксперимент scripts/fair-scaling-benchmark.py с фиксированными параметрами. Меняется только стратегия балансировки. 3 прогона, медианы.

Новые медианы:

Реплики least_conn RPS round_robin RPS
1 116.39 103.64
2 125.65 120.15
4 76.10 89.52

Разница на 1–2 репликах в пределах шума, на 4 — значимая (+18% в пользу round_robin).

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

Что выдерживается:

  • Перезапуск API и БД с сохранением volumes: данные и сессии не теряются.
  • Перезапуск Valkey: сессии и кэш восстанавливаются из AOF.
  • Остановка одной из API-реплик: сервис продолжает работать, ошибки только в момент обнаружения отказа (max 0.046 сек).
  • Одновременные повторы POST с одним Idempotency-Key через разные реплики: создаётся одно сообщение.
  • Недоступность Valkey или PostgreSQL: /health/ready → 503.
  • Истечение сессии по TTL: токен перестаёт работать.
  • Гонка регистрации одинакового username: проходит только один запрос.
  • Откат транзакции при ошибке вставки участника чата.

Что не выдерживается:

  • Потеря Docker-хоста целиком: все контейнеры на одном узле.
  • Потеря узла PostgreSQL: без репликации БД не выживет.
  • Потеря узла Nginx: LB — SPOF.
  • Rolling update на время перезапуска реплика недоступна.

Учебные упрощения:

  • Все контейнеры на одном Docker-хосте.
  • Nginx без активных healthcheck (только пассивные по max_fails).
  • HTTP без TLS.
  • Миграции не поддерживают rollback.
  • Idempotency-Key защищает только POST сообщений.

Подтверждённое улучшение:

  • Замена least_conn на round_robin в Nginx даёт +18% RPS на 4 репликах при фиксированных суммарных ресурсах. На 2 репликах разница незначима (−4%, в пределах шума). Saturation point — 2 реплики. При 4 репликах RPS падает из-за CPU starvation.