Files
mtusi2026lab3/REPORT.md

16 KiB
Raw Permalink Blame History

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

  • Автор, группа: Федоров Арсений, БПИ2302.
  • Целевая оценка: 3. Трек 5: не заявлен.
  • Репозиторий: https://gitea.privcloud.tech/Fedoroff/mtusi2026lab3
  • Ветка: solution/BPI2302-fedorov.
  • Подтверждённый опубликованный коммит до обновления отчёта: 35ae6f7 (feat: implement lab3 load balancing and idempotency). Коммит с данным отчётом будет создан отдельно; его хеш и ссылку на PR можно добавить после публикации.
  • Источники: задание и README лабораторной №3, контракт contracts/openapi.json, код и результаты лабораторной №2, официальная документация Go, Docker Compose, Nginx, PostgreSQL и Redis.
  • Библиотеки: зависимости Go перечислены в go.mod / go.sum (в частности, pgx, go-redis и google/uuid); образы инфраструктуры определены в compose.yaml.
  • Использование ИИ: ChatGPT использовался для подготовки и исправления кода, конфигурации Docker/Nginx, тестов и документации, а также для разбора ошибок Windows/Python. Команды и сценарии, перечисленные как успешные ниже, запускались локально пользователем. ИИ не заменяет фактическую проверку и оценивание преподавателем.

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

Среда фактической проверки: Windows, PowerShell, Docker Desktop / Docker Compose, Python 3.10.5; тесты Go запускались в контейнере golang:1.25.0-alpine. В compose.yaml использовались PostgreSQL 16.10-alpine, Redis 7.4.6-alpine, Nginx 1.29-alpine. Для запуска требуются Git, Docker с Compose и свободный порт 127.0.0.1:8080. Для Python-тестов на Windows требуется установленный Python с командой py -3; make — для запуска целей Makefile.

# Получить исходники и перейти на ветку решения
git clone https://gitea.privcloud.tech/Fedoroff/mtusi2026lab3.git
cd mtusi2026lab3
git switch solution/BPI2302-fedorov

# Создать локальную конфигурацию; вручную заполнить требуемые значения
Copy-Item .env.example .env
notepad .env

# Собрать и запустить инфраструктуру и API
docker compose --env-file .env up -d --build

# Проверить контейнеры (в том числе завершившийся с кодом 0 migrate)
docker compose --env-file .env ps -a

Локальный оператор задаёт значения из .env.example в .env, включая пароль БД; не публикует .env и не вставляет секреты в отчёт. Миграции выполняет отдельный сервис migrate в составе Compose; успешное завершение подтверждается Exited (0). Два экземпляра API (api1, api2) должны быть healthy, как и PostgreSQL/Redis. Балансировщик доступен по http://localhost:8080.

Проверки в том же окне PowerShell:

# Python 3.10 на Windows: читать UTF-8-файлы как UTF-8
$env:PYTHONUTF8 = "1"

# Если в Makefile установлено PYTHON ?= python3,
# использовать переносимый вызов с переопределением:
make check PYTHON="py -3"
make test PYTHON="py -3"

# Проверка конкурентной идемпотентности
py -3 tests/idempotency_concurrent.py --base-url "http://localhost:8080"

# Go-тесты без локальной установки Go
docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./...

Примечание по Makefile: во время локальной проверки команда make выводила py -3 ..., поскольку для Windows было настроено значение PYTHON=py -3. На Linux можно оставить стандартное python3. Перед сдачей следует убедиться, что текущая версия Makefile соответствует командам в репозитории.

Безопасная остановка с сохранением томов и данных:

docker compose --env-file .env down

Только для намеренного удаления учебных данных (удаляет тома Compose, включая данные БД):

docker compose --env-file .env down -v

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

Клиент / публичные тесты
          |
          v
Nginx (lb, 127.0.0.1:8080)
          |
     +----+----+
     |         |
   api1       api2      (Go HTTP API; X-Instance-Id)
     |         |
     +----+----+
          |
    +-----+-----+
    |           |
PostgreSQL     Redis
(данные,       (кеш / сессии)
транзакции,
идемпотентность)

migrate --> PostgreSQL (отдельный одноразовый сервис миграций)

Перенесено из лабораторной №2: API пользователей, авторизации/сессий, чатов и сообщений; PostgreSQL, Redis, проверка JSON, обработка ошибок, публичный контракт и регрессионные тесты.

Изменения лабораторной №3: два экземпляра API за Nginx, общий доступ к хранилищам, заголовок X-Instance-Id, идемпотентная отправка сообщений с Idempotency-Key, отдельный процесс миграций и сценарии проверки конкурентных запросов/остановки одной реплики.

Источник истины: PostgreSQL для сохраняемых сущностей и фиксации результата создания сообщения; Redis используется как вспомогательное хранилище для работы с сессиями. Для идемпотентной записи используются ограничения/транзакции PostgreSQL (см. migrations/002_idempotency.up.sql и internal/storage/message_postgres.go). Запросы к двум API-репликам обращаются к общим хранилищам, а не к независимым базам данных.

Конфигурация: шаблон переменных окружения — .env.example, локальные значения — .env; способ запуска и сервисы — compose.yaml, настройки балансировщика — infra/nginx.conf. Пароли и токены в Git не добавляются.

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

