Files
mtusi2026lab3/REPORT.md
T

31 KiB
Raw Blame History

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

  • Автор: Ремез Олег Романович, БПИ2304.
  • Целевая оценка: «4». Трек на «5» не заявлен.
  • Ветка решения: solution/BPI2304-remez. PR ещё не открыт.
  • Использованы Go 1.27.1, pgx/v5 5.11.0, Goose 3.26.0, go-redis/v9 9.23.0, PostgreSQL 18, Redis 7.4, HAProxy 3.2.24 и Docker Compose. При проектировании, правках и анализе использовался OpenAI Codex; выводы проверялись командами и экспериментами ниже. Основные документы: Docker Compose services, Go HTTP Server, HAProxy configuration.

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

Нужны Docker Desktop с Compose v2, Python 3.9+ для публичных тестов и свободные loopback-порты 8080 и 5432. API и мигратор собираются из Go 1.27.1; образы PostgreSQL 18, Redis 7.4-alpine и HAProxy 3.2.24-alpine закреплены в compose.yaml. Следующие команды выполняются в корне репозитория. Пароль генерируется локально и не печатается:

cp .env.example .env
mkdir -p secrets
chmod 700 secrets
python3 - <<'PY'
from pathlib import Path
from secrets import token_urlsafe
from urllib.parse import quote

password = token_urlsafe(32)
Path('secrets/postgres_password').write_text(password + '\n')
Path('secrets/database_url').write_text(
    f"postgres://messenger:{quote(password, safe='')}@postgres:5432/messenger?sslmode=disable\n"
)
PY
chmod 644 secrets/postgres_password secrets/database_url
make check
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps --all
curl --fail http://127.0.0.1:8080/health/ready
make test

Новый PostgreSQL volume инициализируется один раз. Отдельный сервис migrate после готовности БД применяет pending SQL-миграции и завершается с кодом 0; две реплики API стартуют только после него. Вывод docker compose --env-file .env ps --all должен показывать migrate как Exited (0), API и PostgreSQL/Redis как healthy. Если локальная .env уже создана, не перезаписывайте её и secrets. Для диагностики миграций используйте docker compose --env-file .env logs migrate и инструкцию по миграциям.

Безопасная остановка: docker compose --env-file .env down — контейнеры удаляются, named volumes и данные остаются. Намеренное удаление учебных данных: docker compose --env-file .env down -v; после него данные PostgreSQL и Redis в volumes этого проекта исчезнут. Для проверки persistence без удаления volumes: make test-persistence ACTION_SCRIPT=scripts/restart.sh. Скрипт отказа make test-failover ACTION_SCRIPT=scripts/stop-one.sh намеренно оставляет одну реплику остановленной; восстановление: docker compose --env-file .env up -d --no-build --no-recreate --scale api=2 api.

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

Клиент обращается к одному HAProxy на 127.0.0.1:8080; тот распределяет запросы между двумя контейнерами одного Compose-сервиса api. Контейнеры API не публикуют порт наружу. PostgreSQL хранит пользователей, чаты, сообщения и ключи идемпотентности; Redis хранит общие действующие сессии. Состояние не привязано к отдельной API-реплике. X-Instance-Id берётся из hostname контейнера и стабилен на время жизни процесса. HAProxy обновляет backend-адреса через Docker DNS и проверяет /health/ready; sticky session не используется.

Из lab2 перенесены REST API, PostgreSQL, Redis-сессии, мигратор и существующие бизнес-операции. В lab3 добавлены две взаимозаменяемые реплики за HAProxy, X-Instance-Id, обязательный Idempotency-Key для POST сообщения, скрипты отказа/замены и таблица message_idempotency. Создание сообщения и запись соответствия (user_id, chat_id, key) → message_id выполняются в одной PostgreSQL-транзакции. При конфликте уникального ключа новая транзакция откатывается, затем читается ранее подтверждённое сообщение; другой текст возвращает 409. Текущий контракт POST сообщения содержит только текст, поэтому сравнение текста покрывает семантическое равенство допустимого body. Доступ к чату и сессия проверяются перед вызовом репозитория на каждом запросе.

