Files
mtusi2026lab3/REPORT.md
T
2026-10-25 21:46:21 +03:00

36 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: Чурилин, БВТ2301
  • Текущий завершённый уровень: оценка «5», трек 1 «Цена масштабирования»
  • Итоговая цель: выполнена; уровень «4» и законченный исследовательский трек
  • Commit/PR: заполняется автором после локального коммита и публикации
  • Использованные источники и библиотеки: преподавательские README/OpenAPI/tests, документация Go, pgx, PostgreSQL, Docker Compose, HAProxy, 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-readiness-routing
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
make grade5-experiment

По этому же адресу HAProxy направляет обычные browser-запросы во внутренний 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, включая таблицу сессий. HAProxy — единственная публичная точка входа; он использует leastconn, Docker DNS resolver и активные HTTP-проверки /health/ready раз в секунду. Реплика исключается после двух неуспешных readiness-проверок и возвращается после двух успешных. Поэтому живой, но потерявший PostgreSQL и ставший неготовым процесс перестаёт получать трафик; Docker healthcheck не является единственным механизмом обнаружения. Sticky sessions не применяются. Nginx остаётся отдельным внутренним контейнером и обслуживает только статические файлы React.

Произвольные POST балансировщик автоматически не повторяет. Исключение сделано только для маршрута отправки сообщения: обязательный Idempotency-Key позволяет HAProxy безопасно повторить запрос на другой реплике при connection failure, empty response, timeout или 502/503/504 во время обнаружения отказа и drain. Для этого маршрута тело запроса буферизуется отдельным backend; регистрации пользователя и создание чата контрактом не идемпотентны, поэтому 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. HAProxy предоставляет отдельный браузерный адаптер /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 наружу опубликован только HAProxy; два разных X-Instance-Id, по 10 ответов от каждого compose.yaml, infrastructure/haproxy/haproxy.cfg, 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 frontend 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/, infrastructure/haproxy/
Согласованные 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 на реплику; наружу опубликован только HAProxy 127.0.0.1:8080; container_name отсутствует compose.yaml, evidence/grade4/results.json
Readiness-aware routing make test-readiness-routing одной API-реплике заблокирован PostgreSQL: HAProxy исключил её за 2,861 с; 40 health-запросов получили 200, 20 регистраций — 201; после снятия fault реплика вернулась scripts/test_readiness_routing.py, evidence/readiness-routing.json
Последовательный failover уровня 4 make grade4-experiment обе исходные реплики остановлены по очереди и восстановлены; recovery 2,893/2,938 с; во всех фазах 0 ошибочных запросов evidence/grade4/README.md, throughput-errors.svg, timeline.svg
Rolling update под нагрузкой surge до 3 реплик, замена двух старых по одной, возврат к 2 22 212 успешных запросов, 0 ошибок; все новые реплики проходят healthcheck и DNS-settle scripts/rolling-update.sh, evidence/grade4/
Фиксированный бюджет 1/2/4 API make grade5-experiment; 32 closed-loop клиента при суммарных 1 CPU, 512 MiB и 16 соединениях получено 578,242 / 529,499 / 353,955 RPS; четыре процесса при том же бюджете дали на 38,79% меньше одной реплики evidence/grade5/02-fixed-total.svg, measurements.csv
Рост ресурсов 1/2/4 API тот же workload; по 0,5 CPU, 256 MiB и 8 соединений на реплику 533,656 / 563,460 / 438,868 RPS; нелинейная серия показывает отсутствие пропорционального выигрыша при общей БД в 1 CPU evidence/grade5/03-resource-growth.svg, results.json
Saturation point и bottleneck concurrency 1/2/4/8/16/32, по 10 с после warm-up первый сигнал насыщения — 8: относительно 4 клиентов RPS вырос только на 8,03%, p95 — в 1,92 раза; PostgreSQL в профиле четырёх реплик достиг 101,91% одного CPU evidence/grade5/01-saturation.svg, 04-bottleneck.svg
Подтверждённое улучшение четыре API без изменений; PostgreSQL 1 → 2 CPU RPS 438,868 → 587,574 (+33,88%), ошибок 0, p95 снизился на 14,12%; следующим ограничением стал HAProxy с лимитом 0,25 CPU evidence/grade5/05-improvement.svg, resources.csv

Эксперименты и отказы

Итоговый эксперимент уровня 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; HAProxy — 0,25 CPU/128 MiB; frontend Nginx — 0,10 CPU/64 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, заменяет старые контейнеры по одному и возвращает масштаб к двум. Минимальный подтверждённый размер набора после прогона — 43 810 сообщений.

