docs: complete lab3 report and fix Windows test compatibility

This commit is contained in:
Fedoroff
2026-10-27 20:57:41 +03:00
parent 982a3a5a38
commit 717f5aa0f2
2 changed files with 151 additions and 64 deletions
-22
View File
@@ -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-проекта.
+151 -42
View File
@@ -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, не на промышленное развёртывание.