Close the source image after converting to RGBA so PNGs at the pixel limit fit the render memory limit. Strengthen the fencing test so that it fails without the attempt check, and measure worker and relay stops under load. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
699 lines
49 KiB
Markdown
699 lines
49 KiB
Markdown
# 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`
|