Files
mtusi2026lab3/docs/WINDOWS.md
T
Alexey BodanyukandClaude Opus 5.5 55210c6e9c docs: DEFENSE и WINDOWS под lab3, модель данных, CI, сбор доказательств
- DEFENSE: что изменилось с lab2, путь POST с ключом, ответы на вопросы
  README, ловушки из чужих PR, периоды проверок и время обнаружения.
- WINDOWS: запуск на ноутбуке, make из PowerShell (нужен sh из Git),
  сценарий защиты по шагам README.
- DATA_MODEL: idempotency_keys и функция post_message.
- CI: test-failover с восстановлением, свои тесты.
- scripts/collect_evidence.py: все проверки на чистом clone -> evidence/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 16:03:23 +03:00

10 KiB
Raw Blame History

Запуск на ноутбуке с Windows и сценарий защиты ЛР 3

Команды — в PowerShell из папки проекта (где лежит compose.yaml). Переменные $env:... действуют до закрытия окна.

1. Что установить один раз

Программа Зачем Важно
Git for Windows clone и Git Bash путь по умолчанию C:\Program Files\Git: оттуда scripts\*.cmd запускают .sh-хуки
Docker Desktop PostgreSQL, Valkey, HAProxy, API backend WSL 2, виртуализация в BIOS; для трека 1 в Settings → Resources дать 8 CPU
Python 3.12+ secrets, публичные и свои тесты, скрипты замеров галочка Add python.exe to PATH
GNU make (необязательно) make check/test/test-failover … winget install ezwinports.make, затем новое окно PowerShell. Рецептам Makefile нужен sh: в каждом окне PowerShell один раз $env:Path += ";C:\Program Files\Git\usr\bin" (или запускать make из Git Bash). Без make те же команды есть в таблице REPORT.md

Проверка:

git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version; make --version

2. Развернуть проект (дома, заранее — нужен интернет)

git clone https://gitea.privcloud.tech/wfa/mtusi2026lab3 mtusi2026lab3
cd mtusi2026lab3
git checkout solution/bvt2302-bodanyuk
python scripts\init_secrets.py                      # случайные пароли в .\secrets (не в Git)
Copy-Item .env.example .env
docker compose --env-file .env config --quiet       # конфигурация собирается без ошибок
docker compose --env-file .env up -d --build --wait

