Files
mtusi2026lab5/docs/PIPELINE.md

16 KiB
Raw Permalink Blame History

Pipeline обработки вложений (lab5)

Схема: migrations/0005_pipeline.sql. Код: API — attachments.py, переходы заданий — jobs.py, relay — relay.py, worker — worker.py, картинки — imaging.py, версии — pipeline.py, оператор — jobctl.py, аудит — audit.py.

Кто что делает

клиент ──POST──▶ LB ──▶ API ──(1) INSERT attachments 'pending'          ──▶ PostgreSQL
                         │  (2) PUT оригинал в messenger-staging         ──▶ S3 (staging)
                         │  (3) ОДНА транзакция: 'queued' + jobs + outbox ──▶ PostgreSQL
                         └─ 202 queued
relay:   outbox ─(4) publish + publisher confirm─▶ RabbitMQ (quorum queue) ─(5) deliver─▶ worker
worker:  (6) claim: lease + token попытки ─▶ (7) читает источник, сверяет SHA-256 ─▶ (8) варианты
         в дочернем процессе ─▶ (9) PUT a/<id>/<token>/* в messenger-attachments ─▶
         (10) ОДНА транзакция: варианты + attachment 'ready' (с проверкой токена) ─▶ (11) ack ─▶
         (12) staging 'deleting' → S3 DELETE → 'deleted'
  • Источник истины — PostgreSQL: состояние задания, попытки, lease, время следующей попытки (available_at), реестр failed, аудит (job_events). Брокер только доставляет job_id.
  • API не знает брокер (нет даже сети queue). Брокер упал — upload всё равно 202, задания копятся в outbox.
  • В сообщении только поля jobs.schema.json: schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at. Никаких байтов, URL, ключей S3, имени файла. Worker берёт content_type, размер, SHA-256 и ключ источника из БД.

Что сохранено в момент 202

  1. Полный, проверенный оригинал лежит в приватном bucket messenger-staging: S3 подтвердил PUT и Content-MD5. Проверки 413/415 делаются до этого, синхронно, теми же валидаторами, что в lab4 (PNG — свой потоковый, JPEG — djpeg -strict).
  2. Строка attachments в статусе queued, строка jobs (queued, attempt 0) и строка outbox — в одной транзакции, закоммичены (fsync PostgreSQL).

Значит, после 202 можно убить API, relay, broker и worker: работа восстановится из этих двух записей. Честная граница: staging — это уже S3, а не «временная папка». На одном Docker-хосте «устойчиво» значит «переживает рестарт процессов и контейнеров с volumes», а не потерю диска.

Состояния

Вложение (attachments.status):

Статус Видно клиенту Как попадает Как выходит
pending нет (404) INSERT до PUT в staging → queued (COMMIT задания) или удаляется janitor через PENDING_GRACE_SECONDS
queued да, content 409 COMMIT задания; retry; истёк lease; replay → processing при claim
processing да, content 409 claim worker → ready / queued (retry, lease) / failed
ready да, варианты COMMIT результата никогда не возвращается назад. Reprocess новой версии не меняет статус
failed да, error_code, content 409 постоянная ошибка или попытки кончились → queued только через jobctl replay

Задание (jobs.state): queued → processing → succeeded | failed | superseded, processing → queued (retry, lease, graceful stop). superseded — старая версия pipeline, когда опубликована более новая.

Ограничения в самой БД (CHECK) не дают коду ошибиться:

  • attachments_active_has_source: у queued/processing есть источник — опубликованный оригинал или staging в состоянии present. Уборка физически не может пометить staging принятой работы;
  • jobs_lease: lease есть ровно тогда, когда processing;
  • jobs_one_active: одно активное задание на (attachment, pipeline_version);
  • PK attachment_variants (attachment_id, pipeline_version, name) — ключ эффекта из контракта.

Окна отказа (contracts/attachment-states.md)

Окно Что остаётся Кто восстанавливает Проверка
после staging, до записи задания pending + объект staging, задания нет, 503 клиенту janitor API: объект, потом строка (после grace) API_FAULT_POINTS=after_s3_put, test_consistency
после COMMIT, до publish строка outbox без published_at relay при следующем проходе; никто не создаёт задание вручную broker/relay остановлены, test_pipeline_flow
после publish, до записи confirm сообщение в очереди + неотмеченная строка outbox relay публикует ещё раз → дубль → no-op RELAY_FAULT_POINTS=crash_after_publish
после записи S3, до COMMIT результата объекты под ключами попытки 1, не опубликованы lease истекает → reaper → попытка 2 со своими ключами; уборка удаляет ключи попытки 1 WORKER_FAULT_POINTS=crash_after_s3_write
после COMMIT результата, до ack ready redelivery → claim видит succeeded → ack без работы WORKER_FAULT_POINTS=crash_after_commit
worker умер/завис в processing lease без продления reaper (в relay, раз в 5 с) → queued + outbox; commit старой попытки отвергается токеном crash_after_claim, docker pause

Publisher confirm ≠ consumer ack

  • Publisher confirm (relay ← broker): «брокер принял сообщение и записал его в quorum log». Это граница «намерение передано в очередь»; после неё relay ставит published_at.
  • Consumer ack (worker → broker): «результат работы устойчиво зафиксирован». Worker шлёт ack только после COMMIT результата (или после COMMIT решения «retry/failed/no-op»).
  • Между ними может пройти сколько угодно времени и случиться любой сбой. Confirm без ack = сообщение ждёт в очереди; потеря ack = повторная доставка.

Идемпотентность и повторная доставка

Доставка at-least-once: дубль может появиться из relay (crash до отметки), из брокера (нет ack из-за падения worker, разрыв соединения, consumer_timeout), от оператора. Поэтому каждая доставка начинается с claim под блокировкой строки jobs:

Состояние задания Решение ack
succeeded/failed/superseded no-op (noop_finished) да
processing (lease держит другой) no-op (noop_leased), его смерть обработает reaper да
queued, available_at в будущем no-op (noop_not_due), outbox опубликует вовремя да
queued, опубликована версия ≥ своей superseded да
queued, пора claim: attempt+1, новый lease_token, строка job_attempts с заранее известными ключами после результата

Ключ идемпотентности задания — job_id (строка в БД), ключ эффекта — (attachment_id, pipeline_version, variant). Объекты пишутся под ключами a/<attachment>/<token>/<name>: у каждой попытки свои. Опубликовано ровно то, на что ссылается COMMIT результата. Fencing: COMMIT проходит, только если jobs.lease_token всё ещё равен токену попытки. Reaper обнуляет токен, поэтому «проснувшаяся» старая попытка ничего не опубликует.

Это не exactly-once доставка. Сообщение может прийти несколько раз, а работа выполниться дважды (например, зависший worker досчитает варианты). Exactly-once — только видимый эффект: одна опубликованная запись на ключ эффекта, монотонная версия, мусор попыток убирается.

Зависший vs долго работающий worker

  • Долго работающий продлевает lease каждые JOB_LEASE_SECONDS/3 (heartbeat в БД, WHERE lease_token = мой).
  • Зависший (docker pause, deadlock, потеря сети к БД) не продлевает; через JOB_LEASE_SECONDS reaper возвращает задание.
  • Worker, у которого жив heartbeat, но зависла обработка, ограничен JOB_TIMEOUT_SECONDS: дочерний процесс убивается, heartbeat перестаёт продлевать lease после этого срока.
  • Если heartbeat узнал, что lease потерян, попытка отменяется сама. Даже если не отменилась — её COMMIT отвергнет fencing.
  • Брокер со своей стороны: AMQP heartbeat 10 с закрывает соединение замороженного клиента и возвращает его неподтверждённые сообщения; consumer_timeout 5 мин — для подключённого, но не отвечающего ack.

Retry, failed, replay

  • JOB_MAX_ATTEMPTS=5 claim-ов на задание. Backoff — full jitter: uniform(0, min(JOB_RETRY_MAX_SECONDS, JOB_RETRY_BASE_SECONDS·2^(n−1))). Задержка хранится в jobs.available_at и строке outbox — повтор проходит тем же путём outbox → broker, без TTL-очередей.
  • Постоянные ошибки (сразу failed): invalid_image, image_too_large, source_missing, source_corrupt. Временные: storage_unavailable, processing_timeout, processing_killed, processing_failed. Когда попытки кончились — retry_exhausted.
  • Реестр failed — view failed_jobs (jobctl list-failed). DLQ RabbitMQ (messenger.attachment-jobs.dlq) — для «ядовитых» сообщений: не по схеме или превысили x-delivery-limit=20.
  • Страховка от потерянного сообщения: queued-задание без claim и без публикаций дольше QUEUED_REPUBLISH_SECONDS получает новую строку outbox.
  • jobctl replay <id>: только для failed с живым источником, создаёт новое задание kind=replay, replay_of=<failed>, пишет оператора и причину в job_events. Для ready — отказ already_ready, ничего не создаётся.

Уборка (worker), всегда под блокировкой строки

  • staging ready — сразу после COMMIT результата; staging failed — через STAGING_RETENTION_SECONDS. Порядок: под UPDATE … WHERE <условие заново> пометить deleting → S3 DELETE → deleted. Replay берёт ту же блокировку: либо replay первым (строка уже queued, уборка её пропустит), либо уборка первой (replay видит deleting и отказывает source_missing).
  • Объекты попыток, которые не опубликовали результат (retry/failed/abandoned/superseded): удаляются по planned_keys через ORPHAN_GRACE_SECONDS. Перед этим проверяется, что токен не текущий и ни один ключ не опубликован. Новые результаты (replay, другая попытка) лежат под другими ключами — устаревший проход не может их удалить.
  • pending без задания — janitor API (как в lab4).
  • Опубликованные варианты старых версий pipeline сохраняются (ограничение, см. REPORT).

Версии pipeline (трек 2)

Версия фиксируется в задании при создании (PIPELINE_VERSION для upload, jobctl reprocess --pipeline N для готового вложения). Версии 1/2/3 отличаются параметрами кодеков, геометрия — по контракту. Публикация: только если N > published_version; иначе superseded. Reprocess неготового вложения запрещён: его единственный источник — staging текущего задания.

Лимиты worker

Что Чем
параллельность prefetch = WORKER_CONCURRENCY (2) + семафор на дочерние процессы
bytes размер из БД ≤ MAX_UPLOAD_BYTES проверяется до скачивания; длина и SHA-256 скачанного = БД
пиксели width×height из заголовка ≤ MAX_IMAGE_PIXELS до декодирования; JPEG декодируется с DCT-масштабом (draft)
память RLIMIT_AS = IMAGE_MAX_MEMORY_MB (768) у дочернего процесса; контейнер 1536m без swap
время JOB_TIMEOUT_SECONDS (60): дочерний процесс убивается, lease перестаёт продлеваться

Варианты

Вариант Формат Геометрия Параметры v1
thumbnail JPEG baseline 4:2:0 вписан в 256×256, без увеличения, округление вниз, ≥1 px q=85, optimize
crop JPEG центральный квадрат → 128×128 (маленькие увеличиваются) q=85
optimized WebP lossy вписан в 1280×1280, без увеличения, alpha сохраняется q=80, method=4

EXIF orientation применяется к пикселям; в варианты не копируются EXIF, XMP, ICC, комментарии. Пиксели считаются sRGB. Alpha при ресайзе — premultiplied (без цветных ореолов), для JPEG композится на белый. 16-битный серый масштабируется (/257), а не обрезается. Оригинал публикуется побайтно без изменений. Уменьшение размера маленьких файлов не обещается.