Фаза Успешно / ошибок RPS Доля ошибок p50 / p95 / p99, мс Восстановление
baseline 5762 / 0 479,581 0% 9,178 / 56,402 / 79,978 —
остановка реплики 1 7853 / 0 537,548 0% 8,812 / 50,050 / 66,373 2,893 с
остановка реплики 2 7970 / 0 533,154 0% 8,726 / 48,789 / 64,333 2,938 с
rolling update 22 212 / 0 428,860 0% 10,560 / 58,713 / 83,982 непрерывная нагрузка

На baseline средняя выборка одного API-контейнера составила 27,144% CPU и 31,008 MiB RAM, максимум — 30,93% и 66,17 MiB. PostgreSQL оказался самым нагруженным компонентом: среднее 89,392% CPU при лимите одного ядра, максимум 110,59%; HAProxy использовал в среднем 26,262% CPU. Это не capacity-тест и не доказательство saturation point, но важный ориентир для исследования уровня 5.

HAProxy обновляет Docker DNS раз в 1 с и исключает peer после двух неуспешных активных /health/ready-проверок. Измеренные 2,893 и 2,938 с укладываются в требование 10 с. Отдельный тест потери доступа одной реплики к PostgreSQL подтвердил исключение неготового backend за 2,861 с без 5xx: 40 health-запросов получили 200, а 20 регистраций — 201. Во всех четырёх фазах grade-4 эксперимента ошибок нет. Параллельные 32 POST с одним ключом прошли через обе реплики и вернули один Message ID.

Исходные агрегаты, environment/limits, посекундные таблицы и четыре SVG-графика лежат в evidence/grade4/. Percentile рассчитаны только по успешным ответам; профиль closed-loop имеет coordinated omission. CPU для API агрегируется как средняя/максимальная выборка отдельного контейнера, а не сумма двух реплик.

Исследование уровня 5: цена масштабирования

Трек 1 выполнен командой make grade5-experiment 23.10.2026 на том же однохостовом стенде Windows + WSL2: Docker Engine 29.7.2, Compose 5.5.0, 8 логических CPU и 3813,6 MiB RAM. Базовым commit до изменений уровня 5 был 5300a1a; измерения ожидаемо зафиксировали dirty working tree, поскольку сам скрипт и параметризация лимитов ещё не были закоммичены. Все запросы проходили через единственную публичную точку HAProxy, создавали сообщения с уникальными Idempotency-Key и не повторялись нагрузочным клиентом автоматически.

Методика и воспроизводимость

Каждая измеряемая фаза длилась 10 секунд. После каждой смены профиля выполнялся двухсекундный warm-up, затем контейнеры и реально применённые NanoCpus, RAM и DB_MAX_CONNS проверялись через docker inspect. Скрипт сохраняет посекундные request buckets и каждую выборку docker stats; CPU/RAM API сначала суммируются по всем репликам в одной временной точке и только затем усредняются. Это устраняет ошибку, при которой средняя загрузка одного из четырёх контейнеров выдавалась бы за стоимость всего API-сервиса.

В серии с фиксированным бюджетом сохранялись суммарные 1 CPU, 512 MiB RAM и 16 соединений пула API:

Реплики CPU на реплику RAM на реплику DB_MAX_CONNS на реплику Суммарный пул
1 1,00 512 MiB 16 16
2 0,50 256 MiB 8 16
4 0,25 128 MiB 4 16

В серии роста каждая реплика получала 0,5 CPU, 256 MiB и 8 соединений, поэтому суммарный API-бюджет менялся от 0,5 CPU/256 MiB/8 соединений до 2 CPU/1024 MiB/32 соединений. Во всех основных профилях PostgreSQL оставался на 1 CPU/512 MiB, HAProxy — 0,25 CPU/128 MiB, frontend Nginx — 0,10 CPU/64 MiB, Redis — 0,25 CPU/128 MiB. Сравнение 1/2/4 выполнялось при одинаковом concurrency 32. До и после эксперимента зафиксированы размер набора и базы: 225 626 → 299 524 сообщений и 175 406 103 → 228 793 367 байт. После любого исхода finally возвращает стенд к двум API по 0,5 CPU/256 MiB, пулу 10 на реплику и PostgreSQL с 1 CPU; успешное восстановление также записано в results.json.

Насыщение и цена реплик

Для поиска saturation point две API-реплики с суммарным 1 CPU и пулом 16 нагружались последовательностью concurrency 1/2/4/8/16/32:

