diff --git a/REPORT.md b/REPORT.md index d6f0b8d..152bba2 100644 --- a/REPORT.md +++ b/REPORT.md @@ -2,17 +2,17 @@ - Автор, группа: Боданюк Алексей, БВТ2302 - Целевая оценка: **5**, трек 2 «План запроса и восстановление» -- Ветка: `solution/bvt2302-bodanyuk`. Форк: ``. PR: «ЛР 2 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab2 +- Ветка: `solution/bvt2302-bodanyuk`. Форк: `https://gitea.privcloud.tech/wfa/mtusi2026lab2`. PR: «ЛР 2 — БВТ2302 — Боданюк — на 5» в mtusi2026/mtusi2026lab2 - Стек: Python 3.13.16, Starlette 1.7.0, uvicorn 0.54.0, psycopg 3.3.6 + psycopg-pool 3.3.3, redis-py 8.1.0 (протокол Valkey), argon2-cffi 25.1.0; PostgreSQL 18.6, Valkey 8.1.3. Все образы закреплены по тегу и digest, все Python-пакеты — по хешам ([requirements.txt](requirements.txt)) - Источники: README, COURSE, контракт ([openapi.json](contracts/openapi.json), [семантика](contracts/README.md)), документация PostgreSQL (transactions, EXPLAIN, pg_dump/pg_restore, pgbench), Valkey persistence, RFC 7617, OWASP Password Storage Cheat Sheet (параметры Argon2id). Учтены замечания преподавателя к PR других студентов этого репозитория (см. раздел «Проверки, на которых ловили другие работы») -- Помощь ИИ: код, тесты, скрипты эксперимента и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже, их вывод лежит в [evidence/](evidence/). Пояснения для защиты — [docs/DEFENSE.md](docs/DEFENSE.md) +- Помощь ИИ: код, тесты, скрипты эксперимента и черновик отчёта написаны с помощью ИИ-ассистента Claude Code (Anthropic). Все команды и замеры реально выполнены на стенде ниже, их вывод лежит в [evidence/](evidence/). Пояснения для защиты — [docs/DEFENSE.md](docs/DEFENSE.md), запуск на Windows и сценарий защиты по шагам — [docs/WINDOWS.md](docs/WINDOWS.md) ## Запуск из чистого clone Нужны Git, Docker с Compose v2 (проверено: Docker 29.8.0, Compose 5.5.1) и Python 3.9+ (secrets, публичные тесты). Для своих тестов нужен venv. Учётные данные не хранятся в Git: их создаёт скрипт. ```sh -git clone mtusi2026lab2 && cd mtusi2026lab2 && git checkout solution/bvt2302-bodanyuk +git clone https://gitea.privcloud.tech/wfa/mtusi2026lab2 mtusi2026lab2 && cd mtusi2026lab2 && git checkout solution/bvt2302-bodanyuk python3 scripts/init_secrets.py # случайные локальные пароли -> ./secrets (git-ignored), идемпотентно cp .env.example .env # необязательно: значения по умолчанию заданы в compose.yaml docker compose --env-file .env config --quiet diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md new file mode 100644 index 0000000..649152a --- /dev/null +++ b/docs/WINDOWS.md @@ -0,0 +1,134 @@ +# Запуск на ноутбуке с Windows и сценарий защиты + +Все команды — в **PowerShell**, из папки проекта. Внутри одного окна PowerShell переменные `$env:...` действуют до его закрытия. + +## 1. Что установить один раз + +| Программа | Зачем | Важно | +| --- | --- | --- | +| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | ставить в путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\restart.cmd` запускает `restart.sh` | +| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, API | backend WSL 2; в BIOS включена виртуализация; после установки перезагрузка | +| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные тесты, свои тесты | галочка **Add python.exe to PATH**. Если `python` открывает Microsoft Store — отключить «Псевдонимы выполнения приложений» для python в настройках Windows | + +Проверка: + +```powershell +git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version +``` + +Docker Desktop должен быть **запущен** (кит в трее не мигает). + +## 2. Развернуть проект (дома, заранее — нужен интернет) + +```powershell +git clone https://gitea.privcloud.tech/wfa/mtusi2026lab2 mtusi2026lab2 +cd mtusi2026lab2 +git checkout solution/bvt2302-bodanyuk +python scripts\init_secrets.py +Copy-Item .env.example .env +docker compose --env-file .env up -d --build --wait +``` + +Первый запуск скачивает образы (~700 МБ) и собирает API — 3–10 минут. Сделайте это **дома**: в аудитории сеть может быть медленной. Последняя команда завершается, когда все сервисы `healthy`. + +Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`, Swagger — http://127.0.0.1:8080/docs. + +Окружение для своих тестов (один раз): + +```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 +``` + +Активировать venv не нужно: везде вызывается `.venv\Scripts\python` напрямую, поэтому политика выполнения PowerShell не мешает. + +## 3. Перед защитой (в аудитории) + +```powershell +cd mtusi2026lab2 +docker compose up -d --wait # если стенд был остановлен +$env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON +python tests\smoke.py # PASS: lab2 public API scenario +``` + +## 4. Сценарий защиты из README — команды по шагам + +**Шаг 1. Миграции к пустому volume, пользователи, вход, сообщение.** + +```powershell +docker compose down -v # стереть учебные данные (volumes) +docker compose up -d --wait # postgres и valkey пустые -> migrate применяет схему +docker compose logs migrate # "0001_init: applied" +docker compose run --rm migrate # повтор: "already applied, skipped" +``` + +Дальше в Swagger (http://127.0.0.1:8080/docs): +1. `POST /api/v1/users` — создать двух пользователей (пароль 12+ символов). +2. **Authorize → basicAuth**: логин и пароль первого; `POST /api/v1/auth/sessions` — скопировать `token`. +3. **Authorize → bearerAuth**: вставить токен. +4. `POST /api/v1/chats` (в `member_ids` — оба id) → `POST /api/v1/chats/{chat_id}/messages` → `GET` истории. + +**Шаги 2–3. Перезапуск API и хранилищ с сохранением volumes, тот же токен; logout → 401; короткий TTL.** + +```powershell +python tests\resilience.py --mode persistence --action-script scripts\restart.cmd # PASS +docker compose ps # у api, postgres, valkey свежее время запуска +``` + +В Swagger тот же токен по-прежнему работает. `DELETE /api/v1/auth/sessions/current` → 204, затем любой запрос → 401. + +Короткий TTL: + +```powershell +$env:SESSION_TTL_SECONDS = "2"; docker compose up -d --wait api +docker compose exec api printenv SESSION_TTL_SECONDS # 2 +# в Swagger: войти, сразу GET /users/me -> 200, через 3 секунды -> 401 +Remove-Item Env:SESSION_TTL_SECONDS; docker compose up -d --wait api # вернуть 3600 +``` + +**Шаг 4. Роль Valkey, план SQL, ошибка зависимости.** + +```powershell +# Сессии лежат только в Valkey: ключи session:, самих токенов там нет +# (без двойных кавычек внутри: PowerShell 5.1 ломает их при передаче в docker) +docker compose exec valkey sh -c 'REDISCLI_AUTH=$(cat /run/secrets/valkey_password) valkey-cli --scan --pattern ''session:*''' + +# План: поздняя страница по индексу (Index Cond) против IS NULL OR и OFFSET, 20 000 сообщений +.venv\Scripts\python scripts\explain_history.py + +# Ошибка зависимости: с действующим токеном -> 503, без токена -> 401, после старта всё работает +docker compose stop valkey # или: docker compose pause postgres +# в Swagger: GET /users/me -> 503 unavailable; GET /health/ready -> 503 +docker compose start valkey # или: docker compose unpause postgres +``` + +Всё то же автоматически, с восстановлением в `finally`, около 1 минуты: + +```powershell +.venv\Scripts\python -m pytest student-tests\test_failures.py -v +``` + +**Трек 2 вживую.** + +```powershell +.venv\Scripts\python bench\track2\backup_restore.py --repeats 1 # ~1 мин: dump во время записи -> restore в новый контейнер -> сверка +``` + +Скрипт печатает время дампа и восстановления, `reconciled: true` и сколько сообщений записано после снимка (RPO). Полный замер планов идёт ~25 минут, поэтому на защите показывайте готовые результаты: `evidence\track2\summary.md` и `evidence\track2\plans.png`. При желании можно запустить `.venv\Scripts\python bench\track2\index_sizes.py` (~2 мин). + +**Все свои тесты** (~3,5 мин): `.venv\Scripts\python -m pytest student-tests -v`. + +## 5. Если что-то пошло не так + +| Симптом | Что сделать | +| --- | --- | +| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту | +| `port is already allocated` на 8080 | в `.env` поставить `APP_PUBLISH_PORT=8081`; дальше тесты с `--base-url http://127.0.0.1:8081` (smoke и resilience), для pytest — `$env:BASE_URL="http://127.0.0.1:8081"` | +| `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` | +| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` | +| `restart.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\restart.cmd` | +| api `unhealthy` после сна ноутбука | `docker compose restart` и подождать `docker compose ps` | +| нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --wait` | + +Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).