Files
mtusi2026lab3/REPORT.md
T

257 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
- Целевая оценка: **4**
- Commit/PR: f731f9b
- Источники, библиотеки и помощь ИИ: официальная документация Docker Compose,
HAProxy, Go/Fiber; код и инфраструктура подготовлены с помощью
DeepSeek V4.1 Flash + OpenCode
## 1. Что сделано
Рабочая база lab2 (Go + Fiber v3, PostgreSQL, Redis-сессии, миграции) доведена
до lab3:
- HAProxy стал единственной публичной точкой входа;
- запущены две API-реплики без публикации их портов;
- сессии и идемпотентность сообщений вынесены в общие хранилища;
- `X-Instance-Id` добавлен во все ответы API;
- миграции вынесены в отдельный one-shot сервис;
- настроены readiness, graceful shutdown и ограничения CPU/RAM;
- добавлены action-скрипты для restart/failover и rolling replacement;
- подготовлен профиль k6 для проверки rolling update под нагрузкой.
Обязательный контракт, `lab.json` и публичные тесты не изменялись. Существующие
неочевидные решения отмечены в коде комментариями `AGENT:`; изменения и их
обоснование записаны в `CHANGELOG.md`.
## 2. Запуск из чистого clone
Требуется Docker Engine с Compose v2 и свободный порт `8080` (или другой
`LB_PORT`). Версии образов зафиксированы в `compose.yaml`.
```sh
cp .env.example .env
# задать локальный POSTGRES_PASSWORD; остальное можно оставить по умолчанию
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make wait
```
Порядок запуска:
1. PostgreSQL и Redis проходят healthcheck.
2. Сервис `migrate` один раз применяет миграции и завершается.
3. Запускаются API-реплики с `RUN_MIGRATIONS=false`.
4. HAProxy начинает отдавать `/health/ready` только после готовности API.
Проверки:
```sh
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make test-concurrency
```
Дополнительно:
```sh
make k6 VUS=20 DURATION=60s # нагрузка через HAProxy
make validate PYTHON=.venv/bin/python
```
Остановка без удаления данных:
```sh
docker compose --env-file .env down
```
Намеренное удаление учебных данных (только отдельный стенд):
```sh
docker compose --env-file .env down -v
```
`.env` в репозиторий не попадает; в `.env.example` лежит только placeholder
пароля.
## 3. Архитектура и решения
```text
клиент
│ HTTP :8080
▼
HAProxy ── readiness /health/ready, retries, stats :8404, Prometheus /metrics
│ Docker DNS, server-template api 1..16
├──────────────┐
▼ ▼
API-1 API-2 ... API-N (Go/Fiber, без публикации портов)
│ │
└──────┬───────┘
▼
PostgreSQL ← users/chats/messages + message_idempotency
Redis ← общие сессии (AOF)
migrate — one-shot, RUN_MIGRATIONS / MIGRATE_ONLY
```
### 3.1. Компоненты и лимиты
| Компонент | Роль | Решение |
| --- | --- | --- |
| `haproxy` | LB и публичная точка входа | `server-template api 16 api:8080 resolvers docker`; health check `/health/ready` каждые 1 с, `fall 2` |
| `api` | бизнес-API | `deploy.replicas: ${API_REPLICAS:-2}`, `expose: 8080`, без `ports` |
| `migrate` | миграции | тот же образ, `MIGRATE_ONLY=true`, `restart: "no"` |
| `postgres` | источник истины | named volume `pgdata`, healthcheck, версия 16.10 |
| `redis` | общие сессии | AOF `everysec`, named volume `redisdata` |
| `k6` | нагрузка | профиль `load`, подключается только при явном запуске |
У API, PostgreSQL, Redis и HAProxy есть CPU/RAM-лимиты
(`deploy.resources.limits`, значения из `.env`). У API нет `container_name`,
поэтому Compose может масштабировать сервис.
### 3.2. Миграции
`app/cmd/server/main.go` поддерживает два режима:
- обычный API: `RUN_MIGRATIONS=false`, схемой занимается отдельный сервис;
- `MIGRATE_ONLY=true`: применить миграции, закрыть пул и выйти, не открывая
Redis.
Это убирает гонку миграций при старте нескольких реплик и при rolling update.
Миграция `0002_message_idempotency` аддитивная: старая версия приложения может
работать с уже созданной таблицей, новая версия требует её наличия. Поэтому
порядок «сначала migrate, потом новые API» безопасен.
### 3.3. `X-Instance-Id`
Middleware в `app/internal/app.go` ставит заголовок на каждый ответ, включая
health и ошибки. Значение берётся из `INSTANCE_ID`, а если он не задан — из
hostname процесса. В Compose hostname уникален для контейнера, поэтому
реплики различимы; значение не меняется в течение жизни процесса.
Если hostname получить нельзя и `INSTANCE_ID` не задан, конфигурация
завершается ошибкой. Раньше в этом случае молча подставлялось литеральное
значение `api`, из-за чего несколько процессов могли получить одинаковый
идентификатор.
### 3.4. Идемпотентность сообщений
Таблица `message_idempotency`:
- PK `(sender_id, chat_id, idempotency_key)` — ровно область «пользователь +
путь чата + ключ»; метод в текущем API только один;
- `request_hash` — SHA-256 текста сообщения;
- `message_id` — ссылка на уже созданное сообщение;
- `created_at`, `expires_at` — окно хранения (по умолчанию 24 часа).
Алгоритм в `app/internal/store/messages.go`:
1. Быстрый lookup по ключу. Если запись не истекла и hash совпал — вернуть тот же
`Message` с `201`.
2. Иначе открыть транзакцию, вставить сообщение с проверкой членства в чате,
вставить ключ через `ON CONFLICT`.
3. Если конкурентная реплика уже вставила этот ключ, транзакция текущего
запроса откатывается, и читается результат победившей реплики. При другом
hash — `409`.
4. Транзиентная ошибка не фиксирует ключ: транзакция откатывается, клиент может
повторить с тем же ключом.
Так один ключ создаёт ровно одно сообщение даже при параллельных запросах через
разные реплики. Повтор снова проходит аутентификацию и проверку доступа к чату.
### 3.5. HAProxy и graceful shutdown
- backend discovery: Docker DNS `127.0.0.11:53`, `server-template api 16` (запас
на 16 реплик — больше, чем разумный `API_REPLICAS`), поэтому
`docker compose up --scale api=N` не требует правки конфига;
- health check: `GET /health/ready`, `inter 1s`, `fall 2` — обнаружение отказа
около 2 секунд (при бюджете 10 секунд);
- `retries 2`, `option redispatch` — короткие ошибки соединения не роняют запрос;
- при SIGTERM приложение сначала перестаёт отдавать `200` на readiness, затем
ждёт до 10 секунд; у контейнера `stop_grace_period: 15s`;
- stats UI/CSV на `:8404/stats`, Prometheus на `:8404/metrics`.
### 3.6. Readiness и транзакции
`/health/ready` проверяет PostgreSQL и Redis и не захватывает прикладных
блокировок. `pgxpool.Ping` берёт соединение из пула и возвращает его через
`defer`; `store.Ping` ограничивает проверку двумя секундами.
Отдельно проверены транзакции в `CreateChat` и `CreateMessage`. Откат больше не
выполняется на неограниченном `context.Background()`: используется контекст с
таймаутом. Если PostgreSQL перестал отвечать, соединение закрывается, а
PostgreSQL трактует закрытие соединения как откат и снимает блокировки строк.
Это не даёт неудачной транзакции удерживать соединение пула и мешать readiness
других запросов. Единственная явная advisory-блокировка — миграционная; она
снимается в `defer` с собственным таймаутом.
## 4. Доказательства критериев
| Критерий | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/grade-3-4.md` |
| Офлайн-проверки | `make check` | `PASS: offline skeleton...` | `evidence/grade-3-4.md` |
| OpenAPI | `make validate PYTHON=.venv/bin/python` | `PASS: full OpenAPI 3.1...` | `evidence/grade-3-4.md` |
| ≥2 реплики, одна сессия | 10 запросов `/health/live` через LB | 2 разных `X-Instance-Id` | `evidence/grade-3-4.md` |
| Остановка одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 120–121 запись, 0–1 ошибка, восстановление 2.54–2.93 с | `evidence/grade-3-4.md` |
| Сохранность после restart | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и bearer-токен сохранились | `evidence/grade-3-4.md` |
| Конкурентная идемпотентность | `make test-concurrency` | 12 запросов, 2 реплики, 1 сообщение, другой body → 409 | `evidence/grade-3-4.md` |
| CPU/RAM-лимиты, API без host ports | `compose.yaml`, `docker compose ps` | API только `expose`, лимиты заданы | `compose.yaml` |
| Rolling update под нагрузкой | `scripts/rolling-update.sh 2` + k6 20 VU/60 с | 41 605 итераций, 0 failed checks, p95 55.27 мс | `evidence/k6-rolling-20vu-60s.json` |
| Миграции однократно | `migrate` service, API `RUN_MIGRATIONS=false` | `migrate` завершился, API healthy | `compose.yaml`, `app/cmd/server/main.go` |
Проверки HTTP запускались из контейнера в сети стенда: в рабочей оболочке
published ports были изолированы от хоста. Это ограничение среды, а не
приложения; на обычной машине команды `make test`/`make test-failover`
запускаются с хоста.
## 5. Эксперименты и отказы
### 5.1. Отказ одной API-реплики
| Что сделано | Ожидание | Наблюдение | Восстановление |
| --- | --- | --- | --- |
| Остановлена одна API-реплика при живой второй | LB исключает её, подтверждённые данные и сессия целы | 2 реплики до отказа; 120–121 успешная запись; 0–1 краткая ошибка | 2.54–2.93 с до первой успешной записи |
| Вручную остановлена вторая реплика | Трафик переходит на оставшуюся | 1698 успешных записей, 1 ошибка; обе реплики наблюдались до отказа | вторая реплика восстановлена через `up` |
Ошибка на границе отказа ожидаема: клиент мог отправить запрос в момент, когда
процесс уже остановлен, но HAProxy ещё не убрал backend. Повтор с тем же
`Idempotency-Key` не создал дубль.
### 5.2. Rolling update под нагрузкой
`scripts/rolling-update.sh 2` собирает образ и поочерёдно заменяет контейнеры:
останавливает один, удаляет, создаёт replacement, ждёт health и только потом
переходит к следующему. Во время этого k6 писал сообщения 20 VU в течение 60 с.
| Метрика | Значение |
| --- | ---: |
| Всего запросов | 41 608 |
| Итераций | 41 605 |
| Ошибок проверок | 0 |
| p95 | 55.27 мс |
| p99 | 71.15 мс |
Это подтверждает, что последовательная замена не рвёт поток целиком: HAProxy
успевает исключить остановленный backend. Сырой summary:
`evidence/k6-rolling-20vu-60s.json`.
## 6. Ограничения
- Один Docker-host: потеря узла не переживается. HAProxy, PostgreSQL и Redis
остаются единичными точками отказа; API-реплики не делают БД
высокодоступной.
- PostgreSQL не реплицирован. При потере `pgdata` данные теряются; Redis AOF
спасает сессии от рестарта, но не от потери диска.
- Compose — не Swarm: rolling-скрипт делает поочерёдную замену, но не даёт
маршрутизации между узлами.
- Профиль k6 — write-only. Он выбран намеренно: проверяется запись,
идемпотентность и БД; чтение и смешанный профиль — отдельный эксперимент.
- `X-Instance-Id` здесь — hostname контейнера, не скрыт.
- Проверка пароля и ветка «пользователь не найден» имеют разное время
выполнения: для неизвестного username Argon2 не запускается. Теоретически
это позволяет перечислять имена по времени ответа. Контракт требует только
одинаковый `401` и challenge; в lab3 временная атака не устраняется.