Files
mtusi2026lab5/REPORT.md
T

14 KiB
Raw Blame History

Отчёт — лабораторная 5

  • Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
  • Целевая оценка: 5, трек 2 «Доказанная идемпотентность pipeline». Уровни 3 и 4 тоже проверены.
  • Ветка: solution/bpi2302-samohvalov. Локальные docs/plans/ и LAB_NOTES.md не входят в коммиты.
  • Источники: README.md, COURSE.md, contracts/README.md, contracts/attachment-states.md, contracts/jobs.schema.json, contracts/openapi.json, публичные тесты и собственная lab4. Python 3.12.12, FastAPI 0.118.3, Pillow 11.3.0, psycopg 3.2.12, MinIO SDK 7.2.20, pika 1.4.4. Помощь ИИ: Codex; факты ниже проверены на синтетических данных.

Запуск из чистого clone

Нужны Docker Compose и Python 3.9+. Наружу опубликован только HAProxy на 127.0.0.1:${APP_PORT:-8080}; паролей в Git нет.

cp .env.example .env
python3 scripts/setup-local-secrets.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2
docker compose --env-file .env up -d --wait --scale api=2 api lb worker publisher
make check
make test

Скрипт создаёт только отсутствующие секреты с правами 0600. migrate, s3-volume-init, s3-bootstrap, broker-init — одноразовые роли: Exited (0) для них штатен. Миграции применяются под PostgreSQL advisory lock. Остановить стенд без потери учебных данных: docker compose --env-file .env down. Только для намеренного удаления синтетических данных: docker compose --env-file .env down -v.

Образы: PostgreSQL 17.6, RabbitMQ 4.1.8-management, HAProxy 3.0.11, Python 3.12.12, MinIO RELEASE.2025-10-15T17-29-55Z и MinIO Client 2025.7.21-debian-12-r3 (S3-образы закреплены digest). Проверено в Colima/arm64: 2 CPU, 2 GiB RAM. На этом хосте Docker build не разрешал DNS files.pythonhosted.org; сборка применяла только локальный ignored compose.local.yaml с временным адресом CDN через COMPOSE_FILE=compose.yaml:compose.local.yaml. При обычном DNS/PyPI он не нужен.

Архитектура и границы надёжности

Клиент → HAProxy → две API-реплики. PostgreSQL — источник истины для пользователей, сообщений, вложений, jobs, outbox и версий. MinIO хранит байты в закрытом bucket. RabbitMQ переносит только ID и служебные поля jobs.schema.json, без изображения, credentials, клиентского пути или произвольного URL.

Роль Health, volume, пределы Доступ
lb проверка API backends, без данных единственный host port
api ×2 /health/ready, 0,5 CPU/256 MiB каждая DB URL и ограниченные S3 credentials
postgres pg_isready, postgres_data локальный secret
s3 /minio/health/ready, s3_data, 0,5 CPU/384 MiB root только внутри S3/bootstrap
broker rabbitmq-diagnostics ping, broker_data AMQP URL через secret, без host port
publisher отдельный процесс с publisher confirms DB и AMQP, без S3
worker отдельный процесс, 0,5 CPU/768 MiB, prefetch=1 DB, AMQP, объектные S3 права
staging-cleanup периодический процесс DB и отдельные S3 maintenance credentials

API потоково принимает до 10 MiB PNG/JPEG, сверяет MIME с содержимым и ограничивает изображение 40 млн пикселей. Имя файла используется только для отображения. Перед S3 PUT создаётся временный upload marker; полный staging-object затем сверяется по размеру и SHA-256. Одна транзакция записывает attachment, job и outbox, и лишь после COMMIT API отвечает 202 queued. Поэтому остановленный broker/worker не теряет принятую загрузку; другие сообщения и ссылка на queued-вложение того же чата работают. Пока нет ready, скачивание отвечает 409.

Publisher арендует outbox, публикует persistent сообщение в durable quorum queue и отмечает outbox только после broker confirm. Потеря DB-подтверждения может создать вторую доставку. Worker захватывает job под lease, читает доверенные метаданные из PostgreSQL, сверяет исходные байты и пишет объекты с детерминированными ключами. Статус ready фиксируется лишь после всех четырёх внутренних эффектов: original, thumbnail, crop, optimized. Публичная metadata показывает три производных варианта; доступ к каждому проходит проверку членства в чате через API.

Original остаётся побайтно неизменным. Thumbnail — JPEG quality=85, optimize=True, вписан в 256×256 без увеличения и с округлением вниз: 320×200 → 256×160. Crop — центральный JPEG 128×128; маленький исходник может увеличиваться. Optimized — WebP quality=82, method=4, вписан в 1280×1280 без увеличения. EXIF orientation применяется к производным, alpha кладётся на белый фон, EXIF и прочие метаданные в производные не передаются. Уменьшение размера в байтах каждого файла не обещается.

Worker имеет 60-секундный deadline/lease, одно текущее сообщение и контейнерный предел памяти. Временная ошибка повторяется до 5 попыток с экспоненциальной базой 1–30 с и jitter до 50%; invalid_image постоянна, storage_unavailable и worker_timeout повторяются. Исчерпанная job остаётся failed с безопасным error_code в БД: это реестр вместо отдельной DLQ-очереди. Операторский replay требует явной команды и пишет audit, а ready job повторно не исполняется:

docker compose --env-file .env exec -T worker python -m src.replay JOB_UUID --operator local-operator --reason 'verified repair'

