# Отчёт — лабораторная 3 - Автор, группа: Унру Д.В. БПИ2303 - Целевая оценка; выбранный трек 5, если нужен: **3** (трек 5 не заявлен) - Commit/PR: TODO после публикации - Использованные источники, библиотеки и помощь ИИ: FastAPI, Pydantic v2, Uvicorn, Psycopg 3, redis-py, argon2-cffi, pytest; документация [Nginx load balancing](https://nginx.org/en/docs/http/load_balancing.html), [upstream/resolve](https://nginx.org/en/docs/http/ngx_http_upstream_module.html) и [proxy_next_upstream](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream), [Docker Compose services](https://docs.docker.com/reference/compose-file/services/), [PostgreSQL transactions](https://www.postgresql.org/docs/17/tutorial-transactions.html). ## Запуск из чистого clone ```sh git clone && cd <каталог-fork-лабораторной-3> make up # secrets/.env → build API → migrate → api×2 → LB → дождаться 2 alias curl -fsS http://localhost:8080/health/ready docker compose ps # две API-реплики, postgres, redis, lb — healthy; migrate — Exited(0) make check make validate-container # полный валидатор OpenAPI без локальных pip-зависимостей make test # публичный smoke через LB make test-student # собственные интеграционные тесты: 14 make test-fresh # обе миграции и 14 тестов на отдельных пустых volumes make test-cluster # все распределённые проверки, включая реальные отказы и rolling make load-evidence # отдельные 30 с нагрузки и CPU/RAM ``` Эквивалент `make up`: `./scripts/bootstrap.sh`, `docker compose build api`, `docker compose up -d --wait --wait-timeout 120`, `python3 scripts/cluster.py wait`. Образ собирается до запуска migrate, поэтому готовый сервер из registry не требуется. Хосту доступен только LB `127.0.0.1:8080`; API и хранилища напрямую не опубликованы. Отдельные публичные проверки: ```sh make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Публичный failover намеренно оставляет одну выбранную реплику остановленной. # Восстановление: docker compose up -d --no-recreate --wait --wait-timeout 90 python3 scripts/cluster.py wait ``` `make verify-persistence` дополнительно сохраняет снимки реальных контейнеров до/после. `make verify-failover` выполняет публичный failover и последовательные проверки каждого исходного контейнера, с восстановлением между ними. Полный `make test-cluster` последовательно запускает concurrent replay, persistence, публичный и собственные failover, SIGTERM, rolling, отказы Redis/БД и аудит инфраструктуры. Он меняет состояние стенда и собирает новый локальный образ с новым идентификатором релиза; не запускать параллельно с другими проверками. `bootstrap.sh` создаёт случайный пароль PostgreSQL и файлы secrets один раз; существующие значения не меняет. Каталог `secrets/` — 0700 на хосте, файлы доступны uid 10001 контейнера через Compose secrets; `.env` и secrets исключены из Git и Docker build context. Для lab3 созданы собственные secrets/volumes, данные и credentials lab2 не копировались. Безопасная остановка: `make down` — контейнеры и сети удаляются, именованные volumes сохраняются. После `make up` доступны прежние данные, действующие сессии и результаты идемпотентности. Намеренное удаление всех учебных данных: `docker compose down --volumes`. Hook `restart.sh` volumes не удаляет. `make test-fresh` удаляет только созданные им временные volumes отдельного проекта. Синтетические данные обычных тестов остаются в основной БД. ## Архитектура и решения ```text ┌──► API-процесс A ──┐ клиент ──HTTP──► Nginx ──┤ ├──► PostgreSQL: данные, сессии, результаты POST 127.0.0.1:8080 └──► API-процесс B ──┤ └──► Redis: кэш публичного профиля migrate ──► PostgreSQL (один отдельный job до запуска API) ``` - **Перенос из lab2.** Перенесены исходники FastAPI, миграция 001, Argon2id/Basic/Bearer, users/chats/messages, keyset-пагинация, Redis cache-aside профиля, ограниченные пулы и собственные проверки. Отправка сообщений и тесты адаптированы к обязательному Idempotency-Key. Dockerfile/Compose изменены для отдельных миграций, нескольких API и LB. Публичные `tests/`, `contracts/`, README и COURSE сохранены из skeleton lab3. - **Общее состояние.** PostgreSQL — источник истины для пользователей, чатов, участников, сообщений, сессий и результатов POST. API не держит в локальной памяти данных, от которых зависит корректность. Каждое защищённое обращение проверяет сессию в БД; X-User-Id игнорируется. Разные реплики обслуживают один Bearer без повторного входа. Sticky session не используется. - **Идентификатор процесса.** `X-Instance-Id` — случайный UUID alias, стабильный для жизни конкретного процесса; добавляется ко всем его ответам, включая health/ошибки. После restart alias меняется. `X-App-Release` — дополнительный заголовок для различения сборок в rolling-эксперименте. Ошибка, сформированная самим LB при недоступных backend, может не иметь API-заголовков и JSON. - **Общая идемпотентность** (`src/messenger/messages.py`, миграция 002). Таблица `idempotency_records`: PK(user_id,chat_id,key), request_hash, message_id FK, expires_at. Таблица обслуживает только POST сообщений, поэтому эта область соответствует user+method+chat path+key. Ключ строго ASCII `[A-Za-z0-9._:-]{1, 128}`, иначе 400. Валидированный JSON канонизируется независимо от форматирования/порядка полей, fingerprint — SHA-256. В схеме lab3 допустим только text; attachment_ids появится по контракту lab4. - **Атомарность повтора.** После проверки сессии и членства одна транзакция выполняет INSERT ключа ON CONFLICT DO NOTHING и SELECT FOR UPDATE. Конкурирующие процессы сериализуются на одной записи. При действующем ключе тот же fingerprint возвращает тот же Message и 201, другой — 409. Для нового/истёкшего ключа INSERT сообщения и обновление результата фиксируются одним COMMIT. Исключение откатывает оба эффекта, транзиентный 5xx не сохраняется как результат. Replay снова проверяет авторизацию. Срок ключа — 24 ч; после истечения разрешена новая запись с тем же ключом, старое сообщение не удаляется. - **Миграции.** `migrate` — отдельный одноразовый service, API зависит от `service_completed_successfully`. В API CMD мигратора нет. SQL-файлы 001/002, checksum и advisory lock сохраняют повторяемость и сериализуют возможные ручные запуски. Новая 002 только добавляет таблицу/индекс, не меняет старые поля lab2. Перед rolling один раз выполняется `docker compose run --rm --no-deps migrate`, пока старые API продолжают работу. - **Балансировка и DNS.** Nginx OSS 1.28: `upstream messenger` с общей `zone messenger 64k` и `server api:8080 resolve`. Все A-записи одного Compose-service api участвуют в round-robin; `resolver 127.0.0.11 valid=1s ipv6=off` обновляет IP без restart/reload Nginx. Адреса не зашиты в конфигурации. - **Пассивные проверки upstream.** `max_fails=1 fail_timeout=2s`: первая ошибка подключения/таймаут/503 исключает адрес на 2 с, затем допускается новая попытка. Активного `health_check` Nginx Plus здесь нет. Docker healthcheck каждого API раз в 2 с вызывает его readiness; healthcheck LB раз в 1 с делает GET readiness через Nginx и создаёт фоновый трафик даже без клиента. При двух backend, работающем Docker DNS и настроенных таймаутах консервативный бюджет обнаружения — до 8 с; фактические чтения/записи после отказа проверяются в пределах 10 с. В отличие от активного мониторинга, пассивное исключение происходит только после обращения к backend. - **Таймауты и повтор.** Nginx connect 1 с, read/send 5 с; `proxy_next_upstream error timeout http_503`, не более 2 upstream-попыток и 6 с на переключение. GET может уйти на другую реплику при ошибке. Параметр `non_idempotent` не включён: уже отправленный POST автоматически не пересылается; при connect error до отправки запроса допустим безопасный выбор другого адреса. Неопределённую отправку сообщения повторяет клиент с прежним Idempotency-Key. - **Readiness и graceful.** `/health/live` проверяет процесс; `/health/ready` требует доступную PostgreSQL и таблицу новой схемы. Несовместимая схема/ошибка зависимости →503. Redis — некритичный кэш с fallback, его отказ readiness не меняет. Uvicorn работает PID1, один worker на контейнер, graceful timeout5 с. Docker stop_grace_period10 с; hook stop-one использует 7 с, укладываясь в публичный бюджет 10 с. SIGTERM закрывает listening socket и даёт активным запросам завершиться. - **Остановка выбранной реплики.** `scripts/stop-one.sh` — короткий wrapper Python-оркестратора `cluster.py`. Тот сопоставляет TARGET_INSTANCE_ID с реальным контейнером внутренним GET /health/live, останавливает ровно его, проверяет exit 0 и оставляет остановленным. Идентификаторы контейнеров/процессов и время записываются без credentials. `restart.sh` перезапускает все API, PostgreSQL, Redis и LB с прежними volumes. - **Поочерёдная замена.** Compose не предоставляет здесь автоматический Swarm rolling update. Проверен эквивалент start-first: временно scale api=3 с `--no-recreate`, дождаться новой healthy-реплики и трёх alias через LB, затем stop/remove одного старого контейнера и возврат к 2. Второй старый контейнер в этом шаге не пересоздаётся. Создание до удаления старого гарантирует другой IP; оба адреса сохраняются. Шаг повторяется для второго исходного контейнера. - **Пароли, сессии, кэш.** Argon2id (19456 KiB, time_cost2, parallelism1), opaque token256 бит, в БД только SHA-256 токена и абсолютный expiry; logout удаляет сессию. Redis хранит только User по `user:` на 60 с после проверки сессии. Профиль неизменяем в обязательном API, инвалидация по событию не нужна. История читается из PostgreSQL и не бывает устаревшей из-за кэша. - **Запросы/ошибки.** SQL параметризован; каждый API-пул min 1/max 8, очередь 16, ожидание 2 с, connect_timeout3 с, statement_timeout3 с, lock_timeout2 с. Redis-пул 8, connect/read по 0.2 с без retry. JSON строго UTF-8, неверные типы/поля/формат →400, неподдерживаемый media type →415; чужие чаты →404. X-Request-Id совпадает с request_id ошибки. Access-лог Uvicorn отключён, тела/токены/SQL в логи не выводятся. Конфигурация и ресурсы: | Переменная / service | Значение | Использование | | --- | --- | --- | | `SESSION_TTL_SECONDS` (.env) | 3600 по умолчанию | абсолютный срок сессии, в собственном тесте expiry — 2 с | | `DATABASE_URL_FILE` | `/run/secrets/database_url` | API и migrate читают адрес/credentials БД | | `CACHE_URL_FILE` | `/run/secrets/cache_url` | только API читает адрес Redis | | `POOL_MAX_SIZE` | 8 на API-процесс | ограничение числа соединений | | `api` | `mtusi-lab3-api:lab3`; каждая 0.75 CPU / 384 MiB | один scale-able service, штатно 2 реплики, без container_name и host ports; сети front+data | | `lb` | `nginx:1.28.0-alpine`; 0.5 CPU / 128 MiB | единственный публичный порт 127.0.0.1:8080; только front, без DB secrets | | `postgres` | `postgres:17.5-bookworm`; 1 CPU / 512 MiB | только internal data; volume postgres_data; pg_isready | | `redis` | `redis:7.4.4-bookworm`; 0.25 CPU / 128 MiB | только internal data; volume redis_data; AOF; maxmemory64 MiB/allkeys-lru | | `migrate` | тот же образ API; 0.5 CPU / 256 MiB | только data, только database_url secret; Exited(0) после применения | Dockerfile: `python:3.13.5-slim`, полностью закреплённые зависимости в `requirements.lock`, пользователь messenger uid 10001. Установка зависимостей предшествует копированию исходников; ARG APP_RELEASE расположен после этих слоёв, поэтому смена только метки релиза не переустанавливает библиотеки. CMD — exec Uvicorn. Healthchecks задаются Compose; `.dockerignore` исключает Git, secrets/.env, сертификаты, volumes и evidence. Публичные и собственные проверки включены в образ для запуска без pip на хосте. Номера контейнеров после замен могут иметь пропуски: `cluster.py exec` выбирает реально живой контейнер, не предполагает существование api-1. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Nginx, конфигурация и две реплики | `verify_cluster.py nginx` | `nginx -t` PASS, Server:nginx, два alias через LB | `evidence/nginx.json` | | Контракт и публичный smoke (3) | `make check`, `make validate-container`, `make test` | PASS, lab3 public API scenario через LB | `evidence/check.txt`, `openapi.txt`, `smoke.txt` | | ≥2 API, один LB, общая БД и сессии (3) | `cluster.py wait`; concurrent replay; infrastructure | один Bearer работает на разных alias; реально два API-контейнера, порты только у LB | `evidence/concurrent-idempotency.json`, `infrastructure.json` | | Отказ любой одной реплики, чтение/запись ≤10 с (3) | публичный failover + остановка каждого исходного контейнера | оба сценария PASS; чтение известного сообщения, пока target ещё остановлен; post-stop POST в пределах 10 с | `evidence/public-failover.txt`, `sequential-failover.json` | | Общая идемпотентность и отсутствие дублей (3) | 8 параллельных повторов через 2 alias | все 201 с одним Message, в истории 1 сообщение; другой body409 | `evidence/concurrent-idempotency.json` | | Сохранность и прежняя сессия (3) | `make verify-persistence` | API/БД/Redis/LB действительно перезапущены; volumes те же; прежний токен и данные доступны | `evidence/persistence.txt`, `persistence.json` | | Обязательные key/alias, TTL 24 ч, scope, rollback, повторная авторизация | `make test-student` | 14/14 PASS, включая отказ после INSERT и rollback ключа+сообщения | `evidence/student-tests.txt` | | Миграции отдельно, с нуля и повторяемо | `make test-fresh`; migration test | применены 001/002, повтор без дублей, 14/14 PASS на новых volumes | `evidence/fresh-migrations.txt` | | Health/readiness/timeouts/SIGTERM (4) | Nginx config; test_ready_requires_compatible_schema; SIGTERM с активным POST | схема недоступна→503; активный POST 201, новые TCP отвергнуты пока процесс ещё жив, exit 0 за 1.9171 с | `evidence/student-tests.txt`, `graceful-shutdown.json` | | Последовательно остановлена каждая реплика, RPS/errors/recovery (4) | `verify_cluster.py failover` | два разных исходных container id; предыдущий восстановлен; подтверждения сохранены без дублей | `evidence/sequential-failover.json` | | CPU/RAM, нет API host ports/container_name (4) | `verify_cluster.py infra`; реальное scale 2→3→2 | лимиты есть у всех сервисов, единственный public endpoint у LB, api масштабируется | `evidence/infrastructure.json`, `rolling-update.json` | | Rolling-equivalent под нагрузкой, отдельные совместимые миграции (4) | `verify_cluster.py rolling` | два старых контейнера заменены новым образом, оба новых IP обнаружены LB; 14 975 подтверждённых сообщений сохранены | `evidence/rolling-update.json` | | Предыдущая авторизация и отказ зависимостей сохранены | `verify_cluster.py dependencies`; собственные auth/expiry tests | Redis fallback200; PostgreSQL 503; после восстановления тот же токен работает | `evidence/dependency-failures.json`, `student-tests.txt` | Чтобы повторно сохранить вывод: `make test > evidence/smoke.txt`, `make test-student > evidence/student-tests.txt`, `make validate-container > evidence/openapi.txt`, `make test-fresh > evidence/fresh-migrations.txt`. Распределённые сценарии сами обновляют свои JSON/text в evidence. Контракт и публичные tests не ослаблены; source lab2 переносился без них. Secrets, пароли и Bearer-токены в отчёт/evidence не записываются. ## Эксперименты и отказы Исследовательский трек 5 не проводился. Во всех сценариях используется реальный PostgreSQL/Redis и два API-процесса за Nginx. Генератор отказов/rolling — closed-loop4 потока; после неопределённого результата повторяет только POST сообщения, с прежним key/body. Подтверждённые ответы сверяются с полной историей, проверяются уникальность UUID и текста. Это проверка конкретных ограниченных отказов одного локального стенда. В последовательном сценарии перед воздействиями есть 3 с базовой работы, каждое окно остановки — около 8 с, предыдущий контейнер запускается и обнаруживается через LB перед следующим. Время записи считается только по запросу, **начатому после возврата stop hook**, а общий deadline10 с отсчитывается от старта hook. Чтение известного подтверждённого сообщения также выполняется до восстановления target. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | | Первый исходный API остановлен | другая реплика читает/пишет, остановленная не обслуживает | 400.056 RPS, 1 ошибочная попытка в окне; GET 200 и прежнее сообщение | POST через 1.3835 с от начала hook /0.0138 с после его завершения; GET через 1.38 с от начала | | Второй исходный API остановлен после восстановления первого | те же гарантии | 401.166 RPS, 1 ошибочная попытка; GET 200, target оставался stopped | POST через 1.4405 с от начала hook /0.0151 с после завершения; GET через 1.4375 с от начала | | Оба последовательных отказа | подтверждённые записи не теряются, retry не создаёт дубль | 15 915 подтверждённых сообщений =15 915 в истории | потерь/дублей не обнаружено | | SIGTERM во время активного POST | прекратить новые соединения, завершить активный запрос | SQL-запрос наблюдался в PgSleep; POST 201, новые TCP получили ConnectionRefusedError ещё при живом процессе; exit 0 | 1.9171 с от SIGTERM / сообщение сохранено | | Новый образ, поочерёдная start-first замена | адреса обновляются без рестарта LB, другая API продолжает работу | два шага 5.864/5.6574 с; разные IP, 3 alias при старте; во время замены 687.069 RPS, 1 ошибочная попытка (0.0126%) | 14 975 подтверждённых сообщений сохранены, дублей 0 | | Полный restart API/PG/Redis/LB с volumes | прежний токен читает прежние данные без повторного входа | public persistence PASS, реальные StartedAt изменились | потерь подтверждённого сообщения и сессии не обнаружено | | Redis остановлен | fallback в PostgreSQL без ослабления авторизации | GET 200 за 0.0138 с, ready 200, аноним 401 | данные/сессии в БД сохранены | | PostgreSQL остановлен | защищённый запрос 503, процесс остаётся жив | 503; обе внутренние live 200; после старта БД та же сессия работает | ошибки не приводят к доверию по кэшу | **Как проверялся SIGTERM:** временный BEFORE INSERT trigger задерживает ровно один синтетический текст через pg_sleep(2). После наблюдения активного запроса в pg_stat_activity процесс получает SIGTERM. Проверяется отказ новых TCP, пока процесс ещё работает, затем 201 исходного запроса, exit 0 и чтение результата через surviving API. Trigger/function удаляются в finally, контейнер восстанавливается. В коде приложения тестового endpoint/режима нет. **Что именно обновлялось:** собран действительно другой образ с отличающейся меткой APP_RELEASE, что видно по image id и X-App-Release. Код бизнес-API и схема совместимы; новой функциональной возможности в этом тестовом релизе не добавлялось. Мигратор запускается один раз перед заменами, не каждым новым API. Проверка доказывает поочерёдную замену сборки и обновление адресов, а не безопасное выполнение произвольной destructive migration. **Нагрузка без отказов:** `make load-evidence`, 30 с, concurrency 4, две реплики, без автоматических retry, один сохранённый прогон. Перед ним стенд прогрет функциональными сценариями; отдельного измеряемого нагрузочного прогрева нет. 24 559 успешных запросов, 0 ошибок, 814.97 successful RPS; p50/p95/p99=4.03/5.822/47.235 мс. Число сообщений в БД: до запуска — 102 032, после — 126 591. Исходный summary — `evidence/load.json`, параметры и данные — `environment.json`, замеры ресурсов — `resources.json`. Выборочные пики CPU/RAM за нагрузочный прогон (Docker CPU 100% = одно ядро; это пики отдельных samples, не одновременная сумма): | Контейнер | CPU peak | Memory peak | | --- | --- | --- | | API-процесс 1 | 68.64% | 78.41 MiB | | API-процесс 2 | 69.43% | 66.61 MiB | | Nginx | 10.01% | 7.895 MiB | | PostgreSQL | 42.15% | 99.4 MiB | | Redis | 0.99% | 11.04 MiB | Имена конкретных контейнеров и исходные значения — `evidence/resource-summary.json`. Эти цифры не доказывают максимальную пропускную способность и не являются сравнением с lab2: ресурсы/набор данных отличаются. Closed-loop имеет coordinated omission, latency рассчитана только для успешных ответов, клиент и Docker работают на одном ноутбуке. Переходные ошибки во время отказов/замен измерены и учитывают клиентские результаты. Nginx может скрыть connect error до отправки запроса и повторить безопасный GET; уже отправленные POST не повторяются им автоматически. ## Ограничения и следующие шаги - Один Docker-host; LB, PostgreSQL и Redis — по одному экземпляру. Проверен отказ API-процесса, не узла/диска/БД с failover. Restart с volumes не заменяет backup и не обеспечивает HA. - Compose-замена — наш явный start-first сценарий с временной третьей репликой, не автоматический rolling-контроллер Swarm. Сам по себе обычный `docker compose up` не является доказанным безопасным rolling update. При обрыве нашего сценария может потребоваться ручное восстановление до двух healthy-реплик. - В миграциях используются только совместимые аддитивные изменения. Breaking schema change требует expand/contract, миграции данных или отдельного окна; в этой работе не проверен. Advisory lock предотвращает одновременное применение, но сам по себе не делает любую миграцию совместимой. - При SIGTERM/обнаружении отказа допускаются краткие HTTP/connection errors. Клиент повторяет только отправку сообщения с тем же Idempotency-Key. Создание чата и регистрация не имеют общей идемпотентности и после отправки тела автоматически не повторяются. - TTL идемпотентности 24 ч и expiry сессии проверяются при запросе; фоновой очистки старых строк пока нет. Истёкший ключ можно использовать заново, это создаст новое сообщение. - Redis без пароля в изолированной data-сети Compose; сессии всегда проверяются в PostgreSQL. Изменение профиля в будущем потребует инвалидации кэша. В этой работе нет TLS, rate limiting входа, PKI и secret manager. - Нет общего snapshot между страницами; конкурентная запись с ключом до cursor может остаться позади обхода. Порядок COMMIT не обязан совпадать с порядком created_at. - Когда БД недоступна и LB исключил обе API-реплики, даже `/health/live` через публичную точку может получить 502/503/504 от LB; внутренний `/health/live` каждого процесса остаётся 200. Это различие готовности маршрута и жизни процесса. - UI/WebSocket, изменение участников и редактирование/удаление сообщений не входят в обязательный API. Malformed JSON без Bearer может дать 400 до выполнения зависимости аутентификации.