Files
mtusi2026lab3-fork/REPORT.md
T

14 KiB
Raw Blame History

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

  • Автор: Шурман А.Р., БПИ2302 (как в лабораторной 2).
  • Целевая оценка: 4, без треков на 5 и без UI.
  • Ветка: solution/bpi2302-shurman. PR #142 из aliska/mtusi2026lab3-fork в исходный репозиторий. Реализация и проверки: 7da0348.
  • Основа: собственная лабораторная 2 (mtusi2026lab2-fork), исходный контракт и публичные тесты лабораторной 3. Помощь OpenAI Codex: реализация, проверки, отчёт.
  • Библиотеки: FastAPI, Uvicorn, psycopg/pool, Argon2, redis-py; версии в app/requirements.txt.

Запуск

Нужны Docker Desktop/Engine с Compose и Python 3.9+ для проверок. Из корня этого репозитория:

python3 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api
python3 student-tests/verify.py

После up дождаться ответа 200 от http://localhost:8080/health/ready. После публичного failover запустить остановленную реплику командой start api; собственный сценарий дожидается готовности обеих реплик перед экспериментами. Публичный failover сам передаёт TARGET_INSTANCE_ID action-скрипту. Ручная остановка: TARGET_INSTANCE_ID=<hostname API из docker inspect> scripts/stop-one.sh.

OpenAPI: python3 -m venv .venv, затем .venv/bin/python -m pip install -r requirements-dev.txt и make validate PYTHON=.venv/bin/python. Безопасная остановка: docker compose down (volumes остаются). Преднамеренное удаление учебных данных: docker compose down -v — только если нужен полный сброс. При проверках эта команда не используется.

API и Swagger доступны через LB: http://localhost:8080/docs. Порты API/БД/Valkey на хост не публикуются. Порт LB привязан к loopback. Версии образов: Python 3.12.7, PostgreSQL 16.6, Valkey 8.0.2, HAProxy 3.0.5. Bootstrap создаёт новые локальные secrets, не копирует пароли лабораторной 2, не перезаписывает существующие файлы. Secrets и .env исключены из Git/build. В .env используются HOST_PORT и SESSION_TTL_SECONDS. Адреса БД/кэша передаются через DATABASE_URL_FILE/CACHE_URL_FILE. Сессии всегда PostgreSQL, срок идемпотентности фиксирован 24 часа. Число реплик задаётся deploy.replicas: 2; для изменения — --scale api=N. Остальные переменные исходного .env.example — описание интерфейсов skeleton, а не переключатели реализации.

Архитектура

Клиент → HAProxy → две реплики одного Compose-service api → PostgreSQL. Valkey — общий необязательный кэш неизменяемых профилей, как в лабораторной 2. PostgreSQL хранит пользователей, чаты, участников, сообщения, сессии и ключи идемпотентности. Локального состояния, влияющего на корректность, в API нет. Пароли — Argon2id; токены 256 бит, в БД только hash и абсолютный expiry. Сессия проверяется в БД при каждом запросе; недоступность Valkey даёт fallback. История не кэшируется: подтверждённый COMMIT виден следующему чтению любой реплики.

Каждый ответ API (включая ошибки/health) имеет X-Request-Id и X-Instance-Id. Instance ID — hostname реального контейнера. Один Uvicorn-процесс на контейнер. HAProxy round-robin без sticky sessions; заголовки сопоставляются с docker inspect.

POST сообщения требует ключ ASCII длиной 1–128. Область ключа — пользователь, чат и единственный endpoint POST сообщения. PostgreSQL advisory transaction lock сериализует одинаковый ключ между процессами. Сообщение и результат ключа сохраняются в одной транзакции; сбой откатывает оба изменения. Повтор возвращает тот же Message/201, другой текст — 409. Проверка сессии/доступа выполняется снова. 5xx не сохраняются. Коллизия 64-битного lock только сериализует посторонние ключи, но не смешивает данные: поиск/UNIQUE используют полную тройку значений. Контракт lab3 принимает только text; вложения относятся к lab4.

Готовность, таймауты и обновление

  • Liveness проверяет процесс; readiness — доступность PostgreSQL и таблицы миграций.
  • HAProxy: проверка раз в 1 s, timeout 1 s, fall 2, rise 1. Консервативный бюджет обнаружения недоступного backend — до 4 s при нормальном планировании. Это не гарантия при зависании хоста. DNS Docker обновляется с hold valid/obsolete 1s, адреса не зафиксированы в конфигурации.
  • HAProxy connect timeout 1 s, server timeout 10 s, client 15 s. Автоматических повторов нет (retries 0), чтобы не дублировать POST создания чата/регистрации.
  • Pool 1–8, ожидание до 3 s, SQL timeout 3 s, lock timeout 2 s. Кэш timeout 0.2 s.
  • Uvicorn получает SIGTERM напрямую, закрывает listener, завершает активные запросы (до 8 s), затем закрывает pool/cache. Docker даёт 10 s на остановку. При попадании в закрывающийся backend допустима краткая ошибка; клиент повторяет сообщение с прежним ключом. Исключение backend контролирует HAProxy, а не Compose.
  • Docker healthcheck: каждые 5 s, timeout 4 s; он нужен для запуска/наблюдения. Проверки маршрутизации независимо выполняет HAProxy каждую секунду.