Вторую версию исследователь запускает через python -m src.reprocess ATTACHMENT_UUID в worker-контейнере. Команда принимает только ready с проверенным оригиналом. Версия 1 читает staging, следующие версии — неизменный конечный original. Уникальность (attachment_id, pipeline_version, name) и lease token защищают текущий результат от старой доставки. После COMMIT worker удаляет staging по возможности; staging-cleanup повторяет удаление после сбоя. Orphan без job удаляется только после 3600 с и перепроверки upload marker/БД; queued/processing источник сохраняется.

Доказательства критериев

Критерий README Команда/сценарий Наблюдение Evidence
Общий стенд и quorum docker compose up -d --build --scale api=2; restart broker; rabbitmqctl list_queues Все роли поднялись; durable quorum queue сохранилась после restart evidence/broker-restart.txt, compose.yaml
Публичный API make test BASE_URL=http://127.0.0.1:8085 после финальной сборки PASS; original побайтно верен, thumbnail 256×160 tests/smoke.py
Durable handoff student-tests/test_upload_handoff.py: broker/worker down → 202/409 → restart API/broker PASS; сообщение с вложением создано, та же job стала ready собственный тест
Окно publish→confirm student-tests/test_publish_confirm_gap.py После первой broker confirm outbox остался pending; повтор дал 2 копии в очереди, но один логический ready-результат evidence/pipeline-faults-2026-10-02.md
Варианты, доступ и лимиты student-tests/test_image_pipeline.py в worker; test_variants_api.py через LB 5/5 unit; все 3 варианта совпали с metadata/hash, original точен, чужой пользователь 404 собственные тесты
Retry, lease, replay, версия, crash student-tests/test_pipeline_faults.py на существующих и пустых томах В обеих сериях 6/6 PASS, включая смерть процесса до/после S3 и после result COMMIT evidence/pipeline-faults-2026-10-02.md
Очистка staging student-tests/test_staging_cleanup.py в maintenance-контейнере Старый orphan удалён, active upload сохранён, expired marker/object удалены собственный тест U2
Persistence/failover make test-persistence ACTION_SCRIPT=scripts/restart.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS; сохранены токен/данные после остановки API/LB/publisher/worker/cleanup/broker/PG/S3; 133 успешные записи, 0 ошибок, восстановление 1,327 с hooks, tests/resilience.py
Нагрузка tests/load.py 30 с/4 клиента; scripts/measure-image-pipeline.py 20+20 файлов/4 клиента 22 419 сообщений без ошибок, 747,002 RPS; 40/40 изображений ready за 14,150 с evidence/load-2026-10-02.json, evidence/image-load-2026-10-02.json, evidence/image-resource-samples-2026-10-02.txt

Эксперимент трека 5 и замеры

Гипотеза: подтверждённая job и её эффект останутся логически единичными при дублировании, перестановке версий и смерти worker до/после S3 и COMMIT. evidence/pipeline-faults-2026-10-02.md описывает две обезличенные серии: одна на существующих томах, другая в отдельном изначально пустом PostgreSQL/S3 проекте (до теста 0 jobs/replays). В каждой серии 6/6 PASS; у каждой готовой версии ровно четыре внутренние записи, current version и SHA-256 оригинала верны. Тест publish→confirm намеренно создал две копии в RabbitMQ. Это идемпотентность эффекта, не exactly-once доставка.

Текстовая closed-loop нагрузка 30,012 с, concurrency=4: 22 419 успешных POST, 0 ошибок, 747,002 успешных RPS, latency p50/p95/p99=4,109/11,019/36,533 мс. Closed-loop не измеряет предельную пропускную способность image pipeline и имеет coordinated omission/накладные расходы клиента.

Изображения: 20 PNG 320×200 по 111 817 байт и 20 PNG 800×600 с псевдослучайными пикселями по 1 441 103 байт; concurrency=4, 40/40 ready, 0 ошибок, 14,150 с (~2,827 ready/s). Для маленьких upload p50/p95/p99=20,276/29,796/30,022 мс, от начала upload до ready=1273,778/1285,587/1287,102 мс. Для больших upload=29,097/54,469/57,979 мс, до ready=1585,251/2256,920/2571,138 мс. os.urandom сохраняет размер/разрешение профиля, но не конкретный hash между запусками. Poll каждые 0,3 с увеличивает наблюдаемое время ready; p95/p99 основаны на 20 результатах каждого размера. Выборочные Docker stats во время серии: API 85–86 MiB на реплику, worker 49–61 MiB, S3 182–184 MiB; это снимки, не пик памяти.

После failover вторая API-реплика восстановлена командой docker compose up -d --wait --scale api=2 api lb. Основные тома сохраняют синтетические записи; отдельные пустые тома эксперимента удалены только в проекте mtusi2026lab5fresh.

Ограничения

Единственные PostgreSQL, MinIO, RabbitMQ и Docker-host остаются точками отказа; quorum queue на одном узле не означает кластерную доступность. При недоступности зависимости worker повторяет работу или достигает failed, а не выдаёт ложный ready. Serial worker/prefetch=1 и 60-секундный deadline подходят для учебных лимитов 10 MiB/40 млн пикселей; на другом оборудовании нужны новые замеры. Локальный HTTP используется только с синтетическими данными; удалённой демонстрации нужен TLS. Публичный smoke подтверждает обязательный минимум; отказные сценарии и трек 5 проверены отдельно.