Files
mtusi2026lab3/REPORT.md
T

94 lines
8.7 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
- Целевая оценка; выбранный трек 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 <url-вашего-fork> && 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.