forked from mtusi2026/mtusi2026lab2
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>
64 lines
12 KiB
Markdown
64 lines
12 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, хуки остановки реплики и рестарта стенда.
|
||
|
||
## Команды
|
||
|
||
```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://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) и проверка инвариантов одной командой.
|