Concurrency RPS p95, мс PostgreSQL CPU avg/max Ошибки
1 230,369 5,065 23,900% / 29,41% 0
2 320,190 7,196 54,987% / 62,60% 0
4 435,822 29,304 63,093% / 81,80% 0
8 470,828 56,230 65,945% / 92,98% 0
16 472,892 73,628 65,080% / 88,93% 0
32 564,012 94,785 83,825% / 107,62% 0

Заранее зафиксированное правило считает первым saturation signal шаг, где прирост RPS меньше 10%, а p95 одновременно вырастает не менее чем в 1,5 раза. Это произошло при переходе 4 → 8: throughput вырос только на 8,03%, а p95 — в 1,92 раза. При 16 клиентах прирост относительно 8 почти отсутствует (+0,44%), а p95 продолжает расти; при 32 клиентах RPS увеличивается ценой ещё большей очереди. Поэтому concurrency 8 — первый воспроизводимый saturation signal по заранее заданному правилу, а не утверждение об абсолютном максимуме системы.

При фиксированном суммарном бюджете 1/2/4 реплики дали соответственно 578,242 / 529,499 / 353,955 RPS. Четыре процесса при том же общем бюджете дали на 38,79% меньше одной реплики: дробление ресурсов добавило scheduling и pool overhead, но не увеличило общую ёмкость. В серии роста ресурсов получены 533,656 / 563,460 / 438,868 RPS. Разброс и нестрогая монотонность честно сохранены: это один прогон на одном Docker-host, где контейнеры конкурируют за общий scheduler и одну БД. Главный результат здесь не выбор «лучшего» количества реплик, а отсутствие пропорционального роста: четырёхкратный API-бюджет дал на 17,76% меньше throughput одной реплики в этом конкретном прогоне.

Доминирующее ограничение локализовано в PostgreSQL. В базовом профиле четырёх реплик API суммарно использовал в среднем 35,690% CPU из доступных 200%, HAProxy — 15,595% из 25%, тогда как PostgreSQL использовал 84,847% в среднем и достигал 101,91% лимита одного ядра. Само по себе это корреляция, поэтому выполнено контрольное изменение только одного параметра.

Подтверждённое улучшение

Для тех же четырёх API по 0,5 CPU/256 MiB, того же пула и concurrency 32 лимит PostgreSQL увеличен с 1 до 2 CPU. RPS вырос с 438,868 до 587,574 — на 33,88%; ошибок в обеих фазах не было, p95 снизился с 109,446 до 93,991 мс (-14,12%). Таким образом, снятие именно ограничения CPU БД существенно увеличило throughput и улучшило tail latency, что подтверждает исходную гипотезу.

После улучшения PostgreSQL использовал в среднем 95,573% из доступных 200%, а HAProxy — 22,350% при лимите 0,25 CPU и достигал 26,73%. То есть следующее ограничение ожидаемо сместилось к публичному балансировщику. Увеличивать API дальше без пересмотра лимита или топологии LB уже нерационально — это и есть практическая «цена масштабирования».

Полный JSON с окружением, профилями, фактически применёнными лимитами и сырыми выборками находится в evidence/grade5/results.json; агрегаты — в measurements.csv, посекундные запросы — в timeseries.csv, ресурсы — в resources.csv. Пять SVG показывают saturation curve, обе серии 1/2/4, локализацию bottleneck и контрольное улучшение.

Ограничения и следующие шаги

  • Топология однохостовая: HAProxy и PostgreSQL остаются single points of failure. Репликация БД и несколько балансировщиков в требования уровня «4» не входят.
  • Redis содержит только кэш, поэтому его потеря допустима. Отдельная персистентность Redis для корректности API не требуется.
  • Истёкшие записи идемпотентности удаляются лениво при повторном обращении к той же области ключа. Индекс по expires_at оставлен для будущей периодической очистки без изменения схемы.
  • Исследование уровня «5» выполняет по одному измеряемому прогону на профиль. Для production capacity planning нужны несколько повторов, доверительные интервалы и отдельный генератор нагрузки вне измеряемого Docker-host.
  • Rolling-сценарий заменяет бинарник без изменения схемы. Миграции выполняются однократно до API; для будущей несовместимой схемы потребуется expand/contract, поэтому одновременная работа разных schema-version сейчас не заявляется.
  • Текущий API не содержит endpoint поиска пользователей, аватаров, изменения имени/пароля и агрегатов last message/unread. Поэтому UI принимает UUID участников при создании чата, а профиль честно показывает только доступные поля. Эти функции требуют сначала расширить и зафиксировать API-контракт.
  • Однохостовая среда WSL2 не доказывает устойчивость к потере Docker-host; измерен только отказ и замена процесса API.