# Отчёт — лабораторная 3 - Автор, группа: Булла Максим, БПИ2301 - Целевая оценка: **4** - Commit/PR: f731f9b - Источники, библиотеки и помощь ИИ: официальная документация Docker Compose, HAProxy, Go/Fiber; код и инфраструктура подготовлены с помощью DeepSeek V4.1 Flash + OpenCode ## 1. Что сделано Рабочая база lab2 (Go + Fiber v3, PostgreSQL, Redis-сессии, миграции) доведена до lab3: - HAProxy стал единственной публичной точкой входа; - запущены две API-реплики без публикации их портов; - сессии и идемпотентность сообщений вынесены в общие хранилища; - `X-Instance-Id` добавлен во все ответы API; - миграции вынесены в отдельный one-shot сервис; - настроены readiness, graceful shutdown и ограничения CPU/RAM; - добавлены action-скрипты для restart/failover и rolling replacement; - подготовлен профиль k6 для проверки rolling update под нагрузкой. Обязательный контракт, `lab.json` и публичные тесты не изменялись. Существующие неочевидные решения отмечены в коде комментариями `AGENT:`; перечень файлов для их проверки и удаления находится в `LEFT_TO_REVIEW.md`. Новые комментарии `AGENT:` в этой итерации не добавлялись: изменения и их обоснование записаны в `CHANGELOG.md`. ## 2. Запуск из чистого clone Требуется Docker Engine с Compose v2 и свободный порт `8080` (или другой `LB_PORT`). Версии образов зафиксированы в `compose.yaml`. ```sh cp .env.example .env # задать локальный POSTGRES_PASSWORD; остальное можно оставить по умолчанию docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build make wait ``` Порядок запуска: 1. PostgreSQL и Redis проходят healthcheck. 2. Сервис `migrate` один раз применяет миграции и завершается. 3. Запускаются API-реплики с `RUN_MIGRATIONS=false`. 4. HAProxy начинает отдавать `/health/ready` только после готовности API. Проверки: ```sh make test make test-persistence ACTION_SCRIPT=scripts/restart.sh make test-failover ACTION_SCRIPT=scripts/stop-one.sh make test-concurrency ``` Дополнительно: ```sh make k6 VUS=20 DURATION=60s # нагрузка через HAProxy make validate PYTHON=.venv/bin/python ``` Остановка без удаления данных: ```sh docker compose --env-file .env down ``` Намеренное удаление учебных данных (только отдельный стенд): ```sh docker compose --env-file .env down -v ``` `.env` в репозиторий не попадает; в `.env.example` лежит только placeholder пароля. ## 3. Архитектура и решения ```text клиент │ HTTP :8080 ▼ HAProxy ── readiness /health/ready, retries, stats :8404, Prometheus /metrics │ Docker DNS, server-template api 1..4 ├──────────────┐ ▼ ▼ API-1 API-2 ... API-N (Go/Fiber, без публикации портов) │ │ └──────┬───────┘ ▼ PostgreSQL ← users/chats/messages + message_idempotency Redis ← общие сессии (AOF) migrate — one-shot, RUN_MIGRATIONS / MIGRATE_ONLY ``` ### 3.1. Компоненты и лимиты | Компонент | Роль | Решение | | --- | --- | --- | | `haproxy` | LB и публичная точка входа | `server-template api 4 api:8080 resolvers docker`; health check `/health/ready` каждые 1 с, `fall 2` | | `api` | бизнес-API | `deploy.replicas: ${API_REPLICAS:-2}`, `expose: 8080`, без `ports` | | `migrate` | миграции | тот же образ, `MIGRATE_ONLY=true`, `restart: "no"` | | `postgres` | источник истины | named volume `pgdata`, healthcheck, версия 16.10 | | `redis` | общие сессии | AOF `everysec`, named volume `redisdata` | | `k6` | нагрузка | профиль `load`, подключается только при явном запуске | У API, PostgreSQL, Redis и HAProxy есть CPU/RAM-лимиты (`deploy.resources.limits`, значения из `.env`). У API нет `container_name`, поэтому Compose может масштабировать сервис. ### 3.2. Миграции `app/cmd/server/main.go` поддерживает два режима: - обычный API: `RUN_MIGRATIONS=false`, схемой занимается отдельный сервис; - `MIGRATE_ONLY=true`: применить миграции, закрыть пул и выйти, не открывая Redis. Это убирает гонку миграций при старте нескольких реплик и при rolling update. Миграция `0002_message_idempotency` аддитивная: старая версия приложения может работать с уже созданной таблицей, новая версия требует её наличия. Поэтому порядок «сначала migrate, потом новые API» безопасен. ### 3.3. `X-Instance-Id` Middleware в `app/internal/app.go` ставит заголовок на каждый ответ, включая health и ошибки. Значение берётся из `INSTANCE_ID`, а если он не задан — из hostname процесса. В Compose hostname уникален для контейнера, поэтому реплики различимы; значение не меняется в течение жизни процесса. Если hostname получить нельзя и `INSTANCE_ID` не задан, конфигурация завершается ошибкой. Раньше в этом случае молча подставлялось литеральное значение `api`, из-за чего несколько процессов могли получить одинаковый идентификатор. ### 3.4. Идемпотентность сообщений Таблица `message_idempotency`: - PK `(sender_id, chat_id, idempotency_key)` — ровно область «пользователь + путь чата + ключ»; метод в текущем API только один; - `request_hash` — SHA-256 текста сообщения; - `message_id` — ссылка на уже созданное сообщение; - `created_at`, `expires_at` — окно хранения (по умолчанию 24 часа). Алгоритм в `app/internal/store/messages.go`: 1. Быстрый lookup по ключу. Если запись не истекла и hash совпал — вернуть тот же `Message` с `201`. 2. Иначе открыть транзакцию, вставить сообщение с проверкой членства в чате, вставить ключ через `ON CONFLICT`. 3. Если конкурентная реплика уже вставила этот ключ, транзакция текущего запроса откатывается, и читается результат победившей реплики. При другом hash — `409`. 4. Транзиентная ошибка не фиксирует ключ: транзакция откатывается, клиент может повторить с тем же ключом. Так один ключ создаёт ровно одно сообщение даже при параллельных запросах через разные реплики. Повтор снова проходит аутентификацию и проверку доступа к чату. ### 3.5. HAProxy и graceful shutdown - backend discovery: Docker DNS `127.0.0.11:53`, `server-template api 4`, поэтому `docker compose up --scale api=N` не требует правки конфига; - health check: `GET /health/ready`, `inter 1s`, `fall 2` — обнаружение отказа около 2 секунд (при бюджете 10 секунд); - `retries 2`, `option redispatch` — короткие ошибки соединения не роняют запрос; - при SIGTERM приложение сначала перестаёт отдавать `200` на readiness, затем ждёт до 10 секунд; у контейнера `stop_grace_period: 15s`; - stats UI/CSV на `:8404/stats`, Prometheus на `:8404/metrics`. ### 3.6. Readiness и транзакции `/health/ready` проверяет PostgreSQL и Redis и не захватывает прикладных блокировок. `pgxpool.Ping` берёт соединение из пула и возвращает его через `defer`; `store.Ping` ограничивает проверку двумя секундами. Отдельно проверены транзакции в `CreateChat` и `CreateMessage`. Откат больше не выполняется на неограниченном `context.Background()`: используется контекст с таймаутом. Если PostgreSQL перестал отвечать, соединение закрывается, а PostgreSQL трактует закрытие соединения как откат и снимает блокировки строк. Это не даёт неудачной транзакции удерживать соединение пула и мешать readiness других запросов. Единственная явная advisory-блокировка — миграционная; она снимается в `defer` с собственным таймаутом. ## 4. Доказательства критериев | Критерий | Команда/сценарий | Наблюдаемый результат | Файл | | --- | --- | --- | --- | | Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/grade-3-4.md` | | Офлайн-проверки | `make check` | `PASS: offline skeleton...` | `evidence/grade-3-4.md` | | OpenAPI | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1...` | `evidence/grade-3-4.md` | | ≥2 реплики, одна сессия | 10 запросов `/health/live` через LB | 2 разных `X-Instance-Id` | `evidence/grade-3-4.md` | | Остановка одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 120–121 запись, 0–1 ошибка, восстановление 2.54–2.93 с | `evidence/grade-3-4.md` | | Сохранность после restart | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и bearer-токен сохранились | `evidence/grade-3-4.md` | | Конкурентная идемпотентность | `make test-concurrency` | 12 запросов, 2 реплики, 1 сообщение, другой body → 409 | `evidence/grade-3-4.md` | | CPU/RAM-лимиты, API без host ports | `compose.yaml`, `docker compose ps` | API только `expose`, лимиты заданы | `compose.yaml` | | Rolling update под нагрузкой | `scripts/rolling-update.sh 2` + k6 20 VU/60 с | 41 605 итераций, 0 failed checks, p95 55.27 мс | `evidence/k6-rolling-20vu-60s.json` | | Миграции однократно | `migrate` service, API `RUN_MIGRATIONS=false` | `migrate` завершился, API healthy | `compose.yaml`, `app/cmd/server/main.go` | Проверки HTTP запускались из контейнера в сети стенда: в рабочей оболочке published ports были изолированы от хоста. Это ограничение среды, а не приложения; на обычной машине команды `make test`/`make test-failover` запускаются с хоста. ## 5. Эксперименты и отказы ### 5.1. Отказ одной API-реплики | Что сделано | Ожидание | Наблюдение | Восстановление | | --- | --- | --- | --- | | Остановлена одна API-реплика при живой второй | LB исключает её, подтверждённые данные и сессия целы | 2 реплики до отказа; 120–121 успешная запись; 0–1 краткая ошибка | 2.54–2.93 с до первой успешной записи | | Вручную остановлена вторая реплика | Трафик переходит на оставшуюся | 1698 успешных записей, 1 ошибка; обе реплики наблюдались до отказа | вторая реплика восстановлена через `up` | Ошибка на границе отказа ожидаема: клиент мог отправить запрос в момент, когда процесс уже остановлен, но HAProxy ещё не убрал backend. Повтор с тем же `Idempotency-Key` не создал дубль. ### 5.2. Rolling update под нагрузкой `scripts/rolling-update.sh 2` собирает образ и поочерёдно заменяет контейнеры: останавливает один, удаляет, создаёт replacement, ждёт health и только потом переходит к следующему. Во время этого k6 писал сообщения 20 VU в течение 60 с. | Метрика | Значение | | --- | ---: | | Всего запросов | 41 608 | | Итераций | 41 605 | | Ошибок проверок | 0 | | p95 | 55.27 мс | | p99 | 71.15 мс | Это подтверждает, что последовательная замена не рвёт поток целиком: HAProxy успевает исключить остановленный backend. Сырой summary: `evidence/k6-rolling-20vu-60s.json`. ## 6. Ограничения - Один Docker-host: потеря узла не переживается. HAProxy, PostgreSQL и Redis остаются единичными точками отказа; API-реплики не делают БД высокодоступной. - PostgreSQL не реплицирован. При потере `pgdata` данные теряются; Redis AOF спасает сессии от рестарта, но не от потери диска. - Compose — не Swarm: rolling-скрипт делает поочерёдную замену, но не даёт маршрутизации между узлами. - Профиль k6 — write-only. Он выбран намеренно: проверяется запись, идемпотентность и БД; чтение и смешанный профиль — отдельный эксперимент. - `X-Instance-Id` здесь — hostname контейнера, не скрыт. - Проверка пароля и ветка «пользователь не найден» имеют разное время выполнения: для неизвестного username Argon2 не запускается. Теоретически это позволяет перечислять имена по времени ответа. Контракт требует только одинаковый `401` и challenge; в lab3 временная атака не устраняется.