.env.example соответствует фактическим переменным: APP_HOST/APP_PORT задают адрес API внутри контейнера, SESSION_TTL_SECONDS — срок сессии, DATABASE_URL_FILE — путь к Docker secret, SESSION_STORE=redis и REDIS_ADDR — общее хранилище сессий. APP_ENV читается конфигурацией, но сейчас не меняет поведение. Число реплик задано scale: 2 в Compose. Время 24 часа для записи идемпотентности задано в SQL; строки пока не очищаются автоматически, поэтому повтор с тем же ключом после 24 часов всё ещё вернёт исходное сообщение. Контракт гарантирует поведение в течение 24 часов и не требует разрешать повторное использование ключа позже.

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура skeleton make check PASS; эта проверка не запускает приложение вывод
Публичный smoke через LB make test BASE_URL=http://127.0.0.1:8080 PASS, сквозной сценарий lab3 вывод
Persistence и прежняя сессия make test-persistence ACTION_SCRIPT=scripts/restart.sh и отдельный повтор POST после рестарта PASS в рабочем и одноразовом Compose-проектах; прежний токен и сообщение сохранились, обе API-реплики и хранилища реально перезапущены без смены volumes рабочий стенд 29.10, изолированный прогон
Общая идемпотентность изолированный student-tests/stack.py verify --lab3-only --lab3-scenario idempotency через LB Все 11 сценариев PASS: границы ключа, повтор/конфликт, разные реплики, область ключа, конкуренция, restart, timeout/disconnect и повторная проверка сессии/членства итог, результаты
Отказ каждой реплики изолированный student-tests/stack.py verify --lab3-only и два публичных make test-failover Обе разные реплики остановлены и восстановлены; за два одинаковых 15-секундных профиля 0 ошибок, запись/чтение восстановились не позднее 0,510 с фрагмент и метрики, сырые события
Health/readiness и исключение backend изолированный grade4-runner с управляемой неготовностью live=200, ready=503 у выбранной реплики; LB исключил её и вернул после восстановления; сценарий PASS результаты, события
CPU/RAM-лимиты docker inspect и одинаковые прогоны tests/load.py Лимиты применены ко всем сервисам; под указанной нагрузкой ошибок и OOM нет baseline, limited, samples
Нагрузка с размером набора данных tests/load.py --duration 30 --concurrency 16 и SELECT count(*) FROM messages до/после 247 959 → 283 691 сообщений; 35 732 подтверждённых POST, 0 ошибок, 1187,504/с; CPU/RAM снимались во время прогона профиль, нагрузка, ресурсы
SIGTERM и исключение реплики docker stop --timeout 15 highload-lab3-api-1 при GET через LB API завершился; 105 ответов от оставшейся реплики, 1 переходный timeout events
Поочерёдная замена API под нагрузкой scripts/rolling-update.sh с HAProxy drain; локальный, отдельный rolling, единый полный и диагностический прогоны Во всех прогонах заменены два Docker ID при минимум одной ready-реплике. Три отдельных rolling-прогона дали 0 ошибок; единый полный — 1 GET timeout при клиентском лимите 1 с. Обязательный сценарий PASS, дополнительный порог нуля ошибок в общем прогоне FAIL локальный load, отдельный rolling, единый прогон, диагностика
Однократный мигратор и порядок запуска Docker events с момента до compose up в чистом изолированном проекте Ровно один start мигратора, exit 0; оба API стартовали позже его завершения migration evidence, start events
CI сборка и smoke отдельный job application в .github/workflows/contracts.yml Конфигурация YAML разбирается локально; реальный job требует push/PR и результата runner .github/workflows/contracts.yml

Первый полный собственный runner завершился FAIL: дополнительная проверка обнаружила 3 HTTP-ошибки при rolling, а тест изменения членства остался PENDING_INFRA. После исправления отдельный rolling-прогон дал PASS и 0 ошибок; отдельный idempotency-прогон дал PASS всех 11 сценариев. Затем запущен единый полный runner на новом одноразовом проекте: все обязательные проверки уровня «4», включая членство, прошли, но дополнительная проверка нуля ошибок при rolling завершилась FAIL из-за одного GET timeout. Его общий summary и сырые события сохранены. Диагностический rolling в той же двухсетевой схеме дал 0 ошибок; единичный timeout не воспроизвёлся, и его причина не установлена. Публичный smoke сам по себе не доказывает уровень «4».

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

Лимиты и таймауты

Замер выполнен на MacBook Air с Apple M2 (8 ядер: 4 производительных, 4 эффективных; 8 GB RAM). Docker Desktop ограничен 8 vCPU и 3,83 GiB памяти. Профиль: 16 конкурентных клиентов, 30 секунд, POST текстовых сообщений через публичный HAProxy; генератор tests/load.py работает по схеме closed-loop, не делает автоматических повторов. Это проверка выбранных лимитов под одним профилем, а не измерение предельной пропускной способности. Между прогонами база пополнилась сообщениями и контейнеры были пересозданы, поэтому небольшую разницу RPS нельзя приписывать лимитам. Точный размер набора данных перед этими двумя прогонами не был записан; для строгого сравнения производительности нужен повтор с фиксацией начального и конечного числа строк.

Сервис CPU на контейнер RAM на контейнер Пик RAM без лимита, MiB Пик RAM с лимитом, MiB
API, каждая из двух реплик 2 256 MiB 102,2 134,1
HAProxy 1 256 MiB 103,8 101,3
PostgreSQL 2 512 MiB 135,7 100,7
Redis 0,5 128 MiB 19,8 9,9
Мигратор, однократный процесс 1 256 MiB не измерен не измерен

