Files
mtusi2026lab3/REPORT.md
T

20 KiB
Raw Blame History

Лабораторная 3 — отчёт

  • Автор: Саламатин, БПИ-2304.
  • Целевая оценка: 4, весь минимум уровня 3 и все пункты уровня 4. Треки на 5 не выполнялись.
  • Проверка: 1 ноября 2026 года, Europe/Moscow. В JSON используется UTC.
  • Ветка: solution/bpi-2304-salamatin. Основа задания — commit 0ab3a34 репозитория mtusi2026/mtusi2026lab3.
  • Сборка и обязательные проверки повторены из отдельного локального clone; проверенный commit 8846b05 записан в evidence/clean-source.json.
  • Публикация: fork gwalut/mtusi2026lab3, PR №85 в main преподавателя.
  • Перенесена собственная lab2 из gwalut/mtusi2026lab2, ветка solution/bpi-2304-salamatin. README задания, COURSE, contracts и публичные tests lab3 сохранены.

Запуск

Нужны Docker Desktop с Linux containers и Docker Compose. Для полного автоматического прогона на хосте нужен Python 3.9+; Python приложения и зависимости устанавливаются в контейнере. На Windows текстовые проверки запускаются с -X utf8.

Из корня clone, PowerShell:

python -X utf8 scripts/init_local.py
python -X utf8 scripts/verify.py

verify.py собирает образы, поднимает стенд, выполняет публичные и собственные тесты, полный restart, failover, expiry, проверку SQL-плана и нагрузочные эксперименты. Итог — evidence/verification.json. Данные не удаляются; стенд остаётся работающим. Тесты создают только синтетических пользователей и сообщения.

На текущем компьютере переносимый Python находится на уровень выше репозитория:

..\.tools\python\python.exe -X utf8 scripts/verify.py

Для обычного запуска на Windows без установленного Python: ./start.ps1. Скрипт создаёт конфигурацию через Python-контейнер, собирает и запускает Compose. Эквивалентные команды вручную:

docker run --rm --mount "type=bind,source=$($PWD.Path),target=/work" --workdir /work python:3.13.15-slim-bookworm python scripts/init_local.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120
curl.exe --noproxy "*" http://127.0.0.1:8080/health/ready

init_local.py создаёт .env и локальные случайные пароли/DSN/ключ cursor в secrets/. Существующие значения сохраняются и не печатаются. Эти файлы исключены из Git. Не удалять секреты при сохранённых volumes: пароль существующей PostgreSQL не меняется от замены файла.

По умолчанию опубликован только 127.0.0.1:8080 балансировщика. Для другого свободного порта изменить API_PORT в .env до запуска. API_REPLICAS=2 задаёт число API, SESSION_TTL_SECONDS=3600 — срок новых сессий, APP_VERSION — метку конфигурации; остальные runtime-настройки и пути секретов заданы в Compose. Приложение всегда слушает 0.0.0.0:8080 внутри контейнера.

Отдельные проверки:

docker compose run --rm --no-deps checks make check test
docker compose run --rm --no-deps checks make test-student
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh'
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh'
docker compose start api
docker compose run --rm --no-deps checks make explain
python -X utf8 scripts/experiments.py --base-url http://127.0.0.1:8080

После публичного failover реплика намеренно остаётся остановленной: восстановление выполняется отдельной командой docker compose start api. Полный verify.py делает это сам. После восстановления нужно дождаться готовности обеих реплик. На Linux для прямого запуска hooks: chmod +x scripts/restart.sh scripts/stop-one.sh.

Остановка с сохранением данных: docker compose stop, либо docker compose down для удаления контейнеров и сети с сохранением volumes. Только для намеренного удаления всех учебных данных: docker compose down --volumes. Эта команда не применяется в проверках отказа и restart.

Реализация

Клиент → HAProxy → API × 2 → общие PostgreSQL и Redis. Используется один масштабируемый сервис api без container_name. API, БД и Redis не публикуют порты. Балансировка round-robin, без sticky sessions. Лимиты установлены у всех runtime-контейнеров, сервиса миграций и клиента проверок.

