Files

152 lines
33 KiB
Markdown
Raw Permalink 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
- Автор, группа: Унру Д.В. БПИ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 <fork-url> && 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:<UUID>` на 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 до выполнения зависимости аутентификации.