Files
mtusi2026lab3/REPORT.md
T

69 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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`.
```sh
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](evidence/local-verification.txt) и [second-replica.txt](evidence/second-replica.txt).
## Эксперименты и отказы
При остановке одного API база, HAProxy и второй API продолжают работать. Возможны ошибки нескольких запросов во время пересчёта готовности. Клиент повторяет неопределённый POST сообщения с прежним ключом. В стенде один PostgreSQL и один HAProxy, поэтому их отказ затрагивает весь сервис. Метрика одного прогона описывает локальное переключение между процессами на одном хосте. Истёкшие ключи можно использовать заново, старые записи остаются в таблице до повторного использования или обслуживания.