Из lab2 сохранены FastAPI, PostgreSQL-миграции, параметризованные запросы, ограниченный pool, scrypt, Basic при входе, Bearer-сессии в Redis с TTL/AOF, проверка членства, подписанные cursor и индекс истории. Добавлены X-Instance-Id, обязательный ключ отправки, таблица message_requests, HAProxy и сценарии отказа/замены.

Результат отправки и само сообщение сохраняются одной SQL-транзакцией. Блокировка строки чата синхронизирует разные процессы. Повтор валидного тела и ключа в течение 24 часов возвращает тот же Message с 201; другое тело — 409. Область ключа включает пользователя и чат; повтор заново проходит аутентификацию и проверку доступа. Ошибка транзакции не сохраняется как окончательный результат. История не кэшируется.

Readiness API требует обе зависимости. HAProxy проверяет его с inter 1s, fall 2, rise 1, fastinter 500ms, timeout check/connect 1s; консервативный бюджет обнаружения зависшего backend — до 4 s при штатном планировании. Docker DNS обновляет адреса, HAProxy поддерживает до восьми реплик. API обрабатывает SIGTERM через Uvicorn: закрытие listener, до 5 s на текущие запросы; Compose даёт 8 s. Общий HTTP-бюджет API — 5 s, таймаут HAProxy до backend — 6 s. Прозрачных повторов POST в LB нет.

Миграции выполняет отдельный сервис migrate; advisory lock и checksum предотвращают гонку/изменение применённого SQL. Для последовательной замены миграции проверяются один раз перед обновлением. 002 добавляет новую таблицу, 001 сохранена. Подробности: docs/ARCHITECTURE.md, сценарий защиты — docs/DEFENSE.md.

Проверки критериев

Критерий Команда / сценарий Результат Доказательство в evidence/
Обязательный API и переход lab2 → lab3 make test через LB и smoke с хоста PASS smoke.txt, published-smoke.txt
Две настоящие реплики и общая сессия Повтор /users/me с одним токеном; Docker inspect Не менее двух instance ID и разных контейнеров student-tests.txt, verification.json
Идемпотентность между репликами 100 запросов, 10 клиентов, один ключ Одно сообщение и одна запись результата idempotency.json
Конфликт, область ключа, expiry и повтор после logout Собственные интеграционные тесты 409 / независимые ключи / новый результат после expiry / 401 student-tests.txt
Атомарность сообщения и результата SQL-trigger вызывает ошибку при INSERT результата 503; обе записи откатились; повтор после устранения ошибки успешен student-tests.txt
Полный перезапуск и сохранность make test-persistence с реализованным hook Старый токен и данные сохранены; volumes те же, StartedAt изменился у всех пяти контейнеров persistence.txt, restart.json
Публичный failover make test-failover Две реплики до отказа; восстановление 2.064 s, 2 ошибки, 117 успешных записей failover.txt, last-stop.json
Readiness, timeouts и SIGTERM Healthchecks HAProxy, stop каждой API Оба процесса завершились с exit code 0, записи продолжились менее чем за 10 s failure-api-1.json, failure-api-2.json
Отказ каждой реплики с восстановлением предыдущей scripts/experiments.py Измерены RPS, ошибки, latency и время первой записи после остановки experiments.json
Ресурсные лимиты и одна точка входа Inspect всех runtime-контейнеров CPU/RAM ограничены; опубликован только LB; API non-root verification.json
Поочерёдная замена под нагрузкой Drain → stop/remove → recreate, отдельно для каждой API Два новых контейнера; 0 HTTP-ошибок; все 4475 подтверждений сохранены rolling-update.json
Прежние проверки уровня 4 lab2 12 интеграционных тестов, TTL=2, EXPLAIN PASS; 401 через 2.3 s; индекс на 10 000 сообщениях student-tests.txt, expiry.json, explain.txt
Воспроизводимость из чистого clone Независимые secrets, Compose-проект и первоначально пустые volumes, повтор обязательных проверок PASS; исходники не изменены; отдельный порт 18083 clean-source.json, clean-verification.json, clean-build.txt, clean-student-tests.txt
Сохранность контракта задания Сравнение с исходным commit, SHA-256 после нормализации EOL 15 файлов задания/контракта/публичных проверок без изменений source-integrity.json

Измерения

