# Отчёт — лабораторная 3 - Автор, группа: Меркулова М.А., БВТ2303 - Целевая оценка: 4 - Ветка: `solution/BVT2303-Merkulova`; commit/PR указываются после публикации - Реализация: Go 1.26, PostgreSQL 17.6, Redis 8.2.1, Nginx 1.29.1, Docker Compose - Библиотеки приложения: `pgx/v5`, `go-redis/v9`, `x/crypto/scrypt` - Помощь ИИ: использовалась для проектирования, написания и проверки кода; требования сверялись с файлами текущего skeleton, все приведённые результаты получены локальным запуском ## Запуск из чистого clone Нужны Docker с Compose, Python 3.9+ и `make`. Локальный Go нужен только для `go test`; Docker-образ собирает бинарный файл самостоятельно. ```sh ./scripts/init-local.sh docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build --wait docker compose --env-file .env ps make check make test ``` `init-local.sh` создаёт случайные пароли, URL подключения и `.env` в игнорируемых Git файлах. Единственная публичная точка — `http://127.0.0.1:8080` на Nginx. Порты API-реплик, PostgreSQL и Redis на host не публикуются. Остальные проверки: ```sh go test ./... go vet ./... ACTION_SCRIPT=./scripts/restart.sh make test-persistence ACTION_SCRIPT=./scripts/stop-one.sh make test-failover ./scripts/start-api.sh python3 student-tests/verify_idempotency.py python3 student-tests/failover_experiment.py python3 student-tests/verify_unready_backend.py python3 student-tests/rolling_update_experiment.py python3 student-tests/verify_grade4.py python3 student-tests/verify_expiry.py python3 student-tests/verify_dependencies.py ./scripts/explain_history.sh ``` Безопасная остановка с сохранением данных: ```sh docker compose --env-file .env down ``` Намеренное удаление всех учебных данных и сессий: ```sh docker compose --env-file .env down -v ``` ## Архитектура и решения ```mermaid flowchart LR C[Клиент] -->|HTTP :8080| L[Nginx] L --> A1[API api-1] L --> A2[API api-2] A1 --> P[(PostgreSQL)] A2 --> P A1 --> R[(Redis + AOF)] A2 --> R M[Одноразовый migrate] --> P ``` Обе API-реплики собраны из одного образа, не имеют локального бизнес-состояния и используют общие PostgreSQL и Redis. PostgreSQL хранит пользователей, чаты, сообщения и идемпотентность. Redis хранит общие Bearer-сессии как `SHA-256(token) → user UUID` с TTL и AOF. Поэтому запросы одной сессии обслуживаются обеими репликами без sticky sessions. Nginx выполняет round-robin между готовыми репликами. В его контейнере `health-aware.sh` опрашивает `/health/ready` каждой API-реплики по frontend-сети с паузой 1 секунду между циклами и при изменении набора готовых реплик обновляет upstream и перезагружает конфигурацию Nginx. Если обе реплики неготовы, он оставляет обе в upstream: API может вернуть обычные JSON-ответы `401` и `503` вместо ошибки Nginx «no live upstreams». Пока обновление upstream ещё не произошло, Nginx повторяет идемпотентный GET на второй реплике при `503`, сетевой ошибке или таймауте. Автоматический повтор POST после отправки запроса не включён; после обнаружения отказа POST идёт только на готовую реплику. Docker healthcheck API запускается каждые 3 секунды и используется для начального запуска и наблюдения. Connect timeout равен 500 ms, Docker DNS перечитывается с периодом 2 секунды. `X-Instance-Id` равен стабильным alias `api-1` или `api-2`. API обрабатывает SIGTERM через `http.Server.Shutdown` с бюджетом 8 секунд; Compose даёт 10 секунд до принудительной остановки. Таймауты HTTP: header 5 s, read/write 10 s, idle 30 s. SQL получает `DB_TIMEOUT_MS=3000`; каждая реплика имеет пул максимум из 10 соединений. Миграции выполняет отдельный одноразовый сервис `migrate` до API. При rolling update тот же сервис запускается ещё раз до замены первой реплики; уже применённые версии он пропускает. Таблица `schema_migrations` и транзакция предотвращают повторное применение. Миграция 002 аддитивно добавляет таблицу идемпотентности, поэтому старая схема lab2 остаётся читаемой во время последовательной замены процессов. Для `POST /messages` обязателен `Idempotency-Key`. Область уникальности — `(user_id, method, path, key)`. В одной PostgreSQL-транзакции создаётся запись ключа, сообщение и ссылка на результат. Конкурентный повтор блокируется общим уникальным ключом и после commit получает исходное сообщение с `201`. Тот же ключ с другим логическим JSON даёт `409`. Ключ действует минимум `IDEMPOTENCY_TTL_SECONDS=86400`; при повторном использовании просроченная запись удаляется. Записи ключей, которые больше не используют, пока остаются в таблице. Из lab2 сохранены PostgreSQL, Redis-сессии, scrypt-пароли, транзакционное создание чатов, cursor pagination, request ID, JSON-ошибки, health endpoints и graceful shutdown. Новые обязательные изменения lab3: Nginx, две реплики, `X-Instance-Id`, общий `Idempotency-Key`, отдельные миграции и отказ одной API-реплики. ## Ресурсные границы и секреты Compose реально применил следующие limits: | Сервис | CPU | RAM | | --- | ---: | ---: | | `api1`, `api2` | по 0.50 | по 192 MiB | | `nginx` | 0.25 | 64 MiB | | `postgres` | 1.00 | 512 MiB | | `redis` | 0.25 | 128 MiB | | `migrate` | 0.25 | 128 MiB | PostgreSQL и Redis находятся только во внутренней backend-сети. Nginx видит API по frontend-сети. API получает только URL PostgreSQL и Redis; Nginx не получает секреты, PostgreSQL не получает Redis-пароль. Секретные значения создаются локально в `secrets/` и не входят в Git. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство | | --- | --- | --- | --- | | Публичный API | `make test` | PASS lab3, включая `X-Instance-Id` и повтор сообщения | `evidence/lab3-results.md` | | Две реплики через LB | шесть `GET /health/live` | `api-2`, `api-1` по очереди | `evidence/lab3-results.md` | | Persistence | `ACTION_SCRIPT=... make test-persistence` | прежний токен и сообщение доступны после restart всех процессов и хранилищ | `evidence/lab3-results.md` | | Отказ любой реплики | официальный failover и последовательный эксперимент | остановлены реальные `api1` и `api2`; подтверждённые сообщения сохранились | `evidence/lab3-results.md` | | Метрики двух отказов | `failover_experiment.py` | 642.783 и 569.984 successful RPS; 0 ошибок; 0.600/0.610 s до подтверждения survivor | `evidence/failover-grade4.json` | | Неготовая реплика с работающим HTTP | `verify_unready_backend.py` | после отключения backend-сети `api1` и состояния `unhealthy`: 40 GET и 10 POST через LB обслужила `api2` | `evidence/lab3-results.md` | | Общая идемпотентность | `verify_idempotency.py` | 12 параллельных запросов через обе реплики, один message ID; другой body — 409 | `evidence/idempotency.json` | | Rolling update | `rolling_update_experiment.py` | поочерёдно пересозданы обе реплики; 25 388 успехов, 0 ошибок | `evidence/rolling-update.json` | | Отказ Redis/PostgreSQL | `verify_dependencies.py` | осмысленные 503, после возврата сервисов состояние восстановлено | `evidence/lab3-results.md` | | Индекс истории | `explain_history.sh` | `Index Scan using messages_chat_history_idx` на 10 000 сообщений | `evidence/explain-history.txt` | | Возможности lab2 | `verify_grade4.py`, `verify_expiry.py`, `go test ./...` | гонка username, rollback, logout, TTL и password KDF прошли | `evidence/lab3-results.md` | ## Эксперименты и отказы Стенд повторно проверен 16 октября 2026 года на Docker Desktop/macOS arm64. До измерений выполнены smoke и несколько запросов прогрева. Все данные синтетические. Failover использует один закрытый цикл HTTP-клиента 8 секунд на реплику. Rolling update использует четыре закрытых параллельных клиента; метрики задержки относятся только к успешным ответам и включают клиентские и LB расходы. | Воздействие | Успехи / ошибки | Наблюдаемое переключение | Потеря подтверждённых данных | | --- | ---: | ---: | --- | | Stop `api-1` | 5143 / 0 за 8.001 s | 0.600 s | нет | | Stop `api-2` | 4560 / 0 за 8.000 s | 0.610 s | нет | | Rolling replace `api-1`, затем `api-2` | 25388 / 0 за 16.832 s | обе реплики наблюдались | нет | Rolling update: 1508.329 successful RPS, p50 2.221 ms, p95 3.998 ms, p99 6.040 ms. Это локальное наблюдение, а не универсальная оценка производительности. Closed-loop профиль имеет coordinated omission и не моделирует фиксированный внешний arrival rate. ## Ограничения и следующие шаги Стенд выдерживает остановку одного API-процесса. Все компоненты работают на одном Docker-host, поэтому потеря host останавливает систему. Nginx, PostgreSQL и Redis представлены по одному и остаются single points of failure. Остановка PostgreSQL или Redis корректно даёт 503, но бизнес-функции временно недоступны. Nginx исключает неготовую реплику по HTTP-проверке `/health/ready`; между отказом и очередной проверкой возможна краткая ошибка POST. Docker healthcheck отвечает за запуск и наблюдаемость. Rolling update проверяет последовательную замену процессов одной совместимой версией на одном host. Автоматического rollback образа, репликации БД, отдельного backup/restore и multi-host orchestration в lab3 нет. Просроченная запись ключа удаляется при повторном использовании того же ключа. Для длительной эксплуатации нужна периодическая очистка остальных записей. Приведённые RPS и latency нельзя переносить на другой компьютер без повторения опыта с теми же ресурсами и набором данных.