Files
mtusi2026lab3/REPORT.md
drunkdiente 3aba500a0e Реализовать стенд лабораторной 3: две API-реплики и балансировка
FastAPI + PostgreSQL как единый источник истины: пользователи, Basic/Bearer-сессии, чаты, сообщения. Сессии и идемпотентные ключи хранятся в БД, поэтому реплики взаимозаменяемы. Общая идемпотентность POST сообщения по Idempotency-Key, включая конкурентный повтор через разные реплики. compose.yaml: postgres, one-shot migrate, api1, api2 и nginx как единственная публичная точка входа. Добавлены scripts/stop-one.sh и scripts/restart.sh, student-tests, evidence и заполненный REPORT.md.
2026-11-07 16:04:29 +03:00

19 KiB
Raw Permalink Blame History

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

  • Автор, группа: TODO (заполнить перед PR)
  • Целевая оценка: 3 — работающий минимум. Уровень 4 и трек 5 не заявлены.
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: contracts/openapi.json, contracts/README.md, README.md, публичные тесты tests/; FastAPI 0.115.0, uvicorn 0.30.6, psycopg 3.2.3, psycopg-pool 3.3.3, PostgreSQL 16.4, Nginx 1.26.2. Реализация и текст отчёта подготовлены с помощью ИИ-ассистента Koda; все приведённые проверки выполнены и воспроизведены локально.

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

Проверено на: Windows 11 Pro 22621 x64, AMD Ryzen 7 7700 (8 ядер / 16 потоков), 32 GB RAM, Docker Engine 29.4.3, Docker Compose v5.1.3 (Linux containers), Python 3.10.11 для публичных тестов. Дата прогонов: 2026-11-07.

Версии зафиксированы: python:3.12.6-slim-bookworm, postgres:16.4-alpine, nginx:1.26.2-alpine; Python-зависимости — в requirements.txt.

# 1. Локальная конфигурация (значения в примере синтетические, .env не коммитится)
cp .env.example .env

# 2. Проверка и сборка/запуск всего стенда
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build

# 3. Ожидание готовности (миграции выполняются автоматически отдельным сервисом)
curl -fsS http://localhost:8080/health/ready

# 4. Проверки
make check
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

# 5. Восстановление остановленной в failover реплики (api1 или api2)
docker compose --env-file .env start api1
docker compose --env-file .env restart lb

# 6. Штатная остановка без удаления данных
docker compose --env-file .env down

# 7. Намеренное удаление учебных данных и volumes (необратимо)
docker compose --env-file .env down -v

На Windows-хосте make не установлен, поэтому вместо целей Makefile выполнены те же команды напрямую: python scripts/check_contract.py, python tests/smoke.py --base-url http://localhost:8080, python tests/resilience.py --mode persistence|failover --action-script .... Скрипты restart.sh/stop-one.sh — POSIX shell, поэтому resilience-тесты запускались в Linux-контейнере docker:27-cli с смонтированным репозиторием и Docker-сокетом:

docker run --rm --network mtusi-lab3_appnet \
  -v "<repo>:/repo" -v /var/run/docker.sock:/var/run/docker.sock \
  -w /repo -e PYTHONUTF8=1 docker:27-cli \
  sh -lc "apk add --no-cache python3 >/dev/null && \
  python3 tests/resilience.py --mode failover \
  --action-script scripts/stop-one.sh --base-url http://lb:8080"

На Linux/macOS те же проверки запускаются обычными командами Makefile из блока выше.

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

клиент
  |
  v
