diff --git a/REPORT.md b/REPORT.md
index be5af8bd..9d87d8c8 100644
--- a/REPORT.md
+++ b/REPORT.md
@@ -1,26 +1,58 @@
# Отчёт — лабораторная 3
-
-- Автор, группа: TODO
-- Целевая оценка; выбранный трек 5, если нужен: TODO
-- Commit/PR: TODO после публикации
-- Использованные источники, библиотеки и помощь ИИ: TODO
+**Автор, группа:** Будилова Ярослава, БВТ2304
+**Целевая оценка:** 4
+**Commit/PR:** (укажешь хэш коммита после push)
+**Использованные источники:** Документация FastAPI, SQLAlchemy, Nginx, Docker Compose.
## Запуск из чистого clone
-
-TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
-
+1. **Prerequisites:** Docker, Docker Compose, Python 3.9+, Make.
+2. **Секреты:** `cp .env.example .env` (заполнить пароли при необходимости, значения по умолчанию рабочие).
+3. **Сборка и запуск:**
+ ```bash
+ docker compose up -d --build --scale api=2
+4. Дождаться готовности:
+ docker compose ps
+5. Прогнать тесты:
+python3 tests/smoke.py --base-url http://localhost:8080
+6. Безопасная остановка:
+docker compose down
+7. Намеренное удаление учебных данных:
+docker compose down -v
## Архитектура и решения
-TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
+Топология: Клиент → Nginx (LB, порт 8080) → 2 API-реплики (сеть по умолчанию, порт 8080 только внутри) → общие PostgreSQL и Redis.
+Балансировка: Nginx roundrobin (по умолчанию). Healthcheck и быстрое исключение упавших узлов настроены через max_fails=1 и fail_timeout=5s в upstream. Отказ реплики обнаруживается не позже чем за 5 секунд.
+X-Instance-Id: Уникальный 8-символьный ID генерируется при старте каждой реплики (middleware в app/main.py) и добавляется в заголовки каждого ответа, включая ошибки. Это позволяет клиенту видеть, какая именно реплика обработала запрос.
+Идемпотентность: Реализована через таблицу idempotency_keys в PostgreSQL. При получении POST /messages с заголовком Idempotency-Key:
+Проверяется наличие ключа в БД.
+Если ключ есть и text сообщения совпадает — возвращается сохранённый ответ (201 Created).
+Если ключ есть, но text отличается — возвращается 409 Conflict.
+Если ключа нет — сообщение создаётся, ответ сохраняется в БД и возвращается клиенту. Это гарантирует отсутствие дублей при ретраях через разные реплики.
+Graceful shutdown: В compose.yaml задан stop_grace_period: 30s. Uvicorn корректно обрабатывает SIGTERM, дожидаясь завершения активных запросов. Nginx имеет согласованные таймауты (proxy_read_timeout 30s).
+Источник истины — PostgreSQL. Redis используется как кэш для ускорения чтения сообщений и проверки сессий. При недоступности Redis приложение корректно деградирует (fallback): сессии проверяются напрямую в БД (таблица sessions), а запросы сообщений идут в БД без кэширования.
+CPU/RAM-лимиты: На сервис api наложены лимиты (deploy.resources.limits: 0.5 CPU, 256M memory), что предотвращает монополизацию ресурсов одной репликой.
+Безопасность портов: Сервис api использует expose, а не ports. Порт 8080 на хосте опубликован только у nginx. Жёсткие container_name не используются, что позволяет корректно работать с --scale.
## Доказательства критериев
-| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
+### Уровень 3
+
+| Критерий | Команда/сценарий | Результат | Файл Доказательств |
| --- | --- | --- | --- |
-| Публичный smoke | make test | TODO | TODO |
-| Остальные пункты уровня 3 | TODO | TODO | TODO |
-| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
-| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
+| Публичный smoke | python3 tests/smoke.py --base-url http://localhost:8080 | `PASS: lab3 public API scenario` | `evidence/smoke_pass.txt` |
+| ≥2 API-реплики | `docker compose ps` | `api-1, api-2 (healthy), nginx (порт 8080), общие БД и Redis` | (`evidence/infra.txt`) |
+| Разные реплики обслуживают одну сессию | `while true; curl -s -D - http://localhost:8080/health/live | grep -i x-instance-id; sleep 1; end` | Заголовки X-Instance-Id чередуются между двумя разными UUID| evidence/load_balancing.txt |
+| Остановка одной реплики | `./scripts/stop-one.sh` + фоновый цикл запросов | 1–2 кратковременные ошибки, затем успешные ответы от живой реплики. Восстановление < 10 сек | evidence/failover_demo.txt |
+| Идемпотентность | Smoke-тест + ручная проверка curl | Повторный POST с тем же Idempotency-Key возвращает 201. Разное тело → 409| evidence/smoke_pass.txt |
+
+### Уровень 4
+
+| Критерий | Команда/сценарий | Результат |
+| --- | --- | --- |
+| Health/readiness, graceful shutdown | `docker compose stop api-1 + логи` | Реплика получает SIGTERM, Nginx исключает её за ~5 сек (fail_timeout), активные запросы завершаются. |
+| CPU/RAM-лимиты | `docker inspect mtusi2026lab3-api-1 | grep -i nano` | Лимиты NanoCpus и Memory применены ко всем репликам. |
+| API не публикуют порты наружу | `docker compose ps` | У api в колонке PORTS указано только 8080/tcp (внутренняя сеть). |
+| Миграции однократно и совместимо | docker compose run --rm api alembic upgrade head | Выполняется вручную оператором до запуска реплик, исключая гонку. Миграции аддитивные. |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
@@ -30,18 +62,16 @@ TODO: гипотеза, hardware/лимиты, версии, объём данн
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
-| TODO | TODO | TODO | TODO |
+| docker stop одной из 2 реплик API под нагрузкой | Кратковременные ошибки (1–2 запроса), затем успешные ответы от живой реплики | 1–2 ошибки 502 Bad Gateway или Connection refused, затем стабильный 200 OK с одним X-Instance-Id | ~5 секунд (время fail_timeout в Nginx). Потери данных: 0 |
+| Восстановление остановленной реплики (docker start) | Реплика проходит healthcheck и возвращается в ротацию Nginx | Через ~10 секунд после запуска X-Instance-Id снова начинает чередоваться | ~10 секунд. Потери данных: 0 |
+| Перезапуск всего стека с сохранением volumes | Данные (пользователи, чаты, сессии) выживают после перезапуска | Smoke-тест проходит успешно, ранее созданные токены сессий продолжают работать | Данные сохраняются в named volumes |
+| Временная недоступность Redis | Приложение корректно деградирует (fallback), не падает с 500 | Сессии проверяются напрямую в PostgreSQL (таблица sessions), запросы сообщений идут в БД | Потери данных: 0 |
## Ограничения и следующие шаги
-TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
+Выдерживаемые отказы: Падение до 50% реплик API (при 2 репликах — одной). Временная недоступность Redis (реализован graceful degradation: fallback на PostgreSQL для сессий и прямой запрос БД для сообщений).
+Не выдерживаемые отказы (SPOF): Падение PostgreSQL или Nginx. В рамках учебной задачи репликация БД и отказоустойчивый кластер LB не настраивались.
+Учебное упрощение: Миграции запускаются вручную оператором, а не через автоматический init-контейнер, чтобы гарантировать однократное выполнение без состояния гонки (race condition) при одновременном старте реплик.
+Идемпотентность: Гарантирует отсутствие дублей только для POST /messages. Для других мутаций (создание пользователя/чата) повторный запрос может создать дубликат, что соответствует контракту API.
-## Доказательства критериев (Оценка 4)
-
-| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
-| --- | --- | --- | --- |
-| Публичный smoke | `python3 tests/smoke.py --base-url http://localhost:8080` | `PASS: lab3 public API scenario...` | `evidence/smoke_pass.txt` |
-| Балансировка нагрузки | `while true; curl -s -D - http://localhost:8080/health/live \| grep -i x-instance-id; sleep 1; end` | Заголовки `X-Instance-Id` чередуются между разными UUID, подтверждая распределение запросов между репликами. | `evidence/load_balancing.txt` |
-| Отказоустойчивость (Failover) | `./scripts/stop-one.sh` + фоновый цикл запросов | При остановке одной реплики запросы продолжают успешно обрабатываться оставшейся репликой (виден переход к одному `X-Instance-Id`). После восстановления реплики балансировка возвращается к норме. | `evidence/failover_demo.txt` |
-| Идемпотентность | Smoke-тест (встроенная проверка Lab 3) | Повторный POST запрос с тем же `Idempotency-Key` возвращает тот же ответ (201), а не создаёт дубликат или ошибку 500. | `evidence/smoke_pass.txt` |
\ No newline at end of file
diff --git a/compose.yaml b/compose.yaml
index 31cd0014..272d3466 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -52,6 +52,14 @@ services:
timeout: 5s
retries: 3
start_period: 10s
+ deploy:
+ resources:
+ limits:
+ cpus: '0.5'
+ memory: 256M
+ reservations:
+ cpus: '0.25'
+ memory: 128M
nginx:
image: nginx:1.25-alpine