Первый запуск качает образы (~800 МБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, обе реплики api и lb в состоянии healthy, а migrate завершился с кодом 0.

Окружение для своих тестов и скриптов (один раз):

python -m venv .venv
.venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt
.venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt
$env:PYTHONUTF8 = "1"                               # публичные тесты читают UTF-8 JSON

Проверка в браузере: http://127.0.0.1:8080/health/ready → {"status":"ok"}; Swagger — http://127.0.0.1:8080/docs; состояние балансировщика (какие реплики UP/DOWN) — http://127.0.0.1:8404/.

3. Перед защитой (в аудитории)

cd mtusi2026lab3
$env:PYTHONUTF8 = "1"
$env:Path += ";C:\Program Files\Git\usr\bin"         # sh для рецептов Makefile
docker compose up -d --wait                          # если стенд был остановлен
make check test PYTHON=python                        # или: python scripts\check_contract.py; python tests\smoke.py
python scripts\lbctl.py status                       # обе реплики UP

4. Сценарий защиты из README — по шагам

Шаг 1. ≥ 2 разных X-Instance-Id через LB с одной сессией.

python scripts\lbctl.py replicas                     # контейнеры api: имя, X-Instance-Id (= hostname), PID, IP
# Один пользователь, один токен, 6 запросов подряд через LB — номера реплик чередуются:
$u = "demo_" + (Get-Random); $p = "Demo-password-123"
Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/users -ContentType 'application/json' -Body (@{username=$u; display_name='Демо'; password=$p} | ConvertTo-Json)
$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${u}:${p}"))
$t = (Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/auth/sessions -Headers @{Authorization="Basic $basic"}).token
1..6 | ForEach-Object { (Invoke-WebRequest http://127.0.0.1:8080/api/v1/users/me -Headers @{Authorization="Bearer $t"} -UseBasicParsing).Headers['X-Instance-Id'] }

Повторный вход не нужен: сессия лежит в общем Valkey. То же автоматически: .venv\Scripts\python -m pytest student-tests\test_balancing.py -k one_session -v.

Шаг 2. Отказ реплики публичным тестом.

make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
# без make: python tests\resilience.py --mode failover --action-script scripts\stop-one.cmd

Тест сам выбирает реплику, обслужившую его первое сообщение, и передаёт её X-Instance-Id хуку. Хук останавливает именно этот контейнер и оставляет его остановленным. Вариант «падение процесса» — $env:STOP_MODE = "kill" перед командой (SIGKILL), вернуть — Remove-Item Env:STOP_MODE.

Шаг 3. Показать, какой контейнер действительно остановлен, и повторить для второй.

python scripts\lbctl.py replicas      # у остановленной: exited, exit_code 0 (stop) или 137 (kill)
python scripts\lbctl.py status        # её слот в HAProxy — MAINT/DOWN, вторая UP
docker compose logs --tail 20 api     # drain_started -> shutdown_requested -> stopped у остановленной
make restore PYTHON=python            # или: & "C:\Program Files\Git\bin\bash.exe" scripts/restore-api.sh; python scripts\lbctl.py wait-up 2
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python

Тест останавливает ту реплику, которая обслужила его первое сообщение, поэтому для второй он может снова выбрать прежнюю. Детерминированно по очереди каждую реплику останавливает серия уровня 4 (~5 мин): python bench\failover_series.py --output evidence\failover (stop, kill и pause для каждой реплики, с восстановлением предыдущей).

Шаг 4. Restart всего стенда с сохранением volumes и прежним токеном.

make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python
python scripts\lbctl.py replicas      # у всех api свежий started и новый PID; LB снова видит обе реплики
docker compose ps                     # postgres, valkey, lb — тоже «Up N seconds»

Уровень 4 вживую.

# Неготовая, но живая реплика исключается из LB (pg_hba reject и docker network disconnect), ~1 мин:
.venv\Scripts\python -m pytest student-tests\test_balancing.py -k not_ready -v -s
# Rolling update под нагрузкой (~1,5 мин): новая ревизия на обеих репликах, 0 ошибок
python bench\rolling_under_load.py --output evidence\rolling-update
# Одновременные повторы с одним ключом через разные реплики:
.venv\Scripts\python -m pytest student-tests\test_idempotency.py -k concurrent -v

Трек 1. Полная серия идёт часы, поэтому на защите — готовые результаты: evidence/track1/summary.md и графики evidence/track1/*/*/throughput.svg. Вживую можно показать профиль одной реплики (~2 мин) и одну короткую серию (~6 мин):

docker compose stop                   # основной стенд не должен мешать замеру
python bench\track1\profile.py --label demo --rate 240
python bench\track1\run.py --series demo --label now --rates 150,250,350 --repeats 1 --config replicas=2,MESSAGE_WRITE_PATH=multi --config replicas=2,MESSAGE_WRITE_PATH=function
docker compose up -d --wait           # вернуть основной стенд

Все свои тесты (~8 мин): .venv\Scripts\python -m pytest student-tests -v.

5. Если что-то пошло не так

Симптом Что сделать
error during connect … dockerDesktopLinuxEngine Docker Desktop не запущен — запустить и подождать минуту
port is already allocated на 8080/8404 занято другим стендом (lab2: docker compose -p mtusi-lab2 stop) или в .env поставить APP_PUBLISH_PORT=8081, LB_STATS_PORT=8405; тестам — --base-url http://127.0.0.1:8081 / $env:BASE_URL
secrets/... not found при up не выполнен python scripts\init_secrets.py
UnicodeDecodeError в tests\*.py не задан $env:PYTHONUTF8 = "1"
*.cmd: «не удаётся найти путь» Git установлен не в C:\Program Files\Git — поправить путь в scripts\*.cmd
make: command not found новое окно PowerShell после установки make или команды без make из REPORT.md
make: 'test' is not recognized в этом окне не добавлен C:\Program Files\Git\usr\bin в $env:Path (рецептам нужен sh)
после stop-one в LB одна реплика так и задумано; вернуть: make restore PYTHON=python
api unhealthy после сна ноутбука docker compose restart и python scripts\lbctl.py wait-up 2
нужно начать с чистого листа docker compose down -v (удаляет учебные данные) → docker compose up -d --build --wait

Остановить стенд после защиты: docker compose down (данные сохранятся) или docker compose down -v (данные удаляются).