Снимки docker stats получались примерно раз в 2–4 секунды, поэтому указанные пики — максимум среди выборочных снимков, а не гарантированный максимум процесса. Без лимитов: 1953,147 успешных HTTP-подтверждений/с, 0 ошибок, p99 успешных запросов 24,667 мс. С лимитами: 2000,378/с, 0 ошибок, p99 24,717 мс; OOM kill и самопроизвольных рестартов не было. Сырые данные: baseline load, baseline stats, limited load, limited stats.

Дополнительный профиль с зафиксированным размером данных: перед запуском в messages было 247 959 строк, после — 283 691. За 30,090 с при 16 закрытых клиентских циклах через публичный LB получено 35 732 подтверждённых POST (1187,504/с), 0 ошибок; p50/p95/p99 успешных запросов — 9,977/27,409/54,542 мс. Количество добавленных строк совпало с числом успешных POST в этом прогоне. Из 9 снимков docker stats максимальная RAM: среди API-реплик 147,5 MiB, LB 99,73 MiB, PostgreSQL 149,7 MiB, Redis 9,844 MiB; максимальный CPU по выводимому Docker проценту: среди API-реплик 77,39%, LB 71,92%, PostgreSQL 150,63%, Redis 11,06%. Это выборочные пики, а не непрерывная запись. Профиль, нагрузка, сырые снимки.

HAProxy проверяет GET /health/ready каждые 1 с (inter 1s), исключает backend после двух неудач (fall 2) и возвращает после двух успехов (rise 2). timeout check равен 1 с; для подключения при health-check действует не больше min(timeout connect=2s, inter=1s) = 1s, затем до 1 с на ответ. Консервативная оценка обнаружения отказа по этим таймерам — около 6 с: ожидание первой проверки до 1 с, две проверки до 2 с каждая и до 1 с между ними. В изолированной проверке ready=503 backend был исключён из LB и затем возвращён за 6,042 с с учётом сценария восстановления. Это расчёт по конфигурации и отдельное наблюдение, а не жёсткая гарантия при произвольной задержке планировщика или Docker DNS. Для обычного трафика HAProxy использует timeout connect 2s, timeout http-request 10s, timeout client/server 30s. Go HTTP-сервер ограничивает чтение заголовков 5 с, чтение запроса и запись ответа 10 с, простой соединения 30 с; штатный Shutdown ждёт до 15 с при stop_grace_period: 20s.

Отдельная проверка SIGTERM при запросах через LB: API-контейнер действительно перешёл в exited, целевая реплика не дала ответов после подачи сигнала, из 106 попыток 105 получили 200 от второй реплики и одна завершилась клиентским timeout. После переходной ошибки следующий успешный ответ записан на 1,632 с от начала остановки. Затем контейнер восстановлен. События: SIGTERM events. Повторный публичный failover после введения лимитов и таймаутов прошёл: 113 успешных записей, одна переходная ошибка, первая успешная запись через 2,457 с, подтверждённые данные и старая сессия сохранились.

Поочерёдная замена проверена скриптом scripts/rolling-update.sh. Первоначально он останавливал backend сразу: локальный 35,071-секундный профиль дал 27 773 POST без ошибок, но независимый изолированный 20,003-секундный профиль дал 4304 POST, 4301 GET и 3 HTTP-ошибки. После этого в HAProxy добавлен Runtime API только на loopback внутри LB-контейнера, а скрипт перед остановкой переводит выбранный backend в drain, ждёт завершения его активных запросов, заменяет контейнер и возвращает новый backend в маршрутизацию после готовности. В исправленном локальном профиле при 16 клиентах за 35,071 с получено 26 913 POST (767,381/с), 0 ошибок, p99 успешных запросов 143,931 мс. Отдельный изолированный повтор: за 20,001 с 3729 POST (186,443/с) и 3729 GET, 0 ошибок, два Docker ID заменены, минимум одна реплика оставалась готовой. Последующий единый полный прогон тоже заменил оба Docker ID при минимум одной ready-реплике, но за 20,139 с и 1151 POST/1150 GET получил один GET timeout на 19,193-й секунде при клиентском лимите 1 с. Причину по этим данным определить нельзя; строгий порог нуля ошибок не выполнен. Диагностический повтор в той же двухсетевой схеме сохранил временные метки, Docker events и потоковые логи: за 20,004 с 4649 POST и 4649 GET, 0 ошибок, обе реплики заменены. Прежний timeout не воспроизвёлся, поэтому его причина остаётся неустановленной. Данные: локальный load, локальный lifecycle, отдельный rolling, единый полный прогон, диагностический повтор. Профили отличаются числом клиентов и типами запросов, поэтому их RPS напрямую не сравниваются. Заменялись процессы с тем же образом; совместимость двух разных версий API этим прогоном не доказана.

