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

139 lines
10 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.
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 3
Команды — в **PowerShell** из папки проекта (где лежит `compose.yaml`). Переменные `$env:...` действуют до закрытия окна.
## 1. Что установить один раз
| Программа | Зачем | Важно |
| --- | --- | --- |
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\*.cmd` запускают `.sh`-хуки |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, HAProxy, API | backend WSL 2, виртуализация в BIOS; для трека 1 в Settings → Resources дать **8 CPU** |
| [Python 3.12+](https://www.python.org/downloads/windows/) | 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 |
Проверка:
```powershell
git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version; make --version
```
## 2. Развернуть проект (дома, заранее — нужен интернет)
```powershell
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.
Окружение для своих тестов и скриптов (один раз):
```powershell
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. Перед защитой (в аудитории)
```powershell
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 с одной сессией.**
```powershell
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. Отказ реплики публичным тестом.**
```powershell
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. Показать, какой контейнер действительно остановлен, и повторить для второй.**
```powershell
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 и прежним токеном.**
```powershell
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 вживую.**
```powershell
# Неготовая, но живая реплика исключается из 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/summary.md) и графики `evidence/track1/*/*/throughput.svg`. Вживую можно показать профиль одной реплики (~2 мин) и одну короткую серию (~6 мин):
```powershell
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` (данные удаляются).