Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> collect_evidence на новом clone (новые secrets, пустые volumes): make check/validate/test, test-persistence, test-failover (обе реплики), сценарий защиты, свои тесты 377 passed, матрица трека 2 12/12 без нарушений, аудит ok (522 объекта, SHA-256). Исправлен порядок шагов сценария «reorder версий» (не запускать сервис с обычной конфигурацией между шагами).
27 KiB
Отчёт — лабораторная 5
- Автор, группа: Боданюк Алексей, БВТ2302
- Целевая оценка; трек 5: 5, трек 2 «Доказанная идемпотентность pipeline»
- Commit/PR: ветка
solution/bvt2302-bodanyuk; PR «ЛР 5 — БВТ2302 — Боданюк — на 5» (ссылка после публикации) - Источники, библиотеки, ИИ: Python 3.13, Starlette, uvicorn, psycopg 3, redis-py, argon2-cffi, aiobotocore (из ЛР 2–4); новое: aio-pika 9.6.2 (AMQP), Pillow 12.3.0 (варианты, только в worker). Документация: RabbitMQ reliability, confirms, quorum queues, AWS «Exponential Backoff And Jitter». Код, тесты и документы написаны с помощью ИИ-ассистента (Claude); архитектурные решения разобраны и объяснимы автором (см. docs/DEFENSE.md).
Запуск из чистого clone
Версии (всё по тегу и digest, см. compose.yaml): Python 3.13.16-slim-bookworm, PostgreSQL 18.6, Valkey 8.1.3, SeaweedFS 4.46, RabbitMQ 4.3.7-alpine, HAProxy 3.2.26. Python-пакеты — requirements.txt с sha256-хешами (pip install --require-hashes --no-deps).
Prerequisites: Docker с Compose v2, Python 3.12+, Git; на Windows — docs/WINDOWS.md.
git clone <fork> mtusi2026lab5 && cd mtusi2026lab5 && git checkout solution/bvt2302-bodanyuk
python3 scripts/init_secrets.py # ./secrets: пароли БД/Valkey, 4 пары S3, пользователи RabbitMQ (хеши), URL брокера
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait # migrate и s3-init — один раз, exit 0; остальные healthy
make check test # Windows: $env:PYTHONUTF8="1"; make ... PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
python3 -m venv .venv && .venv/bin/pip install --require-hashes --no-deps -r requirements.txt && .venv/bin/pip install -r requirements-test.txt
.venv/bin/python scripts/demo_pipeline.py # сценарий защиты, шаги 2-3
.venv/bin/python -m pytest student-tests -v
.venv/bin/python bench/pipeline_faults.py --output evidence/track2
make audit # инварианты, read-only
Всё это одной командой на чистом clone: python scripts/collect_evidence.py (вывод — в evidence/). Действий оператора нет. Безопасная остановка: docker compose down (volumes остаются). Намеренное удаление учебных данных: docker compose down -v и удалить ./secrets.
Архитектура и решения
client ─▶ lb (HAProxy) ─▶ api ×2 ──▶ postgres (метаданные, jobs, outbox, попытки, аудит) [data]
├──▶ valkey (сессии) [data]
└──▶ s3: messenger-staging (Write) / messenger-attachments (Read) [storage]
relay ──▶ postgres (outbox, reaper) ──▶ broker (RabbitMQ, quorum queue + DLQ) [data, queue]
worker ◀── broker; ──▶ postgres; ──▶ s3 (Read/Write оба bucket) [data, storage, queue]
- Источник истины — PostgreSQL, включая работу: состояние, попытки, lease, время повтора, реестр failed. Брокер доставляет только
job_id; ack — после COMMIT результата. Подробно — docs/PIPELINE.md; схема — docs/DATA_MODEL.md. - Транзакционные границы. Upload:
pending→ PUT staging → одна транзакцияqueued + jobs + outbox→ 202. Результат: одна транзакцияattachment_variants ×3 + attachments readyс проверкойlease_token→ ack. - API не связан с брокером (нет сети
queue, нет учётных данных). Недоступность worker/брокера не делает resize синхронным и не ломает upload. - Перенесено из lab4 без изменений (коммит
5112be8): API, сессии, идемпотентность сообщений, HAProxy с активной readiness, лимиты загрузки, PNG-валидатор иdjpeg -strict, janitorpending, graceful shutdown, тесты. - Изменено: upload 201 → 202; GET метаданных видит
queued/processing/failed;content→ 409 до ready, вариантыthumbnail/crop/optimized; к сообщению можно прикрепитьqueued/processing(post_message_v3),failed→ 409; S3 разделён на два bucket и четыре identity; restart-хук перезапускает и broker/relay/worker. - Убрано: reconciler lab4 (трек прошлой лабы, не обязательный минимум). В lab5 мусор находится по журналу
job_attempts.planned_keysбез права List; аудитmessenger.auditпроверяет оба bucket read-only-ключом. Удаление файлов reconciler попало в коммитa633949, а не вbc32a50, где об этом сказано, — ошибка при разбиении коммитов, историю не переписывал. - Ограничения доступа. S3: api — Write staging + Read final; worker — Read/Write оба; auditor — Read+List; admin — только
s3-init. RabbitMQ:relay— только write в exchangemessenger.jobs,worker— только read очереди, configure ни у кого;guestнет; management UI и Prometheus выключены. Проверяетсяs3-initпри каждом старте и тестомtest_compose_policy_limits_ports_secrets_images.
Соответствие .env.example
| Переменная | Значение | Где |
|---|---|---|
BROKER_URL_FILE |
/run/secrets/broker_url |
relay и worker, у каждого свой пользователь RabbitMQ |
S3_STAGING_BUCKET |
messenger-staging |
api, worker, s3-init, auditor |
WORKER_CONCURRENCY |
2 | prefetch и число дочерних процессов worker |
JOB_MAX_ATTEMPTS |
5 | claim-ов на задание (пишется в задание при создании) |
JOB_TIMEOUT_SECONDS |
60 | потолок одной попытки (kill процесса, конец продления lease) |
JOB_LEASE_SECONDS |
30 | lease, heartbeat каждые 10 с |
JOB_RETRY_BASE_SECONDS / _MAX_ |
2 / 60 | full jitter |
STAGING_RETENTION_SECONDS |
86400 | хранение staging у failed для replay (у ready удаляется сразу) |
ORPHAN_GRACE_SECONDS |
600 | удаление объектов неуспешных попыток |
IMAGE_MAX_MEMORY_MB |
768 | RLIMIT_AS дочернего процесса |
PIPELINE_VERSION |
1 | версия заданий новых загрузок (1, 2, 3 в pipeline.py) |
API_/RELAY_/WORKER_FAULT_POINTS |
пусто | внедрение отказов только для экспериментов |
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS |
10485760, 40000000 | API (до чтения тела) и worker (до скачивания/декодирования) |
Доказательства критериев
Все файлы — из прогона scripts/collect_evidence.py на чистом clone (новые secrets, пустые volumes), см. раздел «Финальный прогон».
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|---|---|---|---|
| Публичный smoke | make check validate test |
PASS ×3: 202 → ready, JPEG 256×160 | make-check-validate-test.txt |
| 3: минимум lab4 сохранён, 201 → 202 | pytest student-tests (test_api, test_attachments, test_idempotency, test_balancing, test_sessions, test_failures) |
377 passed; 415 на все кейсы рецензий (PNG фильтр 5/0xff, IDAT не zlib, JPEG 27 байт, SOS не из SOF) | student-tests.txt |
| 3: 202 только после устойчивого приёма; остановка API не теряет | test_consistency (after_s3_put, after_enqueue_commit), demo |
окно «после staging» — невидимый pending, убран janitor; после COMMIT — ready |
student-tests.txt |
| 3: отдельные broker и worker, durable, ack после эффекта | compose, rabbitmqctl list_queues; test_worker_crash_after_commit… |
quorum queue durable; redelivery → noop_finished |
clean-clone.txt, student-tests.txt |
| 3: worker недоступен → API не делает resize | test_worker_stopped…, demo |
202 queued, content 409, сообщения 201 | demo-pipeline.txt |
| 3: состояния queued/processing/ready/failed, thumbnail по контракту | test_pipeline_flow (check_variants) |
реальные размеры через Pillow, sha256 = метаданные, оригинал побайтно | student-tests.txt |
| 3: ограниченный retry, failed + error_code; повтор не плодит варианты | test_retry_exhausted…, test_duplicate… |
5 попыток → retry_exhausted; дубли → 1 набор |
student-tests.txt |
| 3: демонстрация stop worker → 202 → сообщение → restart API (+broker) → ready | scripts/demo_pipeline.py |
очередь messages=1 до и после рестарта брокера, ready, одна попытка |
demo-pipeline.txt |
| Persistence / failover (публичные) | make test-persistence, make test-failover |
PASS, состояния контейнеров до/после | test-persistence.txt, test-failover.txt |
| 4: crop 128 и WebP 1280, параметры | unit test_pipeline + check_variants | геометрия, EXIF, alpha, без метаданных — PIPELINE.md | student-tests.txt |
| 4: лимиты bytes/пикселей/времени/памяти worker | test_memory_and_time_limits_of_the_worker, test_exactly_40_megapixels… |
40 Мпикс при 200 МБ → image_too_large; 3 с → processing_timeout; 40 Мпикс в 768 МБ → ready |
student-tests.txt |
| 4: outbox; crash между COMMIT и publish | test_broker_down…, test_relay_down…, test_crash_after_publish… |
строка outbox ждёт, публикуется без ручных действий | student-tests.txt |
| 4: backoff с jitter, постоянные/временные | test_transient_errors…, test_permanent_error… |
задержки в [0, base·2^(n−1)], invalid_image — 1 попытка |
student-tests.txt |
| 4: DLQ/реестр failed, безопасный replay | jobctl list-failed/replay, test_bad_message… |
replay → ready; replay готового → already_ready; плохое сообщение → DLQ |
student-tests.txt |
| 4: crash после записи объекта до ack | test_worker_crash_after_s3_write…, …after_commit… |
один опубликованный набор, мусор попытки 1 удалён | student-tests.txt |
| 4: lease зависшего processing, prefetch, очистка staging | test_hung_worker… (docker pause), test_concurrency…, test_queued_staging…, test_cleanup_racing… |
попытки [abandoned, succeeded]; ≤2 processing; staging queued не удаляется, CHECK отвергает |
student-tests.txt |
| 5, трек 2 | bench/pipeline_faults.py, make audit |
12/12 сценариев, 0 нарушений, аудит ok | evidence/track2/, track2-runs.txt |
Эксперименты и отказы
Трек 2: доказанная идемпотентность versioned pipeline
Гипотеза. При at-least-once доставке, дублях и переупорядочивании сообщений, crash worker до/после побочного эффекта и устаревших заданиях старой версии pipeline: (H1) ни одна принятая 202 работа не теряется; (H2) каждый эффект (attachment, version, variant) опубликован ровно один раз; (H3) опубликованная версия только растёт, ready не откатывается; (H4) мусор прерванных попыток удаляется, опубликованное не удаляется никогда.
Механизм. Ключ эффекта — PK attachment_variants; ключи объектов включают токен попытки; fencing lease_token при каждом COMMIT; монотонный published_version; claim по состоянию задания в БД; уборка только по planned_keys неуспешных попыток под блокировкой.
Методика (bench/pipeline_faults.py). Для каждого сценария пересоздаётся один сервис с FAULT_POINTS (реальные пути кода, реальный os._exit, реальный docker pause), N загрузок через LB, затем читаются факты из PostgreSQL и S3 (List auditor-ключом), а в конце аудит I1–I7 с проверкой SHA-256 всех опубликованных объектов по всему стенду.
| Сценарий | Внедрение |
|---|---|
| baseline | — |
| дубль | relay публикует каждое сообщение дважды |
| дубль + reorder | дважды и в обратном порядке пачки |
| crash relay после confirm до отметки | os._exit relay |
| crash worker до побочного эффекта | os._exit после claim |
| crash worker после S3 до COMMIT | os._exit после PUT объектов |
| crash worker после COMMIT до ack | os._exit после COMMIT |
| временные ошибки | 2 неудачные попытки |
| 2 worker + дубль | конкурирующие потребители |
| устаревшая версия | reprocess v2 (медленный) и v3 одновременно; затем вручную опубликованный дубль задания v1 |
| reorder версий в очереди | v2 и v3 в outbox, relay публикует в обратном порядке, 1 worker |
| зависший worker | 2 worker, docker pause владельца lease |
Результаты (чистый clone, 2026-10-31 14:48–14:57 UTC, 5 загрузок на «плоский» сценарий; summary.txt, подробно — summary.json):
| Сценарий | Загрузок | ready | claim-ов | Нарушений | Последовательность событий задания |
|---|---|---|---|---|---|
| baseline | 5 | 5 | 5 | 0 | created › claimed › succeeded |
| дубль publish | 5 | 5 | 5 | 0 | то же: второе сообщение — noop_finished |
| дубль + обратный порядок | 5 | 5 | 5 | 0 | то же |
| crash relay после confirm | 5 | 5 | 5 | 0 | created › claimed › fault_injected › succeeded |
| crash worker после claim | 5 | 5 | 14 | 0 | claimed › fault_injected › lease_expired › claimed › succeeded (*) |
| crash worker после S3, до COMMIT | 5 | 5 | 10 | 0 | claimed › fault_injected › lease_expired › claimed › succeeded |
| crash worker после COMMIT, до ack | 5 | 5 | 5 | 0 | claimed › succeeded › fault_injected (redelivery = no-op) |
| 2 временные ошибки | 5 | 5 | 15 | 0 | 3 claim-а на загрузку, ровно как задано |
| 2 worker + дубль | 5 | 5 | 5 | 0 | один claim при конкурирующих потребителях |
| устаревшая версия | 1 | — | — | 0 | v1 succeeded, v2 (медленная) superseded при COMMIT, v3 succeeded; статус всё время ready; ручной дубль задания v1 — no-op |
| reorder версий в очереди | 1 | — | 2 | 0 | v3 опубликована первой, v2 superseded при claim без работы |
зависший worker (docker pause) |
1 | — | 2 | 0 | claimed › lease_expired › claimed › succeeded; ожившая попытка fenced |
| аудит всего стенда после матрицы | 0 | ok=True, 522 опубликованных объекта, SHA-256 сверены, final=523 (+sentinel) |
(*) claim-ов больше, чем 2 на загрузку: os._exit при одном задании убивает весь процесс, а с ним и соседнюю попытку другого задания (prefetch 2). Ей тоже приходится ждать истечения lease. Это и есть «crash до побочного эффекта»: лишние claim-ы ничего не публикуют, и ни в одном сценарии нет второго набора вариантов или объектов (столбец «Нарушений» — проверки H2/H4 по БД и S3).
Вывод. H1–H4 подтверждены на всех 12 сценариях: 0 нарушений по сценарным проверкам и по аудиту I1–I7. Время до ready при отказах определяется lease (6 с в эксперименте) + интервалом reaper (5 с): 15–22 с против ~2 с без отказов.
Ограничения эксперимента. Один прогон матрицы на 5 загрузок (плюс прогоны тех же сценариев в student-tests и отладочный прогон на 3 загрузки — тоже 0 нарушений). Это доказательство на конечном наборе чередований, а не формальная верификация. Отказы внедряются в заранее выбранных точках кода, а не в случайные моменты. Один Docker-хост.
Почему это не exactly-once. Доставка остаётся at-least-once: в сценариях дубля в очереди физически два сообщения, а у зависшего worker вычисление выполнялось дважды (попытки abandoned и succeeded). Exactly-once — только у видимого эффекта, за счёт ключа эффекта, fencing и монотонной версии. Чего нет: (1) защиты от двух независимых сред с разными БД; (2) гарантии при потере диска одного Docker-хоста (quorum queue и PostgreSQL на одном узле); (3) удаления опубликованных вариантов старых версий — они остаются (rollback-кандидаты), удаляются только неопубликованные.
Отказы
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря |
|---|---|---|---|
| worker остановлен, upload | 202, content 409, сообщения работают | так и есть | после старта worker → ready, 0 потерь |
| restart API + broker с volumes | сообщение остаётся в quorum queue | messages=1 до и после |
0 потерь |
| broker остановлен | upload 202, outbox ждёт | published=False, текст работает |
relay публикует после возврата брокера |
| relay остановлен | outbox ждёт | так и есть | ready после старта |
| crash relay после confirm | дубль в очереди | один claim, один набор | 0 дублей эффекта |
| crash worker после claim / S3 / COMMIT | lease → reaper → попытка 2; либо no-op | [abandoned, succeeded]; мусор удалён |
lease 6 с в тесте (30 с по умолчанию) + ≤5 с reaper |
| docker pause worker с lease | второй worker публикует, первый fenced | так и есть | ≤ lease + 5 с + AMQP heartbeat |
| 5× временная ошибка | failed/retry_exhausted → replay → ready |
так и есть | replay оператора |
| уборка vs replay (пауза в уборке) | staging не удалён | ready, staging удалён только после ready | — |
| S3 остановлен/заморожен (lab4) | readiness 503, upload 503 < 8 с, текст работает | так и есть | файлы целы |
Дефекты, найденные в ходе работы и исправленные:
- После рестарта брокера worker оставался без consumer, а healthcheck показывал healthy; relay падал на
ChannelInvalidStateError. Причина: aio-pika не выставляетis_closedпри закрытии соединения сервером. Исправлено (1d37fd0):close_callbacks, heartbeat-файл только при живом consumer. - Внедрённый crash worker срабатывал на каждой попытке, а не один раз на задание. Исправлено там же.
- Аудит ошибочно требовал объект staging у
pending(PUT мог не пройти). Исправлен инвариант I5.
Окружение и лимиты
Ноутбук: AMD Ryzen 5 3400G (4 ядра / 8 потоков), 29,9 ГБ RAM, Windows 10 Enterprise 19045, Docker Desktop 29.8.0 (VM: 8 CPU, 15,7 ГБ). Лимиты контейнеров (фактические, docker inspect в clean-clone.txt): api 1 CPU / 512m ×2, worker 2 CPU / 1536m (без swap), broker 1 CPU / 512m, relay 0,5 / 256m, postgres 2 / 1g, s3 1 / 1g, valkey 0,5 / 256m, lb 1 / 128m, migrate/s3-init 0,5 / 256m, auditor 1 / 256m, jobctl 0,5 / 128m. Нагрузочных выводов о производительности в этой лабе не делается (трек 2 — про корректность); tests/load.py приложен как контроль регрессии lab3.
Финальный прогон
python scripts/collect_evidence.py в новой папке (git clone ветки, commit cf6e929): новые secrets, пустые volumes (стенд разработки удалён down -v), образы приложения собраны заново (слои базовых образов из кэша Docker). Все шаги exit 0:
| Файл | Что внутри |
|---|---|
| clean-clone.txt | init_secrets, compose config, up --build --wait, migrate (0001–0005), s3-init (вердикты прав), пользователи и права RabbitMQ, очереди, лимиты docker inspect, версии |
| make-check-validate-test.txt | make check PASS, make validate PASS, make test PASS lab5 |
| test-persistence.txt | PASS; состояния контейнеров до/после (новые pid у lb, api, relay, worker, postgres, valkey, s3, broker) |
| test-failover.txt | PASS дважды, остановлены обе реплики по очереди |
| demo-pipeline.txt | сценарий защиты шаги 2–3, очередь messages=1 до и после рестарта брокера, ready, JPEG 256×160 |
| student-tests.txt | 377 passed, 4 skipped (skipped — unit-тесты djpeg, которого нет на Windows-хосте; те же случаи проходят против стенда), 25 мин |
| track2-runs.txt, track2/ | матрица трека 2, аудит --verify-checksums, jobctl stats (outbox пуст), tests/load.py |
| load.json | контроль регрессии lab3: 183 успешных RPS, 0 ошибок, p95 44 мс (4 клиента, 30 с; не сравнивается с lab3 — другой стенд) |
Свап: у api и worker memswap = memory (без swap). У инфраструктурных контейнеров остался умолчательный swap Docker (= 2 × memory) — видно в docker inspect, для выводов этой лабы не важно.
Ограничения и следующие шаги
- Один Docker-хост: quorum queue на одном узле (без репликации), PostgreSQL один. «Устойчиво» = переживает рестарт процессов/контейнеров с volumes.
- SeaweedFS подтверждает PUT без явного fsync каждой записи; потеря питания хоста — вне модели угроз.
- Опубликованные варианты старых версий не удаляются; квоты на число версий нет.
- Колонки карантина lab4 (
lost_at) сохранены, но ничем не выставляются (reconciler удалён). - Объект, записанный замороженной попыткой после её уборки (пауза дольше
ORPHAN_GRACE_SECONDS), станет мусором; аудит покажет его какleaked_object. Это не потеря: опубликованное не задевается. - Следующие шаги: трассировка (
traceparentв сообщении уже предусмотрен схемой) — lab6.