Files
mtusi2026lab4/AGENTS.md
T

28 KiB
Raw Blame History

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 <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.