From 84dd7fec0a6e9772a2f5e04ea899d4cef4f886cc Mon Sep 17 00:00:00 2001 From: anastasia Date: Thu, 15 Oct 2026 13:43:39 +0300 Subject: [PATCH 01/19] feat: add replicated messenger and reproducible lab3 stand --- .codex/rules/messenger.rules | 147 ++ .dockerignore | 14 + .env.example | 14 +- .gitignore | 5 + AGENTS.md | 354 ++++ Dockerfile | 57 + KNOWN_ISSUES.md | 13 + Makefile | 261 +++ REPORT.md | 495 ++++- alembic.ini | 13 + bench/AGENTS.md | 190 ++ bench/RUNBOOK.md | 326 +++ bench/analysis.py | 546 ++++++ bench/bench.compose.yml | 73 + bench/bench.env | 7 + bench/common.py | 867 ++++++++ bench/compare.py | 248 +++ bench/loadgen.py | 1003 ++++++++++ bench/plots.py | 412 ++++ bench/run.py | 1854 ++++++++++++++++++ bench/sampler.py | 182 ++ compose.yaml | 210 ++ evidence/AGENTS.md | 62 + evidence/failover/failover-each.txt | 127 ++ evidence/replicas/instances.txt | 35 + evidence/replicas/stand.txt | 60 + evidence/rollout/rolling-update.txt | 66 + evidence/stand/early-stop.txt | 41 + evidence/stand/fresh-copy.txt | 92 + evidence/stand/migrations.txt | 61 + evidence/stand/persistence.txt | 43 + evidence/tests/failure-checks.txt | 83 + evidence/tests/student-test-lb.txt | 71 + evidence/tests/test-isolated.txt | 71 + infra/AGENTS.md | 216 ++ infra/haproxy/haproxy.cfg | 129 ++ infra/valkey/valkey.conf | 15 + migrations/AGENTS.md | 86 + migrations/env.py | 82 + migrations/script.py.mako | 25 + migrations/versions/0001_messenger_schema.py | 147 ++ migrations/versions/0002_idempotency_keys.py | 81 + pyproject.toml | 60 + requirements.txt | 196 ++ scripts/lab3.py | 251 +++ scripts/restart.sh | 20 + scripts/rolling-update.sh | 422 ++++ scripts/stop-one.sh | 82 + src/AGENTS.md | 210 ++ src/__init__.py | 7 + src/__main__.py | 10 + src/api/AGENTS.md | 146 ++ src/api/__init__.py | 0 src/api/deps.py | 170 ++ src/api/handlers.py | 121 ++ src/api/identity.py | 89 + src/api/request_id.py | 83 + src/api/routes/__init__.py | 24 + src/api/routes/chats.py | 46 + src/api/routes/health.py | 32 + src/api/routes/messages.py | 51 + src/api/routes/sessions.py | 29 + src/api/routes/users.py | 24 + src/api/schemas.py | 133 ++ src/cache.py | 128 ++ src/clock.py | 51 + src/config.py | 287 +++ src/constants.py | 67 + src/db.py | 168 ++ src/domain.py | 90 + src/early_stop.py | 63 + src/errors.py | 96 + src/healthcheck.py | 25 + src/log.py | 81 + src/main.py | 143 ++ src/pagination.py | 88 + src/passwords.py | 74 + src/services/AGENTS.md | 93 + src/services/__init__.py | 11 + src/services/access.py | 21 + src/services/chats.py | 56 + src/services/messages.py | 87 + src/services/sessions.py | 93 + src/services/users.py | 30 + src/storage/AGENTS.md | 108 + src/storage/__init__.py | 9 + src/storage/base.py | 120 ++ src/storage/cached.py | 177 ++ src/storage/postgres.py | 386 ++++ src/storage/tables.py | 204 ++ student-tests/AGENTS.md | 113 ++ student-tests/conftest.py | 119 ++ student-tests/fault_hook.py | 251 +++ student-tests/helpers.py | 244 +++ student-tests/stand.compose.yml | 21 + student-tests/stand.env | 9 + student-tests/stand.py | 394 ++++ student-tests/test_auth.py | 196 ++ student-tests/test_balancing.py | 77 + student-tests/test_cache.py | 61 + student-tests/test_failures.py | 360 ++++ student-tests/test_idempotency.py | 251 +++ student-tests/test_race.py | 214 ++ student-tests/test_request_id.py | 86 + student-tests/test_rubric.py | 228 +++ uv.lock | 789 ++++++++ 106 files changed, 17235 insertions(+), 24 deletions(-) create mode 100644 .codex/rules/messenger.rules create mode 100644 AGENTS.md create mode 100644 Dockerfile create mode 100644 KNOWN_ISSUES.md create mode 100644 alembic.ini create mode 100644 bench/AGENTS.md create mode 100644 bench/RUNBOOK.md create mode 100644 bench/analysis.py create mode 100644 bench/bench.compose.yml create mode 100644 bench/bench.env create mode 100644 bench/common.py create mode 100644 bench/compare.py create mode 100644 bench/loadgen.py create mode 100644 bench/plots.py create mode 100644 bench/run.py create mode 100644 bench/sampler.py create mode 100644 compose.yaml create mode 100644 evidence/AGENTS.md create mode 100644 evidence/failover/failover-each.txt create mode 100644 evidence/replicas/instances.txt create mode 100644 evidence/replicas/stand.txt create mode 100644 evidence/rollout/rolling-update.txt create mode 100644 evidence/stand/early-stop.txt create mode 100644 evidence/stand/fresh-copy.txt create mode 100644 evidence/stand/migrations.txt create mode 100644 evidence/stand/persistence.txt create mode 100644 evidence/tests/failure-checks.txt create mode 100644 evidence/tests/student-test-lb.txt create mode 100644 evidence/tests/test-isolated.txt create mode 100644 infra/AGENTS.md create mode 100644 infra/haproxy/haproxy.cfg create mode 100644 infra/valkey/valkey.conf create mode 100644 migrations/AGENTS.md create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/0001_messenger_schema.py create mode 100644 migrations/versions/0002_idempotency_keys.py create mode 100644 pyproject.toml create mode 100644 requirements.txt create mode 100755 scripts/lab3.py create mode 100755 scripts/restart.sh create mode 100755 scripts/rolling-update.sh create mode 100755 scripts/stop-one.sh create mode 100644 src/AGENTS.md create mode 100644 src/__init__.py create mode 100644 src/__main__.py create mode 100644 src/api/AGENTS.md create mode 100644 src/api/__init__.py create mode 100644 src/api/deps.py create mode 100644 src/api/handlers.py create mode 100644 src/api/identity.py create mode 100644 src/api/request_id.py create mode 100644 src/api/routes/__init__.py create mode 100644 src/api/routes/chats.py create mode 100644 src/api/routes/health.py create mode 100644 src/api/routes/messages.py create mode 100644 src/api/routes/sessions.py create mode 100644 src/api/routes/users.py create mode 100644 src/api/schemas.py create mode 100644 src/cache.py create mode 100644 src/clock.py create mode 100644 src/config.py create mode 100644 src/constants.py create mode 100644 src/db.py create mode 100644 src/domain.py create mode 100644 src/early_stop.py create mode 100644 src/errors.py create mode 100644 src/healthcheck.py create mode 100644 src/log.py create mode 100644 src/main.py create mode 100644 src/pagination.py create mode 100644 src/passwords.py create mode 100644 src/services/AGENTS.md create mode 100644 src/services/__init__.py create mode 100644 src/services/access.py create mode 100644 src/services/chats.py create mode 100644 src/services/messages.py create mode 100644 src/services/sessions.py create mode 100644 src/services/users.py create mode 100644 src/storage/AGENTS.md create mode 100644 src/storage/__init__.py create mode 100644 src/storage/base.py create mode 100644 src/storage/cached.py create mode 100644 src/storage/postgres.py create mode 100644 src/storage/tables.py create mode 100644 student-tests/AGENTS.md create mode 100644 student-tests/conftest.py create mode 100755 student-tests/fault_hook.py create mode 100644 student-tests/helpers.py create mode 100644 student-tests/stand.compose.yml create mode 100644 student-tests/stand.env create mode 100644 student-tests/stand.py create mode 100644 student-tests/test_auth.py create mode 100644 student-tests/test_balancing.py create mode 100644 student-tests/test_cache.py create mode 100644 student-tests/test_failures.py create mode 100644 student-tests/test_idempotency.py create mode 100644 student-tests/test_race.py create mode 100644 student-tests/test_request_id.py create mode 100644 student-tests/test_rubric.py create mode 100644 uv.lock diff --git a/.codex/rules/messenger.rules b/.codex/rules/messenger.rules new file mode 100644 index 00000000..cae5163b --- /dev/null +++ b/.codex/rules/messenger.rules @@ -0,0 +1,147 @@ +# Правила команд Codex для проекта (execpolicy, Starlark). +# +# Действуют на команды, которые Codex запускает вне sandbox (docker, сеть): +# allow — без вопроса; +# prompt — спросить пользователя перед каждым запуском; +# forbidden — не запускать никогда. +# Несколько совпавших правил — побеждает самое строгое (forbidden → +# prompt → allow). pattern — точный префикс аргументов команды; список в +# позиции — варианты. match / not_match — примеры, которые Codex +# проверяет при загрузке правил. +# +# Файл загружается, только если проект доверенный (слой .codex/ проекта +# trusted). После правки — перезапустить Codex. Проверка правила: +# codex execpolicy check --pretty --rules .codex/rules/messenger.rules -- git push +# +# Источник запретов — корневой AGENTS.md, раздел 2 «Нельзя»; правила их +# дублируют на уровне команд, но не заменяют. + +# --- git: только смотреть; изменения — по просьбе пользователя ------------- + +prefix_rule( + pattern = ["git", ["status", "diff", "log", "show", "rev-parse", "ls-files"]], + decision = "allow", + justification = "Read-only git commands are always fine.", + match = ["git status", "git diff --stat", "git log --oneline -5"], + not_match = ["git commit -m x"], +) + +prefix_rule( + pattern = ["git", ["commit", "checkout", "switch", "reset", "stash", "rebase", "merge", "restore", "tag", "branch"]], + decision = "prompt", + justification = "AGENTS.md: git changes only when the user asked for them (commit message in English, conventional style).", + match = ["git commit -m 'feat: x'", "git reset --hard", "git checkout main"], + not_match = ["git status"], +) + +prefix_rule( + pattern = ["git", ["push", "clean"]], + decision = "forbidden", + justification = "Never push or clean the working tree: the user does it; git clean would delete evidence and local files.", + match = ["git push", "git push origin main", "git clean -fdx"], +) + +# --- данные стендов: удаление только с согласия ----------------------------- + +prefix_rule( + pattern = ["make", "wipe"], + decision = "prompt", + justification = "make wipe deletes the working stand volume (all data). Ask the user first (AGENTS.md, section 2, item 8).", + match = ["make wipe"], +) + +prefix_rule( + pattern = ["docker", "compose", "down", "-v"], + decision = "prompt", + justification = "down -v deletes volumes. The bench and test stands remove their own projects themselves; for the working stand ask the user.", + match = ["docker compose down -v", "docker compose down -v --remove-orphans"], + not_match = ["docker compose down"], +) + +prefix_rule( + pattern = ["docker", "volume", ["rm", "prune"]], + decision = "prompt", + justification = "Deleting volumes deletes data: only bench leftovers (vlad-bench*) and only with the user's consent.", + match = ["docker volume rm vlad-bench_pgdata", "docker volume prune -f"], +) + +prefix_rule( + pattern = ["docker", ["rm", "kill", "stop", "pause"]], + decision = "prompt", + justification = "Only own containers (vladimirceva-lab3*, vlad-bench*); never containers of other projects.", + match = ["docker rm -f vlad-bench-gen", "docker stop some-container"], +) + +prefix_rule( + pattern = ["docker", ["system", "builder", "image", "container", "network"], "prune"], + decision = "forbidden", + justification = "Prune touches every project on this machine. Remove own leftovers by name instead (bench/AGENTS.md).", + match = ["docker system prune -af", "docker image prune -a"], +) + +# --- процессы: не убивать по порту вслепую ------------------------------------ + +prefix_rule( + pattern = [["kill", "pkill", "killall"]], + decision = "prompt", + justification = "Kill only a PID whose command is `python -m src` (AGENTS.md, section 10). A published port on macOS belongs to com.docker.backend: killing it stops Docker Desktop.", + match = ["kill 12345", "pkill -f uvicorn"], +) + +prefix_rule( + pattern = ["rm", ["-rf", "-fr", "-r"]], + decision = "prompt", + justification = "Recursive delete: label folders in evidence/ are removed only with the user's consent (bench/AGENTS.md).", + match = ["rm -rf evidence/scaling/quick-x"], +) + +# --- проект: проверки, стенд, замеры — без вопроса ---------------------------- + +prefix_rule( + pattern = [ + "make", + [ + "install", "lint", "fmt", "check", "validate", "test", "load", + "test-persistence", "test-failover", "student-test", "test-isolated", + "failure-checks", "requirements", "requirements-check", "env", + "docker-build", "up", "stop", "down", "logs", "db-up", "run", + "migrate-local", "replicas", "instances", "lb-stats", + "failover-each", "rolling-update", + "bench-failover", "bench-failover-quick", "bench-rollout", + "bench-rollout-quick", "bench-scaling", "bench-scaling-quick", + "bench-compare", "bench-plots", + ], + ], + decision = "allow", + justification = "Project targets: checks, the working stand without deleting data, bench profiles (bench/RUNBOOK.md).", + match = ["make lint", "make test-isolated", "make bench-scaling SERIES=a", "make failover-each STOP_MODE=kill"], + not_match = ["make wipe"], +) + +prefix_rule( + pattern = ["docker", ["ps", "info", "version", "inspect", "logs", "images", "events", "exec", "cp", "build", "tag", "run", "start", "unpause"]], + decision = "allow", + justification = "Inspecting and running own stand containers; deletion is covered by stricter rules above.", + match = ["docker ps -a", "docker info", "docker logs -t vlad-bench-lb"], +) + +prefix_rule( + pattern = ["docker", "compose"], + decision = "allow", + justification = "Compose of this project; down -v is prompted by the stricter rule above.", + match = ["docker compose ps", "docker compose logs api"], +) + +prefix_rule( + pattern = ["uv", ["run", "sync", "lock", "export"]], + decision = "allow", + justification = "Project environment from uv.lock; new dependencies still need the user's consent (AGENTS.md, section 2, item 11).", + match = ["uv run pytest", "uv sync", "uv run python bench/analysis.py --selftest"], +) + +prefix_rule( + pattern = [["python3", "python"], ["scripts/lab3.py", "student-tests/stand.py", "tests/smoke.py", "tests/resilience.py", "scripts/check_contract.py"]], + decision = "allow", + justification = "Project scripts on the host Python (stdlib only).", + match = ["python3 scripts/lab3.py instances", "python3 student-tests/stand.py isolated"], +) diff --git a/.dockerignore b/.dockerignore index bc16e556..75be601d 100644 --- a/.dockerignore +++ b/.dockerignore @@ -18,3 +18,17 @@ __pycache__ node_modules evidence .DS_Store +.codex +.agents +tests +student-tests +bench +contracts +infra +scripts +**/AGENTS.md +**/__pycache__ +**/*.pyc +**/.DS_Store +*.md +**/*.md diff --git a/.env.example b/.env.example index d32b9be0..fce91510 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,7 @@ # Copy to .env for your LOCAL synthetic test environment; never commit .env. # These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 +# Host process (make run); the container binds 0.0.0.0 in Dockerfile. +APP_HOST=127.0.0.1 APP_PORT=8080 APP_ENV=lab SESSION_TTL_SECONDS=3600 @@ -11,3 +12,14 @@ SESSION_STORE=postgres CACHE_URL_FILE=/run/secrets/cache_url API_REPLICAS=2 IDEMPOTENCY_TTL_SECONDS=86400 + +# Compose and make run. make env fills the empty passwords locally. +HOST_PORT=8080 +POSTGRES_USER=messenger +POSTGRES_DB=messenger +POSTGRES_PASSWORD= +POSTGRES_HOST_PORT=5433 +VALKEY_PASSWORD= +VALKEY_HOST_PORT=6380 +LOG_LEVEL=INFO +SHUTDOWN_TIMEOUT=5 diff --git a/.gitignore b/.gitignore index b5a71896..06bf6477 100644 --- a/.gitignore +++ b/.gitignore @@ -28,5 +28,10 @@ coverage/ .DS_Store .idea/ .vscode/ +# Temporary benchmark state and self-check results are not submission evidence. +bench/.bench.lock +evidence/failover/quick-*/ +evidence/rollout/quick-*/ +evidence/scaling/quick-*/ # Keep small, sanitized evidence summaries in evidence/ under version control. # Inspect git diff --cached: ignore rules are not a secret scanner. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..ed34a612 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,354 @@ +# AGENTS.md — мессенджер MTUSI, лабораторная 3 + +REST API мессенджера (пользователи, чаты, история сообщений): реплики +API за HAProxy, PostgreSQL — источник истины (данные, сессии, ключи +идемпотентности), Valkey — общий кэш карточек чатов. Код перенесён из +лабы 2 и переведён на лабу 3: `X-Instance-Id` в каждом ответе, +обязательный `Idempotency-Key` при отправке сообщения, ≥ 2 +взаимозаменяемые реплики, отказ реплики, поочерёдная замена. Цель — +оценка **«5»**: уровни 3 и 4 из `README.md` и трек 1 уровня 5 «Цена +масштабирования». + +**Состояние (14 октября 2026).** Уровень 3 и всё, что в уровне 4 не +требует нагрузки, реализовано и проверено; доказательства — `evidence/`, +отчёт — `REPORT.md`. Нагрузочный стенд (`bench/`) готов и проверен +самопроверками (`*-quick`), но замеры под нагрузкой ещё не сняты: +отказ каждой реплики и замена под нагрузкой (уровень 4), серии трека 1 +и улучшение. **Следующая работа — `bench/RUNBOOK.md`** (на устройстве, +где идут замеры); в `REPORT.md` их места помечены `TODO (Codex)`. +Гипотезы трека 1 записаны в `REPORT.md` до замеров. + +Стек: Python 3.13, FastAPI + Starlette 1.x, uvicorn, pydantic v2, +SQLAlchemy Core 2.1 + asyncpg, alembic, argon2-cffi, redis-py; +PostgreSQL 18.6, Valkey 9.1.2, HAProxy 3.4; uv (локально), pip + +`requirements.txt` с хешами (в образе), pytest + httpx. + +## 1. Где инструкции и как их читать + +Codex сам загружает `AGENTS.md` от корня репозитория до рабочего +каталога (вместе — не больше 32 КиБ). Правила слоёв лежат глубже, +поэтому **перед правкой файла прочитай каждый `AGENTS.md` на пути к +нему** (`cat`), даже если задача «на одну строку». + +| Файл | Когда читать | +|---|---| +| `AGENTS.md` (этот) | всегда: запреты, команды, карта, Definition of Done | +| `src/AGENTS.md` | любая правка в `src/`: слои, импорты, ошибки, конфиг, точка входа, логи, время | +| `src/api/AGENTS.md` | роуты, схемы, middleware, вход и Bearer, `X-Instance-Id`, `Idempotency-Key` | +| `src/services/AGENTS.md` | бизнес-правила, пароли и сессии, отправка с ключом | +| `src/storage/AGENTS.md` | PostgreSQL: транзакции, гонки, ключ идемпотентности; кэш Valkey | +| `migrations/AGENTS.md` | схема БД, новые ревизии, совместимость с работающей версией | +| `infra/AGENTS.md` | `Dockerfile`, `compose.yaml`, HAProxy и цепочка таймаутов, `scripts/*.sh`, `scripts/lab3.py` | +| `student-tests/AGENTS.md` | собственные тесты, отдельные стенды, проверки отказов | +| `evidence/AGENTS.md` | доказательства для `REPORT.md` | +| `bench/AGENTS.md` | нагрузочный стенд: методика, честность результатов | +| `bench/RUNBOOK.md` | замеры уровня 4 и трека 1 по шагам; читать перед любым `make bench-*` | + +Кроме `AGENTS.md`, Codex читает из проекта: + +- **правила команд** `.codex/rules/messenger.rules` (Starlark, + `prefix_rule`): что запускается вне sandbox без вопроса (`make …` + проекта, `docker ps/logs/compose`, `uv run`), что требует + подтверждения (git-изменения, `make wipe`, `down -v`, удаление + контейнеров и volume, `kill`, `rm -r`) и что запрещено (`git push`, + `git clean`, `docker … prune`). Загружаются, только если проект + **доверенный** (trusted); после правки — перезапустить Codex; + проверка — `codex execpolicy check --pretty --rules + .codex/rules/messenger.rules -- <команда>`. Правила дублируют раздел 2, + но не заменяют его; +- **навыки** `.agents/skills/*/SKILL.md`: `lab3-bench` — замеры по + `bench/RUNBOOK.md`, `messenger-stand` — работа со стендом. Codex + выбирает их по описанию или по `$имя`. + +Конфликт: более глубокий файл уточняет корневой, но не отменяет +раздел 2. Прямая просьба пользователя в чате важнее этих файлов, кроме +пунктов раздела 2, помеченных «спросить»: там сначала переспроси. + +## 2. Нельзя + +1. **Менять skeleton преподавателя** (спросить): `contracts/`, `tests/`, + `scripts/` (кроме своих `restart.sh`, `stop-one.sh`, + `rolling-update.sh`, `lab3.py`), `lab.json`, `README.md`, `COURSE.md`, + `CONTRIBUTING.md`, `MAINTAINERS.md`, `Dockerfile.example`, + `compose.example.yaml`, `infra/README.md`, `requirements-dev.txt`, + `evidence/README.md`, `.github/`, верх `Makefile` до строки `=====` + (цели `help`/`check`/`validate`/`test`/`load`/`test-persistence`/ + `test-failover`). Публичный тест упал — чиним приложение. +2. **Подгонять тесты под код**: ослаблять `assert`, менять ожидаемый + статус, ставить `skip`/`xfail`, удалять тест, чтобы прогон позеленел. +3. **Состояние в памяти процесса, от которого зависит корректность**: + сессии, данные и ключи идемпотентности — только PostgreSQL; Valkey — + только кэш неизменяемой карточки чата. `--workers`, gunicorn, + `reload` в образе: масштабирование — числом реплик. Sticky session + (cookie, stick-table) в HAProxy. +4. **Порты реплик наружу и `container_name` у `api`**: API — только + через HAProxy (рубрика «4»). +5. **Файлы конфигурации приложения** (`config.toml`, pydantic-settings с + файлами): настройки — только переменные окружения (`src/config.py`). +6. **JSON-логи, structlog, `print`** вместо логгера (`src/log.py`). +7. **Писать в лог** текст сообщений, `display_name`, `title`, username, + пароль, токен, их хэши, `Authorization`, `Idempotency-Key`, тела, + параметры SQL. Можно id и длины. +8. **Git без просьбы**: `commit`, `push`, `checkout`, `reset`, `stash`, + `rebase`, `clean`. Смотреть можно: `status`, `diff`, `log`. +9. **Удалять данные стенда без просьбы** (спросить): `make wipe`, + `docker compose down -v`, `docker volume rm`, `FLUSHALL` рабочего + Valkey, `TRUNCATE`/`DROP` в рабочей базе; каталоги меток в `evidence/`. +10. **Секреты и `.env`** в git, образ, `evidence/`, вывод и отчёт; `COPY . + .` в Dockerfile. Пароли и токены в командной строке не печатать. +11. **Незакреплённые версии**: `latest`, тег без digest, пакет без lock. +12. **Новая зависимость** (спросить): объяснить, зачем она и почему не + хватает stdlib и текущих пакетов; проверить точное имя пакета. +13. **Миграция, которая ломает работающую версию** (удаление, + переименование, `NOT NULL` без значения): только расширение схемы, + contract — отдельной ревизией позже (`migrations/AGENTS.md`). Править + применённую ревизию нельзя. +14. **`HTTPException`** в сервисах и хранилище, **403** для чужого чата, + **422** наружу: ошибки только через `src/errors.py`. Прозрачные + повторы `POST` (кроме отказа соединения в LB). +15. **Обходить sandbox Codex** (раздел 10): нет сети или docker — просить + одобрение или пользователя. +16. **Выдумывать результаты**: в отчёт, `REPORT.md` и `evidence/` — только + реальный вывод команд, которые ты запустил. Гипотезы трека 1 после + замеров не переписывать. +17. **Чинить попутно найденное** без просьбы: записать в + `KNOWN_ISSUES.md` (путь, симптом, предложение) и сказать в отчёте. + +## 3. Порядок работы + +1. Найди, откуда требование: `README.md` (рубрика), `contracts/README.md` + (семантика), `contracts/openapi.json` (схемы, коды), `COURSE.md` + (переходы API). Неясно или противоречит контракту — остановись и + спроси. Ответ преподавателя — в раздел 12. +2. Прочитай нужные `AGENTS.md` (раздел 1) и затрагиваемые файлы целиком. +3. Задача больше пары файлов — сначала короткий план в чате. +4. Минимальный дифф: не переименовывать и не «улучшать» лишнее. +5. Проверки из раздела 8 — до того, как сказать «готово». +6. Отчёт пользователю — раздел 11. + +## 4. Команды + +| Команда | Что делает | +|---|---| +| `make install` | `uv sync` (нужна сеть) | +| `make env` | `.env` из `.env.example` со случайными паролями, если его нет | +| `make up` | стенд: postgres, valkey → migrate → api × `API_REPLICAS` (2) → haproxy на `127.0.0.1:HOST_PORT` (8080); ждёт healthy | +| `make stop` / `make down` / `make logs` | остановить / удалить контейнеры (volume остаётся) / журнал реплик | +| `make wipe` | удалить контейнеры и volume: только после ввода `yes` (раздел 2, п. 9) | +| `make replicas [API_REPLICAS=N]` | вернуть остановленные реплики (те же ID) и выставить их число | +| `make instances` | одна сессия, серия запросов через LB: `X-Instance-Id` каждого ответа | +| `make lb-stats` | слоты HAProxy: адрес, состояние, запросы, повторы | +| `make failover-each [STOP_MODE=kill]` | `make test-failover` для каждой реплики по очереди, `STOP_ONE_LOG`, `docker compose ps` | +| `make rolling-update` | поочерёдная замена реплик на образ рабочего дерева без простоя | +| `make db-up` / `make run [RUN_PORT=8081]` / `make migrate-local` | хранилища стенда / один процесс на хосте без LB / миграции с хоста | +| `make lint` / `make fmt` | ruff: проверка / исправление и формат | +| `make test [BASE_URL=...]` | публичный smoke | +| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные и прежний токен после рестарта LB, реплик, PostgreSQL и Valkey | +| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh [STOP_MODE=kill]` | отказ одной реплики через LB: запись восстанавливается ≤ 10 с, без дублей | +| `make student-test [BASE_URL=...] [EXPECT_REPLICAS=...]` | свои тесты против запущенного стенда (без проверок отказов) | +| `make test-isolated` | отдельный стенд с LB и 2 репликами: smoke, свои тесты, test-failover, test-persistence, уборка (~50 с) | +| `make failure-checks [FAULT_ARGS=-rP]` | проверки отказов на отдельном стенде (~55 с) | +| `make check` / `make validate PYTHON=.venv/bin/python` | офлайн-проверка skeleton / полная валидация OpenAPI | +| `make requirements` / `make requirements-check` | `requirements.txt` из `uv.lock` / сверка | +| `make bench-failover` / `make bench-rollout` | уровень 4 под нагрузкой: `evidence/failover/<метка>/`, `evidence/rollout/<метка>/` | +| `make bench-scaling SERIES=a\|b\|db\|ab [CONFIGS=…] [RESUME=1]` | трек 1: серии, `evidence/scaling/<метка>/` | +| `make bench-*-quick`, `make bench-scaling-quick` | самопроверки стенда, метки `quick-*` в отчёт не идут | +| `make bench-compare BEFORE= AFTER= [AA=]` / `make bench-plots LABELS="…"` | «до/после» с шумом A/A / графики SVG | + +`make test`, `make student-test`, `make instances`, `make failover-each` +ходят на `http://localhost:8080` (HAProxy). Внешние порты — `HOST_PORT`, +`POSTGRES_HOST_PORT` (5433), `VALKEY_HOST_PORT` (6380) в `.env`; разовая +подмена — аргументом make (`make test BASE_URL=http://localhost:8090`). +Внутри сети стенда порты фиксированы: 8080, 5432, 6379, 8404 (мониторинг +LB). Тесты против рабочего стенда оставляют в нём данные; чистый +прогон — `make test-isolated`. + +## 5. Карта кода + +``` +src/ пакет приложения: python -m src (__main__ → early_stop.install() → main.run()) + main.py create_app(): Db, кэш, хранилище, пароли, middleware (X-Request-Id, X-Instance-Id), роутеры + config.py Settings.from_env(): только окружение (Database, Cache, instance_id, сроки) + early_stop.py SIGTERM/SIGINT до старта сервера: строка журнала и выход 0 (stdlib) + constants.py, log.py, errors.py, clock.py, domain.py, pagination.py, healthcheck.py + db.py Db: пул и сроки, transaction(), отказ → Unavailable, ping() + cache.py клиент Valkey: срок на команду, обход при отказе + passwords.py Argon2id в потоке с лимитом, фиктивный хэш + api/ routes/ (health, users, sessions, chats, messages + Idempotency-Key), schemas, deps, + identity (BearerBackend), request_id, handlers + services/ UserService, SessionService, ChatService, MessageService (хэш тела); access.py + storage/ base.py (Protocol), postgres.py (ключ + сообщение одной транзакцией), cached.py, tables.py +migrations/ alembic: 0001 схема лабы 2, 0002 idempotency_keys (expand) +student-tests/ тесты по HTTP; stand.py — отдельные стенды; fault_hook.py +bench/ run.py, common.py, analysis.py, loadgen.py, sampler.py, compare.py, plots.py, RUNBOOK.md +infra/haproxy/ haproxy.cfg: DNS Docker, проверки /health/ready, цепочка таймаутов, runtime API +infra/valkey/ valkey.conf: лимит памяти, LRU, без persistence +scripts/ restart.sh, stop-one.sh, rolling-update.sh, lab3.py (свои); остальное — skeleton +.codex/rules/ правила команд Codex; .agents/skills/ — навыки Codex +evidence/ доказательства для REPORT.md; failover/, rollout/, scaling/ — метки стенда +Dockerfile, compose.yaml, alembic.ini, pyproject.toml, uv.lock, requirements.txt, .env.example +``` + +Поток запроса: клиент → HAProxy (round-robin, только готовые реплики) → +uvicorn реплики → `RequestIdMiddleware` → `AuthenticationMiddleware` +(`BearerBackend`: сессия из PostgreSQL, 401 или 503 до роутинга) → роут +(схема тела и ключа, 400) → сервис (членство, 404) → `CachedStorage` → +`PostgresStorage` (ключ и сообщение одной транзакцией, 409) / Valkey. + +## 6. Контракт: самое важное + +Полностью — `src/api/AGENTS.md` и `contracts/`. Переход 2 → 3 +(`COURSE.md`): `Idempotency-Key` обязателен для отправки сообщения, +ответы API содержат `X-Instance-Id`. + +- Любой ответ API несёт непустые `X-Request-Id` и `X-Instance-Id` (одно + значение на процесс; ответы самого HAProxy — без него). Ошибка — + `{"error": {"code", "message", "request_id"}}`. +- 400 (тело, JSON, UUID, `limit`, курсор, нет или неверный + `Idempotency-Key`), 401 (`WWW-Authenticate`: Basic на входе, Bearer + остальное), 404 (нет или чужое), 409 (username занят; ключ с другим + телом), 503 (PostgreSQL недоступен), 500. 422 и 403 не отдаются. +- Сначала аутентификация: 401 раньше 400. Порядок отправки: 401 → 400 → + 404 → 409. +- Повтор того же тела с тем же ключом (24 ч, `IDEMPOTENCY_TTL_SECONDS`) — + тот же 201 и тот же `Message`; область ключа — автор + чат + ключ; + конкурентные повторы через разные реплики — одно сообщение; 5xx не + фиксируется результатом. +- Токен — 256 бит, в БД SHA-256; срок фиксируется при входе. Время — + RFC 3339 UTC с `Z`; порядок `(created_at, id)`; `limit` 1–100. + +## 7. Конфигурация, логи, Docker, зависимости + +**Переменные окружения** читает только `src/config.py`; неверное +значение — выход с кодом 2. Группы: `APP_HOST`, `APP_PORT`, +`APP_INSTANCE_ID` (по умолчанию hostname), `LOG_LEVEL`, +`SHUTDOWN_TIMEOUT`, `KEEP_ALIVE_TIMEOUT`; `SESSION_TTL_SECONDS`, +`IDEMPOTENCY_TTL_SECONDS`, `KDF_CONCURRENCY`; `DB_*`, `CACHE_*`. Таблица +— `src/AGENTS.md`. Логические имена `.env.example` skeleton и их +соответствие — `REPORT.md`, «Конфигурация». + +**Логи**: строка на событие, `время уровень логгер [rid=...] сообщение +key=value`; строка старта содержит `instance=` (значение +`X-Instance-Id`), реплику в `docker compose logs` видно по префиксу. + +**Docker, compose, HAProxy**: правила и цепочка таймаутов — +`infra/AGENTS.md`. Числа менять только вместе (обнаружение отказа ≤ 10 с, +`timeout connect` × 3 < 2 с, `timeout server` > срок операции, +keep-alive LB < keep-alive реплики, `SHUTDOWN_TIMEOUT` < +`stop_grace_period`). + +**Зависимости**: `pyproject.toml` → `uv lock` → `make requirements` → +`make requirements-check` → пересборка образа. + +## 8. Definition of Done + +- [ ] `make fmt`, затем `make lint` — без ошибок; +- [ ] `make test-isolated` — в `results` все 0; +- [ ] правка хранилища, сессий, ключей, кэша, `db.py`, `cache.py`, + таймаутов — ещё `make failure-checks`; +- [ ] правка `compose.yaml`, `haproxy.cfg`, `scripts/*.sh` — `make up`, + `make test`, `make instances`, `make test-persistence + ACTION_SCRIPT=scripts/restart.sh`, `make failover-each`; скрипт + замены — `make rolling-update`; +- [ ] правка схемы — новая expand-ревизия, `alembic check` без + расхождений (`migrations/AGENTS.md`); +- [ ] правка `Dockerfile`, зависимостей — `make up`, все `(healthy)`, + `make test`, `make requirements-check`; +- [ ] правка `bench/` — `uv run python bench/analysis.py --selftest` и + самопроверки `make bench-*-quick` (`bench/AGENTS.md`); +- [ ] новое поведение из рубрики — тест в `student-tests/`; +- [ ] изменилось описанное в `REPORT.md`, `evidence/`, `AGENTS.md` — + обновлено там же; +- [ ] остановлены серверы и удалены контейнеры, которые ты запустил + (кроме рабочего стенда, если он работал до тебя). + +Не смог выполнить пункт (нет сети, docker, порт занят) — так и напиши, +с причиной. «Должно работать» не считается проверкой. + +## 9. Если тест или проверка упали + +1. Воспроизведи и прочитай вывод целиком. +2. Назови причину: **дефект приложения** → чинить код; **ошибка в самом + тесте** (противоречит контракту или зависит от случайного) → править + тест можно, но назови, чему он противоречил; **стенд** (порт занят + чужим сервисом — smoke получает 404 на `/health/live`, старый образ, + не тот `BASE_URL`, остатки прерванного прогона, реплика ещё не `UP` в + LB) → чинить стенд. +3. Причина неясна или правка теста спорная — остановись и спроси. + +Тест `tests/` не правится никогда. Дефект вне задачи — в +`KNOWN_ISSUES.md`. Проверки отказов меряют время с запасом 0,3–1 с: на +загруженном хосте возможно ложное падение — перезапусти один раз и +скажи об этом. + +## 10. Особенности Codex + +- В sandbox нет сети: `uv sync`/`uv lock`/`docker build` упадут. Docker + из sandbox часто недоступен (сокет): почти всё здесь требует docker. + Запроси запуск вне sandbox (правила `.codex/rules/` разрешают команды + проекта без вопроса, если проект доверенный) или попроси пользователя; + приложи команду дословно. +- Долгие команды (`make bench-*` — до часа) — в фоне с журналом: + `nohup make … > /tmp/bench-x.log 2>&1 &`, затем `tail` журнала. +- Сервис на хосте (`make run`) — в фоне с журналом; до запуска проверь + порт (`lsof -nP -iTCP:8081 -sTCP:LISTEN`), в конце убей только PID, + чей `ps -p -o command=` — `python -m src`. +- Никогда не убивать процесс по порту вслепую: порт опубликованного + контейнера на macOS держит `com.docker.backend`. Чужие процессы и + контейнеры не трогать — взять другой порт. +- Держи этот файл ≤ ~28 КБ (`wc -c`, кириллица — два байта на символ): + Codex читает `AGENTS.md` до 32 КиБ вместе. Новое правило слоя — во + вложенный `AGENTS.md`. + +## 11. Отчёт пользователю в конце задачи + +По-русски, коротко: что сделано (файлы и суть); какие проверки и с каким +итогом (`84 passed`, `PASS: lab3 ...`, `results: {...}`); что не +проверено и почему; что записано в `KNOWN_ISSUES.md`, вопросы к +преподавателю. + +## 12. Согласования с преподавателем + +Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`. + +| Дата | Договорённость | Где учтено | +|---|---|---| +| — | пока нет | — | + +## 13. Стиль кода + +- ruff (`pyproject.toml`): строка 88, py313, isort, bugbear, pyupgrade, + simplify, pytest-style, async. Формат — `make fmt`. +- Аннотации типов везде; дженерики PEP 695. Исключение — скрипты на + `python3` хоста (`student-tests/stand.py`, `fault_hook.py`, + `scripts/lab3.py`): Python 3.9+, stdlib, `from __future__ import + annotations`. +- Методы сервисов и изменяющие методы хранилища — keyword-only. +- Комментарии и докстринги — короткие, по-русски, объясняют «почему». + Сообщения логов и `error.message` — по-английски. +- Константы контракта — `src/constants.py`; время — `src/clock.py`. +- Коммиты (только по просьбе): английский, conventional. + +## 14. Документы решения + +- `REPORT.md` — отчёт: запуск из чистого clone, архитектура, таблица + доказательств, эксперименты, гипотезы трека 1, ограничения. +- `evidence/` — реальные выводы проверок (`evidence/AGENTS.md`). +- `KNOWN_ISSUES.md` — найденные, но не исправленные дефекты. +- `bench/RUNBOOK.md` — замеры по шагам. Стенд и метки лабы 2 (EXPLAIN, + восстановление) остались в репозитории лабы 2. + +## 15. Дальше: лаба 4 + +Новый skeleton — отдельный репозиторий; переходы API — в его +`COURSE.md`, читать до правки кода (лаба 4: приватный S3, вложения, +`attachment_ids` в теле сообщения — добавить в `request_hash` со +значением по умолчанию `[]`). Переносить: `src/`, `student-tests/`, +`migrations/`, `alembic.ini`, `bench/`, `infra/haproxy/`, `infra/valkey/`, +свои `scripts/*`, `Dockerfile`, `compose.yaml`, `pyproject.toml`, +`uv.lock`, `requirements.txt`, `.python-version`, все `AGENTS.md`, +`.codex/`, `.agents/`, `KNOWN_ISSUES.md`. Сливать со skeleton: +`Makefile`, `.env.example`, `.gitignore`, `.dockerignore`. Не +копировать: `.git`, `.env`, volumes, `README.md`, `COURSE.md`, `tests/`, +`contracts/`, `lab.json`, `REPORT.md`, `evidence/`. Имя проекта compose +(`name:`) — на `vladimirceva-lab4`. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..884fd4e3 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,57 @@ +# Образ API мессенджера, лаба 3: сервер (реплики за HAProxy) и миграции. +# Правила — infra/AGENTS.md. +# +# Базовый образ закреплён тегом с патч-версией и digest индекса +# (linux/amd64 + linux/arm64), в обоих stage один и тот же: venv ссылается +# на интерпретатор базового образа. Обновление — новый тег и строка +# Digest из `docker buildx imagetools inspect python:<тег>`. + +# deps: зависимости строго по requirements.txt (экспорт uv.lock с хешами). +# У asyncpg, greenlet и argon2-cffi-bindings есть готовые колёса для +# linux amd64/arm64: компилятор в образе не нужен +FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS deps + +ENV PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 + +RUN python -m venv /opt/venv +COPY requirements.txt /tmp/requirements.txt +# --require-hashes: пакет с другим хешем или без пина — сборка падает; +# --no-deps: ставится ровно список из файла, без догрузки зависимостей; +# --only-binary: сборка из исходников (sdist) запрещена +RUN /opt/venv/bin/pip install --require-hashes --no-deps --only-binary=:all: \ + -r /tmp/requirements.txt + + +# runtime: интерпретатор базового образа, venv и код; без pip-кэша и тестов +FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS runtime + +RUN groupadd --system --gid 10001 messenger \ + && useradd --system --uid 10001 --gid messenger --no-create-home \ + --home-dir /nonexistent --shell /usr/sbin/nologin messenger + +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + APP_HOST=0.0.0.0 \ + APP_PORT=8080 + +WORKDIR /app + +# код и venv принадлежат root: пользователю messenger — только чтение. +# Миграции едут в том же образе: сервис migrate запускает его с командой +# `python -m alembic upgrade head` +COPY --from=deps /opt/venv /opt/venv +COPY src ./src +COPY alembic.ini ./ +COPY migrations ./migrations + +USER messenger:messenger + +EXPOSE 8080 + +HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --start-interval=1s \ + --retries=3 CMD ["python", "-m", "src.healthcheck"] + +# exec-форма: сервер — PID 1 и сам получает SIGTERM от docker stop +CMD ["python", "-m", "src"] diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md new file mode 100644 index 00000000..c4de9574 --- /dev/null +++ b/KNOWN_ISSUES.md @@ -0,0 +1,13 @@ +# Известные проблемы + +Найдены попутно и не исправлены без отдельной просьбы (AGENTS.md, +раздел 2, п. 17). Формат: что, где, симптом, предложение. Исправленное +удаляется отсюда. + +Открытых дефектов нет. + +Закрыто при переносе в лабу 3: косметическая находка лабы 2 в +`bench/run.py:render_explain` (подпись раздела «Страница middle без +индекса» у чата без средней страницы). Стенд лабы 2 с планами запроса в +лабу 3 не переносился — стенд переписан под реплики за HAProxy, функции +больше нет; метки и отчёт лабы 2 остались в её репозитории. diff --git a/Makefile b/Makefile index 5d86d171..ddab6e43 100644 --- a/Makefile +++ b/Makefile @@ -28,3 +28,264 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + + +# =========================================================================== +# Собственные цели решения. Цели skeleton выше (help, check, validate, test, +# load, test-persistence, test-failover) не менять: в следующей лабе +# Makefile придёт новый, свои цели переносятся в него слиянием. +# =========================================================================== + +# .env: подстановки compose и окружение приложения на хосте. Без него — +# значения по умолчанию ниже (пароли пустые: сначала `make env`) +-include .env + +IMAGE ?= mtusi-messenger-vladimirceva:lab3 +# порт HAProxy на 127.0.0.1 — единственный порт API стенда на хосте +HOST_PORT ?= 8080 +# порт сервиса на хосте (make run): другой, чем у стенда, — оба могут +# работать одновременно +RUN_PORT ?= 8081 +POSTGRES_USER ?= messenger +POSTGRES_DB ?= messenger +POSTGRES_HOST_PORT ?= 5433 +VALKEY_HOST_PORT ?= 6380 +SESSION_TTL_SECONDS ?= 3600 +# реплик API за HAProxy; разово — `make replicas API_REPLICAS=3` +API_REPLICAS ?= 2 +DC = docker compose +UV_EXPORT = uv export --frozen --no-dev --no-emit-project --no-header --format requirements.txt +# долгие замеры на macOS — под caffeinate: ноутбук не уснёт по простою +CAFFEINATE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu) + +# --- приложение на хосте ---------------------------------------------------- + +.PHONY: install +install: + uv sync + +# окружение сервиса и миграций на хосте: хранилища стенда на 127.0.0.1, +# пароли из .env. .env читается в рецепте, а не при разборе Makefile: так +# первый запуск видит и файл, только что созданный `make env`. Рецепт без +# эха — пароли не печатаются +LOCAL_ENV = set -a; . ./.env; set +a; \ + export DB_HOST=127.0.0.1 DB_PORT="$$POSTGRES_HOST_PORT" DB_NAME="$$POSTGRES_DB" \ + DB_USER="$$POSTGRES_USER" DB_PASSWORD="$$POSTGRES_PASSWORD" CACHE_HOST=127.0.0.1 \ + CACHE_PORT="$$VALKEY_HOST_PORT" CACHE_PASSWORD="$$VALKEY_PASSWORD" + +# PostgreSQL и Valkey из compose, миграции с хоста, затем один процесс +# сервиса на 127.0.0.1:RUN_PORT без LB, текстовые логи в stdout; стоп — +# Ctrl+C. Срок сессии — `make run SESSION_TTL_SECONDS=2` +.PHONY: run +run: migrate-local + @echo "uv run python -m src # 127.0.0.1:$(RUN_PORT), SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS)" + @$(LOCAL_ENV); APP_PORT=$(RUN_PORT) SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS) \ + uv run python -m src + +# миграции с хоста в PostgreSQL стенда (127.0.0.1:POSTGRES_HOST_PORT) +.PHONY: migrate-local +migrate-local: db-up + @echo "uv run alembic upgrade head # 127.0.0.1:$(POSTGRES_HOST_PORT)" + @$(LOCAL_ENV); uv run alembic upgrade head + +.PHONY: lint +lint: + uv run ruff format --check . + uv run ruff check . + +.PHONY: fmt +fmt: + uv run ruff format . + uv run ruff check --fix . + +# собственные тесты против запущенного стенда (BASE_URL, по умолчанию +# HAProxy рабочего стенда); EXPECT_REPLICAS — сколько реплик за BASE_URL +# (против `make run` — 1: тесты реплик пропускаются с причиной). +# Проверки отказов (маркер fault) — make failure-checks +EXPECT_REPLICAS ?= $(API_REPLICAS) +.PHONY: student-test +student-test: + BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest + +# отдельный стенд из того же compose.yaml (свои PostgreSQL, Valkey, volume, +# HAProxy и две реплики, свои пароли, без .env): сборка, миграции, make +# test и make student-test через его LB, затем уборка при любом исходе. +# Рабочий стенд не трогается. $(PYTHON), а не uv run: uv повторно шлёт +# SIGINT, и Ctrl+C обрывал бы уборку +.PHONY: test-isolated +test-isolated: + $(PYTHON) student-tests/stand.py isolated + +# проверки отказов (pytest -m fault, ~1,5 мин) на таком же отдельном +# стенде: обычный и «тесный» API (сроки сессии и ключа 2 с, пул 1), hook +# student-tests/fault_hook.py. FAULT_ARGS — аргументы pytest +.PHONY: failure-checks +failure-checks: + $(PYTHON) student-tests/stand.py failures $(FAULT_ARGS) + +# requirements.txt для образа — только из uv.lock, с хешами +.PHONY: requirements +requirements: + $(UV_EXPORT) --output-file requirements.txt + +.PHONY: requirements-check +requirements-check: + $(UV_EXPORT) | diff -u requirements.txt - && echo "requirements.txt matches uv.lock" + +# --- Docker и compose --------------------------------------------------------- + +# .env из шаблона, если его ещё нет, со случайными паролями PostgreSQL и +# Valkey: в шаблоне они пустые, общего пароля стенда в git нет. +# Существующий .env не трогается +.PHONY: env +env: + @test -f .env || sed \ + -e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \ + -e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \ + .env.example > .env + @echo ".env ready" + +.PHONY: docker-build +docker-build: + docker build -t $(IMAGE) . + +# весь стенд: postgres, valkey -> migrate -> api × API_REPLICAS -> haproxy; +# --wait ждёт healthy реплик и LB (миграции к этому моменту завершились с +# кодом 0). Реплики с изменённым образом пересоздаются все разом, с +# простоем; без простоя — make rolling-update +.PHONY: up +up: env + $(DC) up -d --build --wait api haproxy + +# остановить контейнеры (SIGTERM); данные и контейнеры остаются. LB +# останавливается раньше реплик (depends_on) +.PHONY: stop +stop: + $(DC) stop + +# удалить контейнеры; volume pgdata с данными остаётся (удаление — wipe) +.PHONY: down +down: + $(DC) down + +# журнал всех реплик; префикс строки — имя контейнера реплики +.PHONY: logs +logs: + $(DC) logs -f api + +# только хранилища стенда, с ожиданием healthcheck: для make run +.PHONY: db-up +db-up: env + $(DC) up -d --wait postgres valkey + +# удалить контейнеры и volume с данными стенда: только после ввода yes +.PHONY: wipe +wipe: + @read -p "Удалить все данные стенда (volume PostgreSQL)? Введите yes: " answer; \ + if [ "$$answer" = "yes" ]; then \ + $(DC) down -v --remove-orphans; \ + else \ + echo "cancelled, nothing removed"; exit 1; \ + fi + +# --- Реплики за HAProxy (лаба 3) -------------------------------------------- + +# вернуть остановленные реплики (те же контейнеры и X-Instance-Id) и +# выставить их число API_REPLICAS; ждёт healthy +.PHONY: replicas +replicas: + $(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api + +# вход одним синтетическим пользователем и серия GET /users/me с одним +# токеном через LB: X-Instance-Id каждого ответа и итог по репликам +.PHONY: instances +instances: + $(PYTHON) scripts/lab3.py instances --base-url "$(BASE_URL)" + +# слоты HAProxy: адрес, состояние проверки (DRAIN/MAINT при замене), +# запросы, ошибки соединения, повторы, перенаправления +.PHONY: lb-stats +lb-stats: + $(PYTHON) scripts/lab3.py lb-stats + +# make test-failover для каждой реплики по очереди с возвратом +# предыдущей (make replicas): какой контейнер остановлен, строка +# STOP_ONE_LOG и итог теста. STOP_MODE=kill — без graceful +STOP_MODE ?= stop +.PHONY: failover-each +failover-each: + $(PYTHON) scripts/lab3.py failover-each --base-url "$(BASE_URL)" \ + --replicas $(API_REPLICAS) --mode $(STOP_MODE) + +# поочерёдная замена реплик на образ рабочего дерева без простоя: +# сборка, миграции один раз, по одной реплике через drain в LB +.PHONY: rolling-update +rolling-update: + API_REPLICAS=$(API_REPLICAS) scripts/rolling-update.sh + +# --- Нагрузочный стенд (уровень «4» — отказ и замена под нагрузкой, +# уровень «5» — трек 1 «Цена масштабирования») --------------------------- +# Порядок работы — bench/RUNBOOK.md, правила — bench/AGENTS.md. Свой проект +# compose vlad-bench, рабочий стенд перед замером — make stop. + +FAILOVER_LABEL ?= baseline +ROLLOUT_LABEL ?= baseline +# серия трека 1: a — бюджет 4 CPU на 1/2/4 реплики; b — 1…N реплик по +# 1 CPU; db — PostgreSQL 0,5 CPU при 1/2/4 репликах; ab — ячейки «до/после» +SERIES ?= +SCALING_LABEL ?= +LABELS ?= +PLOTS ?= scaling +BENCH = $(CAFFEINATE) uv run python bench/run.py + +# уровень 4: две реплики под постоянной нагрузкой, каждая в режимах stop, +# kill, pause с возвратом; пишет evidence/failover/<метка>/ +.PHONY: bench-failover +bench-failover: + $(BENCH) failover --label "$(FAILOVER_LABEL)" + +# проверка стенда отказа (~2 мин); метка quick-failover- в отчёт не идёт +.PHONY: bench-failover-quick +bench-failover-quick: + $(BENCH) failover-quick + +# уровень 4: поочерёдная замена (scripts/rolling-update.sh) под той же +# нагрузкой, с новой expand-ревизией; пишет evidence/rollout/<метка>/ +.PHONY: bench-rollout +bench-rollout: + $(BENCH) rollout --label "$(ROLLOUT_LABEL)" + +.PHONY: bench-rollout-quick +bench-rollout-quick: + $(BENCH) rollout-quick + +# уровень 5, трек 1: серия конфигураций, на каждую ячейку свежий стенд, +# открытая модель, поиск R*; пишет evidence/scaling/<метка>/. +# CONFIGS="4x1-pg0.5 4x1" — ячейки вместо профильных (серия ab — всегда); +# RESUME=1 — продолжить прерванную метку +CONFIGS ?= +.PHONY: bench-scaling +bench-scaling: + @test -n "$(SERIES)" || (echo "usage: make bench-scaling SERIES=a|b|db|ab [SCALING_LABEL=...] [CONFIGS=...] [RESUME=1]"; exit 2) + $(BENCH) scaling --series "$(SERIES)" $(if $(SCALING_LABEL),--label "$(SCALING_LABEL)",) \ + $(if $(CONFIGS),--configs "$(CONFIGS)",) $(if $(RESUME),--resume,) + +# самопроверка серий (~5 мин): 1 × 1 и 2 × 1, короткие окна +.PHONY: bench-scaling-quick +bench-scaling-quick: + $(BENCH) scaling --series quick + +# сравнение двух меток (серии — по общим конфигурациям); AA — метка того +# же кода, что BEFORE: уровень шума +.PHONY: bench-compare +bench-compare: + @test -n "$(BEFORE)" -a -n "$(AFTER)" || \ + (echo "usage: make bench-compare BEFORE=