Files
mtusi2026lab3/REPORT.md
T

23 KiB
Raw Blame History

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

Поле Значение
Автор Ситникова Дарья Евгеньевна
Группа БВТ2303
Целевая оценка 4; трек на 5 не заявлен
Commit / PR Будут указаны после публикации
Статус Все критерии на 3 и 4 проверены локально; проверка чистого клона предстоит

1. Запуск и проверки

Требования: Docker Desktop с Linux-контейнерами, Compose V2, Python 3.9+, PowerShell. Для make нужен GNU Make; Go на хосте нужен только для запуска Go-тестов вне Docker.

Все команды выполняются из корня репозитория.

Подготовка и запуск

./scripts/init-local.ps1
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180

После запуска API доступен через балансировщик. Локальные настройки и данные хранятся следующим образом:

Настройка Значение
Единая точка входа http://127.0.0.1:8083
Bootstrap Создаёт .env и secrets/postgres_password.txt; существующие файлы сохраняет
Пароль БД Генерируется локально, не печатается; передаётся через Compose secret
Файлы вне Git .env, secrets/, данные хранилищ
Данные PostgreSQL Volume postgres_lab3_data_v1 в проекте Compose
Существующий volume Требует исходного пароля: замена файла secret не меняет пароль роли в БД

Функциональные проверки

py -X utf8 scripts/check_contract.py
py -X utf8 tests/smoke.py --base-url http://127.0.0.1:8083
py -X utf8 student-tests/replicas.py
py -X utf8 tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8083
py -X utf8 tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8083
# После failover восстановить остановленную API:
docker compose up -d --wait
  • restart.cmd перезапускает LB, API, PostgreSQL и Redis с сохранением volume.
  • stop-one.cmd сопоставляет TARGET_INSTANCE_ID контейнеру и оставляет выбранную API остановленной.
  • Для проверки отказа обеих API необходимо восстановление между прогонами и подтверждение разных остановленных контейнеров через docker compose ps -a.
  • Если py не находит Python, команды выполняются через установленный python.exe; его путь также задаётся в $env:LAB_PYTHON для hooks. Локальные проверки выполнены Python из runtime Codex.
  • Эквивалент через Make: make check test BASE_URL=http://127.0.0.1:8083 PYTHON="python3 -X utf8". На Windows вместо python3 указывается py либо путь к python.exe.
  • Linux-hooks: scripts/restart.sh, scripts/stop-one.sh; нужны Python 3, Docker CLI и chmod +x для обоих файлов. Их выполнение на Linux не проверялось.

Нагрузка и поочерёдная замена

py -X utf8 student-tests/operations_load.py baseline
py -X utf8 student-tests/operations_load.py stop1
py -X utf8 student-tests/operations_load.py stop2
py -X utf8 student-tests/operations_load.py rolling

Сценарий восстанавливает две API после каждого прогона. Результаты: evidence/load-*.json, операции с контейнерами: evidence/operations-*.json.

Остановка

Действие Команда
Остановка с сохранением данных docker compose down
Намеренное удаление данных текущего стенда docker compose down --volumes

При проверках сохранности --volumes не используется.

2. Архитектура

Клиент → HAProxy → API ×2 → PostgreSQL
                       └→ Redis (кэш профилей)

Состав стенда и лимиты ресурсов заданы в compose.yaml. Лимит API указан для каждой реплики отдельно.

Компонент Версия CPU / RAM Назначение
API ×2 Go 1.26.3; итоговый образ scratch По 1 CPU / 384 MiB REST API; порты наружу не опубликованы
HAProxy 3.2.4-alpine 0,5 CPU / 64 MiB Единственный публичный порт: 127.0.0.1:8083
PostgreSQL 17.9-bookworm 1 CPU / 512 MiB Данные, сессии, ключи идемпотентности; постоянный volume
Redis 7.4.11-alpine 0,25 CPU / 128 MiB Кэш профилей; maxmemory 64 MiB, allkeys-lru, tmpfs
migrate postgres:17.9-bookworm 0,5 CPU / 128 MiB Отдельный одноразовый запуск миграций перед API

Основные решения обеспечивают взаимозаменяемость реплик: обязательные данные и сессии хранятся вне процессов API.

Область Решение
Перенос из lab2 Исходники, зависимости, миграции и Dockerfile; lab2 не изменялась
Сохранённые возможности PostgreSQL, пароли Argon2id, общие Bearer-сессии, история с keyset-пагинацией, Redis-кэш
Файлы задания Контракт и публичные тесты lab3 сохранены
Балансировка Roundrobin, без sticky sessions; нет container_name
Выбор HAProxy Активные проверки ready, распределение запросов и обновление backend-адресов через Docker DNS
Идентификатор API Случайный X-Instance-Id, постоянный на срок жизни процесса; есть во всех ответах API
Источник истины PostgreSQL; Redis содержит только восстановимый кэш
Секрет БД Доступен API, PostgreSQL и migrate; недоступен LB и Redis
Миграции schema_migrations, advisory lock; DDL и версия в одной транзакции; применённые версии пропускаются

