Files
mtusi2026lab3/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор, группа: Чурилин, БВТ2301
  • Текущий завершённый уровень: оценка «3»
  • Итоговая цель: оценка «5»; трек будет выбран после реализации уровня «4»
  • 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

По этому же адресу 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, а создание пользователя/чата контрактом не идемпотентно.

Миграции вынесены в одноразовый сервис 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 идемпотентности и ключа курсора. 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

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

Проведены функциональные эксперименты устойчивости, а не capacity benchmark. Окружение: Windows + WSL2, Docker Engine 29.7.2, Docker Compose 5.5.0, две API-реплики; лимиты CPU/RAM пока не задавались, максимальный пул БД — 10 соединений на реплику. Использовались синтетические данные; отдельного прогрева и серии повторов не было. Поэтому результаты подтверждают корректность failover, идемпотентности и сохранности данных, но не предельный RPS или p50/p95/p99. Нагрузочный профиль с лимитами и повторами относится к следующему уровню.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Последовательная остановка api-2 и api-1 с восстановлением между тестами LB обслуживает через оставшуюся реплику не позднее 10 с 142 и 143 успешные записи; в обоих запусках 0 ошибок первое восстановление 0.963 и 0.750 с; подтверждённой потери или дублей нет
Рестарт PostgreSQL, Redis, API и LB без удаления volumes прежний token и данные сохраняются test-persistence завершился PASS уложилось в тайм-аут 90 с; потери данных нет
32 одновременных POST с одним Idempotency-Key один бизнес-эффект 32 ответа 201 с одним Message ID; в БД одно сообщение дубли отсутствуют

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

  • Топология однохостовая: Nginx и PostgreSQL остаются single points of failure. Репликация БД и несколько балансировщиков в требования уровня «3» не входят.
  • Redis содержит только кэш, поэтому его потеря допустима. Отдельная персистентность Redis для корректности API не требуется.
  • Истёкшие записи идемпотентности удаляются лениво при повторном обращении к той же области ключа. Индекс по expires_at оставлен для будущей периодической очистки без изменения схемы.
  • Resource limits, количественный нагрузочный эксперимент и сценарий rolling update ещё не реализованы; это следующий этап уровня «4».
  • Текущий API не содержит endpoint поиска пользователей, аватаров, изменения имени/пароля и агрегатов last message/unread. Поэтому UI принимает UUID участников при создании чата, а профиль честно показывает только доступные поля. Эти функции требуют сначала расширить и зафиксировать API-контракт.
  • Трек уровня «5» пока не заявлен: сначала необходимо завершить и измерить обязательный уровень «4».