PYTHON ?= python3 BASE_URL ?= http://localhost:8080 CA_FILE ?= ACTION_SCRIPT ?= TLS_ARGS = $(if $(CA_FILE),--ca-file "$(CA_FILE)",) .PHONY: help check validate test load test-persistence test-failover help: @echo "check: offline structure; validate: full OpenAPI (requirements-dev.txt); test: running API; load: synthetic writes" check: $(PYTHON) scripts/check_contract.py validate: $(PYTHON) scripts/validate_openapi.py test: $(PYTHON) tests/smoke.py --base-url "$(BASE_URL)" $(TLS_ARGS) load: $(PYTHON) tests/load.py --base-url "$(BASE_URL)" $(TLS_ARGS) test-persistence: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable restart hook"; exit 2) $(PYTHON) tests/resilience.py --mode persistence --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) 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 выше не менять) # ------------------------- # Postgres из compose и миграции, Valkey и S3 с bootstrap из compose, # затем сервис на хосте: 127.0.0.1:APP__PORT, reload по src/ .PHONY: run_dev run_dev: upgrade start_cache start_s3 start_broker APP__RUN_MODE=console uv run python -m src # worker в консоли: тот же .env, адреса на хосте; ключи worker — в окружение # процесса (мост S3__* в .env — ключи API). @: значения в вывод не попадают .PHONY: run_worker run_worker: @S3__ACCESS_KEY_ID="$(S3_WORKER_ACCESS_KEY)" S3__SECRET_ACCESS_KEY="$(S3_WORKER_SECRET_KEY)" APP__RUN_MODE=console uv run python -m src.worker # relay публикации заданий в консоли: без него консольный API принимает файлы, а # задания ждут в PostgreSQL. Брокер поднимает make run_dev; те же мосты .env .PHONY: run_relay run_relay: @APP__RUN_MODE=console uv run python -m src.relay # реестр failed и replay (design change pipeline-reliability, решение 5): без # APPLY=1 только показ; с APPLY=1 выбор обязателен (ATTACHMENT, ERROR_CODE или # REASON), иначе код 2. Коды: 0 — выполнено или показано, 3 — есть отказы, 1 — # отказ PostgreSQL. ATTACHMENT — id вложения, можно несколько через пробел OPERATOR ?= $(USER) .PHONY: replay replay: @$(DC) run --rm --no-deps relay replay$(foreach id,$(ATTACHMENT), --attachment-id $(id))$(if $(ERROR_CODE), --error-code $(ERROR_CODE))$(if $(REASON), --reason $(REASON))$(if $(LIMIT), --limit $(LIMIT))$(if $(filter 1,$(APPLY)), --apply)$(if $(OPERATOR), --operator $(OPERATOR)) # шаблоны копируются только если файла ещё нет: локальные значения # не затираются. В .env подставляются случайные пароли Postgres и # Valkey и секреты S3: в шаблоне они пустые, общего секрета стенда в git # нет. В существующий .env дописываются переменные шаблона, которых в нём # нет (секреты — случайными, остальные — значениями шаблона), прежние # строки не меняются (design change upload-consistency). Печатаются # только имена, значения — нет ENV_SECRETS = POSTGRES_PASSWORD VALKEY_PASSWORD RABBITMQ_DEFAULT_PASS S3_ROOT_ACCESS_KEY S3_ROOT_SECRET_KEY S3_JWT_SIGNING_KEY S3_API_ACCESS_KEY S3_API_SECRET_KEY S3_CLEANER_ACCESS_KEY S3_CLEANER_SECRET_KEY S3_WORKER_ACCESS_KEY S3_WORKER_SECRET_KEY GRAFANA_ADMIN_PASSWORD # шаблон с подставленными секретами — в поток, не в вывод команды ENV_FILLED = sed \ -e "s/^POSTGRES_PASSWORD=$$/POSTGRES_PASSWORD=$$(openssl rand -hex 16)/" \ -e "s/^VALKEY_PASSWORD=$$/VALKEY_PASSWORD=$$(openssl rand -hex 16)/" \ -e "s/^S3_ROOT_ACCESS_KEY=$$/S3_ROOT_ACCESS_KEY=$$(openssl rand -hex 10)/" \ -e "s/^S3_ROOT_SECRET_KEY=$$/S3_ROOT_SECRET_KEY=$$(openssl rand -hex 20)/" \ -e "s/^S3_JWT_SIGNING_KEY=$$/S3_JWT_SIGNING_KEY=$$(openssl rand -hex 32)/" \ -e "s/^S3_API_ACCESS_KEY=$$/S3_API_ACCESS_KEY=$$(openssl rand -hex 10)/" \ -e "s/^S3_API_SECRET_KEY=$$/S3_API_SECRET_KEY=$$(openssl rand -hex 20)/" \ -e "s/^S3_CLEANER_ACCESS_KEY=$$/S3_CLEANER_ACCESS_KEY=$$(openssl rand -hex 10)/" \ -e "s/^S3_CLEANER_SECRET_KEY=$$/S3_CLEANER_SECRET_KEY=$$(openssl rand -hex 20)/" \ -e "s/^S3_WORKER_ACCESS_KEY=$$/S3_WORKER_ACCESS_KEY=$$(openssl rand -hex 10)/" \ -e "s/^S3_WORKER_SECRET_KEY=$$/S3_WORKER_SECRET_KEY=$$(openssl rand -hex 20)/" \ -e "s/^RABBITMQ_DEFAULT_PASS=$$/RABBITMQ_DEFAULT_PASS=$$(openssl rand -hex 16)/" \ -e "s/^GRAFANA_ADMIN_PASSWORD=$$/GRAFANA_ADMIN_PASSWORD=$$(openssl rand -hex 16)/" \ .env.example # строки NAME=… шаблона, имени которых в .env нет, — в конец .env под # комментарием; в вывод — только имена ENV_APPEND_MISSING = awk -F= ' \ BEGIN { \ while ((getline line < ".env") > 0) \ if (line ~ /^[A-Za-z_][A-Za-z0-9_]*=/) { split(line, kv, "="); have[kv[1]] = 1 }; \ close(".env"); \ } \ /^[A-Za-z_][A-Za-z0-9_]*=/ && !($$1 in have) { \ if (!added++) printf "\n\# added by make env_setup from .env.example\n" >> ".env"; \ print >> ".env"; names = names " " $$1 \ } \ END { if (added) print "added to existing .env:" names }' .PHONY: env_setup env_setup: @if [ ! -f .env ]; then \ $(ENV_FILLED) > .env; \ echo "new .env with random $(ENV_SECRETS)"; \ else \ $(ENV_FILLED) | $(ENV_APPEND_MISSING); \ fi @test -f config.toml || cp config_example.toml config.toml @echo "env ready: .env, config.toml" # ------------------------- # Docker targets # ------------------------- # порты — из того же .env, что читает compose; без .env — 8080 -include .env APP__PORT ?= 8080 APP_OUT_PORT ?= 8080 # число реплик api за HAProxy — то же, что deploy.replicas в compose API_REPLICAS ?= 2 # сколько реплик за BASE_URL ждут тесты реплик student-tests: против # стенда с LB — API_REPLICAS, против одного процесса — 1 (их пропуск) EXPECT_REPLICAS ?= $(API_REPLICAS) DC=docker compose # стенд: postgres, valkey, s3, rabbitmq -> migrate, s3-bootstrap -> api × # API_REPLICAS, cleaner, worker -> haproxy; телеметрия — otel-collector, # prometheus, loki, tempo, grafana (приложение их не ждёт) # (единственный порт API на хосте — у haproxy). env_setup создаёт # недостающие .env и config.toml из шаблонов: без config.toml compose не # запустится (bind с create_host_path: false), без паролей — тоже. # Реплики, чей образ изменился, пересоздаются все разом (простой); новый # код без простоя — make rolling_update .PHONY: run_docker run_docker: env_setup DOCKER_BUILDKIT=1 $(DC) build $(DC) up -d .PHONY: stop stop: $(DC) stop # контейнеры удаляются, volume с данными остаётся (удаление — wipe_data) .PHONY: down down: $(DC) down # журнал всех реплик api без префикса "api-1 |": каждая строка — JSON, # реплику называет поле instance_id .PHONY: logs logs: $(DC) logs -f --no-log-prefix api # ------------------------- # PostgreSQL и миграции # ------------------------- # Postgres стенда; --wait ждёт его healthcheck .PHONY: start_db start_db: env_setup $(DC) up -d --wait postgres .PHONY: stop_db stop_db: $(DC) stop postgres # миграции с хоста: 127.0.0.1:POSTGRES_OUT_PORT из .env .PHONY: upgrade upgrade: start_db uv run alembic upgrade head # новая ревизия autogenerate; база сначала доводится до head, иначе # autogenerate сравнит модели не с той схемой .PHONY: revision revision: upgrade @read -p "Сообщение миграции (англ., прошедшее время): " msg; \ uv run alembic revision --autogenerate -m "$$msg" # удалить контейнеры стенда и volumes с данными: только после ввода yes .PHONY: wipe_data wipe_data: @project=$$($(DC) config | sed -n 's/^name: //p'); \ volumes=$$($(DC) config --volumes | sed "s/^/$${project}_/" | paste -sd ' ' -); \ read -p "Удалить все данные стенда (volumes Postgres, S3, брокера и хранилищ телеметрии: $$volumes)? Введите yes: " answer; \ if [ "$$answer" = "yes" ]; then \ $(DC) down -v --remove-orphans; \ else \ echo "cancelled, nothing removed"; exit 1; \ fi # ------------------------- # Valkey (кэш карточек чатов) # ------------------------- # Valkey стенда; --wait ждёт его healthcheck. Volume нет: кэш после # рестарта пуст, данные — в PostgreSQL .PHONY: start_cache start_cache: env_setup $(DC) up -d --wait valkey .PHONY: stop_cache stop_cache: $(DC) stop valkey # ------------------------- # S3 (SeaweedFS, байты вложений) # ------------------------- # S3 стенда и его bootstrap: --wait ждёт healthcheck сервера, но # одноразовый сервис считает готовым уже запущенным, поэтому bootstrap — # отдельным up с его кодом выхода (как миграции в rolling-update.sh) .PHONY: start_s3 start_s3: env_setup $(DC) up -d --wait s3 $(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap # плавная остановка ~15 с (stop_grace_period 20 с) .PHONY: stop_s3 stop_s3: $(DC) stop s3 # брокер стенда: --wait ждёт healthcheck; данные — в volume rabbitmq_data .PHONY: start_broker start_broker: env_setup $(DC) up -d --wait rabbitmq .PHONY: stop_broker stop_broker: $(DC) stop rabbitmq # проверка приватности bucket вне API на запущенном стенде: права ключа # API, чужой bucket и административные запросы (bootstrap в режиме check), # анонимные запросы с хоста и из сети стенда, порты контейнера S3 из сети; # таблица «проверка → ожидаемо → получено», проверочные объекты и bucket # удаляются. Код 1 — нарушение .PHONY: s3_check s3_check: $(PYTHON) .claude/skills/run-mtusi-messenger/driver.py s3-check # разовая сверка bucket и БД в контейнере уборщика (образ собирает # make run_docker): по умолчанию dry-run — отчёт без изменений; APPLY=1 — # исправить, MAX_CHANGES=N — предел изменений прохода вместо [reconciler] # max_changes; STRATEGY=head — HEAD на строку вместо страниц, DEEP=1 — # глубокая (SHA-256 содержимого), RATE=R — предел скорости, объектов S3 в # секунду (0 — без предела) вместо [reconciler] max_objects_per_second. # Код 0 — расхождений нет, 3 — остались, 1 — прерван, 2 — конфигурация # (design change track2-reconciler, решения 1 и 8; track2-reconcile-cost, # решения 4–6) .PHONY: reconcile reconcile: $(DC) run --rm --no-deps cleaner reconcile$(if $(filter 1,$(APPLY)), --apply)$(if $(MAX_CHANGES), --max-changes $(MAX_CHANGES))$(if $(STRATEGY), --strategy $(STRATEGY))$(if $(filter 1,$(DEEP)), --deep)$(if $(RATE), --max-objects-per-second $(RATE)) # ------------------------- # Реплики за балансировщиком (HAProxy) # ------------------------- # вернуть остановленные реплики (scripts/stop-one.sh) и выставить их # число: остановленные контейнеры запускаются с теми же ID, недостающие # создаются, лишние удаляются; ждёт healthcheck реплик. Разовая подмена — # make replicas API_REPLICAS=3, следующий make run_docker вернёт число # из .env .PHONY: replicas replicas: $(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api # поочерёдная замена реплик на новый образ без простоя # (scripts/rolling-update.sh): сборка, миграции один раз, затем по одной — # новая реплика UP в LB, старая выводится из LB (drain), дорабатывает # запросы, останавливается и удаляется. COMMIT= — образ из файлов # commit (git archive, рабочее дерево не трогается), MIGRATE=0 — без # миграций (откат на прежний образ: схема только расширялась). Нужен # штатный стенд: API_REPLICAS реплик, все UP (make replicas) COMMIT ?= MIGRATE ?= 1 .PHONY: rolling_update rolling_update: API_REPLICAS=$(API_REPLICAS) ROLLOUT_COMMIT="$(COMMIT)" ROLLOUT_MIGRATE=$(MIGRATE) scripts/rolling-update.sh # распределение запросов одной сессии через LB: вход одним синтетическим # пользователем, серия GET /users/me с одним токеном, X-Instance-Id каждого # ответа и число ответов каждой реплики .PHONY: instances instances: $(PYTHON) .claude/skills/run-mtusi-messenger/driver.py --port $(APP_OUT_PORT) instances # состояние реплик глазами HAProxy: занятые слоты, адрес, статус проверки, # соединения, запросы, ошибки соединения, повторы и перенаправления. CSV # статистики читается изнутри контейнера LB: порт 8404 наружу не # опубликован, curl в образе нет, bash есть LB_STATS_FIELDS = svname addr status check_status scur stot econ wretr wredis hrsp_5xx .PHONY: lb_stats lb_stats: @$(DC) exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/8404 && printf "GET /stats;csv HTTP/1.0\r\n\r\n" >&3 && cat <&3' \ | awk -F, -v fields="$(LB_STATS_FIELDS)" ' \ /^# pxname/ { sub(/^# /, ""); for (i = 1; i <= NF; i++) col[$$i] = i; \ n = split(fields, f, " "); for (j = 1; j <= n; j++) printf "%s\t", f[j]; print ""; next } \ $$1 != "api" { next } \ $$2 != "BACKEND" && $$(col["addr"]) == "" && $$(col["status"]) == "MAINT (resolution)" { free++; next } \ { for (j = 1; j <= n; j++) { v = $$(col[f[j]]); printf "%s\t", (v == "" ? "-" : v) }; print "" } \ END { printf "free slots: %d\n", free }' \ | column -t -s "$$(printf '\t')" # ------------------------- # Load benchmark # ------------------------- BENCH_LABEL ?= baseline # macOS не засыпает на время замера (сон ставит ВМ Docker на паузу посреди # прогона): -u будит из DarkWake полностью, -i и -s не дают уснуть до # конца; на других ОС caffeinate нет, и префикс пустой KEEP_AWAKE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu) # полная матрица на своём проекте compose mtusi-bench (API, PostgreSQL, # Valkey, без портов хоста), с фоновыми чатами разного размера, вариантами # плана и пробами записи, ~35 мин; метка не должна существовать; # результаты и планы запроса истории — evidence/bench/$(BENCH_LABEL)/, # ход — строки в терминале и progress.json .PHONY: bench bench: $(KEEP_AWAKE) uv run python bench/run.py --profile full --label $(BENCH_LABEL) # самопроверка стенда на малых размерах, ~3 мин; результат в git не идёт .PHONY: bench_quick bench_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ) RESTORE_LABEL ?= restore # трек 2: backup под записью, восстановление в новое хранилище, сверка БД и # через HTTP, кэш до и после FLUSHALL — на 10k / 100k / 500k с фоновыми # чатами, без матрицы прогонов, ~20 мин; результат — # evidence/bench/$(RESTORE_LABEL)/ .PHONY: bench_restore bench_restore: $(KEEP_AWAKE) uv run python bench/run.py --profile restore --label $(RESTORE_LABEL) # то же на малых размерах (самопроверка, сценарий защиты), ~1,5 мин; в git # не идёт .PHONY: bench_restore_quick bench_restore_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile restore_quick --label quick-restore-$(shell date -u +%Y%m%dT%H%M%SZ) FAILOVER_LABEL ?= baseline # уровень 4: отказ реплик под нагрузкой на стенде mtusi-bench (HAProxy, две # реплики с лимитами рабочего стенда): 100 записей с ключом и 100 чтений в # секунду, каждая реплика в режимах stop, kill и pause с возвратом, # посекундная шкала, время обнаружения и восстановления, сверка записей, # CPU и память по компонентам и окнам (сэмплер); ~6 мин; результат — # evidence/failover/$(FAILOVER_LABEL)/ .PHONY: bench_failover bench_failover: $(KEEP_AWAKE) uv run python bench/run.py --profile failover --label $(FAILOVER_LABEL) # то же короче, режимы stop и kill (самопроверка), с CPU и памятью по # компонентам и окнам (сэмплер), ~2 мин; в git не идёт .PHONY: bench_failover_quick bench_failover_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile failover_quick --label quick-failover-$(shell date -u +%Y%m%dT%H%M%SZ) ROLLOUT_LABEL ?= baseline # уровень 4: поочерёдная замена реплик под нагрузкой на стенде mtusi-bench # (HAProxy, две реплики с лимитами рабочего стенда): реплики стартуют на # образе прежнего commit (Profile.rollout_from), посреди 100 записей с # ключом и 100 чтений в секунду scripts/rolling-update.sh меняет их на # образ текущего checkout; посекундная шкала, шаги по репликам, сверка # записей, CPU и память по компонентам и окнам (сэмплер); ~3 мин; # результат — evidence/rollout/$(ROLLOUT_LABEL)/ .PHONY: bench_rollout bench_rollout: $(KEEP_AWAKE) uv run python bench/run.py --profile rollout --label $(ROLLOUT_LABEL) # то же с короткими окнами (самопроверка), с CPU и памятью по компонентам и # окнам (сэмплер), ~2 мин; в git не идёт .PHONY: bench_rollout_quick bench_rollout_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile rollout_quick --label quick-rollout-$(shell date -u +%Y%m%dT%H%M%SZ) UPLOADS_LABEL ?= baseline # выключатель телеметрии профилей загрузок и очереди (лаба 6, design change # track1-telemetry-cost, решение 13): on — Collector, Prometheus, Loki и Tempo # рабочего стенда и SDK реплик, worker и relay; по умолчанию off — методика # прежняя. Режим — в паспорте и сводке, продолжение RESUME=1 — в том же режиме TELEMETRY ?= off # уровень 4 лабы 4: память реплики при одновременных загрузках на стенде # mtusi-bench (HAProxy, одна реплика 1 CPU / 512 МБ без swap, S3 рабочего # стенда): варианты «до» (Profile.uploads_before), «без лимита» и «с # лимитом» × тела 1 и 10 MiB × 1/10/20/40 клиентов × 3 повтора, на каждый # прогон — новые S3 и реплика; пик памяти окна, OOM, ответы по кодам, # загрузок/с; ~50 мин; результат — evidence/uploads/$(UPLOADS_LABEL)/. # TELEMETRY=on|off — выключатель телеметрии стенда .PHONY: bench_uploads bench_uploads: $(KEEP_AWAKE) uv run python bench/run.py --profile uploads --label $(UPLOADS_LABEL) --telemetry $(TELEMETRY) # то же коротко (самопроверка): «без лимита» и «с лимитом», 10 MiB, 1/10/40 # клиентов, один повтор, ~5 мин; в git не идёт .PHONY: bench_uploads_quick bench_uploads_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile uploads_quick --label quick-uploads-$(shell date -u +%Y%m%dT%H%M%SZ) --telemetry $(TELEMETRY) # Очередь под перегрузкой (лаба 5, трек 1; design change track1-queue-overload): # стенд mtusi-bench с S3, брокером, relay, worker и уборщиком, настройки # конкуренции и prefetch × классы изображений × 3 повтора и блоки предела, приёма, # второго worker и рестартов, на каждую ячейку — свежий стенд; ~2 ч 10 мин; # результат — evidence/queue/$(QUEUE_LABEL)/. RESUME=1 — продолжить прерванную метку # на том же commit; TELEMETRY=on|off — выключатель телеметрии стенда QUEUE_LABEL ?= baseline .PHONY: bench_queue bench_queue: $(KEEP_AWAKE) uv run python bench/run.py --profile queue --label $(QUEUE_LABEL) $(if $(RESUME),--resume) --telemetry $(TELEMETRY) # то же коротко (самопроверка, защита): две настройки, предел с пределом 40 и без # него, рестарт worker, второй worker, окна короче, ~11 мин; в git не идёт .PHONY: bench_queue_quick bench_queue_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile queue_quick --label quick-queue-$(shell date -u +%Y%m%dT%H%M%SZ) --telemetry $(TELEMETRY) # Цена наблюдаемости (лаба 6, трек 1; design change track1-telemetry-cost): # стенд mtusi-bench профиля очереди и, в вариантах с телеметрией, Collector, # Prometheus, Loki и Tempo рабочего стенда; варианты off, full, full-aa, head, # tail, metrics, balanced × 3 повтора кругами, свежий стенд на прогон, одинаковая # открытая нагрузка и редкие события; ~1 ч 50 мин; результат — # evidence/telemetry-cost/$(TELEMETRY_LABEL)/. RESUME=1 — продолжить прерванную # метку на том же commit; VARIANTS=a,b — отладка (переопределение в паспорте) TELEMETRY_LABEL ?= baseline .PHONY: bench_telemetry bench_telemetry: $(KEEP_AWAKE) uv run python bench/run.py --profile telemetry --label $(TELEMETRY_LABEL) $(if $(RESUME),--resume) $(if $(VARIANTS),--variants $(VARIANTS)) # то же коротко (калибровка, защита «для 5»): все варианты, кроме копии A/A, по # одному разу, окна 10 + 30 + 15 с, ~20 мин; VARIANTS=off,full,tail — ~10 мин; # в git не идёт .PHONY: bench_telemetry_quick bench_telemetry_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile telemetry_quick --label quick-telemetry-$(shell date -u +%Y%m%dT%H%M%SZ) $(if $(VARIANTS),--variants $(VARIANTS)) RECONCILE_LABEL ?= baseline # трек 2 «5» лабы 4: стоимость сверки bucket и БД на стенде mtusi-bench # (HAProxy, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего # стенда, разовые проходы уборщика 0,25 CPU / 256 МБ, в управляемом опыте # 1 CPU): наполнение мимо API, этапы 1 000 × 1 MiB и 10k → 30k → 100k × # 4 KiB, стратегии batch и head, глубокая сверка, фоновая нагрузка с # пределом скорости и без, отказ по пределу на образе до change # (Profile.reconcile_before) и checkout, 3 повтора; ~50 мин; результат — # evidence/reconcile/$(RECONCILE_LABEL)/ (design change track2-reconcile-cost) .PHONY: bench_reconcile bench_reconcile: $(KEEP_AWAKE) uv run python bench/run.py --profile reconcile --label $(RECONCILE_LABEL) # то же коротко (самопроверка): 2 000 × 4 KiB, по одному проходу каждого # вида, окна под нагрузкой по 5 с, отказ по пределу с 300 кандидатами, # ~4 мин (3,7 мин на шумном хосте, 2026-10-23); в git не идёт .PHONY: bench_reconcile_quick bench_reconcile_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile reconcile_quick --label quick-reconcile-$(shell date -u +%Y%m%dT%H%M%SZ) SCALING_LABEL ?= scaling-$(SERIES) # уровень 5, трек 1 «Цена масштабирования»: серия на стенде mtusi-bench — # SERIES=a (бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1, ~50 мин), b (1…6 реплик по # 1 CPU, ~100 мин), pool (4 реплики при max_connections 100 и 50, ~35 мин), # ab (1 × 1 и 6 × 1 для «до/после» и A/A, ~35 мин), db (1, 2, 4 реплики при # узком лимите CPU PostgreSQL и контроль 4 × 1 при 2 CPU, ~50 мин), db4 # (из серии db только 4 × 1 при 0,5 и 2 CPU, ~25 мин), db_quick # (самопроверка серии db, ~5 мин, метка quick-*); каждая ячейка — свежий # стенд, открытая модель, поиск R* по SLO; результат — # evidence/bench/$(SCALING_LABEL)/. RESUME=1 — продолжить прерванную метку # на том же commit .PHONY: bench_scaling bench_scaling: @if [ -z "$(SERIES)" ]; then \ echo "SERIES is required: make bench_scaling SERIES=a|b|pool|ab|db|db4|quick|db_quick [SCALING_LABEL=...] [RESUME=1]"; \ exit 2; \ fi $(KEEP_AWAKE) uv run python bench/run.py --profile scaling_$(SERIES) --label $(SCALING_LABEL) $(if $(RESUME),--resume) # самопроверка серий: две ячейки (1 × 1 и 2 × 1 при max_connections 50), # короткие окна, ~5 мин; в git не идёт .PHONY: bench_scaling_quick bench_scaling_quick: $(KEEP_AWAKE) uv run python bench/run.py --profile scaling_quick --label quick-scaling-$(shell date -u +%Y%m%dT%H%M%SZ) PLOTS ?= scaling # графики и сводка серий трека 1 из меток LABELS (через пробел): # R* от числа реплик, p95 от интенсивности, CPU по компонентам, точка # насыщения; результат — evidence/plots/$(PLOTS)/, пересоздаётся .PHONY: bench_plots bench_plots: uv run python bench/plots.py --labels "$(LABELS)" --out "$(PLOTS)" # дельта двух меток по ячейкам матрицы или, у серий трека 1, по общим # конфигурациям: BEFORE и AFTER обязательны, AA — метка того же кода, что # BEFORE, для уровня шума; CHANGE — change, к которому относится сравнение # серий (шапка таблицы, по умолчанию scaling-bench); # результат — evidence/compare/$(BEFORE)__$(AFTER).md .PHONY: bench_compare bench_compare: uv run python bench/compare.py --before "$(BEFORE)" --after "$(AFTER)" --aa "$(AA)" $(if $(CHANGE),--change "$(CHANGE)") # «до» и «после» подряд в одной сессии, два прогона bench: bench для # BEFORE, commit доказательств, git revert commit REAPPLY (возврат # откаченного изменения), затем bench для AFTER. С SERIES=<серия> вместо # полной матрицы — серия трека 1 (make bench_scaling). Сам делает два # коммита; рабочее дерево должно быть чистым .PHONY: bench_ab bench_ab: $(KEEP_AWAKE) uv run python bench/ab.py --before "$(BEFORE)" --after "$(AFTER)" --reapply "$(REAPPLY)" $(if $(SERIES),--series "$(SERIES)") # ------------------------- # Observability # ------------------------- PROMETHEUS_DIR = infra/otel/prometheus # правила Prometheus без стенда и без сети (design change slo-alerts, решение # 11): файлы infra/otel/prometheus/ — tar в одноразовый контейнер # закреплённого образа Prometheus (образ — из docker-compose.yml), там promtool # check config, check rules и test rules; затем у каждого оповещения есть # runbook_url, и каждый названный runbook — файл в git. Через stdin, а не bind # mount: так же работает в CI (job не видит своих файлов на хосте Docker) .PHONY: alerts_test alerts_test: @image=$$(sed -n 's/^ *image: *\(prom\/prometheus:[^ ]*\).*$$/\1/p' docker-compose.yml | head -n 1); \ if [ -z "$$image" ]; then echo "prometheus image is not found in docker-compose.yml"; exit 2; fi; \ echo "promtool from $$image"; \ tar -C $(PROMETHEUS_DIR) -cf - prometheus.yml rules.yml rules.test.yml | \ docker run --rm -i --network none --entrypoint sh "$$image" -c \ 'set -e; cd /etc/prometheus; tar -xf -; promtool check config prometheus.yml; promtool check rules rules.yml; promtool test rules rules.test.yml' @alerts=$$(grep -c '^ *- alert:' $(PROMETHEUS_DIR)/rules.yml); \ urls=$$(grep -c '^ *runbook_url:' $(PROMETHEUS_DIR)/rules.yml); \ if [ "$$alerts" -ne "$$urls" ]; then echo "alerts: $$alerts, runbook_url: $$urls"; exit 1; fi; \ missing=0; \ for path in $$(sed -n 's/^ *runbook_url: *//p' $(PROMETHEUS_DIR)/rules.yml); do \ if [ -f "$$path" ]; then echo "runbook $$path: ok"; else echo "runbook $$path: MISSING"; missing=1; fi; \ done; \ if [ "$$missing" -ne 0 ]; then exit 1; fi; \ echo "alerts: $$alerts, each with an existing runbook" # ------------------------- # Common targets # ------------------------- # собственные black-box тесты против запущенного сервера (BASE_URL). # EXPECT_REPLICAS — сколько реплик за BASE_URL: по умолчанию API_REPLICAS # (стенд с LB); против одного процесса — EXPECT_REPLICAS=1, и тесты # реплик пропускаются с причиной .PHONY: student_test student_test: BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest # быстрые тесты сервисов на фейках: без PostgreSQL, Valkey, S3, брокера, docker # и сети (design change unit-of-work, решение 13). Каталог вне student-tests: # правило black-box там прежнее .PHONY: service_test service_test: uv run pytest -c service-tests/pytest.ini service-tests/unit # настоящая единица работы, тот же набор условий repo на SQL и общий срок запроса # на временной базе test_uow_ в PostgreSQL стенда; база создаётся и мигрирует # в начале, удаляется при любом исходе, рабочая база не затрагивается .PHONY: service_test_db service_test_db: start_db uv run pytest -c service-tests/pytest.ini service-tests/db # образ на временной базе test_: сборка, миграции, отдельный # контейнер api на 127.0.0.1:TEST_APP_PORT, make test и make student_test, # затем уборка при любом исходе. KEEP_TEST_DB=1 оставляет базу и объекты # S3 для разбора. Valkey и S3 общие с рабочим стендом: ключи кэша и # объектов разделены именем базы, префикс test_/ удаляется при уборке. # $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и Ctrl+C обрывал уборку .PHONY: test_isolated test_isolated: env_setup start_db start_cache start_s3 start_broker $(PYTHON) student-tests/run_isolated.py $(if $(KEEP_TEST_DB),--keep-db,) # проверки отказов (pytest -m fault) на отдельном стенде: свой проект # compose <рабочий>-failures со своими Postgres и Valkey, обычный и # «тесный» API, hook student-tests/fault_hook.py; стенд и его volume # удаляются при любом исходе, рабочий стенд не затрагивается. # FAULT_ARGS — дополнительные аргументы pytest, например -k "Valkey" .PHONY: failure_checks failure_checks: env_setup $(PYTHON) student-tests/run_failures.py $(FAULT_ARGS) .PHONY: lint lint: @ruff format . @echo "code formatted" @ruff check --fix . @echo "code checked and fixed if needed" @ruff format . @echo "code formatted" @ruff check --fix . @echo "code checked and fixed if needed"