Files
mtusi2026lab2/AGENTS.md
T

87 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Что это за репозиторий
Skeleton лабораторной 5 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`. Skeleton даёт задание (`README.md`), нормативный контракт (`contracts/`) и публичные black-box проверки (`tests/`). Реализация API, worker, relay, Dockerfile, compose-стенд, конфигурация балансировщика, S3 и брокера, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 5 построено переносом решения лабы 4.
Лаба 5: приём вложения отделён от тяжёлой обработки. `POST /api/v1/chats/{chat_id}/attachments` проверяет файл как в лабе 4, кладёт оригинал в приватный префикс `staging/` bucket **RustFS** и одной транзакцией PostgreSQL фиксирует вложение `queued`, задание (`jobs`) и строку **transactional outbox**; только после этого отвечает `202` со снимком `queued`. Отдельный сервис `relay` публикует outbox в **RabbitMQ 4.1** (quorum queue, DLX, publisher confirms, `mandatory`, persistent), отдельный сервис `worker` (тот же образ, свой entrypoint) потребляет очередь через **FastStream** поверх aio-pika с ручным `ack` строго после `COMMIT` результата, захватывает задание арендой (`lease_token`), публикует оригинал в `originals/` и строит варианты Pillow. Источник истины состояний — PostgreSQL, брокер — транспорт и будильник. Остаётся всё из лаб 1–4: HAProxy перед ≥2 репликами, `X-Instance-Id`, `Idempotency-Key`, Basic → Bearer, хуки остановки реплики и рестарта стенда.
Текущий доступ к PostgreSQL — **SQLAlchemy 2.0.45 async**, `postgresql+asyncpg`, `async_sessionmaker`, ORM/Core и `DeclarativeBase`; миграции — **Alembic 1.16.5**, каталог `alembic/versions/`, async `alembic/env.py`. Compose-service `migrate` выполняет `alembic upgrade head` под advisory lock с проверкой legacy-схемы. Сырой asyncpg и прежние SQL-миграции не являются текущей архитектурой.
## Команды
```sh
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, версия 1.5.0
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1 и jobs.schema.json (venv с requirements-dev.txt)
make install # uv sync --group dev
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test # собственные тесты (одноразовые PostgreSQL, Valkey, RustFS и RabbitMQ в Docker)
make secrets # локальные secrets/* (PostgreSQL, Valkey, S3 root/API/worker, RabbitMQ) и .env
make up # docker compose build, затем up -d --wait (relay и worker пересоздаются на новом образе): хранилища и broker → migrate, s3-init → api ×2, relay, worker → lb
make test # публичный smoke через LB (BASE_URL=http://127.0.0.1:18085)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт lb, api, relay, worker и postgres, valkey, s3, broker с volumes
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики TARGET_INSTANCE_ID под запросами
make restore # вернуть остановленные реплики и дождаться их в ротации LB
make worker-stop / worker-start # демонстрация «worker недоступен»
make queues # очереди брокера: ready, unacked, consumers
make level3 # сценарии уровня «3» suite (scripts/pipeline_suite.py) → evidence/level3.json
make level4 # сценарии уровней «3» и «4» suite и инварианты → evidence/level4.json
make track2 TRACK2_OUTPUT=evidence/local-track2.json # 13 сценариев и 8 инвариантов трека 2
make reprocess ID=… PIPELINE_VERSION=2 # новая версия обработки доступного исходника
make failed / make replay ID=… / make dlq # реестр failed, явный replay, просмотр DLQ (python -m messenger.admin, rabbitmqadmin)
make down # остановка своего project без удаления постоянных volumes
```
`tests/*.py` и `scripts/*.py` — только stdlib, синтаксис Python 3.9 (`make check` разбирает их системным `python3`). Проверки сами не поднимают стенд. Хуки `scripts/stop-one.sh` и `scripts/restart.sh` запускаются тестом без shell, поэтому исполняемые и с shebang. Данные не удаляются автоматически: каждый прогон smoke создаёт новых синтетических пользователей и вложения.
## Архитектура skeleton
- `lab.json` — единственный источник номера лабы (5). От него зависят `scripts/check_contract.py` (`info.version == 1.5.0`) и `tests/client.py` (ветки `LAB>=5`: upload отвечает `202 queued`, сообщение с вложением сразу, ожидание `ready` до 60 с от второго участника, ровно один вариант `thumbnail` 256×160 настоящим JPEG).
- `tests/` байт в байт как в лабе 4; поведение переключает только `lab.json`. `tests/resilience.py` после хука рестарта запрашивает метаданные и оригинал один раз с таймаутом 2 с.
- `contracts/jobs.schema.json` — формат сообщения брокера (7 обязательных полей, без bytes, URL, ключей S3 и filename); `contracts/attachment-states.md` — машина состояний и окна отказа.
- `contracts/infrastructure.json` — роли `api`, `postgres`, `load_balancer`, `s3`, `broker` (persistent volume, at-least-once), `worker` (отдельный процесс). `compose.example.yaml` — только worksheet ролей.
## Ключевые правила контракта (lab5)
- Upload: те же лимиты и коды, что в лабе 4 (`413`, `415`, `400`, `404`), но успех — `202 Attachment` со снимком `status=queued`, `variants=[]`, `error_code=null`; снимок берётся из записанного объекта, а не перечитывается после публикации. `202` — только после записи оригинала в `staging/` и `COMMIT` вложения, задания и outbox.
- Состояния: `queued → processing → ready | failed`; `processing → queued` при временной ошибке или истёкшей аренде; `failed → queued` только явным replay. `ready` не откатывается. `ready` выставляется, только когда записаны оригинал и все обещанные уровнем варианты.
- `/content` для `queued`, `processing`, `failed` — `409 conflict` для любого `variant`, включая `original`; неизвестный `variant` — `400`; отсутствующий вариант `ready`-вложения — `404`; посторонний — `404`. Варианты: `thumbnail` JPEG вписан в 256×256 без увеличения, EXIF orientation применяется, alpha на белом, размеры вниз, минимум 1 px.
- Сообщение: вложение `queued`/`processing` прикрепляется (`201`), `failed` — `409`, вложение другого чата или неизвестное — `404`.
- Сообщение брокера — ровно поля `jobs.schema.json`; `job_id` не меняется при redelivery, `attempt` растёт только при управляемом повторе через outbox. Ключ эффекта — `(attachment_id, pipeline_version, variant)`.
- Сохраняются правила lab4 (сырые байты, тип по содержимому, скачивание только через API без redirect), lab3 (`X-Instance-Id`, `Idempotency-Key`, LB не повторяет upload), lab2 (`Basic` только на входе, `Bearer` дальше, `WWW-Authenticate` по пути) и lab1 (формат ошибки, посторонний → `404`, keyset `(created_at, id)`, время RFC 3339 с `Z`).
## Правила работы с репозиторием
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
- Код — `src/messenger/`, миграции — `alembic/versions/`, конфигурация LB, нагрузки, S3 и брокера — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/`.
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
- Порты реплик API, S3, AMQP наружу не публикуются: только LB и UI брокера на `127.0.0.1`. API к брокеру не подключается. Клиенты брокера не объявляют очереди: топология — в `infra/rabbitmq/definitions.json`, права configure есть только у оператора.
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (`docker ps -a`).
- Ветка `solution/bpi2303-kostylev`, коммиты на английском, перед каждым — `make lint`. Никогда не коммитить `.env`, `secrets/`, токены, ключи S3, пароли брокера, volumes, дампы.
- Проверять документацию используемых библиотек через Context7. Изменения реализации проходят OpenSpec propose/apply/archive. `openspec/config.yaml` уже описывает SQLAlchemy/Alembic и ЛР5; оставшееся в design правило `201` относится к прежней загрузке ЛР4, нормативный успех ЛР5 — `202`.
- Автор работы — Костылев Артём, БПИ2303. Не приписывать авторство Claude. Публикация только в private MTUCI-Labs и только назначенным агентом фазы PUBLICATION; вне неё не делать push и не отправлять Telegram.
## Порядок этапов и Docker
- Только runner управляет агентами: один переносит основу и последовательно реализует 3 → 4 → 5 с evidence, затем отдельные review → fix только major → re-review, отчёт, один агент нагрузки и публикации. Review/отчёт предыдущей лабы могут идти параллельно реализации следующей. Самостоятельно фоновых агентов не запускать, runner/state не менять.
- Major — доказанная угроза безопасности, потеря/повреждение данных, недоступность сервиса или провал обязательного сценария. Остальное — minor: сохранять в findings и ограничениях REPORT, не исправлять без назначения и не блокировать этапы. Обязательный FAIL нельзя объявлять PASS.
- Менять только назначенную лабу; другую читать лишь через предоставленный snapshot. Перед итоговым review переносить применимые поздние исправления. Сохранять WIP; `reset/clean` и удаление пользовательских данных запрещены.
- Разрешены основной project `mtusi2026lab5` в основном репозитории или `hlpipe-lab5-*` с working_dir под ним либо `/Users/artemkostylev/projects/learning/HL/labs/.pipeline/.runs/labs`. API — 18085, остальные порты — 25000–25999; текущие значения stats/UI — 25085/25086. Учитывать Compose env, не печатать секреты.
- Обычные Docker-этапы работают совместно на отдельных project/портах/volumes; финальная нагрузка получает эксклюзивный доступ через runner. Останавливать только свой стенд, в конце — без `-v`. Фон и условия замеров фиксировать; пригодные серии сохранять, повторять только отсутствующие, затронутые или непригодные.
- Отчётная фаза меняет только `REPORT.md`, `AGENTS.md`, `evidence/**/*.md`; не меняет код, конфиги, OpenSpec и сырые измерения. Docker, динамические/нагрузочные прогоны и полный `make student-test` в этой фазе запрещены; лёгкие check/validate/lint и OpenSpec validation допустимы.
## Состояние доказательств после ревью
Индекс — [evidence/README.md](evidence/README.md), отчёт — [REPORT.md](REPORT.md). Последняя полная динамическая квалификация — `0e921116610d289716af0a40ec823376eb8bbcbc`; успешное повторное review — `42575281b352d35bda17ee7601bae5548a996e91`. Между ними runtime изменён только в renderer PNG и policy RabbitMQ. Старые PASS не обозначать прогоном текущего кода.
Текущая policy `delivery-limit=-1` сохраняет инфраструктурные redelivery; прикладные попытки после claim ограничены `JOB_MAX_ATTEMPTS=5`. На финальном этапе остаются реальный отказ PostgreSQL с >10 nack и восстановлением без replay, применение policy на существующем volume, HTTP/Linux-проверки tRNS и адресные проверки затронутых сценариев. Процедуры — [исправления доставки](evidence/review-fixes-2026-11-06/RESULTS.md) и [исправления PNG](evidence/review-trns-depth-2026-11-06/RESULTS.md).
Пять minor сохраняются: crash_publish_confirm фактически после confirm до COMMIT outbox; limits.py имеет ложный FAIL порядка secrets; reconcile_track.py ожидает upload 201 ЛР4; failed upgrade v2 нельзя отдельно повторить при ready v1; UTC/elapsed run2/3 расходятся и исключены из performance-выводов. Корневые старые evidence до SQLAlchemy — история; происхождение и неприменимость обозначены в индексе.
## Уровни оценки
Цель — **«5»**, трек 2 «Доказанная идемпотентность pipeline». Полное подтверждение для текущего кода заявлять только после оставшихся адресных динамических проверок; таблица доказательств и границы применимости — в `REPORT.md`.
- **3** — `202 queued` после staging и `COMMIT` задания с outbox; отдельные `broker`, `relay`, `worker` в стенде; durable quorum queue, publisher confirm, ручной `ack` после `COMMIT`; состояния `queued/processing/ready/failed`, оригинал в `originals/` и thumbnail; ограниченный retry (`JOB_MAX_ATTEMPTS=5`) и `failed` с `error_code`; повтор job без второго набора вариантов; worker остановлен → upload → сообщение → рестарт API и broker → worker → `ready`; минимум lab4 сохранён.
- **4** — crop и optimized WebP, лимиты worker по байтам, пикселям, времени и памяти, crash между `COMMIT` и publish, backoff с jitter и классификация ошибок, DLQ и replay, crash после записи объекта до `ack`, lease и fencing для зависшего `processing`, prefetch, очистка staging.
- **5** — трек 2: `pipeline_version` 1 и 2, монотонная публикация, автоматический fault-injection (дубль, reorder, crash до и после side effect, устаревшая job) и проверка инвариантов одной командой.