Files
mtusi2026lab5/REPORT.md
T
2026-11-10 22:13:40 +03:00

23 KiB
Raw Blame History

Лабораторная 5: очередь изображений

Целевая оценка: 5, исследование — трек 1, очередь под перегрузкой. Redis уже хранит сессии. Redis Streams добавляет очередь без второго брокера. Исследование сравнивает три настройки concurrency/prefetch. Методика и результаты: RESEARCH.md. Публичные контракты и проверки lab5 сохранены.

Запуск

Установите Docker с поддержкой Swarm и Python 3.9+. Локальные Go-проверки требуют Go 1.26.4 или новее. Запустите стенд:

make up
make wait
make test

API: http://localhost:18085. Swagger: http://localhost:18085/swagger/. Стек mtusi-lab5 не использует volumes, секреты и порт исходного стенда lab4. Скрипт поддерживает один узел Swarm. Порты хранилищ не опубликованы.

Bootstrap создаёт случайные секреты в локальном каталоге secrets/ и Docker secrets. Каталог исключён из Git и Docker context. Скрипты не загружают .env. Версии закреплены в Dockerfile/stack.yaml:

Компонент Версия
Go / Alpine 1.26.4 / 3.23, базовые digest в Dockerfile
PostgreSQL 17.6-alpine3.22
Redis 7.4.5-alpine3.21
HAProxy 3.2.6-alpine
MinIO RELEASE.2025-09-07T16-13-09Z, фиксированный commit и SHA-256
mc RELEASE.2025-08-13T08-35-41Z, фиксированный commit и SHA-256
libwebp-tools 1.6.0-r0

Go compiler использует -p=1 и GOMAXPROCS=2 при сборке контейнеров. Это ограничивает память сборки на Docker VM с 1,91GiB RAM. Первый параллельный build получил OOM; последовательный build устранил эту ошибку. SKIP_STORAGE_BUILD=1 make up повторно использует уже собранные образы MinIO/mc. Обычный make up собирает все образы из репозитория.

Compose запускает те же роли с одной API-репликой:

make bootstrap
./scripts/compose.sh up -d --build --wait
make test
./scripts/compose.sh down

Остановите один стенд перед запуском другого на том же порту. make down сохраняет volumes и Docker secrets. При обновлении make up останавливает API перед миграциями 005–010. Миграция 009 переводит старые ready-оригиналы lab4 в очередь без повторной загрузки. Старый object key временно становится staging key. Worker удаляет этот staging только после публикации готовых вариантов. Эта пауза исключает запись старой API-версией после backfill. Откат миграций удаляет jobs/outbox; сохранять принятые задачи при downgrade нельзя.

Путь принятой загрузки

  1. API проверяет сессию, членство в чате, имя, bytes, MIME и пиксели.
  2. API сохраняет проверенный оригинал в приватный staging/<attachment_id>.
  3. PostgreSQL одной транзакцией сохраняет attachment, job и outbox.
  4. API возвращает 202 со снимком queued после COMMIT.
  5. Publisher читает outbox через FOR UPDATE SKIP LOCKED и делает XADD.
  6. Worker получает сообщение через XREADGROUP и арендует job в PostgreSQL.
  7. Renderer создаёт варианты в отдельном процессе с deadline.
  8. Worker сохраняет оригинал и три варианта по постоянным versioned keys.
  9. PostgreSQL атомарно публикует ready и метаданные всех вариантов.
  10. Worker подтверждает запись через XACK и удаляет подтверждённую запись XDEL.

API не выполняет resize. Проверка входного изображения в API сохраняет требования lab4. Она включает полный decode для обнаружения повреждений, но не создаёт варианты. Каждая API-реплика проверяет не более одного upload одновременно. Локальный spool ограничен 10MiB и удаляется после staging PUT или ошибки.

