Files
mtusi2026lab3/REPORT.md

8.8 KiB
Raw Permalink Blame History

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

  • Автор, группа: Яковлев Матвей Дмитриевич, БПИ2304
  • Целевая оценка; выбранный трек 5, если нужен: 3
  • Commit/PR: ветка: (solution/BPI2304-Yakovlev); MR: (mtusi2026/mtusi2026lab3#163)
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.135.3, Uvicorn 0.44.0, psycopg 3.3.3, PostgreSQL 16-alpine, nginx 1.27-alpine; версии закреплены в requirements.txt, compose.yaml, Dockerfile. При подготовке использовалась помощь Claude.

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

git clone <url-вашего-fork> && cd <каталог>
cp .env.example .env            # только синтетические локальные креды; .env в Git не попадает
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -i http://localhost:8080/health/ready        # единая точка входа — nginx
python tests/smoke.py --base-url http://localhost:8080

Единственный публичный порт — 8080 балансировщика; напрямую API-реплики портов не публикуют. Остановка с сохранением данных: docker compose --env-file .env stop api1 api2 db. Намеренное удаление учебных данных: docker compose --env-file .env down -v.

Явные сценарии проверок:

make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Windows локально: scripts/restart.cmd и scripts/stop-one.cmd

После останова одной реплики восстановление — отдельной командой: docker compose --env-file .env start api1 (или api2).

Полный вывод — evidence/lifecycle.txt.

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

Клиент → nginx (lb) → api1 / api2 (один образ, две interchangeables реплики) → общий PostgreSQL.

  • infra/nginx.conf: upstream с api1:8080 и api2:8080, max_fails=1 fail_timeout=5s, proxy_next_upstream error timeout http_502 http_503 http_504, таймауты 2/10/10 с. Sticky session не используется: любая реплика обслуживает любой запрос с тем же Bearer-токеном.
  • X-Instance-Id: каждой реплике через окружение задаётся alias api1/api2; заголовок добавляется middleware в каждый ответ. Один клиент видит оба значения через LB (см. доказательства).
  • Общее состояние: PostgreSQL хранит пользователей, чаты, участников, сообщения, сессии — в памяти процесса нет authoritative данных. Сессии не требуют повторного входа при смене реплики.
  • Миграции: SELECT pg_advisory_xact_lock(20261116) перед чтением schema_migrations, поэтому при одновременном старте двух реплик файл 001_init.sql применяется ровно один раз.
  • Общая идемпотентность: таблица idempotency_records с первичным ключом (user_id, method, path, key) в той же БД. POST /chats/{id}/messages требует Idempotency-Key ([A-Za-z0-9._:-]{1,128}); хэш канонического тела, код и тело ответа записываются в одной транзакции с сообщением. Повтор с тем же ключом возвращает сохранённый 201 и тот же Message; другое тело с тем же ключом — 409. При конкуренции двух реплик проигравший ловит UniqueViolation, откатывается и читает зафиксированный ответ победителя — дубля нет. Повтор снова проверяет сессию и доступ к чату.
  • scripts/stop-one.sh отображает TARGET_INSTANCE_ID (alias из X-Instance-Id) на соответствующий Compose-сервис и останавливает только его; БД, volume и LB не трогаются. scripts/restart.sh перезапускает db, api1, api2 без удаления volume.
  • /health/ready проверяет SELECT 1; nginx не использует пассивные проверки API как единственный механизм — при отказе реплики запрос повторяется на другой.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
≥2 реплики, одна точка входа docker compose ps; 8 запросов к LB api1/api2 в заголовке X-Instance-Id у одного клиента; только lb публикует 8080 evidence/lifecycle.txt, разделы 2–3
Публичный smoke c идемпотентностью python tests/smoke.py PASS: lab3 public API scenario...; повтор ключа = тот же Message, другой body = 409 evidence/lifecycle.txt, раздел 4
Общая идемпотентность в БД psql ... SELECT count(*) FROM idempotency_records число записей ledger равно числу сообщений; уникальный ключ (user, method, path, key) evidence/lifecycle.txt, раздел 5
Перезапуск всего стенда с тем же токеном make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session; schema_migrations без повторов (advisory lock) evidence/lifecycle.txt, разделы 6–7
Отказ одной реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh observed_instances_before: 2, 106 успешных записей, 2 transitional failure, first_recovery_seconds: 0.608, PASS evidence/lifecycle.txt, разделы 8–9
Офлайн-проверки python scripts/check_contract.py; 11 unit-тестов PASS, 11 OK evidence/lifecycle.txt, раздел 10

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

Не проводились (целевая оценка 3); уровни 4/5 с нагрузочными сериями и сравнением 1/2/4 реплик не заявлены.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Останов одной API-реплики hook'ом LB направляет запросы на оставшуюся реплику; данные и сессия сохраняются 2 реплики до отказа, 106 успешных записей во время отказа, 2 переходные ошибки, все подтверждённые сообщения на месте, дублей нет первая успешная запись через 0.608 с; потерь данных 0
Перезапуск db + api1 + api2 с volume данные, сессии и ledger остаются PASS; миграции не применялись повторно automatic ready wait; потерь данных 0

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

  • Уровень 4 не реализован: нет CPU/RAM-лимитов, sequnential отказа каждой реплики под нагрузкой, rolling update и автоматической проверки исключения недоступного backend по healthcheck (nginx использует пассивный max_fails/fail_timeout).
  • PostgreSQL остаётся единственной точкой отказа стенда; отказ узла БД не моделируется и не заявляется.
  • Nginx — единственный LB; при его отказе доступ прекращается (SPOF).
  • HTTP допустим только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS.