Files
mtusi2026lab3/AGENTS.md
T

28 KiB
Raw Blame History

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 до замеров.

Указание пользователя от 15 октября 2026: выполнять замеры и при питании от батареи. Предупреждение host on battery power сохраняется в паспортах и описывается в отчёте; само по себе оно не требует остановки этой сессии. Остальные предупреждения проверяются по RUNBOOK.

Стек: 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 <PID> -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.