lb (nginx :8080)  — единственный опубликованный порт
  |  round-robin, passive health, retry на вторую реплику
  +--> api1 (uvicorn :8080, INSTANCE_ID=api-1) --+
  +--> api2 (uvicorn :8080, INSTANCE_ID=api-2) --+
                                                v
                                     postgres:16.4 (volume pgdata)
                                     users, chats, chat_members, messages,
                                     sessions, idempotency_keys
  • Источник истины — PostgreSQL. В API нет локальных сессий, сообщений или идемпотентных ключей. Единственное локальное состояние процесса — стабильный X-Instance-Id (api-1/api-2) из переменной окружения.
  • Реплики взаимозаменяемы. api1 и api2 собираются из одного Dockerfile и образа, не публикуют порты наружу, имеют одинаковый DATABASE_URL. Клиент ходит только через lb.
  • Балансировщик. Nginx upstream api1:8080, api2:8080, max_fails=1 fail_timeout=5s, proxy_connect_timeout 1s, proxy_read_timeout 10s. proxy_next_upstream ... non_idempotent повторяет POST на второй реплике; это безопасно, потому что создание сообщения идемпотентно по Idempotency-Key.
  • Миграции отдельно. Сервис migrate запускается один раз, ждёт готовности PostgreSQL, берёт advisory lock, применяет идемпотентный migrations/001_init.sql и завершается с кодом 0. Реплики стартуют только после service_completed_successfully, поэтому гонки DDL между ними нет.
  • Graceful shutdown. Uvicorn — PID 1, получает SIGTERM, перестаёт принимать соединения и до 5 с завершает текущие запросы (--timeout-graceful-shutdown 5), stop_grace_period: 10s. Nginx в это время повторяет запрос на живую реплику.
  • Сессии. Basic используется только в POST /api/v1/auth/sessions. Токен — secrets.token_urlsafe(48) (384 бита), в БД хранится только SHA-256 токена и expires_at; TTL из SESSION_TTL_SECONDS (по умолчанию 3600). Перезапуск не продлевает TTL.
  • Пароли. hashlib.scrypt (N=2^14, r=8, p=1, 32-байтовый digest, случайная соль), не SHA-256 и не plaintext.
  • Транзакционные границы. Регистрация — один INSERT с уникальным username. Создание чата — чат и все chat_members в одной транзакции после проверки существования участников. Отправка сообщения — проверка членства, вставка/чтение idempotency_keys, вставка messages и запись сохранённого ответа в одной транзакции.
  • Идемпотентность. Первичный ключ (user_id, method, path, key); INSERT ... ON CONFLICT DO NOTHING определяет владельца, конкурентный запрос ждёт завершения транзакции владельца и читает сохранённый ответ. Хранится канонический хеш тела: другой JSON при том же ключе — 409, тот же JSON — исходный 201 и то же сообщение. Срок хранения — IDEMPOTENCY_TTL_SECONDS (24 ч).
  • История. Keyset-пагинация по (created_at, id) по возрастанию, limit 1–100 (по умолчанию 50), непрозрачный base64-cursor со scope. Cursor от другого чата/коллекции — 400; последний элемент страницы не повторяется; next_cursor=null, если следующей записи нет.
  • Ошибки. Единый конверт {"error":{"code","message","request_id"}}, X-Request-Id совпадает с телом, X-Instance-Id добавляется middleware ко всем ответам API, включая ошибки и health.
  • Перенос из lab2. В этом репозитории нет кода lab2, поэтому обязательные возможности lab2 (PostgreSQL, регистрация с паролем, Basic → Bearer-сессия, миграции, сохранность) реализованы здесь же. In-memory fallback отсутствует.

Соответствие .env.example реальной конфигурации:

Переменная Где используется Смысл
APP_HOST, APP_PORT, APP_ENV compose информационные параметры стенда
SESSION_TTL_SECONDS API TTL сессии, по умолчанию 3600
IDEMPOTENCY_TTL_SECONDS API срок хранения результата, по умолчанию 86400
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD compose → DATABASE_URL общая БД; пароль в примере синтетический
DATABASE_URL / DATABASE_URL_FILE API, migrate альтернативные способы передать строку подключения
API_REPLICAS документация фактическое число реплик задано сервисами api1/api2

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Офлайн-структура и контракт python scripts/check_contract.py (эквивалент make check) PASS: offline skeleton structure... evidence/check.txt
Compose-стенд описан и валиден docker compose --env-file .env config --quiet код 0, ошибок нет вывод в отчёте, compose.yaml
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 (эквивалент make test) PASS: lab3 public API scenario evidence/smoke-final.txt, evidence/smoke.txt
≥2 API-реплики, одна точка входа, общая БД docker compose ps; 10 запросов /health/live api1/api2 healthy; опубликован только lb 8080; postgres healthy evidence/instances.txt, evidence/final-ps.txt
Одна сессия обслуживается разными репликами без повторного входа python student-tests/session_across_replicas.py 12 запросов с одним Bearer: api-1, api-2, api-1, api-2, ... evidence/session-across-replicas.txt
Остановка одной реплики: чтение/запись продолжаются failover-тест, цель api-1 85 успешных записей, 0 ошибок, первое восстановление 0.558 с (в повторных прогонах 0.65–1.43 с); api1 — Exited (0), api2 работает evidence/failover-final.txt, evidence/failover-final-ps.txt
Остановка второй реплики failover-тест, цель api-2 90 успешных записей, 0 ошибок, восстановление 0.546 с; api2 — Exited (0), api1 работает evidence/failover-final-2.txt, evidence/failover-final-2-ps.txt
Подтверждённые сообщения доступны после отказа, дублей нет тот же failover-тест тест читает всю историю, проверяет исходное сообщение, все подтверждённые записи и уникальность текстов evidence/failover-final.txt
Последовательный повтор Idempotency-Key публичный smoke повтор возвращает то же сообщение; другой body — 409; без ключа — 400 evidence/smoke-final.txt
Конкурентный повтор через разные реплики python student-tests/concurrent_idempotency.py 40 одновременных POST с одним ключом: реплики api-1 и api-2, ровно 1 сообщение, другой body — 409 evidence/concurrent-idempotency.txt
Сохранность данных и сессии после перезапуска persistence-тест + scripts/restart.sh PASS; прежний токен и данные доступны без повторного входа; в БД после всех прогонов 40 пользователей, 13 чатов, 4171 сообщение, 37 сессий evidence/persistence-final.txt, evidence/db-counts.txt
Hook действительно перезапустил хранилища docker inspect до/после scripts/restart.sh у postgres, api1, api2, lb изменился State.StartedAt evidence/restart-scope.txt
Health/readiness curl /health/ready {"status":"ok"}; readiness проверяет SELECT 1 к PostgreSQL evidence/instances.txt
Миграции не гоняются репликами docker compose ps -a migrate завершился Exited (0) до старта API evidence/failover-final-ps.txt
Версии образов/зависимостей зафиксированы Dockerfile, compose.yaml, requirements.txt явные теги/пины, без latest файлы репозитория
Нагрузочный профиль (дополнительно) python tests/load.py --duration 15 --concurrency 4 3722 успешных запроса, 0 ошибок, 247.6 RPS, p50/p95/p99 = 16/32/46 мс evidence/load.txt, evidence/load.json

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