Стенд: Windows, Docker Desktop 4.50.0/Engine 28.5.1, Linux x86_64. Docker VM: 16 логических CPU, около 7.47 GiB RAM. Лимиты: каждая API — 1 CPU/256 MiB, PostgreSQL — 1 CPU/512 MiB, Redis — 0.5 CPU/192 MiB, HAProxy — 0.5 CPU/128 MiB, checks — 1 CPU/256 MiB. Нагрузочный клиент работает на хосте; CPU/RAM компонентов во время нагрузки сохранены в JSON.

Версии образов: Python 3.13.15-slim-bookworm, PostgreSQL 17.6-bookworm, Redis 7.4.5-bookworm, HAProxy 3.0.12-alpine, Docker CLI проверок 28.5.1-cli. Зависимости закреплены в requirements.txt; image ID фактического стенда записаны в JSON.

Перед каждой нагрузкой создаётся отдельный чат и подтверждённое сообщение; наблюдаются две реплики с одной сессией. Нагрузка closed-loop, четыре клиента, преимущественно отправка сообщений и периодическое чтение текущего пользователя. Воздействие начинается через 4 секунды. При неопределённом результате POST сохраняются ключ и тело. После опыта читаются все страницы истории: сверяются ID и тела всех подтверждений, проверяются дубли. Общий snapshot истории не требуется.

Опыт Длительность Успешные RPS Ошибок попыток Первая запись после воздействия p50 / p95 / p99, ms Подтверждений сверено
Остановка первой API 24.041 s 105.235 51 (1.976%) 1.715 s 32.652 / 75.027 / 96.705 2350
Остановка второй API 24.034 s 108.762 57 (2.134%) 1.697 s 32.088 / 65.561 / 97.489 2429
Поочерёдная замена обеих API 45.015 s 107.276 0 Запросы продолжались; замена заняла около 23.5 s 28.249 / 82.882 / 127.075 4475

Краткие ошибки при резкой остановке допустимы: HAProxy ещё обнаруживает отказ. Они включены в счётчики, потерянных подтверждений и дублей не обнаружено. При управляемой замене backend сначала переводится в drain; в выполненном опыте ошибок не было. Поле first_write_after_action_seconds отсчитывается от начала действия до первой записи после завершения действия; для rolling оно включает длительность всей замены и не означает 23.5 секунды простоя.

В отдельном clone повторены сборка, публичный API, 12 тестов, полный restart, публичный failover, expiry и SQL-план. Нагрузочные опыты там не повторялись. Вспомогательный запуск TTL-контейнера один раз завис в Compose Desktop: скрипт теперь после таймаута проверяет точное имя, метки проекта/сервиса, TTL и состояние запущенного контейнера, затем всё равно выполняет HTTP-проверку истечения сессии. Итоговый повтор завершился PASS. Проверочный стенд остановлен без удаления volumes.

Это одиночные функциональные опыты, не исследование максимальной производительности. Первые 4 s нагрузки служат коротким прогревом и входят в общий RPS. Percentile рассчитаны только для успешных HTTP-операций; closed-loop ограничен клиентом и не показывает реальную очередь при фиксированной входящей интенсивности. Профиль и лимиты одинаковы для двух отказов. Сырые агрегаты, двухсекундные интервалы нагрузки, ошибки, состояния контейнеров и выборки CPU/RAM находятся в соответствующих JSON.

Ограничения

Один host, одна БД, один Redis и один LB остаются точками отказа. Проверен отказ одной API-реплики, а не потеря host или любого хранилища. Сессии требуют сохранённого volume Redis. Backup/restore и треки на 5 не выполнялись. Просроченные ключи очищаются при повторном использовании; периодическая фоновая уборка не добавлена.

Проверена эквивалентная поочерёдная замена контейнеров того же приложения с APP_VERSION=lab3-v2, без изменения бизнес-кода между версиями. Совместимость произвольных будущих миграций не обещается; изменения схемы должны быть обратно совместимыми либо требовать отдельного окна обслуживания. Смешанный запуск старого lab2 и нового lab3 API не поддерживается из-за изменения обязательного контракта ключа.

Учебный стенд использует локальный HTTP и синтетические данные. У API нет UI; отдельные опыты масштабирования 1/2/4 и отказ нескольких узлов не заявляются.

Источники