From 90c936832c879b441009c78f7b5c0918b44a29bf Mon Sep 17 00:00:00 2001 From: Rauf Date: Tue, 10 Nov 2026 15:53:49 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B7=D0=B0=D0=BF=D0=BE=D0=BB=D0=BD?= =?UTF-8?q?=D0=B5=D0=BD=20=D0=BE=D1=82=D1=87=D1=91=D1=82=20=D0=BF=D0=BE=20?= =?UTF-8?q?=D0=BB=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82=D0=BE=D1=80=D0=BD?= =?UTF-8?q?=D0=BE=D0=B9=203?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- REPORT.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 186 insertions(+), 15 deletions(-) diff --git a/REPORT.md b/REPORT.md index c2679005..be034efe 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,208 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор / группа: Фараджев Р.Э / БПИ2303 +- Целевая оценка(3/4/5): 3 ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Prerequisites:** +- Docker Desktop для Windows (версия 4.25+) +- Go 1.22+ (локально не требуется, только в Docker) +- Python 3.10+ (для тестов) +- PowerShell 5.1+ или Git Bash + +**Команды запуска:** + +```powershell +# 1. Клонирование и переход в директорию +git clone +cd mtusi2026lab3 + +# 2. Создание .env файла (опционально, конфигурация в docker-compose.yaml) +cp .env.example .env + +# 3. Очистка старых контейнеров (если есть) +docker compose down -v + +# 4. Сборка и запуск +docker compose up -d --build + +# 5. Ожидание готовности (healthcheck ~15-20 секунд) +Start-Sleep -Seconds 20 +docker compose ps +# Все контейнеры должны быть в статусе "healthy" + +# 6. Применение миграций (ТОЛЬКО НА ОДНОЙ РЕПЛИКЕ) +docker compose exec api1 ./migrate up + +# 7. Проверка работоспособности +curl http://localhost:8080/health +# Ожидаемый ответ: {"instance":"api1","status":"ok"} или api2 + +# 8. Запуск тестов +python tests/client.py +python tests/load.py + +# 9. Безопасная остановка +docker compose down + +# 10. Удаление учебных данных (полная очистка) +docker compose down -v +``` + +**Необходимые действия оператора:** +- Миграции запускаются вручную один раз после первого поднятия +- Healthcheck автоматически проверяет готовность сервисов (15-20 сек) +- Для повторного запуска с чистыми данными: `docker compose down -v` ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +**Схема компонентов:** + +``` +Клиент (curl/Python тесты) + ↓ + HAProxy:8080 (балансировщик, round-robin) + ↓ + ─────┴─────┐ + ↓ ↓ +api1:8080 api2:8080 (Go HTTP серверы) + ↓ ↓ + └─────┬─────┘ + ↓ + PostgreSQL:5432 (общая БД) + - users (пользователи) + - sessions (сессии) + - messages (сообщения) + - idempotency_keys (идемпотентность) +``` + +**Источник истины:** PostgreSQL — единственное хранилище состояния (сессии, сообщения, ключи идемпотентности). + +**Транзакционные границы:** +- Каждая HTTP обработка — отдельная транзакция +- Идемпотентность: `BEGIN` → `SELECT FOR UPDATE` → `INSERT` → `COMMIT` +- Блокировка на уровне БД предотвращает дубли при конкурентных запросах + +**Ограничения:** +- PostgreSQL и HAProxy — единые точки отказа (не реплицированы) +- Сессии хранятся 24 часа (sessionTTL) +- Максимальный размер запроса: 1MB +- Graceful shutdown: 15 секунд + +**Что перенесено из lab2:** +- Модели данных (users, sessions, messages) +- Хэширование паролей (bcrypt) +- Миграции SQL + +**Что изменено/добавлено:** +- Docker Compose оркестрация +- HAProxy балансировщик +- Две API-реплики (api1, api2) +- X-Instance-Id заголовок +- Идемпотентность через idempotency_keys таблицу +- Healthcheck endpoints +- Graceful shutdown + +**Соответствие .env.example:** +- `DATABASE_URL` → используется в docker-compose.yaml (postgres://app:app@postgres:5432/app) +- `APP_INSTANCE_ID` → передаётся как env в контейнеры (api1/api2) +- `APP_PORT` → 8080 (внутренний порт контейнера) ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| **Публичный smoke** | `make test` или `python tests/client.py` | `All API checks passed` (12 PASS) | tests/client.py | +| **2 API-реплики** | `docker compose ps` | api1 и api2 в статусе Up (healthy) | docker-compose.yaml | +| **Одна точка входа** | `curl http://localhost:8080/health` | JSON с instance field | infra/haproxy.cfg | +| **Балансировка без sticky** | 4 запроса подряд к /health | Чередование api1/api2 | tests/load.py | +| **Общая БД и сессии** | Логин → GET /api/messages | Сессия работает на обеих репликах | cmd/server/main.go | +| **X-Instance-Id** | `curl -sI http://localhost:8080/health \| grep X-Instance-Id` | Заголовок присутствует | cmd/server/main.go | +| **Отказоустойчивость** | `docker compose stop api1` + запросы | В течение 10с запросы идут через api2 | tests/load.py | +| **Идемпотентность** | POST с Idempotency-Key дважды | Первый 201, второй 200, тот же id | cmd/server/main.go | +| **Миграции отдельно** | `docker compose exec api1 ./migrate up` | `migrate up: done` | cmd/migrate/main.go | +| **Graceful shutdown** | `docker compose stop api1` | В логах: "shutting down" | cmd/server/main.go | +| **Failover сценарий** | `python tests/load.py` | `Failover scenario passed` | tests/load.py | +| **Persistence** | `python tests/load.py` | `no duplicate messages in history` | tests/load.py | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +**Гипотеза:** Система выдерживает остановку одной API-реплики без потери данных и с минимальным временем восстановления. + +**Hardware/лимиты:** +- CPU: AMD Ryzen 7 4000 series (8 cores) +- RAM: 16 GB +- Docker limits: api1/api2 — 256MB RAM, 1.0 CPU; postgres — 512MB RAM +- OS: Windows 11 + Docker Desktop + +**Профиль нагрузки:** +- Объём данных: 1 пользователь, ~10 сообщений +- Concurrency: 20 параллельных запросов (threading) +- Длительность: ~15 секунд (включая failover) +- Прогрев: 5 запросов перед тестом + +**Результаты:** | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `docker compose stop api1` | HAProxy перенаправляет на api2 | `requests recovered within 10s (5.24s, 3 transient errors)` | 5.24 сек / 0 потерянных сообщений | +| `docker compose start api1` | api1 возвращается в ротацию | `api1 is back in rotation: ['api1', 'api2']` | ~10 сек (healthcheck) / нет | +| POST с тем же Idempotency-Key | Не создаётся дубль | `replay returns the same id (1 vs 1)` | N/A / нет дублей | +| Запросы во время failover | Кратковременные ошибки 502/503 | `3 transient errors` за 5.24 сек | N/A / допустимы | + +**Raw summary (tests/load.py):** +``` +PASS: message written before failover (got 201) +PASS: requests reached at least two replicas: ['api1', 'api2'] +PASS: docker compose stop api1 succeeded +PASS: reads recovered within 10s (5.24s, 3 transient errors) +PASS: requests still served while api1 is down +PASS: api1 left rotation, served by: ['api2'] +PASS: write works while api1 is down (got 201) +PASS: docker compose start api1 succeeded +PASS: api1 is back in rotation: ['api1', 'api2'] +PASS: history readable after failover (got 200) +PASS: message written before failover survived +PASS: no duplicate messages in history + +Failover scenario passed +``` + +**Ограничения измерения:** +- Тесты запускаются локально (сетевая задержка минимальна) +- Не измеряется p95/p99 (мало запросов) +- Docker Desktop добавляет оверхед (~10-20%) +- Не тестируется отказ PostgreSQL или HAProxy ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +**Какие отказы выдерживаются:** +- ✅ Остановка одной API-реплики (api1 или api2) +- ✅ Конкурентные запросы с одинаковым Idempotency-Key (нет дублей) +- ✅ Graceful shutdown (15s timeout) + +**Какие отказы НЕ выдерживаются:** +- ❌ Отказ PostgreSQL (единая точка отказа) +- ❌ Отказ HAProxy (единая точка отказа) +- ❌ Потеря данных при `docker compose down -v` + +**Что не реализовано:** +- Репликация PostgreSQL (master-slave) +- Healthcheck для HAProxy (external) +- Rolling update (level 4) +- Нагрузочное тестирование (ab, wrk) +- Metrics (Prometheus) и логирование (ELK) + +**Учебное упрощение:** +- Сессии не инвалидизируются при logout на всех репликах (только в БД) +- Нет rate limiting +- Нет HTTPS (только HTTP) +- Пароль тестового пользователя захардкожен в миграции + +**Следующие шаги (если нужно улучшить):** +1. Добавить репликацию PostgreSQL (Patroni или pgpool) +2. Добавить keepalived для HAProxy (VIP) +3. Реализовать circuit breaker между репликами +4. Добавить Prometheus metrics (request_count, error_rate, latency) +5. Настроить централизованное логирование (Loki + Promtail)