diff --git a/README_LOCAL.md b/README_LOCAL.md deleted file mode 100644 index 7dc37aee..00000000 --- a/README_LOCAL.md +++ /dev/null @@ -1,22 +0,0 @@ -# Быстрый запуск на Windows (оценка 3) - -1. Сделать fork lab3 и клонировать свою ветку. -2. Скопировать **содержимое** этого архива в корень форка (не заменять `.git`). -3. В PowerShell: `Copy-Item .env.example .env`; задать пароль в `.env`. -4. `docker compose --env-file .env up -d --build`. -5. `docker compose --env-file .env ps` — postgres, redis, api1, api2, lb healthy/up; migrate exited 0. -6. `py -3 tests/smoke.py --base-url http://localhost:8080`. -7. Для автоматического теста отказа используйте WSL/Git Bash с Docker CLI и `sh`-скриптом. -8. После теста отказа: `docker compose --env-file .env up -d --no-deps api1 api2`. -9. Проверить `git status`, затем коммит и push. - -**Важно:** если lab2 ещё использует порт 8080, остановите его: `docker compose down` из каталога lab2 (без `-v`). -Старый volume lab2 не переносится автоматически; lab3 создаёт собственную базу. -Никогда не коммитьте `.env`. - -Дополнительная проверка конкурентной идемпотентности: -`py -3 tests/idempotency_concurrent.py --base-url http://localhost:8080`. - -Для запуска `make test-failover` и `make test-persistence` из WSL выполните -команды из корня проекта с доступом к Docker Desktop. Скрипты остановки и -перезапуска работают с сервисами именно текущего Compose-проекта. diff --git a/REPORT.md b/REPORT.md index 9492a0b6..e243aa77 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,52 +1,161 @@ -# Отчёт — лабораторная работа №3 +# Отчёт — лабораторная 3 -## Целевая оценка -3 (работающий минимум). Используется Go REST API из лабораторной №2. +- **Автор, группа:** Федоров Арсений, БПИ2302. +- **Целевая оценка:** 3. **Трек 5:** не заявлен. +- **Репозиторий:** https://gitea.privcloud.tech/Fedoroff/mtusi2026lab3 +- **Ветка:** `solution/BPI2302-fedorov`. +- **Подтверждённый опубликованный коммит до обновления отчёта:** `35ae6f7` (`feat: implement lab3 load balancing and idempotency`). Коммит с данным отчётом будет создан отдельно; его хеш и ссылку на PR можно добавить после публикации. +- **Источники:** задание и README лабораторной №3, контракт `contracts/openapi.json`, код и результаты лабораторной №2, официальная документация Go, Docker Compose, Nginx, PostgreSQL и Redis. +- **Библиотеки:** зависимости Go перечислены в `go.mod` / `go.sum` (в частности, pgx, go-redis и google/uuid); образы инфраструктуры определены в `compose.yaml`. +- **Использование ИИ:** ChatGPT использовался для подготовки и исправления кода, конфигурации Docker/Nginx, тестов и документации, а также для разбора ошибок Windows/Python. Команды и сценарии, перечисленные как успешные ниже, запускались локально пользователем. ИИ не заменяет фактическую проверку и оценивание преподавателем. -## Архитектура -Клиент → Nginx (localhost:8080) → api1 / api2 → общая PostgreSQL и Redis. -Обе API-реплики без локального состояния пользователей, сообщений и сессий. -Токены проверяются по общей PostgreSQL; Redis используется как общий кэш. +## Запуск из чистого clone -## Запуск -1. Скопировать `.env.example` в `.env`, заполнить POSTGRES_PASSWORD. -2. `docker compose --env-file .env up -d --build`. -3. `docker compose --env-file .env ps`. -4. `py -3 tests/smoke.py --base-url http://localhost:8080`. +**Среда фактической проверки:** Windows, PowerShell, Docker Desktop / Docker Compose, Python 3.10.5; тесты Go запускались в контейнере `golang:1.25.0-alpine`. В `compose.yaml` использовались PostgreSQL `16.10-alpine`, Redis `7.4.6-alpine`, Nginx `1.29-alpine`. Для запуска требуются Git, Docker с Compose и свободный порт `127.0.0.1:8080`. Для Python-тестов на Windows требуется установленный Python с командой `py -3`; `make` — для запуска целей Makefile. -Миграции выполняются единственным сервисом `migrate`, завершение которого -предшествует запуску обеих API-реплик. Миграция 002 добавляет общую таблицу -идемпотентности; она и сообщение фиксируются в одной транзакции. +```powershell +# Получить исходники и перейти на ветку решения +git clone https://gitea.privcloud.tech/Fedoroff/mtusi2026lab3.git +cd mtusi2026lab3 +git switch solution/BPI2302-fedorov -## Балансировка и отказ -Nginx round-robin, Docker DNS resolver 127.0.0.11, обновление DNS каждые 2 с, -проверка соединений при запросе и пассивное исключение backend после ошибки -на 2 с. Переключение обычно происходит сразу при повторе через другую реплику; -время восстановления требуется измерить на реальном Docker-стенде. +# Создать локальную конфигурацию; вручную заполнить требуемые значения +Copy-Item .env.example .env +notepad .env -API имеет /health/live и /health/ready; заголовок X-Instance-Id принимает -значения api1/api2. Graceful shutdown по SIGTERM — до 8 секунд. +# Собрать и запустить инфраструктуру и API +docker compose --env-file .env up -d --build -## Идемпотентность -`Idempotency-Key` обязателен для POST /api/v1/chats/{chat_id}/messages. -Формат ASCII `[A-Za-z0-9._:-]{1,128}`. Область ключа: отправитель + чат + ключ. -Уникальный PK в PostgreSQL сериализует конкурентные запросы; одинаковый -текст возвращает исходный Message и HTTP 201, другой текст — 409. -Срок удержания записи: минимум 24 часа (устаревшая запись очищается при -повторном использовании того же ключа). При сбое транзакции нет ни сообщения, -ни зафиксированного ключа. Авторизация и членство проверяются до операции. +# Проверить контейнеры (в том числе завершившийся с кодом 0 migrate) +docker compose --env-file .env ps -a +``` -## Проверки и доказательства -Проверить на машине с Docker: -- `make check` / `make test` (или `py -3 tests/smoke.py ...`). -- `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (Linux/WSL). -- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` (Linux/WSL). -- `docker compose --env-file .env up -d --no-deps api1 api2` после failover. -- Повторить отказ, выбрав вторую реплику; собрать вывод в evidence/. +Локальный оператор задаёт значения из `.env.example` в `.env`, включая пароль БД; **не публикует `.env` и не вставляет секреты в отчёт**. Миграции выполняет отдельный сервис `migrate` в составе Compose; успешное завершение подтверждается `Exited (0)`. Два экземпляра API (`api1`, `api2`) должны быть `healthy`, как и PostgreSQL/Redis. Балансировщик доступен по `http://localhost:8080`. -Для Windows без WSL скрипты `.ps1` выполняются вручную, а Python failover -ожидает исполняемый POSIX hook: запускать в WSL или Git Bash с доступом к Docker. +Проверки в том же окне PowerShell: -Ограничения: PostgreSQL, Redis и LB остаются единичными точками отказа; -отказ узла Docker не покрыт. Результаты нагрузочных/отказных испытаний нельзя -считать подтверждёнными до выполнения на пользовательской машине. +```powershell +# Python 3.10 на Windows: читать UTF-8-файлы как UTF-8 +$env:PYTHONUTF8 = "1" + +# Если в Makefile установлено PYTHON ?= python3, +# использовать переносимый вызов с переопределением: +make check PYTHON="py -3" +make test PYTHON="py -3" + +# Проверка конкурентной идемпотентности +py -3 tests/idempotency_concurrent.py --base-url "http://localhost:8080" + +# Go-тесты без локальной установки Go +docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./... +``` + +**Примечание по Makefile:** во время локальной проверки команда `make` выводила `py -3 ...`, поскольку для Windows было настроено значение `PYTHON=py -3`. На Linux можно оставить стандартное `python3`. Перед сдачей следует убедиться, что текущая версия `Makefile` соответствует командам в репозитории. + +Безопасная остановка с сохранением томов и данных: + +```powershell +docker compose --env-file .env down +``` + +**Только для намеренного удаления учебных данных** (удаляет тома Compose, включая данные БД): + +```powershell +docker compose --env-file .env down -v +``` + +## Архитектура и решения + +```text +Клиент / публичные тесты + | + v +Nginx (lb, 127.0.0.1:8080) + | + +----+----+ + | | + api1 api2 (Go HTTP API; X-Instance-Id) + | | + +----+----+ + | + +-----+-----+ + | | +PostgreSQL Redis +(данные, (кеш / сессии) +транзакции, +идемпотентность) + +migrate --> PostgreSQL (отдельный одноразовый сервис миграций) +``` + +**Перенесено из лабораторной №2:** API пользователей, авторизации/сессий, чатов и сообщений; PostgreSQL, Redis, проверка JSON, обработка ошибок, публичный контракт и регрессионные тесты. + +**Изменения лабораторной №3:** два экземпляра API за Nginx, общий доступ к хранилищам, заголовок `X-Instance-Id`, идемпотентная отправка сообщений с `Idempotency-Key`, отдельный процесс миграций и сценарии проверки конкурентных запросов/остановки одной реплики. + +**Источник истины:** PostgreSQL для сохраняемых сущностей и фиксации результата создания сообщения; Redis используется как вспомогательное хранилище для работы с сессиями. Для идемпотентной записи используются ограничения/транзакции PostgreSQL (см. `migrations/002_idempotency.up.sql` и `internal/storage/message_postgres.go`). Запросы к двум API-репликам обращаются к общим хранилищам, а не к независимым базам данных. + +**Конфигурация:** шаблон переменных окружения — `.env.example`, локальные значения — `.env`; способ запуска и сервисы — `compose.yaml`, настройки балансировщика — `infra/nginx.conf`. Пароли и токены в Git не добавляются. + +## Доказательства критериев + +| Проверяемое требование | Команда / сценарий | Фактически наблюдаемый результат | Где воспроизвести / доказательство | +| --- | --- | --- | --- | +| Структура и синтаксис | `make check` с `PYTHON=py -3`, `PYTHONUTF8=1` | `PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.` | `scripts/check_contract.py`; вывод локальной проверки | +| Публичный сценарий API | `make test` с `PYTHON=py -3`, `PYTHONUTF8=1` | `PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.` | `tests/smoke.py`; вывод локальной проверки | +| Go-тесты | `docker run --rm -v "${PWD}:/app" -w /app golang:1.25.0-alpine go test ./...` | Пакеты `internal/handler` и `internal/storage`: `ok`; остальные показали `[no test files]`; ошибок `FAIL` не было | Go-тесты в `internal/handler`, `internal/storage`; вывод локальной проверки | +| Конкурентная идемпотентность | `py -3 tests/idempotency_concurrent.py --base-url "http://localhost:8080"` | `PASS: 16 concurrent retries, one message, replicas: api1, api2` | `tests/idempotency_concurrent.py`; вывод локальной проверки | +| Балансировка двух реплик | 10 запросов `GET /health/live` через Nginx, чтение `X-Instance-Id` | В ответах присутствовали `api1` и `api2` | `compose.yaml`, `infra/nginx.conf`; вывод PowerShell | +| Доступность после отказа одной реплики | `docker compose --env-file .env stop api1`; затем 5 запросов `GET /health/live` | Все пять ответов получены от `api2` | Вывод PowerShell и состояние контейнеров | +| Возврат реплики в строй | `docker compose --env-file .env up -d --no-deps api1`; затем `docker compose --env-file .env ps` | `api1` снова `healthy`; `api2`, PostgreSQL и Redis также `healthy` | Вывод `docker compose ps` | +| Миграции | `docker compose --env-file .env ps -a` | `migrate` завершился с `Exited (0)`; API и хранилища запустились | `compose.yaml`, `migrations/`; вывод `ps -a` | +| Уровень 4 | Не заявлен | Не проверялся как критерий сдачи | — | +| Трек 5 | Не заявлен | Не проверялся | — | + +**Фактические фрагменты вывода:** + +```text +make check: +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. + +make test: +PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. + +idempotency_concurrent.py: +PASS: 16 concurrent retries, one message, replicas: api1, api2 + +GET /health/live при остановленном api1: +api2 +api2 +api2 +api2 +api2 +``` + +Эти результаты получены на локальной машине, но отдельные файлы с полными логами в `evidence/` пока не приложены. Для независимого воспроизведения приведены команды и исходники тестов. Сами `make check` и `make test` не доказывают всех инфраструктурных критериев: они дополнены ручным сценарием отказа и конкурентным тестом. + +## Эксперименты и отказы + +**Гипотеза 1:** Nginx направляет запросы к обоим экземплярам API. **Метод:** десять последовательных HTTP-запросов к `/health/live` с чтением заголовка `X-Instance-Id`. **Наблюдение:** ответы от `api1` и `api2`; распределение в этом небольшом прогоне близко к чередованию. Это функциональная проверка маршрутизации, не измерение производительности. + +**Гипотеза 2:** остановка одной реплики не приводит к полной недоступности API. **Метод:** `docker compose ... stop api1`, затем пять запросов через балансировщик. **Наблюдение:** пять успешных ответов с `X-Instance-Id: api2`. После `up -d --no-deps api1` реплика вновь стала `healthy`. + +**Гипотеза 3:** конкурентные повторы одного запроса не создают дубликаты сообщения. **Метод:** `tests/idempotency_concurrent.py`, 16 одновременных повторов. **Наблюдение:** `one message`, запросы обработаны через обе реплики. + +| Воздействие | Ожидание | Фактическое наблюдение | Восстановление / данные | +| --- | --- | --- | --- | +| Запросы через Nginx при двух работающих API | Обе реплики получают запросы | Наблюдались `api1` и `api2` | Не применимо | +| Остановка `api1` | Доступность через `api2` | Пять ответов `api2` | Время переключения не измерялось; потеря данных отдельно не проверялась | +| Повторный запуск `api1` | Возврат к двум здоровым репликам | `api1` и `api2` в состоянии `healthy` | Время до `healthy` не замерялось | +| 16 конкурентных повторов с одним ключом | Одна логическая запись сообщения | Тест сообщил `one message` | Дубликаты в этом сценарии не обнаружены | + +**Условия и пределы измерения:** локальная Windows-машина с Docker Desktop; точные характеристики CPU/RAM, выделенные лимиты контейнеров, продолжительность прогрева, arrival rate, успешные RPS, число ошибок под длительной нагрузкой, p50/p95/p99 и потребление ресурсов **не фиксировались**. Проведены функциональные сценарии, а не полноценный нагрузочный бенчмарк. Утверждений об улучшении производительности или гарантированном времени восстановления не делается. + +## Ограничения и следующие шаги + +- При остановке **одного** Go API работа через оставшуюся реплику подтверждена; одновременная потеря обоих API не выдерживается. +- Nginx — один экземпляр и потенциальная единая точка отказа; отказоустойчивый кластер балансировщиков не реализован. +- PostgreSQL и Redis запущены без подтверждённого автоматического переключения на резервный узел; их отказоустойчивость не заявляется. +- Проверена конкурентная идемпотентность в одном сценарии на 16 запросов; исчерпывающие испытания при сбоях БД и во всех сетевых условиях не проводились. +- Нет измеренных RPS, p50/p95/p99, CPU/RAM и времени восстановления. Следующий шаг — выполнить повторяемый нагрузочный тест и сохранить сырые результаты без секретов. +- Локальная совместимость Python 3.10/Windows потребовала включения UTF-8 и корректного разбора дробных секунд RFC3339 в тестовом клиенте. Эти исправления должны быть включены в ветку вместе с отчётом. +- Решение ориентировано на учебную среду Docker Compose, не на промышленное развёртывание.