Files
mtusi2026lab5/REPORT.md
T

21 KiB
Raw Blame History

Отчёт — лабораторная 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, janitor pending, 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 в exchange messenger.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 test PASS lab5: 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) все проходят, 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 см. ниже 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

Результаты: РЕЗУЛЬТАТЫ_ТРЕКА_2

Почему это не 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 с, текст работает так и есть файлы целы

Дефекты, найденные в ходе работы и исправленные:

  1. После рестарта брокера worker оставался без consumer, а healthcheck показывал healthy; relay падал на ChannelInvalidStateError. Причина: aio-pika не выставляет is_closed при закрытии соединения сервером. Исправлено (1d37fd0): close_callbacks, heartbeat-файл только при живом consumer.
  2. Внедрённый crash worker срабатывал на каждой попытке, а не один раз на задание. Исправлено там же.
  3. Аудит ошибочно требовал объект 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.

Ограничения и следующие шаги

  • Один Docker-хост: quorum queue на одном узле (без репликации), PostgreSQL один. «Устойчиво» = переживает рестарт процессов/контейнеров с volumes.
  • SeaweedFS подтверждает PUT без явного fsync каждой записи; потеря питания хоста — вне модели угроз.
  • Опубликованные варианты старых версий не удаляются; квоты на число версий нет.
  • Колонки карантина lab4 (lost_at) сохранены, но ничем не выставляются (reconciler удалён).
  • Объект, записанный замороженной попыткой после её уборки (пауза дольше ORPHAN_GRACE_SECONDS), станет мусором; аудит покажет его как leaked_object. Это не потеря: опубликованное не задевается.
  • Следующие шаги: трассировка (traceparent в сообщении уже предусмотрен схемой) — lab6.