Files
mtusi2026lab3/REPORT.md
T
2026-10-21 13:51:35 +03:00

172 lines
16 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
- Текущий завершённый уровень: оценка «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`. Пример генерации синтетических
локальных значений без их вывода в терминал:
```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
```
`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`, а создание пользователя/чата контрактом не идемпотентно.
Миграции вынесены в одноразовый сервис `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».