Files
mtusi2026lab3/REPORT.md
T

8.4 KiB
Raw Blame History

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

  • Автор, группа — Архипов Антон Андреевич, БПИ2304
  • Целевая оценка — «3»
  • Commit/PR — указать после публикации в своём fork.
  • Использованные библиотеки и инструменты — TypeScript, Express, tsoa, Zod, UUID, Pino, Swagger UI, node-postgres, Node.js crypto, Docker Compose и HAProxy. Материалы — README.md, COURSE.md, contracts/README.md и OpenAPI из задания.
  • ИИ использовался для разбора требований, проектирования структуры приложения, проверки соответствия контракту и подготовки отчёта.

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

Нужны Docker Engine с Docker Compose v2, shell, GNU Make и Python 3.9+. Версии образов — Node.js 22.16.0-alpine3.22, postgres:15.18-bookworm и haproxy:3.0.11-alpine.

chmod +x scripts/init-env.sh scripts/restart.sh scripts/stop-one.sh
./scripts/init-env.sh
docker compose config --quiet
docker compose build migrate
docker compose up -d --no-build --wait
curl -fsS http://localhost:8080/health/ready
make check
make test
python3 student-tests/auth_and_chat.py
python3 student-tests/idempotency.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps --all api-a api-b
docker compose start api-a api-b

Миграции запускает сервис migrate. Повторить вручную можно командой docker compose run --rm migrate. После отказа скрипт оставляет целевую реплику остановленной. docker compose start api-a api-b возвращает стенд в исходное состояние. Для ручного выбора используйте TARGET_INSTANCE_ID=api-b ./scripts/stop-one.sh при готовой api-a.

docker compose down сохраняет данные. docker compose down -v намеренно удаляет учебный том. При изменении APP_BIND_PORT передайте соответствующий BASE_URL проверкам. Swagger UI доступен через HAProxy по /docs.

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

Сохранены PostgreSQL, Bearer-сессии, миграция 001_core.sql, таблицы и API из лабораторной 2. Между клиентом и API добавлен HAProxy. api-a и api-b запускают один образ и читают одну базу, в которой хранятся и сессии. HAProxy распределяет запросы round-robin без привязки сессии к реплике.

Роль Сервис Готовность Данные и доступ
PostgreSQL postgres pg_isready по TCP Именованный том postgres_data, внутренняя сеть
Миграции migrate Успешное завершение SQL Один запуск перед обеими репликами
API api-a, api-b /health/ready проверяет PostgreSQL и миграцию Внутренний порт 8080, свой X-Instance-Id
Балансировщик lb HTTP-проверки backend /health/ready Единственный порт хоста 127.0.0.1:8080

.env содержит POSTGRES_USER, POSTGRES_DB, POSTGRES_PASSWORD, длительность сессии и настройки локального порта и логов. В Compose каждому API присвоен собственный INSTANCE_ID, соответствующий имени сервиса. HAProxy использует DNS Compose для обновления адресов и проверяет готовность раз в секунду, исключая реплику после двух неудач. Таймаут подключения — 1 секунда. При SIGTERM API закрывает HTTP-сервер, дожидается активных запросов и освобождает пул соединений.

Миграция 002_idempotency.sql добавляет общий реестр ключей POST сообщений. Область ключа — пользователь и чат для этого метода. PostgreSQL сериализует конкурентное занятие одинакового ключа по составному первичному ключу. Запись сообщения и привязка результата к ключу фиксируются одной транзакцией. Повтор с тем же телом в течение 24 часов возвращает тот же объект с 201. Другое тело получает 409. Если транзакция прервётся, резервирование ключа откатывается.

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

16.11.2026 проверены локальные процессы Node.js 22.16.0, PostgreSQL 15.18 и HAProxy 3.0.11. Маршрут HTTP шёл через реальный HAProxy. В локальной проверке имена backend заменены loopback-адресами, а hooks управляли PID. Compose-манифест проверен отдельно через config --quiet (Compose v2.36.2).

Критерий уровня 3 Команда или сценарий Результат
Один вход и две реплики с общей сессией make test-failover До отказа клиент с одним токеном увидел два разных X-Instance-Id
Контракт с обязательным ключом make test Пройдены smoke, replay и конфликт изменённого тела
Конкурентный повтор python3 student-tests/idempotency.py 16 запросов через две реплики вернули один и тот же объект. В истории осталась одна запись
Перезапуск всей схемы make test-persistence с локальным hook HAProxy, PostgreSQL и обе реплики сменили PID. Сохранились токен и подтверждённое сообщение
Отказ API-реплики make test-failover с локальным hook Остановлена api-a. За 15 секунд теста подтверждено 125 записей, 8 попыток завершились ошибкой. Первый успешный POST после hook зафиксирован через 0,231 сек. Дублей и потери подтверждений не обнаружено
Контракт и конфигурация make check, docker compose config --quiet, проверка HAProxy Команды завершились успешно

В отдельном прогоне была остановлена api-b. После остановки api-a подтвердила запись и чтение обеих записей за 1,224 секунды.

Вывод команд и PID — local-verification.txt и second-replica.txt.

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

При остановке одного API база, HAProxy и второй API продолжают работать. Возможны ошибки нескольких запросов во время пересчёта готовности. Клиент повторяет неопределённый POST сообщения с прежним ключом. В стенде один PostgreSQL и один HAProxy, поэтому их отказ затрагивает весь сервис. Метрика одного прогона описывает локальное переключение между процессами на одном хосте. Истёкшие ключи можно использовать заново, старые записи остаются в таблице до повторного использования или обслуживания.