# 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 со `status` `queued`, а метаданные через несколько секунд — 200 со `status` `queued`, `variants` `[]`, `error_code` null #### Scenario: Вложение становится готовым - **WHEN** worker работает, участник загружает `tests/fixtures/sample.png` и опрашивает метаданные - **THEN** не позже чем через 60 с `status` `ready`, `error_code` null, а в `variants` ровно по одному элементу `thumbnail`, `crop` и `optimized` #### Scenario: Обработка видна в API - **WHEN** worker взял задание, а фиксация его результата задержана - **THEN** метаданные — 200 со `status` `processing`, скачивание — 409 `conflict`, а после фиксации метаданные — `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_code` `processing_failed`, число начатых попыток — 1, а объекта в конечном префиксе нет #### Scenario: Нет объекта staging - **WHEN** worker остановлен, участник загрузил файл, объект staging удалён, и worker запущен - **THEN** вложение `failed` с `error_code` `processing_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_code` null, а в записи задания есть причина и время следующей попытки #### Scenario: Попытки исчерпаны - **WHEN** S3 остановлен дольше, чем длятся все попытки задания - **THEN** вложение становится `failed` с `error_code` `retry_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_code` `invalid_image`, число начатых попыток — 1, вариантов нет, а скачивание — 409 `conflict` ### 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_code` `invalid_image`, причина — лимит пикселей, число начатых попыток — 1 #### Scenario: Объект больше лимита не читается - **WHEN** worker остановлен, объект staging заменён объектом больше 10 MiB, и worker запущен - **THEN** вложение `failed` с `error_code` `processing_failed`, причина — испорченный объект, число начатых попыток — 1 #### Scenario: Дорогое изображение - **WHEN** участник загружает JPEG в пределах лимитов контракта, декодирование которого занимает больше лимита CPU: прогрессивный, с сотнями тысяч повторённых сканов - **THEN** ответ 202, вложение `failed` с `error_code` `invalid_image`, причина — лимит CPU, число начатых попыток — 1, у контейнера worker счётчик перезапусков 0, а следующий файл становится `ready` #### Scenario: Предел памяти процесса обработки - **WHEN** worker запущен с пределом памяти 200 МиБ, и участник загружает PNG с альфа-каналом 8000 × 5000 - **THEN** вложение `failed` с `error_code` `invalid_image`, причина — лимит памяти, число начатых попыток — 1, а процесс worker работает #### Scenario: Срок процесса обработки - **WHEN** worker запущен со сроком процесса обработки короче времени декодирования, и участник загружает файл - **THEN** каждая попытка заканчивается временной ошибкой, вложение `failed` с `error_code` `retry_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_attempts` 1 завершён сигналом KILL посреди попытки, снова запущен, и срок аренды истёк - **THEN** вложение `failed` с `error_code` `retry_exhausted`, а число начатых попыток — 1 ### Requirement: Реестр failed и replay Реестр неудач SHALL быть записями заданий `failed` в PostgreSQL: идентификатор задания и вложения, код, причина, число попыток, время. Операторская команда SHALL показывать реестр и возвращать из него работу: по умолчанию ничего не меняет и называет, что сделала бы; с `--apply` выполняет. Выбор — по `id` вложения, по коду или причине, не больше заданного числа заданий. С `--apply` выбор обязателен. Публичному API replay MUST NOT быть доступен. Replay задания SHALL одной транзакцией: - вернуть вложение из `failed` в `queued` с `error_code` null, а задание — в `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`