89 lines
19 KiB
Markdown
89 lines
19 KiB
Markdown
## Что это за репозиторий
|
||
|
||
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 не обозначать прогоном текущего кода.
|
||
|
||
Финальная validation на `b30e2f6a84419d1ca64525ffb40df92183cccaef` (runtime = reviewed R) завершила real PostgreSQL outage: 12 requeue → ready без replay, policy `delivery-limit=-1` на сохранённом volume, DLQ не выросла. HTTP PNG: 8 fixtures / 48 сравнений вариантов v1/v2 PASS. Delivery subset: 12 сценариев / 8 инвариантов PASS. Student-test: 980 passed / 1 Linux-only skip. Аудит повторного использования — [evidence/load-validation.md](evidence/load-validation.md), результаты — [evidence/final-validation-2026-11-07/RESULTS.md](evidence/final-validation-2026-11-07/RESULTS.md).
|
||
|
||
**Новый major, validation blocked:** четыре PNG tRNS 8000×5000 (grayscale 2/4/16 и RGB16) получают 202 → failed/processing_failed при штатных 448 MiB/30 с вместо объявленного ready. Linux-пробник с импортами worker подтверждает MemoryError. Требуются отдельный fix/re-review и повтор только затронутых PNG/ресурсных сценариев. Реализация финальной фазой не менялась, исходные FAIL сохранены; полный track2 и пригодные серии автоматически не повторять. Свой стенд остановлен, четыре volume сохранены; push не выполнялся.
|
||
|
||
Пять 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». Полное подтверждение для текущего кода заявлять только после устранения major граничного PNG, review и адресной проверки; таблица доказательств и границы применимости — в `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) и проверка инвариантов одной командой.
|