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