# Отчёт — лабораторная 3 - Автор, группа: Чурилин, БВТ2301 - Текущий завершённый уровень: оценка «4» - Итоговая цель: оценка «5»; исследовательский трек выполняется следующим этапом - Commit/PR: заполняется автором после локального коммита и публикации - Использованные источники и библиотеки: преподавательские README/OpenAPI/tests, документация Go, pgx, PostgreSQL, Docker Compose, Nginx, React, TypeScript, Vite, TanStack Query, React Router, Lucide и Vitest. Для разбора архитектуры, рефакторинга, реализации и проверок использовался OpenAI Codex; решения проверены тестами и описанными ниже воспроизводимыми сценариями. ## Запуск из чистого clone Локальные секреты не входят в Git. Перед первым запуском оператор создаёт каталог `secrets/`, генерирует пароль PostgreSQL и общий для всех API-реплик ключ подписи курсоров длиной не менее 32 байт. Значение `database_url` должно использовать имя Compose-сервиса `postgres`, а не `localhost`. Пример генерации синтетических локальных значений без их вывода в терминал: ```bash mkdir -p secrets openssl rand -hex 32 > secrets/postgres_password.txt openssl rand -base64 48 > secrets/cursor_signing_key.txt printf 'postgres://messenger:%s@postgres:5432/messenger?sslmode=disable' \ "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt chmod 600 secrets/*.txt cp .env.example .env ``` Единственная публичная точка входа — `http://localhost:8080`; контейнеры API не публикуют порты на host. Последовательность запуска и проверки: ```bash docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build --wait make test make test-failover ACTION_SCRIPT=./scripts/stop-one.sh docker compose --env-file .env up -d --wait api make test-persistence ACTION_SCRIPT=./scripts/restart.sh make grade4-experiment ``` По этому же адресу Nginx отдаёт production-сборку React. Переход на `http://localhost:8080` открывает Messenger, а `/api/v1/*` и health endpoints остаются доступны автоматическим проверкам. Отдельный Node.js на машине для обычного запуска не нужен: multi-stage image сам выполняет `npm ci`, Vitest, TypeScript build и копирует статические файлы в Nginx. Для production с HTTPS нужно установить `SESSION_COOKIE_SECURE=true`; локально по HTTP значение остаётся `false`. `stop-one.sh` оставляет выбранную тестом реплику остановленной. Команда `up` в примере явно возвращает желаемые две реплики перед следующей проверкой. Обычная остановка не удаляет named volumes: ```bash docker compose --env-file .env down ``` Для демонстрации балансировки одним и тем же клиентом можно многократно вызвать любой API endpoint через `localhost:8080` и сравнить `X-Instance-Id`. В проверке 20 последовательных health-запросов наблюдались оба процесса: 10 ответов от одной реплики и 10 от другой. Запрос `/health/ready` непосредственно из Windows PowerShell вернул HTTP 200 и `X-Instance-Id`, поэтому браузер Windows и будущий frontend смогут использовать тот же `http://localhost:8080`. ## Архитектура и решения Перенесённая основа lab2 разделена на явные слои: - `internal/domain` — сущности и бизнес-инварианты без HTTP/JSON-зависимостей; - `internal/application` — сценарии, команды и узкие порты репозиториев; - `internal/adapter/postgres`, `memory`, `redis`, `cache` — реализации внешних зависимостей и кэширующий декоратор; - `internal/transport/http/dto` — wire-модели HTTP-контракта и преобразование domain → response DTO; - `internal/transport/http/handlers` — тонкие обработчики, по одному нетривиальному endpoint на файл; - `cmd/server` — composition root, единственное место сборки зависимостей. PostgreSQL остаётся источником истины для пользователей, сессий, чатов и сообщений. Redis содержит только удаляемую производную копию неизменяемых данных чата; его отказ не делает API неготовым и не отменяет подтверждённую запись в PostgreSQL. Compose запускает один сервис `api` с `API_REPLICAS=2`. Реплики не имеют host ports и разделяют PostgreSQL, включая таблицу сессий. Nginx — единственная публичная точка входа; он использует `least_conn` и Docker DNS resolver с повторным разрешением имени `api` раз в секунду. Sticky sessions не применяются. Произвольные POST балансировщик автоматически не повторяет. Исключение сделано только для маршрута отправки сообщения: обязательный `Idempotency-Key` позволяет Nginx безопасно повторить запрос на другой реплике при 502/503/504 во время drain. Клиент также сохраняет ключ для повтора после неопределённого результата. Создание пользователя и чата контрактом не идемпотентно, поэтому автоматический retry для этих маршрутов запрещён. Миграции вынесены в одноразовый сервис `migrate`, завершение которого является предусловием запуска API. Поэтому две реплики не конкурируют за изменение схемы. Пагинационный курсор теперь формируется в application-слое из канонических полей границы `(created_at, id, scope_id)` и подписывается HMAC-SHA-256. Подпись не скрывает payload, но обнаруживает подмену. В scope входит пользователь для списка чатов и чат для истории сообщений. Все реплики обязаны использовать один `CURSOR_SIGNING_KEY` или `CURSOR_SIGNING_KEY_FILE`; в Compose используется Docker secret `cursor_signing_key`. Репозитории получают только уже проверенную типизированную границу и ничего не знают о формате HTTP-курсора. `.env.example` перечисляет реально читаемые приложением параметры PostgreSQL, пула, readiness/shutdown, Redis-кэша, числа реплик, TTL идемпотентности и ключа курсора. Там же задаются CPU/RAM API и задержка drain перед shutdown. `API_REPLICAS` используется Compose, а `IDEMPOTENCY_TTL_SECONDS` читает Go-приложение и не допускает значение меньше 86400 секунд. Секретных значений в шаблоне нет: там указаны только пути внутри контейнера. Каждый процесс определяет стабильный `instance_id` один раз при загрузке конфигурации. По умолчанию используется hostname контейнера; это одновременно даёт уникальность между Compose-репликами и позволяет инфраструктурному hook сопоставить `X-Instance-Id` с конкретным контейнером. Опциональный `INSTANCE_ID` проверяется по безопасному для HTTP-заголовка шаблону. Сам middleware является внешним относительно router/recovery, поэтому заголовок присутствует также на health, 404/405 и восстановленных 500-ответах. POST сообщения принимает только ASCII-ключ по шаблону `[A-Za-z0-9._:-]{1,128}`. HTTP-слой нормализует UUID чата и формирует канонический path, application-слой хэширует SHA-256 не исходные bytes JSON, а типизированное семантическое представление запроса. Поэтому форматирование и порядок JSON-полей не влияют на повтор; задел под `attachment_ids` уже канонизирует отсутствующий список как пустой. Область уникальности в `message_idempotency` состоит из пользователя, метода, канонического пути и ключа. В одной PostgreSQL-транзакции сначала захватывается эта область через primary key, затем создаётся Message. Отложенный foreign key позволяет заранее записать будущий `message_id`, но проверяется при commit. При гонке вторая реплика ждёт разрешения уникального конфликта и затем либо возвращает то же сообщение, либо отвечает 409 при другом request hash. Любая ошибка до commit откатывает и бизнес-эффект, и запись ключа, поэтому transient 5xx не фиксируется как успешный результат. Перед replay снова выполняются обычная проверка bearer-сессии и проверка членства в чате. ### Frontend и браузерная сессия Клиент находится в `frontend/` и собран на React + TypeScript + Vite. TanStack Query отвечает за серверное состояние и периодическое обновление списков, React Router — за маршруты login/register, выбранного чата и профиля. UI сделан адаптивным: на широком экране одновременно видны навигация, список и разговор, а на узком список и чат переключаются как отдельные мобильные экраны. Фон чата добавлен из предоставленного изображения; нейтральная графитово-белая палитра, мягкая системная типографика и скруглённая геометрия компонентов подобраны самостоятельно, без копирования Telegram. Токен не хранится в `localStorage` и недоступен JavaScript. Успешный login по-прежнему возвращает преподавательский JSON с bearer token, но дополнительно ставит host-only cookie `mtusi_session` с `Path=/`, `HttpOnly` и `SameSite=Strict`. Флаг `Secure` управляется `SESSION_COOKIE_SECURE`: `false` нужен только локальному HTTP, на HTTPS должен быть `true`. Контрактные `/api/v1/*` сознательно остались Bearer-only. Nginx предоставляет отдельный браузерный адаптер `/web-api/v1/*`: берёт token из HttpOnly-cookie, формирует `Authorization: Bearer ...`, удаляет исходный `Cookie` и проксирует на обычный `/api/v1/*`. Поэтому преподавательские тесты и внешние API-клиенты не получили скрытый альтернативный способ авторизации. Same-origin deployment, `SameSite=Strict`, JSON-only изменяющие запросы и отсутствие CORS для сторонних origin уменьшают CSRF-поверхность. Logout удаляет серверную сессию и истекает cookie. Список чатов показывает только данные, реально существующие в контракте: title и число участников. Превью последнего сообщения и unread counter не имитируются, поскольку backend их пока не отдаёт. При неопределённой ошибке отправки клиент сохраняет текст вместе с `Idempotency-Key`; повтор использует тот же ключ. ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Воспроизводимая конфигурация и качество Go | `make check && make go-check && make validate PYTHON=../mtusi2026lab2/.venv/bin/python` | форматирование, tests, race detector, vet, Compose config и OpenAPI validation завершились без ошибок | `evidence/lab3-summary.md` | | Две API-реплики за одним LB | `docker compose --env-file .env up -d --build --wait`; 20 health-запросов через `:8080` | наружу опубликован только Nginx; два разных `X-Instance-Id`, по 10 ответов от каждого | `compose.yaml`, `infrastructure/nginx/nginx.conf`, `evidence/lab3-summary.md` | | Публичный smoke lab3 | `make test` | `tests/smoke.py` завершился `PASS: lab3 public API scenario` | `evidence/lab3-summary.md` | | Общая сессия без sticky routing | smoke, затем failover и persistence через тот же bearer token | обе реплики обслуживали запросы; сессия работает после остановки API и рестартов | `evidence/lab3-summary.md` | | Идемпотентность сообщения | `go test ./student_tests -run Idempotency`; 32 конкурентных POST с одним ключом через LB | один Message и ровно одна строка в PostgreSQL; другой payload даёт 409 | `student_tests/idempotency_test.go`, `evidence/lab3-summary.md` | | Failover каждой API-реплики | два последовательных запуска `make test-failover ACTION_SCRIPT=./scripts/stop-one.sh` с восстановлением между ними | реально остановлены `api-2`, затем `api-1`; получено 142/143 успешных записи, 0 ошибок, восстановление 0.963/0.750 с | `scripts/stop-one.sh`, `evidence/lab3-summary.md` | | Persistence после рестартов | `make test-persistence ACTION_SCRIPT=./scripts/restart.sh` | PASS; прежняя сессия и данные доступны после рестарта PostgreSQL, Redis, API и LB | `scripts/restart.sh`, `evidence/lab3-summary.md` | | Миграции перед API | `docker compose --env-file .env ps -a` и логи `migrate` | миграции 1 и 2 применены; one-shot контейнер завершился с кодом 0; API healthy | `migrations/000002_message_idempotency.up.sql`, `evidence/lab3-summary.md` | | React frontend и HttpOnly BFF | `docker compose build load-balancer`; browser QA; cookie-only curl-сценарий | Vitest/TypeScript/Vite build PASS; register/login 201; прямой `/api` 401; `/web-api` 200; logout 204, после logout 401; browser console без warning/error | `frontend/`, `infrastructure/nginx/Dockerfile`, `infrastructure/nginx/nginx.conf` | | Согласованные health и shutdown | SIGTERM каждой реплики под нагрузкой | API сразу закрывает availability gate, 2 с дренирует запросы и укладывается в 10 с shutdown; `/health/live` остаётся доступен | `internal/transport/http/middleware/availability.go`, `evidence/grade4/` | | CPU/RAM и изоляция портов | `docker inspect`; `docker compose ps` | API: 0,5 CPU/256 MiB на реплику; наружу опубликован только Nginx `127.0.0.1:8080`; `container_name` отсутствует | `compose.yaml`, `evidence/grade4/results.json` | | Последовательный failover уровня 4 | `make grade4-experiment` | обе исходные реплики остановлены по очереди и восстановлены; recovery 3,464/3,476 с, одна краткая ошибка из 4614 запросов в первом прогоне и 0 из 5815 во втором | `evidence/grade4/README.md`, `throughput-errors.svg`, `timeline.svg` | | Rolling update под нагрузкой | surge до 3 реплик, замена двух старых по одной, возврат к 2 | 20 350 успешных запросов, 1 краткий 502 (0,005%), все новые реплики проходят healthcheck и DNS-settle | `scripts/rolling-update.sh`, `evidence/grade4/` | ## Эксперименты и отказы Итоговый эксперимент уровня 4 выполнен 23.10.2026 на Windows + WSL2: Docker Engine 29.7.2, Compose 5.5.0, 8 логических CPU и 3813,6 MiB RAM, commit-base `34618bd4237bbb8bf6a3a303056fc95d799577f9` с незакоммиченными изменениями текущего уровня. В Compose каждой API-реплике выделено 0,5 CPU и 256 MiB; Nginx — 0,25 CPU/128 MiB; PostgreSQL — 1 CPU/512 MiB; Redis — 0,25 CPU/128 MiB. Команда `make grade4-experiment` создаёт синтетических пользователей и чат, делает 12 warm-up записей, затем запускает 8 closed-loop клиентов без повторов на стороне клиента. Baseline длится 12 с. В каждом failover воздействие начинается через 3 с, предыдущая реплика восстанавливается перед остановкой следующей, после действия нагрузка продолжается ещё 8 с. Rolling update временно увеличивает сервис до трёх реплик, ждёт healthcheck и два периода Docker DNS, заменяет старые контейнеры по одному и возвращает масштаб к двум. Минимальный подтверждённый размер набора после прогона — 34 808 сообщений. | Фаза | Успешно / ошибок | RPS | Доля ошибок | p50 / p95 / p99, мс | Восстановление | | --- | ---: | ---: | ---: | ---: | ---: | | baseline | 4017 / 0 | 319,463 | 0% | 16,799 / 55,515 / 93,803 | — | | остановка реплики 1 | 4613 / 1 | 301,040 | 0,0217% | 17,145 / 69,558 / 89,752 | 3,464 с | | остановка реплики 2 | 5815 / 0 | 374,449 | 0% | 14,211 / 49,542 / 81,040 | 3,476 с | | rolling update | 20 350 / 1 | 376,959 | 0,0049% | 15,725 / 48,724 / 79,337 | непрерывная нагрузка | На baseline средняя выборка одного API-контейнера составила 28,453% CPU и 42,413 MiB RAM, максимум — 36,1% и 66,07 MiB. PostgreSQL оказался самым нагруженным компонентом: в rolling-фазе среднее 98,172% CPU при лимите одного ядра, максимум RAM 145,2 MiB. Это не capacity-тест и не доказательство saturation point, но важный ориентир для исследования уровня 5. Nginx обновляет Docker DNS раз в 1 с, исключает peer после двух неудач за 2 с, а connect timeout равен 1 с. При постоянной нагрузке ожидаемое максимальное обнаружение — около 4 с; измеренные 3,464 и 3,476 с укладываются в требование 10 с. Одна 504 и одна 502 сохранены в отчёте честно: README прямо допускает краткие ошибки обнаружения. Подтверждённых потерь и дублей нет. Параллельные 32 POST с одним ключом прошли через обе реплики и вернули один Message ID. Исходные агрегаты, environment/limits, посекундные таблицы и четыре SVG-графика лежат в `evidence/grade4/`. Percentile рассчитаны только по успешным ответам; профиль closed-loop имеет coordinated omission. CPU для API агрегируется как средняя/максимальная выборка отдельного контейнера, а не сумма двух реплик. ## Ограничения и следующие шаги - Топология однохостовая: Nginx и PostgreSQL остаются single points of failure. Репликация БД и несколько балансировщиков в требования уровня «4» не входят. - Redis содержит только кэш, поэтому его потеря допустима. Отдельная персистентность Redis для корректности API не требуется. - Истёкшие записи идемпотентности удаляются лениво при повторном обращении к той же области ключа. Индекс по `expires_at` оставлен для будущей периодической очистки без изменения схемы. - Уровень «5» ещё не реализован: сравнение 1/2/4 реплик при фиксированных ресурсах и поиск saturation point выполняются следующим отдельным этапом. - Rolling-сценарий заменяет бинарник без изменения схемы. Миграции выполняются однократно до API; для будущей несовместимой схемы потребуется expand/contract, поэтому одновременная работа разных schema-version сейчас не заявляется. - Текущий API не содержит endpoint поиска пользователей, аватаров, изменения имени/пароля и агрегатов last message/unread. Поэтому UI принимает UUID участников при создании чата, а профиль честно показывает только доступные поля. Эти функции требуют сначала расширить и зафиксировать API-контракт. - Однохостовая среда WSL2 не доказывает устойчивость к потере Docker-host; измерен только отказ и замена процесса API.