24 KiB
Отчёт — лабораторная 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. Пример генерации синтетических
локальных значений без их вывода в терминал:
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. Последовательность запуска и проверки:
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:
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.