Files
mtusi2026lab2/AGENTS.md
T
ArtyomandClaude Opus 5.5 573220e12a Record level 4 evidence and fill in the report
evidence/level4.json: all 17 scenarios of levels 3 and 4 and the eight
invariants pass on 0b85edf; evidence/operator.txt shows the failed
registry, a replay to ready, a noop replay, an expired replay and the
DLQ. Smoke, topology, level3, persistence, failover, lab 4 scenarios,
limits, student tests and contract checks are refreshed on the same
commit. REPORT.md describes the variants, worker limits, jitter, lease
renewal, crash points, replay and retention, adds rows 4.1-4.4, the
level 4 failure experiments and the updated limitations.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 03:39:20 +03:00

12 KiB
Raw Blame History

Что это за репозиторий

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 build, затем up -d --wait (relay и worker пересоздаются на новом образе): хранилища и 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 level4                     # сценарии уровней «3» и «4» suite и инварианты → evidence/level4.json
make failed / make replay ID=… / make dlq   # реестр failed, явный replay, просмотр DLQ (python -m messenger.admin, rabbitmqadmin)
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 с от второго участника, ровно один вариант 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/, миграции — 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_version 1 и 2, монотонная публикация, автоматический fault-injection (дубль, reorder, crash до и после side effect, устаревшая job) и проверка инвариантов одной командой.