API publisher работает независимо от worker. Worker также может опубликовать ожидающий outbox. Row locks исключают конкурентную публикацию одной outbox-строки. Разрыв между XADD и PostgreSQL COMMIT может создать дубль; потеря принятой задачи не возникает. Подтверждение XADD означает durable запись Redis с appendfsync always. XACK означает устойчивый результат обработки либо устойчивую запись следующего состояния. Это at-least-once доставка с идемпотентным эффектом, а не exactly-once доставка.

Redis хранит stream attachments:jobs:v1, группа — image-workers-v1. Одно поле stream job содержит JSON по contracts/jobs.schema.json. Поля включают UUID job/attachment, version, attempt, type, schema_version и created_at. Сообщение не содержит bytes, credentials, filename, URL или S3 key. Worker берёт доверенные storage metadata из PostgreSQL.

Состояния, retry и защита результата

PostgreSQL — источник истины состояний queued/processing/ready/failed. Queued и processing можно прикрепить к сообщению своего чата. Content до ready и после failed возвращает 409. Метаданные доступны во всех состояниях. Failed нельзя прикрепить заново. Ранее подтверждённые сообщения и их idempotency replay сохраняются.

Claim увеличивает attempts и fence, задаёт lease_until. Фиксация результата требует текущий fence, pipeline_version и ещё действующий lease. Она также требует ровно одну изменённую строку attachment нужной версии и состояния. Старый процесс не публикует ready после аренды новой попыткой. Объекты используют ключ original/<attachment_id>/v<pipeline_version>/<variant>. Имена эффектов: original, thumbnail, crop, optimized. Повтор той же версии пишет те же байты в те же четыре ключа. Новая версия получает другой prefix. Стандартный pipeline_version равен 1.

XAUTOCLAIM возвращает pending-доставки умерших consumers после lease. Истёкший processing возвращается в queued через устойчивую транзакцию и новый outbox. Attempts учитывают управляемые попытки обработки; простой дубль ready не увеличивает attempts. Перед ack дубля ready проверяются метаданные и наличие четырёх S3-объектов нужного размера. Дубль не изменяет updated_at, варианты или готовый результат.

Временные ошибки хранилищ, timeout и worker crash используют ограниченный retry. Постоянные ошибки изображения и исчезнувший staging дают failed сразу. Backoff после попытки n: 2^min(n,5) секунд плюс случайные 0–499ms. По умолчанию разрешено пять попыток. Финальный public error_code безопасен и не содержит внутренних данных. Реестр failed хранится в attachment_jobs; последняя причина сохраняется в last_error.

make failed-jobs
make replay JOB_ID=<uuid> OPERATOR=<name> REASON='Причина повторной обработки'

Replay принимает только failed с доступным staging и свободным admission slot. Он сохраняет job_id и versioned effect identity, сбрасывает счётчик попыток и увеличивает fence. Транзакция записывает operator, reason, предыдущую ошибку и время в attachment_replays. Replay ready или ещё активной работы отклоняется. После истечения retention replay отклоняется.

Изображения и пределы ресурсов

Thumbnail — JPEG quality85, вписан в 256×256 без увеличения, размеры округляются вниз. Crop — центрированный квадрат JPEG128×128 quality85, малые исходники увеличиваются. Optimized — WebP quality80, method4, вписан в 1280×1280 без увеличения. JPEG/PNG EXIF orientation1–8 применяется до изменения размеров. Alpha компонуется на белый. Варианты не сохраняют EXIF; cwebp получает -metadata none. Уменьшение каждого маленького файла не обещается. Оригинал сохраняется побайтно.

API ограничивает bytes10MiB и 40 миллионов пикселей до полного decode. Worker повторно проверяет размер, SHA-256, DecodeConfig и pixel budget. Resize/decode/cwebp работают в дочернем renderer; CommandContext ограничивает весь процесс. Renderer создаёт отдельную process group. Deadline убивает renderer и потомков, включая cwebp. Общий pixel semaphore ограничивает одновременно распакованные исходники 40Mpx на worker service. Orientation использует представление исходника, без второй копии полного изображения. Renderer получает GOMEMLIMIT384MiB; worker service ограничен cgroup1536MiB и1CPU. GOMEMLIMIT является мягким Go-лимитом; жёсткий предел задаёт cgroup всей службы.

Настройка По умолчанию Назначение
WORKER_CONCURRENCY 2 Одновременные обработки, максимум8
WORKER_PREFETCH 4 Ёмкость локальной очереди, максимум32
WORKER_TIMEOUT_SECONDS 25 Вся попытка: admission пикселей, download, renderer и PUT
WORKER_LEASE_SECONDS 40 Lease; минимум timeout+5s
WORKER_PIXEL_BUDGET 40000000 Общий pixel budget, максимум80000000
WORKER_MAX_ATTEMPTS 5 Число попыток новой job, задаётся API при upload
MAX_OUTSTANDING_JOBS 200 Максимум queued+processing на весь стенд

Prefetch ограничивает ожидающую локальную очередь. Активные процессы добавляют concurrency к числу полученных сообщений. Настройки bounded; число принятых незавершённых jobs ограничено отдельно. Admission использует общий PostgreSQL advisory lock и count queued/processing. Этот lock также защищает replay. Превышение возвращает 429 с Retry-After. Проверка и вставка выполняются в одной транзакции, поэтому две API-реплики не превышают лимит. Lock удерживается во время staging PUT. Это ограничивает throughput upload и измеряется в исследовании.

Retention и согласованность S3

Очистка выполняется каждые пять секунд, не более100 metadata rows за проход. Ready staging удаляется после устойчивой публикации всех вариантов. Failed staging и частичные конечные объекты сохраняются семь дней для расследования и replay. После семи дней cleanup удаляет bytes и ставит storage_cleaned_at, но сохраняет metadata/job/audit. Replay и cleanup блокируют одну metadata row; очистка не удаляет текущую работу. Старый stage без metadata имеет grace90s и общий с upload advisory lock. После PUT без COMMIT API возвращает ошибку; такой stage удаляется после grace. Готовые конечные вложения сохраняются бессрочно, включая ещё не привязанные к сообщению. Их staging очищается одинаково. Автоматическое удаление готовых конечных вложений не реализовано.

Reconciler lab4 сохранён: make reconcile, make reconcile-apply. Он защищает текущий versioned prefix и staging_key, включая legacy staging в original-prefix. Отсутствующий ready-оригинал атомарно переводит attachment и job в failed. Reconciler не удаляет ссылки из подтверждённых сообщений. Reconciler контролирует original; внешняя утрата отдельного варианта требует ручного восстановления. Проверка дубля пишет безопасный retry-log, если готовый эффект недоступен. Автоматический ремонт внешних удалений вариантов не реализован.

Проверки и исследование

Подготовьте зависимости проверок:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt -r requirements-research.txt
make check validate
make test-own
make test-integration
make test
make test-lab5
make test-persistence
make test-failover
make benchmark
make plot-research

Go-тесты проверяют геометрию, EXIF1–8, alpha, повреждения, MIME, concurrency и транзакции. Интеграционный тест проверяет stale/expired fence и защиту более новой pipeline_version. Fault suite внедряет ошибку после staging, разрыв COMMIT/publish и два broker restart. Он останавливает worker после S3 effects и после result COMMIT перед ack. Проверяются повторная доставка, lease recovery, bounded retry, permanent failure и audit replay. Отдельный renderer_timeout блокирует настоящий cwebp на FIFO и проверяет уничтожение потомков. Очистка проверяется для ready, unconfirmed и expired failed staging. Все пользователи и изображения синтетические. Токены и секреты в evidence не сохраняются. Запускайте fault, persistence и benchmark последовательно на учебном стенде.