В текущем Compose-проекте migrate имеет restart: "no", один успешный completion record, RestartCount=0 и ExitCode=0; обе работающие API-реплики созданы после его завершения. api зависит от migrate: service_completed_successfully. Этот проект уже имел схему, поэтому мигратор применил 0 новых SQL-файлов. Отдельный чистый изолированный запуск записал Docker events с момента до compose up: ровно один start мигратора, exit 0 в 2026-10-29T11:49:04.046Z, обе API-реплики стартовали позже (11:49:04.531Z и 11:49:04.651Z). Данные: текущий проект, чистый проект. Lab3-миграция 00004_message_idempotency.sql только создаёт новую таблицу и не меняет существующие таблицы/колонки; по SQL она совместима с прежними запросами. Одновременная работа двух разных собранных версий API не испытывалась, поэтому это остаётся ограничением. Миграцию 00003_drop_session_table.sql нельзя безопасно применять при старом API, который ещё использует PostgreSQL-таблицу sessions; при обновлении такой версии требуется отдельный порядок перехода.

Обе реплики проверены в одном изолированном проекте одинаковым 15-секундным циклом POST+GET через LB. При остановке первой: 3566 успешных записей (237,682/с), 3566 чтений, 0 ошибок, первая успешная запись/чтение через 0,355/0,356 с. При остановке второй: 3494 записи (232,901/с), 3494 чтения, 0 ошибок, запись/чтение через 0,508/0,510 с. Docker StartedAt подтвердил остановку и восстановление каждого выбранного процесса; публичный make test-failover тоже прошёл дважды с разными целевыми контейнерами. Методика и результаты, сырые события. В последующем едином полном прогоне оба отказа также прошли, но на каждом зафиксирован один переходный GET timeout с клиентским лимитом 1 с; запись и чтение восстановились не позднее 2,055 с. Единый прогон.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
SIGTERM одной API-реплики Вторая продолжает отвечать, первая перестаёт принимать 105 ответов 200, 1 клиентский timeout, целевая реплика завершилась Первый успешный ответ после сигнала через 1,632 с; сохранность данных этим GET-прогоном не измерялась
Отказ первой API-реплики Вторая продолжает чтение/запись, прежняя сессия действует 3566 POST и GET, 0 ошибок, 237,682 успешных POST/с Запись/чтение через 0,355/0,356 с; подтверждённые данные доступны
Отказ второй API-реплики Первая продолжает чтение/запись, прежняя сессия действует 3494 POST и GET, 0 ошибок, 232,901 успешных POST/с Запись/чтение через 0,508/0,510 с; подтверждённые данные доступны
Поочерёдная замена двух API-процессов после drain Одна реплика остаётся готовой; запись продолжается Минимум 1 ready; 3729 POST и GET за 20,001 с, 0 ошибок в целевом изолированном повторе Обе новые реплики работают; старые Docker ID исчезли

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

Проверена потеря одного API-процесса при работающих HAProxy, PostgreSQL и Redis. Потеря самого узла Docker Desktop, HAProxy, PostgreSQL или Redis этим стендом не переживается: они остаются единичными точками отказа. Обновление выполняется поочерёдной заменой процессов в одном Docker host, без распределения по разным узлам. Пиковая производительность не заявлена: tests/load.py — closed-loop генератор, а два нагрузочных прогона не нормализованы по размеру базы и шуму хоста. Для текущего профиля подтверждено отсутствие ошибок при выбранных CPU/RAM-лимитах и при замене API; запас до насыщения БД/LB не исследован.

Идемпотентность хранится без фоновой очистки после 24 часов, что увеличивает таблицу со временем. PostgreSQL и Redis доступны сервисам внутри общей Compose-сети; PostgreSQL дополнительно опубликован на loopback host для локальной диагностики. Secret с URL БД смонтирован только в API и мигратор, пароль инициализации PostgreSQL — только в PostgreSQL. Это локальные файлы secrets/, не централизованный secret manager. Роль messenger в текущем учебном стенде имеет права владельца БД; разделение DDL/DML-ролей не реализовано. Для теста изменения членства после отправки сообщения понадобился синтетический адаптер только в одноразовой БД: внешний ключ запрещает обычное удаление автора сообщения, а обязательный API не предоставляет удаления участника. Адаптер ограничил SQL точными UUID и восстановил данные в finally; повтор при отсутствии членства вернул 404, после восстановления — исходное сообщение. Этот тест не доказывает работу будущего публичного endpoint удаления участников. Единый полный runner после исправлений подтвердил все обязательные критерии, но завершился FAIL по дополнительному требованию нуля ошибок rolling: был один GET timeout с лимитом клиента 1 с, причина не установлена.