Готовность и таймауты

Балансировщик направляет запросы только готовым репликам. Таймаут завершения API меньше периода, который Docker отводит на остановку контейнера.

Параметр Настройка
/health/live Проверка жизни процесса
/health/ready Проверка критического пути с PostgreSQL; отказ Redis допускает fallback
Проверки HAProxy GET ready; интервал 1 с, timeout 1 с, fall=2, rise=2
Обнаружение отказа Расчётный бюджет до 4 с при сетевом зависании плюс задержки планировщика; фактические результаты ниже
DNS Docker DNS 127.0.0.11; до 10 backend-слотов с актуализацией адресов
Таймауты LB connect 1 с, server 12 с, client 15 с; автоматические повторы отключены
Таймауты API read/write 10 с; graceful shutdown до 8 с
Остановка Docker SIGTERM; stop_grace_period 15 с

Конфигурация окружения

Ниже указано, какие параметры действительно используются приложением и Compose. Наличие переменной в исходном .env.example само по себе не включает соответствующую настройку.

Переменные Использование
SESSION_TTL_SECONDS Compose передаёт API; по умолчанию 3600
LB_PORT Порт хоста; по умолчанию 8083
APP_HOST, APP_PORT Поддержаны Go; Compose использует defaults 0.0.0.0:8080
DATABASE_PASSWORD_FILE, REDIS_ADDR Заданы в Compose
APP_ENV, DATABASE_URL_FILE, CACHE_URL_FILE, SESSION_STORE Предложения исходного .env.example; не используются
API_REPLICAS, IDEMPOTENCY_TTL_SECONDS Не используются: scale: 2 в Compose, TTL ключа фиксирован 24 часа

Идемпотентность сообщений

Повтор отправки с тем же ключом должен возвращать исходное сообщение. Общая транзакция PostgreSQL защищает от дублей при одновременных запросах через разные API.

Условие Поведение
Формат ключа Обязательный ASCII [A-Za-z0-9._:-]{1,128}; нарушение → 400
Область Пользователь + чат + ключ; таблица используется только для POST сообщений
Проверка доступа Действующая сессия и членство проверяются при каждом повторе
Конкуренция Транзакция блокирует строку чата в общей БД перед проверкой ключа
Первый запрос Сообщение и запись message_keys сохраняются одним COMMIT
Повтор того же текста Исходный Message и код 201
Другой текст с тем же ключом 409 conflict
Сравнение тела Декодированный text, а не байты JSON; OpenAPI lab3 допускает только поле text
Срок 24 часа без продления при повторе; истёкшая привязка заменяется при новом использовании
Ошибка транзакции Изменения откатываются; временный 5xx не сохраняется как результат

3. Критерии на 3 и 4

Все пункты закрыты в локальном стенде. Нумерация соответствует порядку критериев README.

Пункт Проверка и результат Доказательства
3.1. Стенд, ≥2 API, единый вход, общие БД и сессии Compose запускается; работают две API; опубликован только LB Процессы, smoke
3.2. Одна сессия через разные API Один токен принят двумя процессами; заголовок стабилен внутри процесса Реплики, Go-тест
3.3. Отказ любой одной API Обе API остановлены в разных прогонах; запись восстановлена ≤10 с, подтверждённые сообщения и сессия сохранены API-1, API-2, снимок 1, снимок 2
3.4. Идемпотентность 16 параллельных повторов через две API → одно сообщение; другой текст → 409, без ключа → 400; failover не создал дублей Конкурентность, failover
3.5. Публичные проверки make check test, persistence и failover — PASS; PostgreSQL действительно перезапущен Make, persistence, БД
4.1. Readiness, таймауты, SIGTERM LB исключает остановленную API; параметры согласованы; shutdown в прогонах завершён за 0–1 мс Shutdown, failover
4.2. Отказы каждой API и измерения Между прогонами API восстановлены; RPS, ошибки и восстановление измерены; конкурентные ключи проверены stop1, stop2, ключи
4.3. Лимиты, порты, секреты CPU/RAM-лимиты применены; API ports={}; секреты и volume ограничены назначением; нет container_name Лимиты, Compose
4.4. Поочерёдная замена под нагрузкой Оба контейнера заменены; сосед сохранялся; новая API видна через LB до следующей замены; ограничения миграций описаны Нагрузка, операции, проверка после замены

Дополнительно: go test ./... -count=1 — PASS; go vet ./... — без замечаний. Проверки HTTP выполнялись вне песочницы, ограничивающей loopback-соединения.

4. Результаты экспериментов

Методика

Во всех профилях используется один генератор и одинаковый параллелизм. Меняется воздействие на API: штатная работа, остановка одной реплики или поочерёдная замена.