Условия: один Docker-host, сервисные лимиты api 1 CPU / 256 MB, postgres 1 CPU / 512 MB, lb 0.5 CPU / 128 MB. Все запросы идут через http://localhost:8080 (nginx). Данные синтетические.

Воздействие Что ожидали Что наблюдали Время восстановления / потеря данных
stop api1 во время 15-секундной серии POST Записи продолжаются через api2, подтверждённые сообщения не теряются 85 успешных записей, 0 неудачных попыток; api1 остановлен (Exited (0)), api2 healthy первое восстановление 0.558 с; потерь и дублей нет
stop api2 во время такой же серии То же через api1 90 успешных записей, 0 неудачных; api2 остановлен, api1 healthy 0.546 с; потерь и дублей нет
40 одновременных POST с одним Idempotency-Key Ровно одно сообщение, одинаковые ответы Оба экземпляра обслужили запросы, все ответы совпали, в истории 1 копия; другой body — 409 потерь нет
scripts/restart.sh: рестарт PostgreSQL, api1, api2, lb Данные, сессии и схема сохраняются Persistence-тест PASS; у всех четырёх контейнеров новый StartedAt сессия и сообщения доступны без повторного входа
Пересборка образа и up -d --build Сессии/сообщения не зависят от жизни процесса Smoke после пересборки PASS; в PostgreSQL сохранились 40 пользователей, 13 чатов, 4171 сообщение и 37 сессий потерь нет

Нагрузочный прогон: 15 с, concurrency 4, closed-loop генератор tests/load.py без автоматических retry. Получено 3722 успешных POST, 0 ошибок, 247.6 успешных RPS, p50 16 мс, p95 32 мс, p99 46 мс. Это throughput HTTP-подтверждений через LB, а не точный счётчик COMMIT; генератор ограничен клиентом, страдает coordinated omission, а latency посчитана только по успешным запросам. CPU/RAM контейнеров в этом прогоне не сэмплировались, поэтому цифры не заявляются как saturation point.

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

  • Стенд работает на одном Docker-host. Потеря узла, а также отказ единственных PostgreSQL и nginx не выдерживаются: они остаются SPOF. Проверен только отказ одного API-процесса.
  • Nginx разрешает имена api1/api2 при старте. После восстановления остановленной реплики надёжный способ вернуть её в балансировку — docker compose start apiN и docker compose restart lb; в проверенных прогонах Docker переиспользовал IP, но на это не следует опираться. Следующий шаг — динамический resolver/resolve в upstream.
  • После восстановления реплика возвращается в балансировку не мгновенно: если первый запрос к ней попал в момент старта, nginx держит её вне пула до fail_timeout=5s. Это наблюдалось один раз сразу после restart lb; в рабочий период оба экземпляра получают запросы. Поэтому student-tests/session_across_replicas.py сначала ждёт появления обоих экземпляров, а затем проверяет одну сессию.
  • Сессии и идемпотентные ключи хранятся в PostgreSQL; Redis/Valkey не используется. Это соответствует контракту lab3, но увеличивает нагрузку на БД.
  • Просроченные идемпотентные ключи удаляются лениво — при повторном использовании ключа; фоновой очистки нет.
  • Не реализованы TLS, rate limiting, вложения, фоновая обработка, телеметрия — это следующие лабораторные, для оценки 3 они не требуются.
  • Уровень 4 (поочерёдная остановка всех реплик с метриками RPS/ошибок, rolling update под нагрузкой, CPU/RAM-лимиты как проверяемый критерий) и трек 5 не заявляются. Лимиты ресурсов в compose заданы, но измерение saturation и сравнение 1/2/4 реплик не проводилось.
  • На Windows-хосте отсутствует make, поэтому публичные цели запускались эквивалентными командами; на Linux/macOS команды Makefile применимы без изменений.