Лимиты: каждая API/migrate 0.5 CPU/256 MiB, PostgreSQL 1 CPU/512 MiB, Valkey 0.25 CPU/128 MiB, LB 0.5 CPU/128 MiB. container_name нет. API non-root. Пароль PostgreSQL получает только БД; URL БД/кэша — API и мигратор. LB не получает secrets. Сетевые зависимости доступны только в сети проекта.

Мигратор — отдельный завершённый сервис, до запуска API, с advisory lock и checksum применённых SQL. Повторный запуск безопасен. Миграция 002 добавляет таблицу, не меняя старые структуры. Для обновления: собрать новый образ, docker compose run --rm migrate, затем python3 scripts/rolling.py. Скрипт поочерёдно останавливает/заменяет каждую старую API-реплику и ждёт здоровья новой, пока другая работает. Проверен эквивалент rolling update: замена обоих контейнеров текущим образом под нагрузкой. Совместимость произвольных будущих версий не заявляется: нужны обратно совместимые миграции; удаление колонок потребует отдельного плана. В этой работе destructive migration нет.

Проверки и результаты

Измерения 12.11.2026 на локальном Docker Desktop arm64, только синтетические данные. Публичные tests/, contracts/, README и COURSE не изменены.

Критерий Проверка Доказательство
Структура, OpenAPI, обязательный API make check/validate/test evidence/check.txt, validate.txt, smoke.txt
Данные и прежний токен после рестарта всех сервисов test-persistence evidence/persistence.txt, restart-containers.json
Две реальные реплики и отказ через LB публичный test-failover evidence/failover.txt
Один ключ одновременно на двух репликах 16 параллельных POST, 1 Message evidence/grade4.json
Последовательный отказ каждой реплики 4 потока чтения/записи, восстановление предыдущей evidence/grade4.json
Поочерёдная замена под нагрузкой новые container IDs, чтение/запись продолжаются evidence/grade4.json
Лимиты и отсутствие обходных портов compose + inspect evidence/containers.json

student-tests/verify.py создаёт отдельный чат, проверяет гонку одного ключа, затем поочерёдный отказ каждой реплики и замену обеих. Каждый эксперимент: 4 закрытых клиентских потока, прогрев 2 s, воздействие, ещё 5 s нагрузки; одна итерация — POST сообщения + GET пользователя, пауза 20 ms. RPS в grade4.json — успешные пары записи/чтения в секунду, не максимум системы. При неопределённом результате повторяется тот же ключ. После каждого сценария проверяется сохранность всех подтверждённых сообщений и отсутствие дубликатов. max_success_gap_seconds — максимальный промежуток без успешных пар; first_success_after_action_seconds отсчитывается от завершения action. Публичный failover отдельно измеряет восстановление от начала action (бюджет 10 s). Ошибки учитываются, процентили/throughput не объявляются production SLA.

Фактический прогон:

Воздействие Успешных пар/с Ошибок Максимальный разрыв между успехами
Остановка первой API 87.66 24 1.051 s
Остановка второй API 81.78 25 1.055 s
Замена обеих API 99.08 50 1.025 s

Ошибки кратковременны во время обнаружения остановки, нулевая потеря HTTP-запросов не заявляется. Все подтверждённые сообщения сохранены; повтор с прежним ключом не создал дубликатов. Продолжительность экспериментов: 7.974 / 7.459 / 28.603 s. Это один функциональный прогон, а не исследование масштабирования уровня 5. Публичный failover: 2 наблюдаемых реплики, 116 успешных записей, 2 неудачные попытки, восстановление за 1.682 s от начала action. Persistence прошёл с прежним токеном; StartedAt всех пяти работающих контейнеров изменился. Повторный запуск мигратора: Migrations OK (evidence/migrations.txt).

Ограничения

Один LB, PostgreSQL и хост остаются точками отказа; отказ узла/диска не проверен. HTTP разрешён только локально для учебных данных, для удалённого стенда нужен TLS. Нет UI, файлов, брокера, треков на 5, фоновой очистки истёкших ключей/сессий. Keyset pagination сортирует по (created_at,id); на неизменной истории повторов нет, но поздний COMMIT с более ранним временем может остаться за уже пройденным cursor. Между страницами snapshot не сохраняется. Часы и порядок commit различны.