Files
mtusi2026lab3-fork/REPORT.md
T

9.8 KiB
Raw Blame History

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

  • Автор, группа: Гадяцкий Л. Е., БПИ2302
  • Целевая оценка: 3
  • Commit/PR: solution/BPI2302-Gadiatskiy
  • Использованные источники и библиотеки:
    • контракт и семантика: contracts/openapi.json, contracts/README.md, README.md, COURSE.md
    • перенос из lab2: FastAPI, PostgreSQL/сессии, SQLAlchemy, миграции, формат ошибок
    • runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0
    • PostgreSQL: postgres:16-alpine; LB: nginx:1.27-alpine
  • Помощь ИИ использована при переносе lab2, частично при настройке Compose+Nginx и при написании отчёта. Результаты подтверждаются сохранёнными запусками.

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

Prerequisites: Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (make check / make test / tests/resilience.py). Runtime приложения — внутри образа.

Версии:

  • API: базовый образ python:3.12.8-slim-bookworm → локальный mtusi-messenger:lab3
  • PostgreSQL: postgres:16-alpine
  • Nginx: nginx:1.27-alpine
  • зависимости: requirements.txt

Конфигурация: секретов в Git нет. Локальный .env создаётся из примера и не коммитится:

cp .env.example .env

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

  • APP_HOST / APP_PORT — bind uvicorn внутри контейнеров API
  • HOST_PORT — порт LB на host (по умолчанию 8080; если занят — например 8081)
  • APP_ENV — среда запуска (lab)
  • SESSION_TTL_SECONDS — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)
  • SESSION_STORE=postgres — сессии в PostgreSQL (общие для всех реплик)
  • DATABASE_URL — строка подключения API/migrate к PostgreSQL в compose-сети
    (приложение также поддерживает DATABASE_URL_FILE)
  • IDEMPOTENCY_TTL_SECONDS — срок хранения идемпотентных записей (по умолчанию 86400)
  • API_REPLICAS=2 — в compose.yaml зафиксированы сервисы api1 и api2

Учебные credentials compose (messenger / messenger) только для локального синтетического стенда.

Сборка и запуск:

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

Миграции migrations/*.sql применяет one-shot сервис migrate до старта api1/api2 (учёт в schema_migrations). Реплики API миграции при старте не выполняют.

Готовность через LB (подставьте свой HOST_PORT):

curl -i http://127.0.0.1:8080/health/ready

Ожидается HTTP 200, тело {"status":"ok"}, заголовки X-Request-Id и X-Instance-Id (api1 или api2).

Публичный smoke (при уже запущенном стенде):

python tests/smoke.py --base-url http://127.0.0.1:8080
# или: make test BASE_URL=http://127.0.0.1:8080

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

# Unix:
chmod +x scripts/restart.sh
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080

# Windows:
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080

Hook выполняет docker compose --env-file .env restart для postgres, api1, api2, lb без удаления volumes (down -v не используется).

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

# Unix:
chmod +x scripts/stop-one.sh
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080

# Windows:
python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080

TARGET_INSTANCE_ID = X-Instance-Id (api1/api2); hook делает docker compose stop только этой реплики и оставляет её остановленной. После теста: docker compose --env-file .env start api1 (или api2). Для защиты повторить на второй реплике после восстановления первой.

Локальная проверка автора выполнялась на HOST_PORT=8082 (host-порты 8080/8081 были заняты другими контейнерами).

Остановка:

docker compose --env-file .env down

Намеренное удаление учебных данных (volumes):

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

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

HTTP-клиент
  → lb (Nginx)
      → api1 / api2 (uvicorn + FastAPI)
          → PostgreSQL
             users, chats, chat_members, messages, sessions, idempotency_records
  • Источник истины — PostgreSQL. Локального состояния, от которого зависит корректность, в API нет.
  • Сессии в PostgreSQL: один Bearer работает через любую реплику без sticky sessions.
  • X-Instance-Id стабилен на жизнь процесса (INSTANCE_ID сервиса).
  • Idempotency-Key обязателен на POST .../messages; область: пользователь + метод + путь + ключ; запись результата атомарна с сообщением; другой body при том же ключе → 409; TTL 24ч.
  • ORM-модели: src/messenger/tables.py. Доступ к данным: src/messenger/store.py.
  • Миграции: SQL в migrations/ + one-shot migrate; Alembic не используется.
  • Порты API наружу не публикуются; публичная точка входа — LB (infra/nginx.conf: least_conn, max_fails=1, proxy_next_upstream).
  • Compose: lb + api1 + api2 + postgres + migrate, volume pgdata; .env в Git не коммитится.

Перенесено из lab2: auth Basic→Bearer, Argon2id, чаты/сообщения, keyset-пагинация, формат ошибок.
Добавлено в lab3: Nginx LB, две реплики API, X-Instance-Id, общая идемпотентность, отдельный migrate, scripts/stop-one.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke (lab2 + Idempotency-Key / X-Instance-Id) python tests/smoke.py --base-url http://127.0.0.1:8082 PASS: lab3 public API scenario... evidence/smoke.txt
Стенд: ≥2 API, один LB, общая БД и сессии docker compose --env-file .env ps lb, api1, api2, postgres; migrate Exited 0 evidence/compose-ps.txt
Разные реплики через LB с одной сессией серия запросов через LB api1 и api2 evidence/instances.txt
Persistence: рестарт без удаления volumes, прежний токен python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8082 PASS: persistence preserved... evidence/restart.txt
Failover: остановка одной API-реплики python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8082 2 instance до отказа; first_recovery ≈2.75 с; без дублей evidence/failover.txt
Идемпотентность POST сообщений smoke replay + failover retries тот же ключ → то же Message; другой body → 409 evidence/smoke.txt, evidence/failover.txt

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

Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверены сохранность и отказ API-реплики:

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose --env-file .env restart (postgres+api1+api2+lb), volumes сохранены /health/ready ok; прежний Bearer читает те же данные; сессия действует persistence PASS в бюджете теста (hook ≤90 с, ready ≤90 с); потери данных нет
docker compose stop одной API-реплики LB обслуживает живую; записи ≤10 с; без дублей по retry failover PASS; first_recovery_seconds≈2.75 подтверждённые сообщения на месте

Аппаратный профиль: локальный Docker Desktop на Windows; 2 API + Nginx + PostgreSQL без CPU/RAM limits.

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

  • Redis/Valkey, CPU/RAM limits, rolling update под нагрузкой и трек 5 не выполнялись.
  • Единственный PostgreSQL и единственный Nginx — SPOF; отказ host/узла не выдерживается.
  • Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.