28 KiB
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 «Согласованность двух хранилищ».
Состояние (30 октября 2026). Работа на «5», трек 2 завершена. Исправлена JPEG-валидация: пустой скан после SOS (в том числе одни RST) — 415; добавлены 4 HTTP-теста. Прогон: 134 теста, все results 0 (evidence/tests/jpeg-validation.txt). Метки до правки: evidence/uploads/baseline/ — 48 прогонов; evidence/reconcile/baseline/ — 45 проходов, model_ok=True, предупреждений нет. Итоги U1–U4, H1–H5 — в REPORT.md; H4 опровергнута. Пики uploads — выборки 0,2 с (peak_sampled, Docker Linux 6.10.14), всплески между ними не проверены. Гипотезы не менялись. Ветка solution/bvt2301-vladimirceva.
Стек: 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. Нельзя
- Менять 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до строки=====. Публичный тест упал — чиним приложение. - Подгонять тесты под код: ослаблять
assert, менять ожидаемый статус, ставитьskip/xfail, удалять тест, чтобы прогон позеленел. - Состояние в памяти процесса, от которого зависит корректность:
сессии, данные, ключи идемпотентности и метаданные — только
PostgreSQL, байты вложений — только S3 (не диск реплики и не БД);
Valkey — только кэш неизменяемой карточки чата.
--workers, gunicorn,reloadв образе: масштабирование — числом реплик. Sticky session в HAProxy. Уборка и сверка — только процессcleaner, не реплики. - Порты реплик наружу и
container_nameуapi; консоль, master, volume, filer SeaweedFS и мониторинг LB — наружу. - Файлы конфигурации приложения (
config.toml, pydantic-settings с файлами): настройки — только переменные окружения (src/config.py). - JSON-логи, structlog,
printвместо логгера (src/log.py). - Писать в лог текст сообщений,
display_name,title, username,filename(только длину), пароль, токен, ключи S3, их хэши,Authorization,Idempotency-Key, тела, параметры SQL. Можно id, ключ объекта S3, длины и размеры. - Git без просьбы:
commit,push,checkout,reset,stash,rebase,clean. Смотреть можно:status,diff,log. - Удалять данные стенда без просьбы (спросить):
make wipe,docker compose down -v,docker volume rm,FLUSHALLрабочего Valkey,TRUNCATE/DROPв рабочей базе, удаление объектов рабочего bucket мимо API; каталоги меток вevidence/. - Секреты и
.envв git, образ,evidence/, вывод и отчёт;COPY . .в Dockerfile. Пароли, токены и ключи S3 в командной строке не печатать. Административную пару S3 — никому, кроме сервераs3. - Незакреплённые версии:
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/— только реальный вывод команд, которые ты запустил. Гипотезы U1–U4 и H1–H5 после замеров не переписывать. - Чинить попутно найденное без просьбы: записать в
KNOWN_ISSUES.md(путь, симптом, предложение) и сказать в отчёте. - Менять код приложения ради замеров (спросить): профили
bench/проверяют записанные гипотезы на коде, который уже проверен.
3. Порядок работы
- Найди, откуда требование:
README.md(рубрика),contracts/README.md(семантика, раздел «Вложения (с lab4)»),contracts/openapi.json(схемы, коды),COURSE.md(переходы API). Неясно или противоречит контракту — остановись и спроси. Ответ преподавателя — в раздел 12. - Прочитай нужные
AGENTS.md(раздел 1) и затрагиваемые файлы целиком. - Задача больше пары файлов — сначала короткий план в чате.
- Минимальный дифф: не переименовывать и не «улучшать» лишнее.
- Проверки из раздела 8 — до того, как сказать «готово».
- Отчёт пользователю — раздел 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. Если тест или проверка упали
- Воспроизведи и прочитай вывод целиком.
- Назови причину: дефект приложения → чинить код; ошибка в самом
тесте (противоречит контракту или зависит от случайного) → править
тест можно, но назови, чему он противоречил; стенд (порт занят
чужим сервисом — smoke получает 404 на
/health/live, старый образ, не тотBASE_URL, остатки прерванного прогона, реплика ещё неUPв LB, S3 ещё не healthy) → чинить стенд. - Причина неясна или правка теста спорная — остановись и спроси.
Тест 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. Чужие процессы и контейнеры не трогать — взять другой порт (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.