# Отчёт — лабораторная 3 - Автор, группа: Яковлев Матвей Дмитриевич, БПИ2304 - Целевая оценка; выбранный трек 5, если нужен: 3 - Commit/PR: ветка: (solution/BPI2304-Yakovlev); MR: (TODO после публикации) - Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.135.3, Uvicorn 0.44.0, psycopg 3.3.3, PostgreSQL 16-alpine, nginx 1.27-alpine; версии закреплены в `requirements.txt`, `compose.yaml`, `Dockerfile`. При подготовке использовалась помощь Claude. ## Запуск из чистого clone ```sh git clone && cd <каталог> cp .env.example .env # только синтетические локальные креды; .env в Git не попадает docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build curl -i http://localhost:8080/health/ready # единая точка входа — nginx python tests/smoke.py --base-url http://localhost:8080 ``` Единственный публичный порт — 8080 балансировщика; напрямую API-реплики портов не публикуют. Остановка с сохранением данных: `docker compose --env-file .env stop api1 api2 db`. Намеренное удаление учебных данных: `docker compose --env-file .env down -v`. Явные сценарии проверок: ```sh make test make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Windows локально: scripts/restart.cmd и scripts/stop-one.cmd ``` После останова одной реплики восстановление — отдельной командой: `docker compose --env-file .env start api1` (или `api2`). Полный вывод — `evidence/lifecycle.txt`. ## Архитектура и решения Клиент → **nginx** (`lb`) → **api1 / api2** (один образ, две interchangeables реплики) → общий **PostgreSQL**. - `infra/nginx.conf`: upstream с `api1:8080` и `api2:8080`, `max_fails=1 fail_timeout=5s`, `proxy_next_upstream error timeout http_502 http_503 http_504`, таймауты 2/10/10 с. Sticky session не используется: любая реплика обслуживает любой запрос с тем же Bearer-токеном. - `X-Instance-Id`: каждой реплике через окружение задаётся alias `api1`/`api2`; заголовок добавляется middleware в каждый ответ. Один клиент видит оба значения через LB (см. доказательства). - Общее состояние: PostgreSQL хранит пользователей, чаты, участников, сообщения, сессии — в памяти процесса нет authoritative данных. Сессии не требуют повторного входа при смене реплики. - Миграции: `SELECT pg_advisory_xact_lock(20261116)` перед чтением `schema_migrations`, поэтому при одновременном старте двух реплик файл `001_init.sql` применяется ровно один раз. - **Общая идемпотентность**: таблица `idempotency_records` с первичным ключом `(user_id, method, path, key)` в той же БД. `POST /chats/{id}/messages` требует `Idempotency-Key` (`[A-Za-z0-9._:-]{1,128}`); хэш канонического тела, код и тело ответа записываются **в одной транзакции** с сообщением. Повтор с тем же ключом возвращает сохранённый `201` и тот же Message; другое тело с тем же ключом — `409`. При конкуренции двух реплик проигравший ловит `UniqueViolation`, откатывается и читает зафиксированный ответ победителя — дубля нет. Повтор снова проверяет сессию и доступ к чату. - `scripts/stop-one.sh` отображает `TARGET_INSTANCE_ID` (alias из `X-Instance-Id`) на соответствующий Compose-сервис и останавливает только его; БД, volume и LB не трогаются. `scripts/restart.sh` перезапускает `db`, `api1`, `api2` без удаления volume. - `/health/ready` проверяет `SELECT 1`; nginx не использует пассивные проверки API как единственный механизм — при отказе реплики запрос повторяется на другой. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | ≥2 реплики, одна точка входа | `docker compose ps`; 8 запросов к LB | `api1`/`api2` в заголовке `X-Instance-Id` у одного клиента; только `lb` публикует 8080 | `evidence/lifecycle.txt`, разделы 2–3 | | Публичный smoke c идемпотентностью | `python tests/smoke.py` | `PASS: lab3 public API scenario...`; повтор ключа = тот же Message, другой body = 409 | `evidence/lifecycle.txt`, раздел 4 | | Общая идемпотентность в БД | `psql ... SELECT count(*) FROM idempotency_records` | число записей ledger равно числу сообщений; уникальный ключ `(user, method, path, key)` | `evidence/lifecycle.txt`, раздел 5 | | Перезапуск всего стенда с тем же токеном | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data and existing session`; `schema_migrations` без повторов (advisory lock) | `evidence/lifecycle.txt`, разделы 6–7 | | Отказ одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `observed_instances_before: 2`, 106 успешных записей, 2 transitional failure, `first_recovery_seconds: 0.608`, PASS | `evidence/lifecycle.txt`, разделы 8–9 | | Офлайн-проверки | `python scripts/check_contract.py`; 11 unit-тестов | PASS, 11 OK | `evidence/lifecycle.txt`, раздел 10 | ## Эксперименты и отказы Не проводились (целевая оценка 3); уровни 4/5 с нагрузочными сериями и сравнением 1/2/4 реплик не заявлены. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | Останов одной API-реплики hook'ом | LB направляет запросы на оставшуюся реплику; данные и сессия сохраняются | 2 реплики до отказа, 106 успешных записей во время отказа, 2 переходные ошибки, все подтверждённые сообщения на месте, дублей нет | первая успешная запись через 0.608 с; потерь данных 0 | | Перезапуск `db` + `api1` + `api2` с volume | данные, сессии и ledger остаются | PASS; миграции не применялись повторно | automatic ready wait; потерь данных 0 | ## Ограничения и следующие шаги - Уровень 4 не реализован: нет CPU/RAM-лимитов, sequnential отказа каждой реплики под нагрузкой, rolling update и автоматической проверки исключения недоступного backend по healthcheck (nginx использует пассивный `max_fails`/`fail_timeout`). - PostgreSQL остаётся единственной точкой отказа стенда; отказ узла БД не моделируется и не заявляется. - Nginx — единственный LB; при его отказе доступ прекращается (SPOF). - HTTP допустим только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS.