Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 to lab 4 specs and the
archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5
continues the same spec history instead of starting from scratch. The
files come from the lab 4 solution commit d2744bc.
Rewrite AGENTS.md and the openspec context and rules for lab 5: upload
answers 202 queued after the original is in a private staging prefix
and the attachment, the job and the outbox row are committed in one
transaction, a separate relay publishes the outbox to RabbitMQ with
publisher confirms, a separate worker built from the same image
consumes the queue through FastStream with a manual ack after the
result commit, PostgreSQL stays the source of truth for job states,
Out of scope moves to labs 6-7, track 1 and broker HA, and the rules
add the failure windows between PostgreSQL and the broker, the effect
key and the lease to specs and designs.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
12 KiB
Что это за репозиторий
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, хуки остановки реплики и рестарта стенда.
Команды
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 up -d --build --wait: хранилища и broker → migrate, s3-init → api ×2, relay, worker → lb
make test # публичный smoke через LB (BASE_URL, по умолчанию http://localhost:8080)
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 down # остановка без удаления данных; make reset-data — намеренное удаление 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 с от второго участника, ровно один вариантthumbnail256×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. Варианты:thumbnailJPEG вписан в 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/, миграции —src/messenger/migrations/NNNN_*.sql, конфигурация 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, дампы.
Уровни оценки
Решение заявлено на «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_version1 и 2, монотонная публикация, автоматический fault-injection (дубль, reorder, crash до и после side effect, устаревшая job) и проверка инвариантов одной командой.