Files
mtusi2026lab3/REPORT.md
T
2026-10-23 16:20:43 +03:00

252 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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.