28 KiB
AGENTS.md — мессенджер MTUSI, лабораторная 3
REST API мессенджера (пользователи, чаты, история сообщений): реплики
API за HAProxy, PostgreSQL — источник истины (данные, сессии, ключи
идемпотентности), Valkey — общий кэш карточек чатов. Код перенесён из
лабы 2 и переведён на лабу 3: X-Instance-Id в каждом ответе,
обязательный Idempotency-Key при отправке сообщения, ≥ 2
взаимозаменяемые реплики, отказ реплики, поочерёдная замена. Цель —
оценка «5»: уровни 3 и 4 из README.md и трек 1 уровня 5 «Цена
масштабирования».
Состояние (14 октября 2026). Уровень 3 и всё, что в уровне 4 не
требует нагрузки, реализовано и проверено; доказательства — evidence/,
отчёт — REPORT.md. Нагрузочный стенд (bench/) готов и проверен
самопроверками (*-quick), но замеры под нагрузкой ещё не сняты:
отказ каждой реплики и замена под нагрузкой (уровень 4), серии трека 1
и улучшение. Следующая работа — bench/RUNBOOK.md (на устройстве,
где идут замеры); в REPORT.md их места помечены TODO (Codex).
Гипотезы трека 1 записаны в REPORT.md до замеров.
Стек: Python 3.13, FastAPI + Starlette 1.x, uvicorn, pydantic v2,
SQLAlchemy Core 2.1 + asyncpg, alembic, argon2-cffi, redis-py;
PostgreSQL 18.6, Valkey 9.1.2, HAProxy 3.4; uv (локально), pip +
requirements.txt с хешами (в образе), pytest + httpx.
1. Где инструкции и как их читать
Codex сам загружает AGENTS.md от корня репозитория до рабочего
каталога (вместе — не больше 32 КиБ). Правила слоёв лежат глубже,
поэтому перед правкой файла прочитай каждый AGENTS.md на пути к
нему (cat), даже если задача «на одну строку».
| Файл | Когда читать |
|---|---|
AGENTS.md (этот) |
всегда: запреты, команды, карта, Definition of Done |
src/AGENTS.md |
любая правка в src/: слои, импорты, ошибки, конфиг, точка входа, логи, время |
src/api/AGENTS.md |
роуты, схемы, middleware, вход и Bearer, X-Instance-Id, Idempotency-Key |
src/services/AGENTS.md |
бизнес-правила, пароли и сессии, отправка с ключом |
src/storage/AGENTS.md |
PostgreSQL: транзакции, гонки, ключ идемпотентности; кэш Valkey |
migrations/AGENTS.md |
схема БД, новые ревизии, совместимость с работающей версией |
infra/AGENTS.md |
Dockerfile, compose.yaml, HAProxy и цепочка таймаутов, scripts/*.sh, scripts/lab3.py |
student-tests/AGENTS.md |
собственные тесты, отдельные стенды, проверки отказов |
evidence/AGENTS.md |
доказательства для REPORT.md |
bench/AGENTS.md |
нагрузочный стенд: методика, честность результатов |
bench/RUNBOOK.md |
замеры уровня 4 и трека 1 по шагам; читать перед любым make bench-* |
Кроме AGENTS.md, Codex читает из проекта:
- правила команд
.codex/rules/messenger.rules(Starlark,prefix_rule): что запускается вне sandbox без вопроса (make …проекта,docker ps/logs/compose,uv run), что требует подтверждения (git-изменения,make wipe,down -v, удаление контейнеров и volume,kill,rm -r) и что запрещено (git push,git clean,docker … prune). Загружаются, только если проект доверенный (trusted); после правки — перезапустить Codex; проверка —codex execpolicy check --pretty --rules .codex/rules/messenger.rules -- <команда>. Правила дублируют раздел 2, но не заменяют его; - навыки
.agents/skills/*/SKILL.md:lab3-bench— замеры поbench/RUNBOOK.md,messenger-stand— работа со стендом. Codex выбирает их по описанию или по$имя.
Конфликт: более глубокий файл уточняет корневой, но не отменяет раздел 2. Прямая просьба пользователя в чате важнее этих файлов, кроме пунктов раздела 2, помеченных «спросить»: там сначала переспроси.
2. Нельзя
- Менять 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). Публичный тест упал — чиним приложение. - Подгонять тесты под код: ослаблять
assert, менять ожидаемый статус, ставитьskip/xfail, удалять тест, чтобы прогон позеленел. - Состояние в памяти процесса, от которого зависит корректность:
сессии, данные и ключи идемпотентности — только PostgreSQL; Valkey —
только кэш неизменяемой карточки чата.
--workers, gunicorn,reloadв образе: масштабирование — числом реплик. Sticky session (cookie, stick-table) в HAProxy. - Порты реплик наружу и
container_nameуapi: API — только через HAProxy (рубрика «4»). - Файлы конфигурации приложения (
config.toml, pydantic-settings с файлами): настройки — только переменные окружения (src/config.py). - JSON-логи, structlog,
printвместо логгера (src/log.py). - Писать в лог текст сообщений,
display_name,title, username, пароль, токен, их хэши,Authorization,Idempotency-Key, тела, параметры SQL. Можно id и длины. - Git без просьбы:
commit,push,checkout,reset,stash,rebase,clean. Смотреть можно:status,diff,log. - Удалять данные стенда без просьбы (спросить):
make wipe,docker compose down -v,docker volume rm,FLUSHALLрабочего Valkey,TRUNCATE/DROPв рабочей базе; каталоги меток вevidence/. - Секреты и
.envв git, образ,evidence/, вывод и отчёт;COPY . .в Dockerfile. Пароли и токены в командной строке не печатать. - Незакреплённые версии:
latest, тег без digest, пакет без lock. - Новая зависимость (спросить): объяснить, зачем она и почему не хватает stdlib и текущих пакетов; проверить точное имя пакета.
- Миграция, которая ломает работающую версию (удаление,
переименование,
NOT NULLбез значения): только расширение схемы, contract — отдельной ревизией позже (migrations/AGENTS.md). Править применённую ревизию нельзя. HTTPExceptionв сервисах и хранилище, 403 для чужого чата, 422 наружу: ошибки только черезsrc/errors.py. Прозрачные повторыPOST(кроме отказа соединения в LB).- Обходить sandbox Codex (раздел 10): нет сети или docker — просить одобрение или пользователя.
- Выдумывать результаты: в отчёт,
REPORT.mdиevidence/— только реальный вывод команд, которые ты запустил. Гипотезы трека 1 после замеров не переписывать. - Чинить попутно найденное без просьбы: записать в
KNOWN_ISSUES.md(путь, симптом, предложение) и сказать в отчёте.
3. Порядок работы
- Найди, откуда требование:
README.md(рубрика),contracts/README.md(семантика),contracts/openapi.json(схемы, коды),COURSE.md(переходы API). Неясно или противоречит контракту — остановись и спроси. Ответ преподавателя — в раздел 12. - Прочитай нужные
AGENTS.md(раздел 1) и затрагиваемые файлы целиком. - Задача больше пары файлов — сначала короткий план в чате.
- Минимальный дифф: не переименовывать и не «улучшать» лишнее.
- Проверки из раздела 8 — до того, как сказать «готово».
- Отчёт пользователю — раздел 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);limit1–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. Если тест или проверка упали
- Воспроизведи и прочитай вывод целиком.
- Назови причину: дефект приложения → чинить код; ошибка в самом
тесте (противоречит контракту или зависит от случайного) → править
тест можно, но назови, чему он противоречил; стенд (порт занят
чужим сервисом — smoke получает 404 на
/health/live, старый образ, не тотBASE_URL, остатки прерванного прогона, реплика ещё неUPв LB) → чинить стенд. - Причина неясна или правка теста спорная — остановись и спроси.
Тест 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.