Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
16 KiB
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
- Полный, проверенный оригинал лежит в приватном bucket
messenger-staging: S3 подтвердил PUT и Content-MD5. Проверки 413/415 делаются до этого, синхронно, теми же валидаторами, что в lab4 (PNG — свой потоковый, JPEG —djpeg -strict). - Строка
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_SECONDSreaper возвращает задание. - Worker, у которого жив heartbeat, но зависла обработка, ограничен
JOB_TIMEOUT_SECONDS: дочерний процесс убивается, heartbeat перестаёт продлевать lease после этого срока. - Если heartbeat узнал, что lease потерян, попытка отменяется сама. Даже если не отменилась — её COMMIT отвергнет fencing.
- Брокер со своей стороны: AMQP heartbeat 10 с закрывает соединение замороженного клиента и возвращает его неподтверждённые сообщения;
consumer_timeout5 мин — для подключённого, но не отвечающего ack.
Retry, failed, replay
JOB_MAX_ATTEMPTS=5claim-ов на задание. 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 результата; stagingfailed— через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), а не обрезается. Оригинал публикуется побайтно без изменений. Уменьшение размера маленьких файлов не обещается.