16 KiB
Отчёт — лабораторная 3
- Автор, группа: Чурилин, БВТ2301
- Текущий завершённый уровень: оценка «3»
- Итоговая цель: оценка «5»; трек будет выбран после реализации уровня «4»
- Commit/PR: заполняется автором после локального коммита и публикации
- Использованные источники и библиотеки: преподавательские README/OpenAPI/tests, документация Go, pgx, PostgreSQL, Docker Compose и Nginx. Для разбора архитектуры, рефакторинга, реализации и проверок использовался 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
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-сессии и проверка членства в чате.
Доказательства критериев
| Критерий 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 |
Эксперименты и отказы
Проведены функциональные эксперименты устойчивости, а не 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».
- Frontend на React + TypeScript + Vite будет отдельным этапом и отдельным коммитом после фиксации уровня «3». Тогда же будет спроектирована cookie-based авторизация с учётом текущего bearer-контракта API.
- Трек уровня «5» пока не заявлен: сначала необходимо завершить и измерить обязательный уровень «4».