14 KiB
Отчёт — лабораторная 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 различны.