forked from mtusi2026/mtusi2026lab3
172 lines
16 KiB
Markdown
172 lines
16 KiB
Markdown
# Отчёт — лабораторная 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».
|