Проверяемое требование Команда / сценарий Фактически наблюдаемый результат Где воспроизвести / доказательство
Структура и синтаксис make check с PYTHON=py -3, PYTHONUTF8=1 PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. scripts/check_contract.py; вывод локальной проверки
Публичный сценарий API make test с PYTHON=py -3, PYTHONUTF8=1 PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. tests/smoke.py; вывод локальной проверки
Go-тесты docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./... Пакеты internal/handler и internal/storage: ok; остальные показали [no test files]; ошибок FAIL не было Go-тесты в internal/handler, internal/storage; вывод локальной проверки
Конкурентная идемпотентность py -3 tests/idempotency_concurrent.py --base-url "http://localhost:8080" PASS: 16 concurrent retries, one message, replicas: api1, api2 tests/idempotency_concurrent.py; вывод локальной проверки
Балансировка двух реплик 10 запросов GET /health/live через Nginx, чтение X-Instance-Id В ответах присутствовали api1 и api2 compose.yaml, infra/nginx.conf; вывод PowerShell
Доступность после отказа одной реплики docker compose --env-file .env stop api1; затем 5 запросов GET /health/live Все пять ответов получены от api2 Вывод PowerShell и состояние контейнеров
Возврат реплики в строй docker compose --env-file .env up -d --no-deps api1; затем docker compose --env-file .env ps api1 снова healthy; api2, PostgreSQL и Redis также healthy Вывод docker compose ps
Миграции docker compose --env-file .env ps -a migrate завершился с Exited (0); API и хранилища запустились compose.yaml, migrations/; вывод ps -a
Уровень 4 Не заявлен Не проверялся как критерий сдачи —
Трек 5 Не заявлен Не проверялся —

Фактические фрагменты вывода:

make check:
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.

make test:
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.

idempotency_concurrent.py:
PASS: 16 concurrent retries, one message, replicas: api1, api2

GET /health/live при остановленном api1:
api2
api2
api2
api2
api2

Эти результаты получены на локальной машине, но отдельные файлы с полными логами в evidence/ пока не приложены. Для независимого воспроизведения приведены команды и исходники тестов. Сами make check и make test не доказывают всех инфраструктурных критериев: они дополнены ручным сценарием отказа и конкурентным тестом.

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

Гипотеза 1: Nginx направляет запросы к обоим экземплярам API. Метод: десять последовательных HTTP-запросов к /health/live с чтением заголовка X-Instance-Id. Наблюдение: ответы от api1 и api2; распределение в этом небольшом прогоне близко к чередованию. Это функциональная проверка маршрутизации, не измерение производительности.

Гипотеза 2: остановка одной реплики не приводит к полной недоступности API. Метод: docker compose ... stop api1, затем пять запросов через балансировщик. Наблюдение: пять успешных ответов с X-Instance-Id: api2. После up -d --no-deps api1 реплика вновь стала healthy.

Гипотеза 3: конкурентные повторы одного запроса не создают дубликаты сообщения. Метод: tests/idempotency_concurrent.py, 16 одновременных повторов. Наблюдение: one message, запросы обработаны через обе реплики.

Воздействие Ожидание Фактическое наблюдение Восстановление / данные
Запросы через Nginx при двух работающих API Обе реплики получают запросы Наблюдались api1 и api2 Не применимо
Остановка api1 Доступность через api2 Пять ответов api2 Время переключения не измерялось; потеря данных отдельно не проверялась
Повторный запуск api1 Возврат к двум здоровым репликам api1 и api2 в состоянии healthy Время до healthy не замерялось
16 конкурентных повторов с одним ключом Одна логическая запись сообщения Тест сообщил one message Дубликаты в этом сценарии не обнаружены

Условия и пределы измерения: локальная Windows-машина с Docker Desktop; точные характеристики CPU/RAM, выделенные лимиты контейнеров, продолжительность прогрева, arrival rate, успешные RPS, число ошибок под длительной нагрузкой, p50/p95/p99 и потребление ресурсов не фиксировались. Проведены функциональные сценарии, а не полноценный нагрузочный бенчмарк. Утверждений об улучшении производительности или гарантированном времени восстановления не делается.

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

  • При остановке одного Go API работа через оставшуюся реплику подтверждена; одновременная потеря обоих API не выдерживается.
  • Nginx — один экземпляр и потенциальная единая точка отказа; отказоустойчивый кластер балансировщиков не реализован.
  • PostgreSQL и Redis запущены без подтверждённого автоматического переключения на резервный узел; их отказоустойчивость не заявляется.
  • Проверена конкурентная идемпотентность в одном сценарии на 16 запросов; исчерпывающие испытания при сбоях БД и во всех сетевых условиях не проводились.
  • Нет измеренных RPS, p50/p95/p99, CPU/RAM и времени восстановления. Следующий шаг — выполнить повторяемый нагрузочный тест и сохранить сырые результаты без секретов.
  • Локальная совместимость Python 3.10/Windows потребовала включения UTF-8 и корректного разбора дробных секунд RFC3339 в тестовом клиенте. Эти исправления должны быть включены в ветку вместе с отчётом.
  • Решение ориентировано на учебную среду Docker Compose, не на промышленное развёртывание.