Исследование трека1 использует реальные свежие измерения, а не результаты исходного проекта. Пары concurrency/prefetch: (1,1), (2,4), (4,8); размеры PNG512² и1536². Отдельный опыт проверяет предел admission при остановленном worker и последующее восстановление. Raw данные, графики, ограничения методики и объяснение для защиты находятся в RESEARCH.md. Исследование завершено: все 120 измеряемых загрузок стали ready, шесть сочетаний настроек и размеров проверены. Пара concurrency=2, prefetch=4 дала лучший throughput для обоих размеров: 4,013 и 0,851 изображения/с. При остановленном worker лимит 8 принял 8 из 16 загрузок; остальные получили 429. После запуска все 8 заданий завершились, очередь опустела, новая загрузка прошла. Текстовое сообщение сохранилось при полной очереди. Исходные настройки восстановлены. Итог PASS и наблюдения: evidence/lab5-research.json; таблица: evidence/lab5-research.csv. Исторические evidence/lab4-* не считаются доказательством lab5.

make test прошёл на новом API lab5. Журнал: evidence/lab5-smoke.txt. Host race-тесты и контейнерные интеграционные тесты прошли. Интеграционный журнал: evidence/lab5-integration.txt; исходная ошибка fixture сохранена отдельно. Прежний fixture удалял migration journal из уже обновлённой схемы. Теперь он сначала возвращает физическую схему lab4, затем проверяет её импорт.

Все обязательные fault cases проверены на реальных PostgreSQL, Redis Streams и MinIO. Первый полный вызов подтвердил основные durability/crash/retry сценарии и выявил гонку тестового stop helper. Desired replicas=0 ещё не означает остановку старого consumer-контейнера. Helper и make worker-stop теперь ожидают фактическое отсутствие работающих контейнеров. Поздние независимые cases повторены через --tail-only с новыми пользователями и изображениями. Повтор завершился exit0; прежние успешные cases и время продолжения сохранены в JSON. Исходный полный вызов завершился exit1 и не объявляется успешным полным прогоном. Журналы: evidence/lab5-faults-main.txt, evidence/lab5-faults-tail.txt. Все case-level результаты находятся в evidence/lab5-faults.json.

Отдельный initial fault обнаружил старый worker при обновлении образа с прежним tag. make up теперь принудительно обновляет worker вместе с API. После исправления фактические JPEG/PNG EXIF проверки прошли. Статические проверки и команды воспроизведения собраны в evidence/lab5-validation.txt. make test-persistence прошёл после перезапуска компонентов собственного стенда. Подтверждённые данные и существующая сессия сохранились: evidence/lab5-persistence.txt. make test-failover прошёл при остановке одной из двух API-реплик. Зафиксированы 123 успешные записи, одна неудачная попытка и восстановление за 0,696s. Подтверждённые данные и сессия сохранились: evidence/lab5-failover.txt.

Соответствие критериям

Уровень Критерий Реализация и доказательство
3 Возможности lab4 и переход upload на 202 PORTING.md, публичный smoke, persistence/failover
3 Устойчивый приём до ответа MinIO staging + PostgreSQL attachment/job/outbox; cases stage_before_commit, commit_publish_and_restarts
3 Отдельный broker/worker, durable at-least-once Redis Streams/AOF; два broker restart, worker stop/start
3 Четыре состояния, оригинал и thumbnail Контракт API; smoke, small_alpha_exif, bounded_retry_replay
3 Ограниченные повторы и единый результат max_attempts, versioned keys; cases crash_after_objects, commit_before_ack_and_duplicate
4 Crop/WebP, качество и ограничения Renderer, pixel budget, process deadline; EXIF/alpha/geometry tests и renderer_process_group_timeout
4 Восстановление разрыва COMMIT/publish Transactional outbox; case commit_publish_and_restarts
4 Backoff/jitter, permanent failure, failed registry/replay Cases bounded_retry_replay, permanent_stage_error; audit replay
4 Crash после S3, lease/fence, bounded concurrency/prefetch Crash cases, TestFenceIntegration, конфигурация worker
4 Безопасная очистка staging Case staging_cleanup; ready/failed/unconfirmed retention
5 Трек 1: настройки, размеры, backpressure и восстановление Методика, raw данные, графики и ограничения в RESEARCH.md

Источники case-level результатов: evidence/lab5-faults.json и журналы split-run выше.