Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
49 KiB
attachment-processing Specification
Purpose
Фоновая обработка принятого вложения с лабы 5. Здесь описано:
- состояния вложения и переходы между ними;
- задание в PostgreSQL и сообщение брокера;
- доставка at least once и подтверждение после устойчивого эффекта;
- публикация оригинала и thumbnail;
- идемпотентный эффект, ограниченные повторы и коды ошибок;
- worker как отдельный процесс и сохранность принятой работы.
Requirements
Requirement: Состояния вложения
Вложение, принятое ответом 202, SHALL находиться в одном из состояний
API: queued, processing, ready, failed. Переходы:
queued→processing— worker взял задание; зафиксированы номер попытки и срок её аренды;processing→queued— временная ошибка, попытки остались; зафиксированы причина без секретов и время следующей попытки;processing→queued— истёк срок аренды (требование «Аренда попытки»);processing→ready— оригинал, thumbnail, crop и optimized записаны, а метаданные вариантов и состояние зафиксированы одной транзакцией;processing→failed— ошибка постоянная или попытки исчерпаны; зафиксированы код ошибки и запись для оператора;failed→queued— явный replay оператора (требование «Реестр failed и replay»).
Готовое вложение MUST NOT возвращаться в другое состояние, в том числе
из-за повторной доставки и replay. error_code SHALL быть null во всех
состояниях, кроме failed, variants — пустым во всех, кроме ready.
Scenario: Принятое вложение в очереди
- WHEN worker остановлен, и участник загружает настоящий PNG
- THEN ответ 202 со
statusqueued, а метаданные через несколько секунд — 200 соstatusqueued,variants[],error_codenull
Scenario: Вложение становится готовым
- WHEN worker работает, участник загружает
tests/fixtures/sample.pngи опрашивает метаданные - THEN не позже чем через 60 с
statusready,error_codenull, а вvariantsровно по одному элементуthumbnail,cropиoptimized
Scenario: Обработка видна в API
- WHEN worker взял задание, а фиксация его результата задержана
- THEN метаданные — 200 со
statusprocessing, скачивание — 409conflict, а после фиксации метаданные —ready, скачивание — 200
Scenario: Готовое вложение не откатывается
- WHEN задание готового вложения доставлено ещё раз
- THEN метаданные совпадают с прежними во всех полях, включая
updated_at
Requirement: Задание в PostgreSQL
Вложению SHALL соответствовать одно логическое задание на
pipeline_version; в курсе pipeline_version равен 1. У задания есть
идентификатор, вложение, версия, состояние, число начатых попыток, число
попыток до последнего replay, причина последней ошибки, время следующей
попытки, срок аренды текущей попытки и время, когда брокер подтвердил его
последнее сообщение.
Перевод вложения в queued и запись задания SHALL быть одной
транзакцией: это устойчивое намерение обработать файл (job-outbox).
Идентификатор задания MUST NOT меняться при повторах, повторной доставке и
replay.
Scenario: Что сохранено к ответу 202
- WHEN worker и relay остановлены, и участник получил ответ 202
- THEN объект оригинала есть в staging, а в конечном префиксе его
нет, в PostgreSQL вложение
queuedи одно задание с нулём начатых попыток без времени подтверждения брокером, а в очереди сообщения нет - AND после запуска relay в очереди одно сообщение, а у задания есть время подтверждения
Scenario: Повторы под одним заданием
- WHEN обработка вложения прошла две попытки и закончилась
ready - THEN задание у вложения одно, с тем же идентификатором, что после первой попытки, а число начатых попыток — 2
Requirement: Сообщение брокера
Сообщение SHALL соответствовать contracts/jobs.schema.json:
schema_version, job_id, type, attachment_id, pipeline_version,
attempt, created_at. Сообщение MUST NOT содержать байты файла, имя
файла, ключи и адреса объектов, URL и учётные данные. Ключи объектов,
размер, SHA-256 и тип worker SHALL брать только из PostgreSQL.
attempt начинается с 1 и растёт с каждой управляемой повторной
попыткой. Повторная доставка брокером нового job_id не создаёт.
Сообщение не по схеме worker MUST NOT обрабатывать: он SHALL отбросить
его с записью уровня error без содержимого сообщения. Сообщение с
неизвестным заданием worker SHALL подтверждать без эффекта.
Scenario: Сообщение по схеме
- WHEN worker остановлен, участник загрузил файл с уникальным
filename, и сообщение прочитано из очереди без подтверждения - THEN тело проходит проверку по
contracts/jobs.schema.json,attachment_id— это вложение,attempt— 1, аfilename, ключей объектов, адресов и учётных данных в сообщении нет
Scenario: Сообщение не по схеме
- WHEN в очередь попало сообщение, которое не проходит схему, а затем участник загружает файл
- THEN чужое сообщение из очереди ушло, в журнале worker есть запись
error, а вложение становитсяready
Scenario: Неизвестное задание
- WHEN в очередь попало сообщение по схеме с
job_id, которого нет в PostgreSQL - THEN сообщение подтверждено, новых вложений и объектов не появилось
Requirement: Доставка at least once
Сообщение брокера SHALL быть подсказкой: истина о задании — в PostgreSQL. Worker SHALL подтверждать сообщение (ack) только после того, как устойчиво записано, что делать с заданием дальше:
- зафиксировано
readyилиfailed; - задание возвращено в
queuedсо временем следующей попытки, и следующее сообщение опубликует relay (job-outbox); - задание уже завершено, или его ведёт попытка с живой арендой, или его срок ещё не наступил: сообщение лишнее, и записывать нечего.
Если worker потерян до подтверждения, брокер SHALL доставить сообщение снова, и задание SHALL быть доведено до конца: сразу, если аренда уже истекла, иначе — когда её вернёт relay (требование «Аренда попытки»).
Повторная доставка завершённого задания SHALL быть no-op с подтверждением после проверки зафиксированного эффекта.
Дубль сообщения, пока идёт попытка с живой арендой, MUST NOT начинать новую попытку и тратить её номер.
Scenario: Worker убит посреди обработки
- WHEN worker завершён сигналом KILL, пока задание в
processing, и затем снова запущен - THEN вложение становится
readyсо всеми вариантами не позже срока аренды с запасом, число начатых попыток — 2, сообщений в очереди не осталось
Scenario: Повторная доставка готового
- WHEN в очередь для готового вложения снова попало сообщение его задания
- THEN сообщение подтверждено, а метаданные, число вариантов и объекты вариантов не изменились
Scenario: Дубль во время обработки
- WHEN пока попытка задания идёт, в очередь дважды попадает сообщение этого задания, и попытка длится дольше времени их доставки
- THEN сообщения подтверждены без новой попытки, вложение становится
readyс одним набором вариантов, число начатых попыток — 1, сообщений в очереди не осталось
Scenario: Crash после записи объектов до фиксации
- WHEN worker записал оригинал и все варианты, фиксация
readyзадержана, worker завершён сигналом KILL и снова запущен - THEN вложение становится
ready, число начатых попыток — 2, у каждого варианта один объект, а его SHA-256 равен SHA-256 объекта, записанного до сбоя
Scenario: Crash после фиксации до подтверждения
- WHEN фиксация
readyдошла до COMMIT, worker заморожен до ответа PostgreSQL, фиксация завершена, worker завершён сигналом KILL без подтверждения сообщения и снова запущен - THEN брокер доставляет сообщение снова, worker подтверждает его без эффекта, метаданные
совпадают с зафиксированными во всех полях, включая
updated_at, число начатых попыток — 1, а сообщений в очереди не осталось
Requirement: Публикация оригинала
Worker SHALL прочитать оригинал из staging по ключу из PostgreSQL, сверить
его размер и SHA-256 с метаданными вложения и записать те же байты в
конечный префикс. Оригинал SHALL оставаться неизменным: скачанные после
ready байты равны загруженным. Объект staging MUST NOT удаляться до
фиксации ready; worker его не удаляет: это делает уборщик
(storage-consistency, «Очистка staging»).
Объект staging другого размера или с другим SHA-256 и его отсутствие —
постоянная ошибка processing_failed. Причина SHALL быть в записи для
оператора.
Scenario: Оригинал неизменен
- WHEN загруженный PNG стал
ready - THEN скачанный оригинал побайтно равен загруженному, а его SHA-256
равен
sha256метаданных, объект есть в конечном префиксе, а объекта в staging нет не позже следующего прохода уборщика с запасом
Scenario: Испорченный staging
- WHEN worker остановлен, участник загрузил файл, объект staging заменён другими байтами, и worker запущен
- THEN вложение
failedсerror_codeprocessing_failed, число начатых попыток — 1, а объекта в конечном префиксе нет
Scenario: Нет объекта staging
- WHEN worker остановлен, участник загрузил файл, объект staging удалён, и worker запущен
- THEN вложение
failedсerror_codeprocessing_failed, число начатых попыток — 1
Requirement: Thumbnail
Thumbnail SHALL быть изображением JPEG, вписанным в 256 × 256 с сохранением пропорций:
- большая сторона становится 256, меньшая вычисляется от неё и округляется вниз, но не меньше 1 px;
- изображение, которое и так вписано в 256 × 256, MUST NOT увеличиваться;
- EXIF orientation SHALL применяться: размеры и содержимое thumbnail — как у показанного с учётом ориентации;
- alpha SHALL компоноваться на белый, в том числе прозрачность палитры.
Метаданные варианта SHALL содержать name thumbnail, content_type
image/jpeg, size_bytes, sha256, width и height записанного
объекта. Формат декодируется только как PNG или JPEG. Ограничения памяти и
времени — требование «Лимиты обработки».
Scenario: Fixture 320 × 200
- WHEN
tests/fixtures/sample.pngсталready, и участник скачиваетvariant=thumbnail - THEN ответ 200
image/jpeg, настоящие размеры JPEG 256 × 160, аwidth,height,size_bytesиsha256варианта совпадают со скачанным объектом
Scenario: Маленькое изображение не увеличивается
- WHEN участник загружает PNG 100 × 50 и PNG 256 × 256
- THEN размеры thumbnail — 100 × 50 и 256 × 256
Scenario: Округление вниз и минимум
- WHEN участник загружает изображения 1000 × 601, 601 × 1000, 5000 × 10 и 10 × 5000
- THEN размеры thumbnail — 256 × 153, 153 × 256, 256 × 1 и 1 × 256
Scenario: EXIF orientation
- WHEN участник загружает JPEG 400 × 200 с левой половиной красной и правой синей и EXIF orientation 6
- THEN thumbnail 128 × 256, его верхняя половина красная, а нижняя синяя
Scenario: Alpha на белый
- WHEN участник загружает PNG с прозрачной половиной и PNG с палитрой и прозрачностью
- THEN на месте прозрачных пикселей thumbnail белый
Scenario: Разновидности форматов
- WHEN участник загружает PNG с палитрой, с альфа-каналом, серый с альфа-каналом, серый 16 бит, RGB 16 бит, 1 бит, чересстрочный и JPEG прогрессивный, серый, CMYK, с EXIF и без таблиц Хаффмана
- THEN каждое вложение становится
ready, его thumbnail и crop — настоящие JPEG, а optimized — настоящий WebP
Scenario: Изображение в лимите пикселей
- WHEN участник загружает столько PNG с альфа-каналом 8000 × 5000, сколько заданий worker обрабатывает одновременно
- THEN каждое вложение становится
ready, thumbnail 256 × 160, crop 128 × 128, optimized 1280 × 800, а контейнер worker не завершён из-за памяти - WHEN участник загружает по одному PNG 8000 × 5000 других типов: серый с альфа-каналом, RGB 8 и 16 бит с tRNS, палитра с tRNS, серый 16 бит
- THEN каждое вложение становится
readyс теми же размерами вариантов, а неfailed: контракт разрешает 40 млн пикселей в любом типе
Requirement: Идемпотентный эффект
Ключ эффекта SHALL быть (attachment_id, pipeline_version, variant). Из
него однозначно следует ключ объекта варианта, а метаданные варианта
уникальны по нему в PostgreSQL. Повтор задания MUST NOT создавать второй
набор вариантов: он пишет те же ключи объектов теми же байтами при той же версии
декодера. Метаданные всех вариантов и состояние ready SHALL фиксироваться одной
транзакцией: вложение ready без метаданных любого варианта уровня MUST NOT
появляться.
Scenario: Повтор после записи объектов
- WHEN объекты вложения записаны, а фиксация
readyне удалась, и worker выполняет следующую попытку - THEN вложение
ready, у него по одному вариантуthumbnail,cropиoptimized, а объект каждого варианта в bucket один, и его SHA-256 равенsha256варианта
Requirement: Ограниченные повторы
Временная ошибка — недоступность или отказ S3, истёкший срок попытки или процесса
обработки, процесс обработки убит или упал, другая непредвиденная ошибка — SHALL вести к
новой попытке, пока число попыток с последнего replay не достигло [worker] max_attempts
(service-configuration, «Параметры worker»). Между попытками вложение SHALL быть в
queued.
Пауза перед попыткой N + 1 SHALL быть экспоненциальной со случайной добавкой: это случайная
величина из [d / 2, d], где d = min([worker] retry_max_delay_seconds, [worker] retry_base_delay_seconds × 2^(N − 1)). Она записывается временем следующей попытки. На время
паузы задание MUST NOT занимать место конкуренции worker: сообщение прежней попытки
подтверждено, а новое сообщение с тем же job_id и attempt на единицу больше публикует relay,
когда срок наступил (job-outbox). Сообщение, пришедшее раньше срока, worker подтверждает без
новой попытки.
Каждая начатая попытка считается, в том числе та, в которой worker был
потерян. Когда попытки исчерпаны, вложение SHALL стать failed с
error_code retry_exhausted. Бесконечный немой повтор MUST NOT
происходить. Пока недоступен PostgreSQL, исход записать нельзя: сообщение
возвращается в очередь после паузы, новые попытки не начинаются, а журнал worker называет
отказ.
Ограничение называется в REPORT.md. Отказ S3 дольше суммы пауз и сроков переводит взятые
задания в failed; после возврата S3 их возвращает replay (требование «Реестр failed и
replay»).
Scenario: Временная ошибка
- WHEN S3 остановлен, worker взял задание, и S3 возвращается раньше, чем исчерпаны попытки
- THEN вложение становится
ready, число начатых попыток больше 1, а у задания тот же идентификатор
Scenario: Состояние между попытками
- WHEN попытка задания закончилась временной ошибкой, и попытки остались
- THEN до следующей попытки метаданные —
queuedсerror_codenull, а в записи задания есть причина и время следующей попытки
Scenario: Попытки исчерпаны
- WHEN S3 остановлен дольше, чем длятся все попытки задания
- THEN вложение становится
failedсerror_coderetry_exhausted, число начатых попыток равноmax_attempts, сообщений в очереди не осталось, а после возврата S3 состояние прежнее
Scenario: PostgreSQL недоступен при обработке
- WHEN PostgreSQL останавливается, пока в очереди есть задание, а затем снова запускается
- THEN worker без перезапуска доводит задание до
ready, сообщений в очереди не осталось
Scenario: Пауза растёт со случайной добавкой
- WHEN S3 остановлен, и два задания проходят все попытки
- THEN пауза каждой попытки лежит в границах формулы, у следующей попытки верхняя граница вдвое больше, а паузы двух заданий на одной попытке различаются
Scenario: Попытка не раньше срока
- WHEN задание ждёт следующую попытку, в очередь попало его сообщение, а worker перезапущен
- THEN сообщение подтверждено без новой попытки, число начатых попыток прежнее, а следующая попытка начинается не раньше записанного времени
Scenario: Пауза не занимает место конкуренции
- WHEN задание ждёт следующую попытку, S3 доступен, и участник загружает другой файл
- THEN другое вложение становится
readyраньше срока следующей попытки первого, а первое в это времяqueued
Requirement: Постоянные ошибки и коды
Ошибка, которую повтор не исправит, SHALL сразу вести к failed, без
новых попыток. Коды error_code:
invalid_image— изображение прошло проверку при загрузке, но не декодируется или не укладывается в лимиты обработки (требование «Лимиты обработки»);processing_failed— объект staging отсутствует или испорчен;retry_exhausted— попытки исчерпаны.
error_code MUST NOT содержать stack trace, пути, ключи и адреса. Причину
SHALL называть запись задания и журнал worker, доступные оператору. Причины
постоянных ошибок: не декодируется, больше лимита пикселей, памяти или CPU, объект
staging отсутствует или испорчен. Причины временных: S3 недоступен, истёк срок попытки
или процесса обработки, процесс обработки убит или упал, истёк срок аренды, непредвиденная
ошибка.
Scenario: Изображение не декодируется
- WHEN участник загружает JPEG с 12 битами на компоненту, который проходит проверку структуры, но не декодируется
- THEN ответ 202, затем вложение
failedсerror_codeinvalid_image, число начатых попыток — 1, вариантов нет, а скачивание — 409conflict
Requirement: Worker — отдельный процесс
Обработку SHALL выполнять worker — отдельный процесс стенда (container-run).
Реплики API MUST NOT декодировать изображения и создавать варианты ни при
каких обстоятельствах, в том числе когда worker недоступен. Worker SHALL
обрабатывать одновременно не больше [worker] concurrency заданий, а брокер
выдаёт ему не больше [worker] prefetch неподтверждённых сообщений.
Scenario: Worker недоступен
- WHEN worker остановлен, и участник загружает файл, отправляет текст и читает историю
- THEN загрузка — 202, вложение
queued, вариантов нет, отправка — 201, история — 200,/health/ready— 200
Scenario: Ограниченная конкуренция
- WHEN в очереди заданий больше, чем
[worker] concurrency, и фиксация результатов задержана - THEN неподтверждённых сообщений и вложений в
processingне большеconcurrency, а остальные задания —queued, и все они затем становятсяready
Requirement: Принятая работа переживает рестарты
Работа, на которую ответили 202, MUST NOT теряться при остановке API, worker и брокера с сохранённым volume. Клиент узнаёт итог опросом метаданных.
Scenario: Реплика API убита после ответа
- WHEN участник получил 202, и реплика API сразу завершена сигналом KILL
- THEN вложение становится
ready, а метаданные и thumbnail читаются после возврата реплики
Scenario: Рестарт брокера с volume
- WHEN worker остановлен, участник получил 202, брокер перезапущен с сохранённым volume, а затем worker запущен
- THEN вложение становится
ready
Scenario: Принудительное завершение брокера
- WHEN worker остановлен, участник получил 202 на несколько загрузок, брокер сразу завершён сигналом KILL и запущен снова, а затем worker запущен
- THEN каждое вложение становится
ready
Scenario: Сценарий защиты
- WHEN worker остановлен, участник загрузил файл (202), отправил сообщение с этим вложением (201), скачивание дало 409, текстовое сообщение — 201, затем перезапущены API и брокер с сохранёнными volumes и запущен worker
- THEN то же вложение становится
ready, его оригинал равен загруженному, а thumbnail — настоящий JPEG, и сообщение отдаётattachment_idsс ним
Requirement: Вариант crop
Crop SHALL быть изображением JPEG 128 × 128: центрированный квадрат по короткой стороне
показанного изображения, сжатый или растянутый до 128 × 128. Маленькое изображение
увеличивается. EXIF orientation SHALL применяться, alpha — компоноваться на белый.
Параметры кодирования (quality, отсутствие EXIF и ICC) SHALL быть описаны в REPORT.md.
Метаданные варианта SHALL содержать name crop, content_type image/jpeg,
size_bytes, sha256, width и height записанного объекта.
Scenario: Crop большого изображения
- WHEN участник загружает PNG 400 × 200: полосы шириной 100, 200 и 100 красного, синего и зелёного
- THEN вариант
crop— настоящий JPEG 128 × 128, синий в центре и по краям, а поля варианта совпадают со скачанным объектом
Scenario: Crop маленького изображения
- WHEN участник загружает PNG 50 × 20
- THEN вариант
crop— настоящий JPEG 128 × 128
Scenario: Crop с ориентацией и прозрачностью
- WHEN участник загружает JPEG 400 × 200 с левой половиной красной и правой синей и EXIF orientation 6 и PNG с прозрачной половиной
- THEN у первого crop верхняя половина красная, а нижняя синяя, а у второго на месте прозрачных пикселей белый
Requirement: Вариант optimized
Optimized SHALL быть изображением WebP, вписанным в 1280 × 1280 с сохранением пропорций:
большая сторона становится 1280, меньшая округляется вниз, но не меньше 1 px; изображение,
которое и так вписано, MUST NOT увеличиваться. EXIF orientation SHALL применяться, потому что
EXIF, XMP и ICC в результат MUST NOT попадать. Прозрачность SHALL сохраняться. Уменьшение
каждого маленького файла MUST NOT обещаться. Параметры кодирования SHALL быть описаны в
REPORT.md.
Метаданные варианта SHALL содержать name optimized, content_type image/webp,
size_bytes, sha256, width и height записанного объекта.
Scenario: Optimized большого изображения
- WHEN участник загружает изображения 2000 × 1000, 5000 × 3001 и 5000 × 10
- THEN варианты
optimized— настоящие WebP 1280 × 640, 1280 × 768 и 1280 × 2, а поля варианта совпадают со скачанным объектом
Scenario: Optimized маленького изображения
- WHEN участник загружает PNG 100 × 50
- THEN вариант
optimized— настоящий WebP 100 × 50
Scenario: Optimized без метаданных
- WHEN участник загружает JPEG 400 × 200 с EXIF orientation 6, строкой производителя в EXIF и профилем ICC
- THEN вариант
optimized— WebP 200 × 400 с верхней половиной цвета левой половины исходника, а чанков EXIF, XMP и ICC и строки производителя в его байтах нет
Scenario: Optimized сохраняет прозрачность
- WHEN участник загружает PNG с прозрачной половиной
- THEN на месте прозрачных пикселей у варианта
optimizedальфа-канал равен нулю
Requirement: Лимиты обработки
Декодирование и преобразование изображения SHALL выполняться в отдельном процессе на задание, а не в процессе worker. У этого процесса в окружении MUST NOT быть секретов приложения. Лимиты:
- байты: объект staging другого размера, чем в метаданных, MUST NOT читаться: это постоянная
ошибка
processing_failed. Размер в метаданных ограничен контрактом; - пиксели: изображение больше лимита контракта MUST NOT декодироваться, постоянная ошибка
invalid_image; - память: адресное пространство процесса ограничено
[worker] render_memory_limit_mib, превышение — постоянная ошибкаinvalid_image; - CPU: время процессора ограничено
[worker] render_cpu_limit_seconds, превышение — постоянная ошибкаinvalid_image; - время: процесс, не закончивший за
[worker] render_timeout_seconds, SHALL быть убит, это временная ошибка.
Процесс, убитый ядром или упавший, — временная ошибка. Сам worker SHALL продолжать работу в
каждом из этих случаев, без перезапуска контейнера. Пик памяти процессов обработки на изображении
в лимите контракта при настроенной конкуренции вместе с памятью самого worker SHALL укладываться в
лимит контейнера; расчёт SHALL быть в REPORT.md.
Ограничение называется в REPORT.md. Лимит адресного пространства не действует там, где его не
поддерживает ядро (worker на хосте macOS).
Scenario: Пикселей больше лимита
- WHEN worker остановлен, объект staging заменён PNG с заголовком на 50 млн пикселей, размер и SHA-256 в метаданных приведены в соответствие с ним, и worker запущен
- THEN вложение
failedсerror_codeinvalid_image, причина — лимит пикселей, число начатых попыток — 1
Scenario: Объект больше лимита не читается
- WHEN worker остановлен, объект staging заменён объектом больше 10 MiB, и worker запущен
- THEN вложение
failedсerror_codeprocessing_failed, причина — испорченный объект, число начатых попыток — 1
Scenario: Дорогое изображение
- WHEN участник загружает JPEG в пределах лимитов контракта, декодирование которого занимает больше лимита CPU: прогрессивный, с сотнями тысяч повторённых сканов
- THEN ответ 202, вложение
failedсerror_codeinvalid_image, причина — лимит CPU, число начатых попыток — 1, у контейнера worker счётчик перезапусков 0, а следующий файл становитсяready
Scenario: Предел памяти процесса обработки
- WHEN worker запущен с пределом памяти 200 МиБ, и участник загружает PNG с альфа-каналом 8000 × 5000
- THEN вложение
failedсerror_codeinvalid_image, причина — лимит памяти, число начатых попыток — 1, а процесс worker работает
Scenario: Срок процесса обработки
- WHEN worker запущен со сроком процесса обработки короче времени декодирования, и участник загружает файл
- THEN каждая попытка заканчивается временной ошибкой, вложение
failedсerror_coderetry_exhausted, причина — срок, а процессов обработки после этого не осталось
Scenario: Процесс обработки убит
- WHEN во время попытки процесс обработки завершён сигналом KILL
- THEN worker продолжает работу, у контейнера счётчик перезапусков 0, а задание получает новую попытку с причиной «процесс обработки убит»
Scenario: Секретов нет у процесса обработки
- WHEN идёт декодирование, и проверяющий смотрит окружение процесса обработки
- THEN в нём нет переменных настроек PostgreSQL, S3 и брокера
Requirement: Аренда попытки
При взятии задания SHALL фиксироваться срок аренды: [worker] job_timeout_seconds + [worker] lease_margin_seconds. Живая попытка SHALL укладываться в этот срок: по job_timeout_seconds её шаги
прерываются, а процесс обработки убивается. Поэтому истёкшая аренда значит, что worker потерян или завис,
а долго работающий, но живой worker свою аренду не теряет.
Relay SHALL возвращать задание с истёкшей арендой в queued с причиной «истёк срок аренды», без паузы, а
worker SHALL брать такое задание и сам, если сообщение пришло раньше. Пока аренда жива, новая попытка MUST
NOT начинаться: сообщение подтверждается без эффекта.
Номер попытки SHALL защищать итог: ready, failed и возврат в очередь фиксирует только та попытка, номер
которой равен текущему у задания в processing. Прежняя попытка, которая пережила срок аренды, MUST NOT
менять итог, в том числе после разморозки процесса.
Попытка, потерянная при исчерпанном бюджете, SHALL вести к failed с retry_exhausted при следующем взятии.
Scenario: Зависший worker
- WHEN worker заморожен посреди попытки, срок аренды истёк, второй worker довёл задание до
ready, и первый разморожен - THEN число начатых попыток — 2, причина возврата записана в журнал relay, а метаданные после разморозки совпадают с зафиксированными вторым worker во всех полях
Scenario: Прежняя попытка при живой новой
- WHEN worker заморожен посреди попытки, срок аренды истёк, второй worker взял задание, ещё не зафиксировал результат и не держит блокировку строки, и первый разморожен
- THEN первая попытка завершается без записи, задание остаётся в
processingс номером второй попытки, а вложение неready; итог даёт только вторая: вложениеready, число начатых попыток — 2
Scenario: Долгая живая попытка
- WHEN фиксация результата задержана дольше всех пауз, но попытка укладывается в срок
- THEN вложение становится
ready, а число начатых попыток — 1
Scenario: Последняя попытка потеряна
- WHEN worker с
max_attempts1 завершён сигналом KILL посреди попытки, снова запущен, и срок аренды истёк - THEN вложение
failedсerror_coderetry_exhausted, а число начатых попыток — 1
Requirement: Реестр failed и replay
Реестр неудач SHALL быть записями заданий failed в PostgreSQL: идентификатор задания и вложения, код, причина,
число попыток, время. Операторская команда SHALL показывать реестр и возвращать из него работу: по умолчанию
ничего не меняет и называет, что сделала бы; с --apply выполняет. Выбор — по id вложения, по коду или причине,
не больше заданного числа заданий. С --apply выбор обязателен. Публичному API replay MUST NOT быть доступен.
Replay задания SHALL одной транзакцией:
- вернуть вложение из
failedвqueuedсerror_codenull, а задание — вqueuedбез причины и времени окончания; - начать новый бюджет: следующие
max_attemptsпопыток считаются заново, а сам номер попытки продолжает расти; - записать аудит: кто, когда, прежние код и причина, число попыток.
Идентификатор задания SHALL оставаться прежним, сообщение публикует relay, а ключи объектов и варианты защищены ключом эффекта. Команда SHALL отказывать и ничего не менять, если задание:
- завершено успешно: «повторить» не значит исполнить дубль готовой работы;
- ещё идёт или ждёт в очереди;
- потеряло исходник: объект staging убран по сроку хранения;
- не найдено.
Код выхода: 0 — всё выбранное выполнено или показано, 3 — есть отказы, 1 — отказ PostgreSQL, 2 — неверные аргументы или конфигурация.
Scenario: Реестр показан без изменений
- WHEN есть вложение
failed, и выполняется команда без--apply - THEN журнал называет его задание, код и причину, код выхода 0, а вложение и задание не изменились
Scenario: Replay возвращает работу
- WHEN объект staging был заменён, вложение стало
failedсprocessing_failed, объект возвращён, и выполняется команда с--apply - THEN вложение становится
ready, задание то же, число начатых попыток — 2, в журнале аудита одна запись с прежним кодом, а оригинал скачивается с тем же SHA-256
Scenario: Replay готового не создаёт дубль
- WHEN выполняется команда с
--applyдля готового вложения - THEN код выхода 3, отказ называет причину, метаданные совпадают с прежними во всех полях, включая
updated_at, число начатых попыток и объекты вариантов не изменились, а записи аудита нет
Scenario: Replay идущей работы
- WHEN выполняется команда с
--applyдля вложения вqueuedи для вложения вprocessing - THEN код выхода 3, отказ называет причину, а новых сообщений и попыток нет
Scenario: Replay без исходника
- WHEN срок хранения staging вложения
failedистёк, объект убран, и выполняется команда с--apply - THEN код выхода 3, отказ называет причину, вложение остаётся
failedс прежним кодом
Scenario: Новый бюджет попыток
- WHEN вложение стало
failedсretry_exhausted, S3 возвращён, и выполняется команда с--apply - THEN вложение становится
ready, а число начатых попыток большеmax_attempts
Scenario: Replay по причине
- WHEN несколько вложений стали
failedсretry_exhausted, другое — сinvalid_image, и выполняется команда с выбором по кодуretry_exhaustedи--apply - THEN первые становятся
ready, а второе остаётсяfailed
Requirement: Ограниченный prefetch
Брокер SHALL выдавать worker не больше [worker] prefetch неподтверждённых сообщений. Сообщение, для которого нет места
конкуренции, SHALL ждать в процессе worker без взятия: попытка и её аренда начинаются, когда место есть. Значения
конкуренции и prefetch SHALL быть в записи о старте worker, а время ожидания в очереди, длительность обработки и пик памяти
процесса обработки — в записях задания (service-logging, «Журнал worker»), чтобы их можно было мерить.
Scenario: Prefetch больше конкуренции
- WHEN worker запущен с конкуренцией 1 и prefetch 3, в очереди 5 заданий, и фиксация результатов задержана
- THEN неподтверждённых сообщений не больше 3, вложений в
processingне больше 1, а все вложения затем становятсяready