Параметр Значение
Docker 29.1.2; доступно 16 CPU и 16 389 435 392 байт RAM
Генератор Неизменённый tests/load.py; closed-loop POST сообщений
Параллелизм 4 клиента
Данные Новый чат и три синтетических пользователя на прогон; история изначально пустая и растёт; предыдущие данные БД сохраняются
Продолжительность baseline/stop1/stop2 — 25 с; rolling — 50 с
Повторы и прогрев Один прогон на режим; отдельного исключаемого прогрева нет
Начало воздействия Через 5 с после запуска генератора, включая bootstrap
Повторы POST Отключены; ошибки учитываются отдельно
RPS Успешные HTTP-запросы / фактическая длительность нагрузки
Перцентили Только успешные ответы

Нагрузка

baseline — работа двух API; stop1 и stop2 — остановка соответствующей реплики; rolling — замена обеих по очереди. RPS и доля ошибок рассчитаны по всему прогону; задержки — только по успешным ответам.

Профиль Длительность, с Успешных / ошибок Успешных RPS Доля ошибок p50 / p95 / p99, мс
baseline 25,094 5378 / 0 214,314 0% 16 / 32 / 62
stop1 25,110 5110 / 57 203,505 1,1032% 16 / 32 / 47
stop2 25,109 4826 / 51 192,202 1,0457% 16 / 46 / 63
rolling 50,094 10125 / 151 202,120 1,4694% 16 / 32 / 62

Исходные результаты: baseline, stop1, stop2, rolling.

Отказы и сохранность

Отдельный сценарий отправляет сообщения во время отказа, безопасно повторяет неопределённые запросы и проверяет историю с прежней сессией. Время восстановления POST отсчитывается от запуска скрипта остановки.

Воздействие Успешных записей / неуспешных попыток Восстановление POST Сохранность
Отказ API-2; 15 с запросов 111 / 2 2,750 с Подтверждённые сообщения и прежняя сессия сохранены
Повтор отказа API-2 117 / 2 2,688 с То же
Отказ API-1 после восстановления API-2 116 / 1 2,781 с То же
Перезапуск всего стенда persistence PASS Готовность дождался сценарий Прежний токен и сообщение сохранены

Поочерёдная замена

Замена выполняется при продолжающейся нагрузке. Следующая реплика останавливается только после появления новой API в ответах через балансировщик.

Шаг Действие
1 Остановить и удалить одну API; работающую соседнюю API сохранить
2 Создать недостающую API: up -d --no-deps --no-recreate --scale api=2 api
3 Дождаться нового X-Instance-Id через LB
4 Повторить для второй API при продолжающейся нагрузке
  • Обе API получили новые container ID; ID работающего соседа проверен на каждом шаге.
  • Новые API стали видны через LB за 5,204 и 3,890 с от начала соответствующей замены. Это длительность операции, не полной недоступности сервиса.
  • Использован тот же образ; миграции во время замены не запускались.
  • Применённые миграции пропускаются; миграция 2 добавляет таблицу без изменения существующих.
  • Смешанный запуск lab2/lab3 не поддерживается: lab2 не обеспечивает идемпотентность. Для несовместимых изменений нужен отдельный план миграции.
  • После замены make check test и проверка общей сессии/идемпотентности — PASS.

Ресурсы

Разовый docker stats во время stop1; это не средние и не пиковые значения.

Компонент CPU RAM
API-1 Остановлена, 0 PIDs —
API-2 81,87% 148,8 MiB
PostgreSQL 45,35% 36,29 MiB
LB 38,25% 19,15 MiB

Доказательство: resources-during-load.jsonl.

5. Ограничения

  • Один Docker-host; PostgreSQL и LB — единичные точки отказа. Потеря узла/диска не проверялась.
  • Локальный HTTP с синтетическими данными; PostgreSQL без TLS, роль messenger — superuser, Redis без пароля.
  • Истёкшие ключи и сессии не очищаются фоновым процессом.
  • Проверена замена контейнеров с тем же образом, не обновление между разными версиями приложения.
  • Во время отказов и замены есть измеренные ошибки; бесшовное обновление не заявляется.
  • Нагрузка closed-loop: клиентский overhead и coordinated omission; единичные прогоны не определяют максимальную производительность и не доказывают преимущество одного режима.
  • Timeout не доказывает отсутствие записи. Безопасные повторы и сохранность проверяются отдельно сценарием resilience.
  • stop_and_ready_seconds в operations-stop1/stop2.json (1,032/1,078 с) измеряет stop → GET ready живой API; это не время восстановления POST или окончательного исключения backend.
  • Linux-hooks и запуск из чистого клона пока не проверены. Проверка клона выполняется после коммита с отдельными локальными secrets и пустым volume; текущие доказательства относятся к рабочему дереву.

6. Источники и помощь

  • Задание, README, OpenAPI и публичные тесты lab3; собственная реализация lab2.
  • Библиотеки: pgx, go-redis, golang.org/x/crypto (Argon2id).
  • Docker Compose, HAProxy DNS.
  • Codex: помощь с реализацией, объяснениями, проверками и подготовкой отчёта.