From fea6770389542a7ee94d31e3f1d083b59d6c1aa7 Mon Sep 17 00:00:00 2001 From: anastasia Date: Tue, 27 Oct 2026 22:14:19 +0300 Subject: [PATCH 1/6] feat: implement lab 4 attachments and storage reconciliation --- .agents/skills/lab4-bench/SKILL.md | 35 + .agents/skills/messenger-stand/SKILL.md | 40 + .codex/rules/messenger.rules | 168 ++ .dockerignore | 14 + .env.example | 26 +- .gitignore | 8 + .python-version | 1 + AGENTS.md | 340 +++ Dockerfile | 62 + KNOWN_ISSUES.md | 46 + Makefile | 330 +++ REPORT.md | 592 +++- alembic.ini | 13 + bench/AGENTS.md | 186 ++ bench/RUNBOOK.md | 230 ++ bench/analysis.py | 546 ++++ bench/bench.compose.yml | 104 + bench/bench.env | 8 + bench/common.py | 1056 +++++++ bench/compare.py | 248 ++ bench/fill_objects.py | 118 + bench/loadgen.py | 1250 ++++++++ bench/plots.py | 412 +++ bench/reconcile.py | 950 ++++++ bench/run.py | 2694 ++++++++++++++++++ bench/sampler.py | 274 ++ bench/uploads.py | 578 ++++ compose.yaml | 399 +++ evidence/AGENTS.md | 67 + evidence/attachments/failover.txt | 96 + evidence/attachments/smoke.txt | 18 + evidence/reconcile/working-stand.txt | 53 + evidence/s3/bootstrap.txt | 43 + evidence/s3/privacy.txt | 101 + evidence/stand/migrations.txt | 95 + evidence/stand/persistence.txt | 59 + evidence/stand/stand.txt | 91 + evidence/tests/failure-checks.txt | 131 + evidence/tests/student-test-lb.txt | 42 + evidence/tests/test-isolated.txt | 94 + infra/AGENTS.md | 297 ++ infra/haproxy/haproxy.cfg | 152 + infra/s3/bootstrap.sh | 500 ++++ infra/valkey/valkey.conf | 15 + migrations/AGENTS.md | 98 + migrations/env.py | 82 + migrations/script.py.mako | 25 + migrations/versions/0001_messenger_schema.py | 147 + migrations/versions/0002_idempotency_keys.py | 81 + migrations/versions/0003_attachments.py | 169 ++ pyproject.toml | 64 + requirements.txt | 396 +++ scripts/lab4.py | 600 ++++ scripts/restart.sh | 23 + scripts/rolling-update.sh | 424 +++ scripts/stop-one.sh | 82 + src/AGENTS.md | 241 ++ src/__init__.py | 7 + src/__main__.py | 10 + src/api/AGENTS.md | 181 ++ src/api/__init__.py | 0 src/api/deps.py | 193 ++ src/api/handlers.py | 130 + src/api/identity.py | 89 + src/api/request_id.py | 83 + src/api/routes/__init__.py | 26 + src/api/routes/attachments.py | 160 ++ src/api/routes/chats.py | 46 + src/api/routes/health.py | 32 + src/api/routes/messages.py | 52 + src/api/routes/sessions.py | 29 + src/api/routes/users.py | 24 + src/api/schemas.py | 198 ++ src/cache.py | 128 + src/cleaner/__init__.py | 1 + src/cleaner/__main__.py | 10 + src/cleaner/main.py | 293 ++ src/clock.py | 51 + src/config.py | 448 +++ src/constants.py | 92 + src/db.py | 185 ++ src/domain.py | 117 + src/early_stop.py | 63 + src/errors.py | 171 ++ src/healthcheck.py | 25 + src/images.py | 389 +++ src/log.py | 88 + src/main.py | 167 ++ src/pagination.py | 88 + src/passwords.py | 74 + src/s3.py | 369 +++ src/services/AGENTS.md | 160 ++ src/services/__init__.py | 17 + src/services/access.py | 21 + src/services/attachments.py | 384 +++ src/services/chats.py | 56 + src/services/cleanup.py | 154 + src/services/messages.py | 109 + src/services/reconcile.py | 680 +++++ src/services/sessions.py | 93 + src/services/users.py | 30 + src/storage/AGENTS.md | 159 ++ src/storage/__init__.py | 12 + src/storage/base.py | 224 ++ src/storage/cached.py | 210 ++ src/storage/objects.py | 94 + src/storage/postgres.py | 719 +++++ src/storage/tables.py | 316 ++ src/uploads.py | 65 + student-tests/AGENTS.md | 134 + student-tests/conftest.py | 133 + student-tests/fault_hook.py | 503 ++++ student-tests/fixtures/sample.jpg | Bin 0 -> 8804 bytes student-tests/helpers.py | 362 +++ student-tests/images.py | 101 + student-tests/stand.compose.yml | 25 + student-tests/stand.env | 11 + student-tests/stand.py | 481 ++++ student-tests/test_attachments.py | 456 +++ student-tests/test_auth.py | 196 ++ student-tests/test_balancing.py | 77 + student-tests/test_cache.py | 61 + student-tests/test_failures.py | 754 +++++ 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 | 1065 +++++++ 128 files changed, 27650 insertions(+), 24 deletions(-) create mode 100644 .agents/skills/lab4-bench/SKILL.md create mode 100644 .agents/skills/messenger-stand/SKILL.md create mode 100644 .codex/rules/messenger.rules create mode 100644 .python-version 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/fill_objects.py create mode 100644 bench/loadgen.py create mode 100644 bench/plots.py create mode 100644 bench/reconcile.py create mode 100644 bench/run.py create mode 100644 bench/sampler.py create mode 100644 bench/uploads.py create mode 100644 compose.yaml create mode 100644 evidence/AGENTS.md create mode 100644 evidence/attachments/failover.txt create mode 100644 evidence/attachments/smoke.txt create mode 100644 evidence/reconcile/working-stand.txt create mode 100644 evidence/s3/bootstrap.txt create mode 100644 evidence/s3/privacy.txt create mode 100644 evidence/stand/migrations.txt create mode 100644 evidence/stand/persistence.txt create mode 100644 evidence/stand/stand.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 100755 infra/s3/bootstrap.sh 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 migrations/versions/0003_attachments.py create mode 100644 pyproject.toml create mode 100644 requirements.txt create mode 100755 scripts/lab4.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/attachments.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/cleaner/__init__.py create mode 100644 src/cleaner/__main__.py create mode 100644 src/cleaner/main.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/images.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/s3.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/attachments.py create mode 100644 src/services/chats.py create mode 100644 src/services/cleanup.py create mode 100644 src/services/messages.py create mode 100644 src/services/reconcile.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/objects.py create mode 100644 src/storage/postgres.py create mode 100644 src/storage/tables.py create mode 100644 src/uploads.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/fixtures/sample.jpg create mode 100644 student-tests/helpers.py create mode 100644 student-tests/images.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_attachments.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/.agents/skills/lab4-bench/SKILL.md b/.agents/skills/lab4-bench/SKILL.md new file mode 100644 index 00000000..f9b12d24 --- /dev/null +++ b/.agents/skills/lab4-bench/SKILL.md @@ -0,0 +1,35 @@ +--- +name: lab4-bench +description: Load measurements of lab 4 for grade 5 — peak memory of concurrent attachment uploads (level 4, profile uploads) and the cost of the bucket/database reconcile pass (track 2, profile reconcile). Use when asked to run benchmarks, make bench-uploads / bench-reconcile (or their -quick self-checks), or fill REPORT.md with measured numbers and hypothesis outcomes. +--- + +# Замеры лабы 4 (уровень 4 и трек 2) + +Порядок работы — **`bench/RUNBOOK.md`**, правила стенда — +`bench/AGENTS.md`. Прочитать оба целиком (`cat`) до первой команды +`make bench-*`; корневой `AGENTS.md` (разделы 2, 8–11) действует всегда. + +Коротко: + +1. Шаг 0 RUNBOOK: ресурсы ВМ Docker (≥ 10 CPU, ≥ 7 ГиБ, ядро ≥ 6.12), + самопроверки разбора (`bench/analysis.py`, `uploads.py`, + `reconcile.py` с `--selftest`), `make test-isolated`, + `make failure-checks`, `make stop`, самопроверки + `make bench-uploads-quick` и `make bench-reconcile-quick`. Остановка и + отчёт пользователю. +2. Уровень 4: `make bench-uploads` (~45 мин) → `evidence/uploads/baseline/`; + таблица ячеек и итоги U1–U4 из `summary.md` — в `REPORT.md`. +3. Трек 2: `make bench-reconcile` (~45 мин) → + `evidence/reconcile/baseline/`; таблицы проходов и фоновой нагрузки, + итоги H1–H5 — в `REPORT.md`. +4. Шаг 3 RUNBOOK: строки `TODO (Codex)` в `REPORT.md`, раздел «Железо и + стенд замеров» из `meta.json`, `make lint`, `make check`, + `make test-isolated`, уборка `vlad-bench*`. + +Нельзя: переписывать гипотезы после замеров, менять код приложения или +профиль ради результата, править файлы меток руками, перезаписывать или +удалять каталоги меток без согласия, считать числа вручную вместо +`summary.md`. Долгие команды — в фоне с журналом (`nohup make … > +/tmp/bench-*.log 2>&1 &`), docker — вне sandbox с одобрения пользователя. +`found differs from the model`, `aborted`, `host_warnings` — остановиться +и сказать пользователю. diff --git a/.agents/skills/messenger-stand/SKILL.md b/.agents/skills/messenger-stand/SKILL.md new file mode 100644 index 00000000..b1de6300 --- /dev/null +++ b/.agents/skills/messenger-stand/SKILL.md @@ -0,0 +1,40 @@ +--- +name: messenger-stand +description: Run, check and operate the lab 4 messenger stand — HAProxy with API replicas, PostgreSQL, Valkey, SeaweedFS S3 with bootstrap, the cleaner. Use when asked to start or stop the stand, run make test / student-test / test-isolated / failure-checks / s3-check, show X-Instance-Id distribution, stop one replica (test-failover, attachment-failover), restore replicas, run cleanup or reconcile, do a rolling update, or reproduce an API bug over HTTP. +--- + +# Стенд мессенджера лабы 4 + +Команды — корневой `AGENTS.md`, раздел 4; устройство стенда, S3, +уборщик, таймауты, скрипты — `infra/AGENTS.md`; тесты — +`student-tests/AGENTS.md`. + +| Задача | Команда | +|---|---| +| поднять стенд (LB + 2 реплики + хранилища + S3 + уборщик) | `make up` → `127.0.0.1:${HOST_PORT:-8080}` | +| публичный smoke / свои тесты | `make test`, `make student-test` | +| всё на чистом отдельном стенде | `make test-isolated` (smoke, тесты, attachment-failover, test-failover, test-persistence) | +| проверки отказов | `make failure-checks [FAULT_ARGS=-rP]` | +| приватность bucket вне API | `make s3-check` | +| вложение после остановки принявшей реплики | `make attachment-failover [STOP_MODE=kill]` | +| реплики за LB | `make instances`, `make lb-stats` | +| отказ каждой реплики по очереди | `make failover-each [STOP_MODE=kill]` | +| вернуть реплики / изменить число | `make replicas [API_REPLICAS=3]` | +| уборка незавершённых загрузок / сверка (dry-run) | `make cleanup-once` / `make reconcile [STRATEGY=head] [DEEP=1]` | +| обновить код без простоя | `make rolling-update` | +| остановить / удалить контейнеры | `make stop` / `make down` (volume остаются) | + +Правила: + +- Порт занят другим сервисом — не убивать процесс: другой порт в `.env` + (`make env HOST_PORT=… S3_HOST_PORT=…` до первого `make up`) и + `BASE_URL=http://localhost:<порт>` у тестов. +- Тесты против рабочего стенда оставляют в базе и bucket синтетические + данные; чистый прогон — `make test-isolated`. +- `make reconcile APPLY=1` меняет рабочий стенд (удаляет объекты без + строки, помечает потерянные оригиналы) — только с согласия + пользователя; без `APPLY` — только отчёт. +- `make wipe`, `docker compose down -v` и любое удаление volume — только + с согласия пользователя. +- Пароли и ключи S3 из `.env` и токены не печатать; в `evidence/` — + только обезличенный вывод (`evidence/AGENTS.md`). diff --git a/.codex/rules/messenger.rules b/.codex/rules/messenger.rules new file mode 100644 index 00000000..551ea7c1 --- /dev/null +++ b/.codex/rules/messenger.rules @@ -0,0 +1,168 @@ +# Правила команд 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 "$PWD/.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-lab4*, 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", + "attachment-failover", "s3-check", "cleanup-once", + "bench-uploads", "bench-uploads-quick", "bench-reconcile", + "bench-reconcile-quick", + "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-uploads", "make bench-reconcile-quick", "make failover-each STOP_MODE=kill"], + not_match = ["make wipe", "make reconcile APPLY=1"], +) + +# make reconcile без APPLY — dry-run: ничего не меняет +prefix_rule( + pattern = ["make", "reconcile"], + decision = "allow", + justification = "Dry-run reconcile only reports discrepancies (exit 0 or 3).", + match = ["make reconcile", "make reconcile STRATEGY=head DEEP=1"], +) + +# с APPLY=1 сверка удаляет объекты без строки и помечает потерянные +# оригиналы в рабочей базе: спросить пользователя +prefix_rule( + pattern = ["make", "reconcile", "APPLY=1"], + decision = "prompt", + justification = "reconcile --apply deletes orphan objects and marks lost originals in the working stand: ask the user first.", + match = ["make reconcile APPLY=1", "make reconcile APPLY=1 MAX_CHANGES=10"], +) + +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/reconcile.py --selftest"], +) + +prefix_rule( + pattern = [["python3", "python"], ["scripts/lab4.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/lab4.py s3-check", "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 d99d26a2..5ac0a2cd 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,6 +12,8 @@ SESSION_STORE=postgres CACHE_URL_FILE=/run/secrets/cache_url API_REPLICAS=2 IDEMPOTENCY_TTL_SECONDS=86400 +# Lab 4 logical names (skeleton). Containers get S3_ENDPOINT from compose.yaml, +# make run overrides it with 127.0.0.1:S3_HOST_PORT; keys come from the lines below. S3_ENDPOINT=http://s3:9000 S3_REGION=us-east-1 S3_BUCKET=messenger-attachments @@ -18,3 +21,24 @@ S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key MAX_UPLOAD_BYTES=10485760 MAX_IMAGE_PIXELS=40000000 + +# Compose and make run. make env fills the empty passwords and keys 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 +# S3 (SeaweedFS): the root pair and the signing key stay with the s3 server; +# the API and the cleaner have their own users created by s3-bootstrap. +S3_HOST_PORT=8334 +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= diff --git a/.gitignore b/.gitignore index b5a71896..a14ce6f5 100644 --- a/.gitignore +++ b/.gitignore @@ -25,8 +25,16 @@ bin/ obj/ coverage/ *.log +!evidence/**/raw/*.log .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-*/ +evidence/uploads/quick-*/ +evidence/reconcile/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/.python-version b/.python-version new file mode 100644 index 00000000..24ee5b1b --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.13 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..c1bb5170 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,340 @@ +# AGENTS.md — мессенджер MTUSI, лабораторная 4 + +REST API мессенджера с вложениями-изображениями: реплики API за HAProxy, +PostgreSQL — источник истины (в том числе метаданные вложений), Valkey — +кэш карточек чатов, S3 (SeaweedFS) — байты в приватном bucket. Код +перенесён из сданной лабы 3: загрузка PNG/JPEG (201 `ready`), скачивание +через API, `attachment_ids`, уборщик, сверка bucket и БД. Цель — **«5»**: +уровни 3 и 4 `README.md` и трек 2 «Согласованность двух хранилищ». + +**Состояние (23 октября 2026).** Код, тесты, стенд и все проверки без +нагрузки готовы и сняты на машине разработки (`evidence/`, таблица +доказательств `REPORT.md`): `make test-isolated` — все 0, +`make failure-checks` — 24 passed, `make s3-check` — 63 проверки без +нарушений. Самопроверки `make bench-uploads-quick` и +`make bench-reconcile-quick` прошли. **Остались замеры под нагрузкой на +машине замеров** — порядок в `bench/RUNBOOK.md`: профили `uploads` +(уровень 4, пик памяти) и `reconcile` (трек 2, стоимость обхода), итоги +гипотез U1–U4 и H1–H5 в `REPORT.md` (строки `TODO (Codex)`). Гипотезы +записаны до замеров — не переписывать. + +Стек: Python 3.13, FastAPI, uvicorn, pydantic v2, SQLAlchemy Core 2.1 + +asyncpg, alembic, argon2-cffi, redis-py, aiobotocore 3.x; PostgreSQL +18.6, Valkey 9.1.2, HAProxy 3.4.6, SeaweedFS 4.48; 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; объекты S3 | +| `migrations/AGENTS.md` | схема БД, новые ревизии, совместимость с работающей версией | +| `infra/AGENTS.md` | `Dockerfile`, `compose.yaml`, S3 и bootstrap, уборщик, HAProxy и цепочка таймаутов, `scripts/*.sh`, `scripts/lab4.py` | +| `student-tests/AGENTS.md` | собственные тесты, отдельные стенды, проверки отказов | +| `evidence/AGENTS.md` | доказательства для `REPORT.md` | +| `bench/AGENTS.md` | нагрузочный стенд: методика, честность результатов | +| `bench/RUNBOOK.md` | замеры лабы 4 по шагам; читать перед любым `make bench-*` | + +Ещё Codex читает **правила команд** `.codex/rules/messenger.rules` (что +идёт вне sandbox без вопроса, что с подтверждением, что запрещено; +только у доверенного проекта, после правки — перезапуск Codex; проверка +— `codex execpolicy check --pretty --rules "$PWD/.codex/rules/messenger.rules" +make wipe`, команда без `--`) и **навыки** `.agents/skills/`: `lab4-bench` (замеры по +`bench/RUNBOOK.md`), `messenger-stand` (стенд, проверки, демонстрация). +Правила дублируют раздел 2, но не заменяют его. + +Конфликт: более глубокий файл уточняет корневой, но не отменяет +раздел 2. Прямая просьба пользователя в чате важнее этих файлов, кроме +пунктов раздела 2, помеченных «спросить»: там сначала переспроси. + +## 2. Нельзя + +1. **Менять skeleton преподавателя** (спросить): `contracts/`, `tests/`, + `scripts/` (кроме своих `restart.sh`, `stop-one.sh`, + `rolling-update.sh`, `lab4.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`, `examples/`, `.github/`, верх `Makefile` до + строки `=====`. Публичный тест упал — чиним приложение. +2. **Подгонять тесты под код**: ослаблять `assert`, менять ожидаемый + статус, ставить `skip`/`xfail`, удалять тест, чтобы прогон позеленел. +3. **Состояние в памяти процесса, от которого зависит корректность**: + сессии, данные, ключи идемпотентности и метаданные — только + PostgreSQL, байты вложений — только S3 (не диск реплики и не БД); + Valkey — только кэш неизменяемой карточки чата. `--workers`, + gunicorn, `reload` в образе: масштабирование — числом реплик. Sticky + session в HAProxy. Уборка и сверка — только процесс `cleaner`, не + реплики. +4. **Порты реплик наружу и `container_name` у `api`**; консоль, + master, volume, filer SeaweedFS и мониторинг LB — наружу. +5. **Файлы конфигурации приложения** (`config.toml`, pydantic-settings с + файлами): настройки — только переменные окружения (`src/config.py`). +6. **JSON-логи, structlog, `print`** вместо логгера (`src/log.py`). +7. **Писать в лог** текст сообщений, `display_name`, `title`, username, + `filename` (только длину), пароль, токен, ключи S3, их хэши, + `Authorization`, `Idempotency-Key`, тела, параметры SQL. Можно id, + ключ объекта S3, длины и размеры. +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` в рабочей базе, удаление объектов рабочего + bucket мимо API; каталоги меток в `evidence/`. +10. **Секреты и `.env`** в git, образ, `evidence/`, вывод и отчёт; `COPY . + .` в Dockerfile. Пароли, токены и ключи S3 в командной строке не + печатать. Административную пару S3 — никому, кроме сервера `s3`. +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/` — только + реальный вывод команд, которые ты запустил. Гипотезы U1–U4 и H1–H5 + после замеров не переписывать. +17. **Чинить попутно найденное** без просьбы: записать в + `KNOWN_ISSUES.md` (путь, симптом, предложение) и сказать в отчёте. +18. **Менять код приложения ради замеров** (спросить): профили `bench/` + проверяют записанные гипотезы на коде, который уже проверен. + +## 3. Порядок работы + +1. Найди, откуда требование: `README.md` (рубрика), `contracts/README.md` + (семантика, раздел «Вложения (с lab4)»), `contracts/openapi.json` + (схемы, коды), `COURSE.md` (переходы API). Неясно или противоречит + контракту — остановись и спроси. Ответ преподавателя — в раздел 12. +2. Прочитай нужные `AGENTS.md` (раздел 1) и затрагиваемые файлы целиком. +3. Задача больше пары файлов — сначала короткий план в чате. +4. Минимальный дифф: не переименовывать и не «улучшать» лишнее. +5. Проверки из раздела 8 — до того, как сказать «готово». +6. Отчёт пользователю — раздел 11. + +## 4. Команды + +| Команда | Что делает | +|---|---| +| `make install` / `make env [HOST_PORT=…]` | `uv sync` / `.env` со случайными паролями и ключами S3 (существующий дополняется) | +| `make up` | postgres, valkey, s3 → migrate, s3-bootstrap → api × `API_REPLICAS` (2), cleaner → haproxy на `127.0.0.1:HOST_PORT` (8080); ждёт healthy | +| `make stop` / `make down` / `make logs` | остановить / удалить контейнеры (volume остаются) / журнал реплик | +| `make wipe` | удалить контейнеры и volume `pgdata`, `s3data`: только после `yes` (раздел 2, п. 9) | +| `make replicas [API_REPLICAS=N]` / `make instances` / `make lb-stats` | вернуть реплики / `X-Instance-Id` одной сессии / слоты HAProxy | +| `make failover-each [STOP_MODE=kill]` | `make test-failover` для каждой реплики по очереди | +| `make attachment-failover [STOP_MODE=kill]` | вложение → стоп принявшей реплики → скачивание через другую (тот же SHA-256), 404 постороннему | +| `make s3-check` | приватность bucket вне API: права ключей, анонимно с хоста и из сети, порты S3 | +| `make cleanup-once` / `make reconcile [APPLY=1] [MAX_CHANGES=N] [STRATEGY=head] [DEEP=1] [RATE=R]` | разовый проход уборщика / разовая сверка, по умолчанию dry-run (0 / 3 / 1 / 2) | +| `make rolling-update` | поочерёдная замена реплик без простоя | +| `make db-up` / `make run [RUN_PORT=8081]` / `make migrate-local` | хранилища и bootstrap / процесс на хосте без LB / миграции с хоста | +| `make lint` / `make fmt` | ruff: проверка / исправление и формат | +| `make test [BASE_URL=...]` | публичный smoke (вложение, SHA-256, 404 постороннему) | +| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные, токен и оригинал после рестарта LB, реплик и всех хранилищ | +| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh [STOP_MODE=kill]` | отказ одной реплики: запись ≤ 10 с, без дублей | +| `make student-test [BASE_URL=...] [EXPECT_REPLICAS=...]` | свои тесты против запущенного стенда (без проверок отказов) | +| `make test-isolated` / `make failure-checks [FAULT_ARGS=-rP]` | отдельный стенд: всё выше (~2 мин) / проверки отказов (~4 мин) | +| `make check` / `make validate PYTHON=.venv/bin/python` | офлайн-проверка skeleton / валидация OpenAPI | +| `make requirements` / `make requirements-check` | `requirements.txt` из `uv.lock` / сверка | +| `make bench-uploads` / `make bench-reconcile` (+ `-quick`) | лаба 4 под нагрузкой (`bench/RUNBOOK.md`); `quick-*` в отчёт не идут | +| `make bench-failover`, `bench-rollout`, `bench-scaling` | профили лабы 3 (сохранены, в лабе 4 не обязательны) | + +Проверки ходят на `http://localhost:8080` (HAProxy). Внешние порты — +`HOST_PORT`, `POSTGRES_HOST_PORT` (5433), `VALKEY_HOST_PORT` (6380), +`S3_HOST_PORT` (8334) в `.env`; разовая подмена — аргументом make (`make +test BASE_URL=http://localhost:8090`). В сети стенда: 8080, 5432, 6379, +8333, 8404. Тесты против рабочего стенда оставляют данные; чистый прогон +— `make test-isolated`. + +## 5. Карта кода + +``` +src/ пакет приложения: python -m src (__main__ → early_stop.install() → main.run()) + main.py create_app(): Db, кэш, хранилище, клиент S3, места загрузок, пароли, middleware, роутеры + config.py Settings.from_env(): только окружение (Database, Cache, ObjectStorage, Uploads, Cleaner, сроки) + early_stop.py SIGTERM/SIGINT до старта сервера: строка журнала и выход 0 (stdlib) + constants.py, log.py, errors.py, clock.py, domain.py, pagination.py, healthcheck.py + images.py структурная проверка PNG/JPEG без декодирования пикселей (stdlib) + db.py, cache.py PostgreSQL (пул, сроки, transaction()/read()) и Valkey (срок, обход при отказе) + s3.py ObjectStore (aiobotocore): put/head/get/delete/list, срок на вызов и блок, без повторов, счётчики + uploads.py UploadSlots: места загрузок процесса, очередь, срок ожидания → 429 + passwords.py Argon2id в потоке с лимитом, фиктивный хэш + cleaner/ python -m src.cleaner: уборка незавершённых загрузок, сверка (разовая и плановая) + api/ routes/ (health, users, sessions, chats, messages, attachments), schemas, deps, + identity (BearerBackend), request_id, handlers + services/ User/Session/Chat/Message/Attachment/Cleanup/ReconcileService; access.py + storage/ base.py (Storage, MaintenanceStorage), postgres.py, cached.py, tables.py, objects.py (AttachmentObjects) +migrations/ alembic: 0001 схема лабы 2, 0002 idempotency_keys, 0003 attachments (expand) +student-tests/ тесты по HTTP; stand.py — отдельные стенды; fault_hook.py; images.py; fixtures/ +bench/ run.py, common.py, uploads.py, reconcile.py, fill_objects.py, loadgen.py, sampler.py, analysis.py, RUNBOOK.md +infra/haproxy/ haproxy.cfg: DNS Docker, проверки /health/ready, цепочка таймаутов, путь загрузки 40 с, буферы +infra/valkey/ valkey.conf: лимит памяти, LRU, без persistence +infra/s3/ bootstrap.sh: bucket, политики, пользователи API и уборщика, проверки приватности +scripts/ restart.sh, stop-one.sh, rolling-update.sh, lab4.py (свои); остальное — skeleton +.codex/rules/ правила команд Codex; .agents/skills/ — навыки Codex +evidence/ доказательства для REPORT.md; uploads/, reconcile/ — метки стенда +Dockerfile, compose.yaml, alembic.ini, pyproject.toml, uv.lock, requirements.txt, .env.example +``` + +Поток загрузки: HAProxy → реплика → middleware (401) → роут (400) → +`AttachmentService` (404, 415, 413, место 429, тело, структура) → +`pending` (PostgreSQL) → PUT (S3) → `ready` → 201; сбой между ними — +компенсация или уборщик (`src/services/AGENTS.md`). + +## 6. Контракт: самое важное + +Полностью — `src/api/AGENTS.md` и `contracts/`. Переход 3 → 4 +(`COURSE.md`): вложения и `attachment_ids`; текстовые POST лабы 3 +остаются валидными. + +- Каждый ответ API — с `X-Request-Id` и `X-Instance-Id`; ошибка — + `{"error": {"code", "message", "request_id"}}`. Коды: 400, 401, 404 + (нет или чужое — одинаково), 409, 413, 415, 429 (с `Retry-After`), 503 + (PostgreSQL или S3), 500; 422 и 403 — никогда. +- Загрузка — сырые байты, 201 `ready` только после PUT и фиксации + строки; ключ объекта назначает сервер, `filename` — для показа. Байты — + только через API участникам чата. +- Сообщение: `attachment_ids` до 10, `ready` из того же чата; пустой + текст — только с вложением. Повтор с тем же ключом (24 ч) — тот же 201. + +## 7. Конфигурация, логи, Docker, зависимости + +**Переменные окружения** читает только `src/config.py`; неверное +значение — выход с кодом 2. Группы: `APP_*`, `LOG_LEVEL`, +`SHUTDOWN_TIMEOUT`, `KEEP_ALIVE_TIMEOUT`; `SESSION_TTL_SECONDS`, +`IDEMPOTENCY_TTL_SECONDS`, `KDF_CONCURRENCY`; `DB_*`, `CACHE_*`, `S3_*`, +`UPLOAD_*`, `CLEANER_*`, `RECONCILE_*`. Таблица — `src/AGENTS.md`. +Логические имена `.env.example` skeleton и их соответствие — `REPORT.md`, +«Конфигурация». Лимиты контракта (10 MiB, 40 млн пикселей, 10 вложений) +— константы `src/constants.py`, не окружение. + +**Логи**: строка на событие, `время уровень логгер [rid=...] сообщение +key=value`; итог сверки `reconcile pass finished …` разбирает +`bench/reconcile.py` — имена полей не менять. + +**Docker, compose, S3, HAProxy** — `infra/AGENTS.md`. Числа менять только +вместе: обнаружение отказа ≤ 10 с; `timeout server` пути загрузки 40 с > +ожидание места 5 с + срок тела 30 с; `CLEANER_GRACE` 900 с > граница +живой загрузки 21 с; дренаж замены 90 с > 40 с. + +**Зависимости**: `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`, `s3.py`, таймаутов — ещё `make failure-checks`; +- [ ] правка `compose.yaml`, `haproxy.cfg`, `infra/s3/`, `scripts/*` — + `make up`, `make test`, `make instances`, `make s3-check`, + `make attachment-failover`, `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/` — самопроверки разбора и `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, S3 ещё не healthy) → чинить стенд. +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`. Чужие процессы и + контейнеры не трогать — взять другой порт (`make env HOST_PORT=… + POSTGRES_HOST_PORT=… VALKEY_HOST_PORT=… S3_HOST_PORT=…` до первого + `make up`). +- Держи этот файл ≤ ~28 КБ (`wc -c`, кириллица — два байта на символ): + Codex читает `AGENTS.md` до 32 КиБ вместе. Новое правило слоя — во + вложенный `AGENTS.md`. + +## 11. Отчёт пользователю в конце задачи + +По-русски, коротко: что сделано (файлы и суть); какие проверки и с каким +итогом (`24 passed`, `PASS: lab4 ...`, `results: {...}`, метки +`evidence/…`); что не проверено и почему; что записано в +`KNOWN_ISSUES.md`, вопросы к преподавателю. + +## 12. Согласования с преподавателем + +Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`. + +| Дата | Договорённость | Где учтено | +|---|---|---| +| 2026-10-20 | Лаба 4: «пустой текст» сообщения — и `""`, и строка только из пробельных символов. Допустимы: вложение + непустой текст, без вложения + непустой текст, вложение + пустой текст. `" "` с ≥ 1 вложением — 201, без вложений — 400 | `src/api/schemas.py` (`CreateMessage`), `student-tests/test_attachments.py`, `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/lab4.py`): Python 3.9+, stdlib, `from __future__ import + annotations`. +- Методы сервисов и изменяющие методы хранилища — keyword-only. +- Комментарии и докстринги — короткие, по-русски, объясняют «почему». + Сообщения логов и `error.message` — по-английски. +- Константы контракта — `src/constants.py`; время — `src/clock.py`. +- Коммиты (только по просьбе): английский, conventional. + +## 14. Документы решения + +`REPORT.md` (отчёт, гипотезы U1–U4 и H1–H5, ответы защиты), `evidence/` +(`evidence/AGENTS.md`), `KNOWN_ISSUES.md`, `bench/RUNBOOK.md`. Метки и +отчёт лабы 3 остались в её репозитории. + +## 15. Дальше: лаба 5 + +Новый skeleton — отдельный репозиторий; сначала его `COURSE.md` (брокер, +worker, превью; загрузка — 202). Переносить всё своё (код, тесты, +миграции, `bench/`, `infra/` кроме `README.md`, свои `scripts/*`, +Dockerfile, compose, lock-файлы, `AGENTS.md`, `.codex/`, `.agents/`, +`KNOWN_ISSUES.md`); `Makefile`, `.env.example`, `.gitignore`, +`.dockerignore` — сливать; skeleton, `.env`, volumes, `REPORT.md` и +`evidence/` — не копировать. `name:` compose — `vladimirceva-lab5`. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..fdb8026d --- /dev/null +++ b/Dockerfile @@ -0,0 +1,62 @@ +# Образ API мессенджера, лаба 4: сервер (реплики за HAProxy), миграции и +# уборщик (`python -m src.cleaner`). Правила — 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 + +# MALLOC_MMAP_THRESHOLD_: блоки glibc от 128 KiB всегда в mmap, и буфер +# тела загрузки (io.BytesIO до 10 MiB) растёт через mremap без копии. С +# динамическим порогом после первой загрузки glibc поднимает его до ~10 +# MiB, буферы растут в куче, и realloc на миг держит два тела +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + MALLOC_MMAP_THRESHOLD_=131072 \ + 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..38bfd16c --- /dev/null +++ b/KNOWN_ISSUES.md @@ -0,0 +1,46 @@ +# Известные проблемы + +Найдены попутно и не исправлены без отдельной просьбы (AGENTS.md, +раздел 2, п. 17). Формат: что, где, симптом, предложение. Исправленное +удаляется отсюда. + +## Докстринг пакета называет лабу 3 + +`src/__init__.py`: «REST API мессенджера MTUSI, лабораторная 3: реплики +за HAProxy», без S3 и вложений. Поведения не меняет. Не исправлено +намеренно: `src_sha256` (хеш `src/` и `migrations/`) подписывает +доказательства `evidence/` и метки замеров лабы 4, правка докстринга его +бы изменила. Предложение: исправить вместе со следующей правкой кода, до +новых замеров. + +## Записи лабы 3 + +Две записи ниже перенесены из лабы 3 вместе с `bench/`: они касаются +серий трека 1 лабы 3 (`make bench-scaling`), которые в лабе 4 сохранены, +но не обязательны. Профилей лабы 4 (`uploads`, `reconcile`) они не +затрагивают. + +## Возобновление прерванной серии требует доработки + +Статический анализ `bench/run.py:run_scaling` и `scaling_cell`: +ветка `resume` сохраняет прежний `meta.aborted`, а финальная проверка +этого поля возвращает ошибку даже после завершения оставшихся ячеек. +Ступени незавершённой ячейки уже записываются в `runs.csv` и +`samples.csv`; повтор той же ячейки добавляет строки с теми же номерами, +а соответствующие raw JSON перезаписываются. Очистки/разделения +незавершённого повтора в коде нет. + +Прерванный прогон специально не запускался. Обычные завершённые серии +не затронуты. Предложение: отдельно реализовать восстановление только +незавершённой ячейки с сохранением её исходных данных и снятием +`aborted` после успешного продолжения. + +## Подпись насыщения для A/B с одной конфигурацией + +В `bench/plots.py:saturation` единственная точка возвращает `None`, +а `main` трактует это как продолжающийся рост ≥ 10 %. В лабе 3 это было +видно в сводке графиков `scaling-h6` (её репозиторий): для каждой метки +и лимита БД есть только 4 реплики, поэтому проверить рост от числа +реплик нельзя. Сами R*, диапазоны и график сравнения верны. +Предложение: отдельно печатать «недостаточно конфигураций» при числе +точек меньше двух. diff --git a/Makefile b/Makefile index 5d86d171..8bb9f2a0 100644 --- a/Makefile +++ b/Makefile @@ -28,3 +28,333 @@ 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:lab4 +# порт 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 +S3_HOST_PORT ?= 8334 +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, +# пароли и ключи пользователя API в S3 из .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" \ + S3_ENDPOINT="http://127.0.0.1:$$S3_HOST_PORT" S3_ACCESS_KEY_ID="$$S3_API_ACCESS_KEY" \ + S3_SECRET_ACCESS_KEY="$$S3_API_SECRET_KEY" + +# PostgreSQL, Valkey и S3 из 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, S3, +# volume, HAProxy и две реплики, свои пароли и ключи, без .env): сборка, +# миграции и bootstrap S3, make test и make student-test через его LB, +# test-failover, test-persistence, затем уборка при любом исходе. Рабочий +# стенд не трогается. $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и +# Ctrl+C обрывал бы уборку +.PHONY: test-isolated +test-isolated: + $(PYTHON) student-tests/stand.py isolated + +# проверки отказов (pytest -m fault) на таком же отдельном стенде: свои +# хранилища и S3, уборщик с grace 25 с, обычный, «тесный» и «узкий по +# загрузкам» API, 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 и ключами S3: +# в шаблоне они пустые, общего пароля стенда в git нет. Существующий .env +# не перезаписывается — дописываются только переменные шаблона, которых в +# нём нет (секреты — случайными). Печатаются только имена +.PHONY: env +env: + @$(PYTHON) scripts/lab4.py env + +.PHONY: docker-build +docker-build: + docker build -t $(IMAGE) . + +# весь стенд: postgres, valkey, s3 -> migrate, s3-bootstrap -> api × +# API_REPLICAS и cleaner -> haproxy; --wait ждёт healthy реплик и LB +# (миграции и bootstrap к этому моменту завершились с кодом 0). Реплики с +# изменённым образом пересоздаются все разом, с простоем; без простоя — +# make rolling-update +.PHONY: up +up: env + $(DC) up -d --build --wait api cleaner haproxy + +# остановить контейнеры (SIGTERM); данные и контейнеры остаются. LB +# останавливается раньше реплик (depends_on); S3 — плавно, ~15 с +.PHONY: stop +stop: + $(DC) stop + +# удалить контейнеры; volume pgdata и s3data с данными остаются +# (удаление — wipe) +.PHONY: down +down: + $(DC) down + +# журнал всех реплик; префикс строки — имя контейнера реплики +.PHONY: logs +logs: + $(DC) logs -f api + +# хранилища стенда с ожиданием healthcheck и bootstrap S3: для make run. +# --wait одноразовый сервис не ждёт — код bootstrap отдельно +.PHONY: db-up +db-up: env + $(DC) up -d --wait postgres valkey s3 + $(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap + +# удалить контейнеры и volume с данными стенда: только после ввода yes +.PHONY: wipe +wipe: + @read -p "Удалить все данные стенда (volume PostgreSQL pgdata и S3 s3data)? Введите 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/lab4.py instances --base-url "$(BASE_URL)" + +# слоты HAProxy: адрес, состояние проверки (DRAIN/MAINT при замене), +# запросы, ошибки соединения, повторы, перенаправления +.PHONY: lb-stats +lb-stats: + $(PYTHON) scripts/lab4.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/lab4.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 + +# --- S3 и вложения (лаба 4) --------------------------------------------------- + +# вложение через LB → остановка реплики, принявшей загрузку (stop-one.sh по +# её X-Instance-Id) → скачивание через другую, тот же SHA-256 → 404 +# постороннему → make replicas. STOP_MODE=kill — без graceful +.PHONY: attachment-failover +attachment-failover: + $(PYTHON) scripts/lab4.py attachment-failover --base-url "$(BASE_URL)" \ + --replicas $(API_REPLICAS) --mode $(STOP_MODE) + +# приватность bucket вне API: права ключей API и уборщика (bootstrap в +# режиме check), анонимные запросы с хоста и из сети стенда, порты +# контейнера S3; затем уборка проверочных объектов. Код 1 при нарушении +.PHONY: s3-check +s3-check: + $(PYTHON) scripts/lab4.py s3-check + +# разовый проход уборщика незавершённых загрузок: 0 — проход дошёл до +# конца, 1 — прерван отказом, 2 — конфигурация +.PHONY: cleanup-once +cleanup-once: + $(DC) run --rm --no-deps cleaner --once + +# разовая сверка bucket и БД (трек 2) в контейнере уборщика. По умолчанию +# dry-run; APPLY=1 — исправить безопасное; MAX_CHANGES, STRATEGY=head, +# DEEP=1 (SHA-256 содержимого), RATE (объектов S3/с, 0 — без предела). +# Коды: 0 — расхождений нет, 3 — остались, 1 — прервана, 2 — конфигурация +APPLY ?= +MAX_CHANGES ?= +STRATEGY ?= +DEEP ?= +RATE ?= +.PHONY: reconcile +reconcile: + $(DC) run --rm --no-deps cleaner reconcile $(if $(APPLY),--apply,) \ + $(if $(MAX_CHANGES),--max-changes $(MAX_CHANGES),) \ + $(if $(STRATEGY),--strategy $(STRATEGY),) $(if $(DEEP),--deep,) \ + $(if $(RATE),--rate $(RATE),) + +# --- Нагрузочный стенд (уровень «4» — отказ и замена под нагрузкой лабы 3, +# память одновременных загрузок; уровень «5» — трек 2, стоимость сверки) -- +# Порядок работы — bench/RUNBOOK.md, правила — bench/AGENTS.md. Свой проект +# compose vlad-bench, рабочий стенд перед замером — make stop. + +FAILOVER_LABEL ?= baseline +ROLLOUT_LABEL ?= baseline +UPLOADS_LABEL ?= baseline +RECONCILE_LABEL ?= baseline +# серия трека 1 лабы 3 (сохраняется): a, b, db, ab, quick +SERIES ?= +SCALING_LABEL ?= +LABELS ?= +PLOTS ?= scaling +BENCH = $(CAFFEINATE) uv run python bench/run.py + +# уровень 4 лабы 3: две реплики под постоянной нагрузкой, каждая в режимах +# 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 лабы 3: поочерёдная замена (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 + +# уровень 4 лабы 4: память реплики при 1/10/20/40 одновременных загрузках +# по ~1 и ~10 MiB, варианты «с лимитом» (места по умолчанию) и «без +# лимита»; пишет evidence/uploads/<метка>/ +.PHONY: bench-uploads +bench-uploads: + $(BENCH) uploads --label "$(UPLOADS_LABEL)" + +# самопроверка профиля загрузок (~5 мин); метка quick-uploads- +.PHONY: bench-uploads-quick +bench-uploads-quick: + $(BENCH) uploads-quick + +# уровень 5, трек 2: стоимость сверки bucket и БД по размеру набора, +# стратегиям и под фоновой нагрузкой; пишет evidence/reconcile/<метка>/ +.PHONY: bench-reconcile +bench-reconcile: + $(BENCH) reconcile --label "$(RECONCILE_LABEL)" + +# самопроверка профиля сверки (~6 мин); метка quick-reconcile- +.PHONY: bench-reconcile-quick +bench-reconcile-quick: + $(BENCH) reconcile-quick + +# трек 1 лабы 3 (сохраняется для сравнения, в лабе 4 не обязателен): +# серия конфигураций, на каждую ячейку свежий стенд, открытая модель, +# поиск R*; пишет evidence/scaling/<метка>/. CONFIGS="4x1-pg0.5 4x1" — +# ячейки вместо профильных; 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=