8.4 KiB
Отчёт — лабораторная 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, поэтому их отказ затрагивает весь сервис. Метрика одного прогона описывает локальное переключение между процессами на одном хосте. Истёкшие ключи можно использовать заново, старые записи остаются в таблице до повторного использования или обслуживания.