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>
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`
|