# Отчёт — лабораторная 3 - Автор, группа: TODO (заполнить перед PR) - Целевая оценка: **3 — работающий минимум**. Уровень 4 и трек 5 не заявлены. - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: `contracts/openapi.json`, `contracts/README.md`, `README.md`, публичные тесты `tests/`; FastAPI 0.115.0, uvicorn 0.30.6, psycopg 3.2.3, psycopg-pool 3.3.3, PostgreSQL 16.4, Nginx 1.26.2. Реализация и текст отчёта подготовлены с помощью ИИ-ассистента Koda; все приведённые проверки выполнены и воспроизведены локально. ## Запуск из чистого clone Проверено на: Windows 11 Pro 22621 x64, AMD Ryzen 7 7700 (8 ядер / 16 потоков), 32 GB RAM, Docker Engine 29.4.3, Docker Compose v5.1.3 (Linux containers), Python 3.10.11 для публичных тестов. Дата прогонов: 2026-11-07. Версии зафиксированы: `python:3.12.6-slim-bookworm`, `postgres:16.4-alpine`, `nginx:1.26.2-alpine`; Python-зависимости — в `requirements.txt`. ```sh # 1. Локальная конфигурация (значения в примере синтетические, .env не коммитится) cp .env.example .env # 2. Проверка и сборка/запуск всего стенда docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build # 3. Ожидание готовности (миграции выполняются автоматически отдельным сервисом) curl -fsS http://localhost:8080/health/ready # 4. Проверки make check make test BASE_URL=http://localhost:8080 make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh # 5. Восстановление остановленной в failover реплики (api1 или api2) docker compose --env-file .env start api1 docker compose --env-file .env restart lb # 6. Штатная остановка без удаления данных docker compose --env-file .env down # 7. Намеренное удаление учебных данных и volumes (необратимо) docker compose --env-file .env down -v ``` На Windows-хосте `make` не установлен, поэтому вместо целей Makefile выполнены те же команды напрямую: `python scripts/check_contract.py`, `python tests/smoke.py --base-url http://localhost:8080`, `python tests/resilience.py --mode persistence|failover --action-script ...`. Скрипты `restart.sh`/`stop-one.sh` — POSIX shell, поэтому resilience-тесты запускались в Linux-контейнере `docker:27-cli` с смонтированным репозиторием и Docker-сокетом: ```sh docker run --rm --network mtusi-lab3_appnet \ -v ":/repo" -v /var/run/docker.sock:/var/run/docker.sock \ -w /repo -e PYTHONUTF8=1 docker:27-cli \ sh -lc "apk add --no-cache python3 >/dev/null && \ python3 tests/resilience.py --mode failover \ --action-script scripts/stop-one.sh --base-url http://lb:8080" ``` На Linux/macOS те же проверки запускаются обычными командами Makefile из блока выше. ## Архитектура и решения ```text клиент | v lb (nginx :8080) — единственный опубликованный порт | round-robin, passive health, retry на вторую реплику +--> api1 (uvicorn :8080, INSTANCE_ID=api-1) --+ +--> api2 (uvicorn :8080, INSTANCE_ID=api-2) --+ v postgres:16.4 (volume pgdata) users, chats, chat_members, messages, sessions, idempotency_keys ``` - **Источник истины — PostgreSQL.** В API нет локальных сессий, сообщений или идемпотентных ключей. Единственное локальное состояние процесса — стабильный `X-Instance-Id` (`api-1`/`api-2`) из переменной окружения. - **Реплики взаимозаменяемы.** `api1` и `api2` собираются из одного Dockerfile и образа, не публикуют порты наружу, имеют одинаковый `DATABASE_URL`. Клиент ходит только через `lb`. - **Балансировщик.** Nginx upstream `api1:8080`, `api2:8080`, `max_fails=1 fail_timeout=5s`, `proxy_connect_timeout 1s`, `proxy_read_timeout 10s`. `proxy_next_upstream ... non_idempotent` повторяет POST на второй реплике; это безопасно, потому что создание сообщения идемпотентно по `Idempotency-Key`. - **Миграции отдельно.** Сервис `migrate` запускается один раз, ждёт готовности PostgreSQL, берёт advisory lock, применяет идемпотентный `migrations/001_init.sql` и завершается с кодом 0. Реплики стартуют только после `service_completed_successfully`, поэтому гонки DDL между ними нет. - **Graceful shutdown.** Uvicorn — PID 1, получает SIGTERM, перестаёт принимать соединения и до 5 с завершает текущие запросы (`--timeout-graceful-shutdown 5`), `stop_grace_period: 10s`. Nginx в это время повторяет запрос на живую реплику. - **Сессии.** Basic используется только в `POST /api/v1/auth/sessions`. Токен — `secrets.token_urlsafe(48)` (384 бита), в БД хранится только SHA-256 токена и `expires_at`; TTL из `SESSION_TTL_SECONDS` (по умолчанию 3600). Перезапуск не продлевает TTL. - **Пароли.** `hashlib.scrypt` (N=2^14, r=8, p=1, 32-байтовый digest, случайная соль), не SHA-256 и не plaintext. - **Транзакционные границы.** Регистрация — один INSERT с уникальным `username`. Создание чата — чат и все `chat_members` в одной транзакции после проверки существования участников. Отправка сообщения — проверка членства, вставка/чтение `idempotency_keys`, вставка `messages` и запись сохранённого ответа в одной транзакции. - **Идемпотентность.** Первичный ключ `(user_id, method, path, key)`; `INSERT ... ON CONFLICT DO NOTHING` определяет владельца, конкурентный запрос ждёт завершения транзакции владельца и читает сохранённый ответ. Хранится канонический хеш тела: другой JSON при том же ключе — `409`, тот же JSON — исходный `201` и то же сообщение. Срок хранения — `IDEMPOTENCY_TTL_SECONDS` (24 ч). - **История.** Keyset-пагинация по `(created_at, id)` по возрастанию, `limit` 1–100 (по умолчанию 50), непрозрачный base64-cursor со scope. Cursor от другого чата/коллекции — `400`; последний элемент страницы не повторяется; `next_cursor=null`, если следующей записи нет. - **Ошибки.** Единый конверт `{"error":{"code","message","request_id"}}`, `X-Request-Id` совпадает с телом, `X-Instance-Id` добавляется middleware ко всем ответам API, включая ошибки и health. - **Перенос из lab2.** В этом репозитории нет кода lab2, поэтому обязательные возможности lab2 (PostgreSQL, регистрация с паролем, Basic → Bearer-сессия, миграции, сохранность) реализованы здесь же. In-memory fallback отсутствует. Соответствие `.env.example` реальной конфигурации: | Переменная | Где используется | Смысл | | --- | --- | --- | | `APP_HOST`, `APP_PORT`, `APP_ENV` | compose | информационные параметры стенда | | `SESSION_TTL_SECONDS` | API | TTL сессии, по умолчанию 3600 | | `IDEMPOTENCY_TTL_SECONDS` | API | срок хранения результата, по умолчанию 86400 | | `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` | compose → `DATABASE_URL` | общая БД; пароль в примере синтетический | | `DATABASE_URL` / `DATABASE_URL_FILE` | API, migrate | альтернативные способы передать строку подключения | | `API_REPLICAS` | документация | фактическое число реплик задано сервисами `api1`/`api2` | ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Офлайн-структура и контракт | `python scripts/check_contract.py` (эквивалент `make check`) | `PASS: offline skeleton structure...` | `evidence/check.txt` | | Compose-стенд описан и валиден | `docker compose --env-file .env config --quiet` | код 0, ошибок нет | вывод в отчёте, `compose.yaml` | | Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` (эквивалент `make test`) | `PASS: lab3 public API scenario` | `evidence/smoke-final.txt`, `evidence/smoke.txt` | | ≥2 API-реплики, одна точка входа, общая БД | `docker compose ps`; 10 запросов `/health/live` | `api1`/`api2` healthy; опубликован только `lb` 8080; `postgres` healthy | `evidence/instances.txt`, `evidence/final-ps.txt` | | Одна сессия обслуживается разными репликами без повторного входа | `python student-tests/session_across_replicas.py` | 12 запросов с одним Bearer: `api-1, api-2, api-1, api-2, ...` | `evidence/session-across-replicas.txt` | | Остановка одной реплики: чтение/запись продолжаются | failover-тест, цель `api-1` | 85 успешных записей, 0 ошибок, первое восстановление 0.558 с (в повторных прогонах 0.65–1.43 с); `api1` — `Exited (0)`, `api2` работает | `evidence/failover-final.txt`, `evidence/failover-final-ps.txt` | | Остановка второй реплики | failover-тест, цель `api-2` | 90 успешных записей, 0 ошибок, восстановление 0.546 с; `api2` — `Exited (0)`, `api1` работает | `evidence/failover-final-2.txt`, `evidence/failover-final-2-ps.txt` | | Подтверждённые сообщения доступны после отказа, дублей нет | тот же failover-тест | тест читает всю историю, проверяет исходное сообщение, все подтверждённые записи и уникальность текстов | `evidence/failover-final.txt` | | Последовательный повтор `Idempotency-Key` | публичный smoke | повтор возвращает то же сообщение; другой body — `409`; без ключа — `400` | `evidence/smoke-final.txt` | | Конкурентный повтор через разные реплики | `python student-tests/concurrent_idempotency.py` | 40 одновременных POST с одним ключом: реплики `api-1` и `api-2`, ровно 1 сообщение, другой body — `409` | `evidence/concurrent-idempotency.txt` | | Сохранность данных и сессии после перезапуска | persistence-тест + `scripts/restart.sh` | `PASS`; прежний токен и данные доступны без повторного входа; в БД после всех прогонов 40 пользователей, 13 чатов, 4171 сообщение, 37 сессий | `evidence/persistence-final.txt`, `evidence/db-counts.txt` | | Hook действительно перезапустил хранилища | `docker inspect` до/после `scripts/restart.sh` | у `postgres`, `api1`, `api2`, `lb` изменился `State.StartedAt` | `evidence/restart-scope.txt` | | Health/readiness | `curl /health/ready` | `{"status":"ok"}`; readiness проверяет `SELECT 1` к PostgreSQL | `evidence/instances.txt` | | Миграции не гоняются репликами | `docker compose ps -a` | `migrate` завершился `Exited (0)` до старта API | `evidence/failover-final-ps.txt` | | Версии образов/зависимостей зафиксированы | `Dockerfile`, `compose.yaml`, `requirements.txt` | явные теги/пины, без `latest` | файлы репозитория | | Нагрузочный профиль (дополнительно) | `python tests/load.py --duration 15 --concurrency 4` | 3722 успешных запроса, 0 ошибок, 247.6 RPS, p50/p95/p99 = 16/32/46 мс | `evidence/load.txt`, `evidence/load.json` | ## Эксперименты и отказы Условия: один Docker-host, сервисные лимиты `api` 1 CPU / 256 MB, `postgres` 1 CPU / 512 MB, `lb` 0.5 CPU / 128 MB. Все запросы идут через `http://localhost:8080` (nginx). Данные синтетические. | Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | `stop api1` во время 15-секундной серии POST | Записи продолжаются через `api2`, подтверждённые сообщения не теряются | 85 успешных записей, 0 неудачных попыток; `api1` остановлен (`Exited (0)`), `api2` healthy | первое восстановление 0.558 с; потерь и дублей нет | | `stop api2` во время такой же серии | То же через `api1` | 90 успешных записей, 0 неудачных; `api2` остановлен, `api1` healthy | 0.546 с; потерь и дублей нет | | 40 одновременных POST с одним `Idempotency-Key` | Ровно одно сообщение, одинаковые ответы | Оба экземпляра обслужили запросы, все ответы совпали, в истории 1 копия; другой body — `409` | потерь нет | | `scripts/restart.sh`: рестарт PostgreSQL, api1, api2, lb | Данные, сессии и схема сохраняются | Persistence-тест `PASS`; у всех четырёх контейнеров новый `StartedAt` | сессия и сообщения доступны без повторного входа | | Пересборка образа и `up -d --build` | Сессии/сообщения не зависят от жизни процесса | Smoke после пересборки `PASS`; в PostgreSQL сохранились 40 пользователей, 13 чатов, 4171 сообщение и 37 сессий | потерь нет | Нагрузочный прогон: 15 с, concurrency 4, closed-loop генератор `tests/load.py` без автоматических retry. Получено 3722 успешных POST, 0 ошибок, 247.6 успешных RPS, p50 16 мс, p95 32 мс, p99 46 мс. Это throughput HTTP-подтверждений через LB, а не точный счётчик COMMIT; генератор ограничен клиентом, страдает coordinated omission, а latency посчитана только по успешным запросам. CPU/RAM контейнеров в этом прогоне не сэмплировались, поэтому цифры не заявляются как saturation point. ## Ограничения и следующие шаги - Стенд работает на одном Docker-host. Потеря узла, а также отказ единственных PostgreSQL и nginx не выдерживаются: они остаются SPOF. Проверен только отказ одного API-процесса. - Nginx разрешает имена `api1`/`api2` при старте. После восстановления остановленной реплики надёжный способ вернуть её в балансировку — `docker compose start apiN` и `docker compose restart lb`; в проверенных прогонах Docker переиспользовал IP, но на это не следует опираться. Следующий шаг — динамический resolver/`resolve` в upstream. - После восстановления реплика возвращается в балансировку не мгновенно: если первый запрос к ней попал в момент старта, nginx держит её вне пула до `fail_timeout=5s`. Это наблюдалось один раз сразу после `restart lb`; в рабочий период оба экземпляра получают запросы. Поэтому `student-tests/session_across_replicas.py` сначала ждёт появления обоих экземпляров, а затем проверяет одну сессию. - Сессии и идемпотентные ключи хранятся в PostgreSQL; Redis/Valkey не используется. Это соответствует контракту lab3, но увеличивает нагрузку на БД. - Просроченные идемпотентные ключи удаляются лениво — при повторном использовании ключа; фоновой очистки нет. - Не реализованы TLS, rate limiting, вложения, фоновая обработка, телеметрия — это следующие лабораторные, для оценки 3 они не требуются. - Уровень 4 (поочерёдная остановка всех реплик с метриками RPS/ошибок, rolling update под нагрузкой, CPU/RAM-лимиты как проверяемый критерий) и трек 5 не заявляются. Лимиты ресурсов в compose заданы, но измерение saturation и сравнение 1/2/4 реплик не проводилось. - На Windows-хосте отсутствует `make`, поэтому публичные цели запускались эквивалентными командами; на Linux/macOS команды Makefile применимы без изменений.