25 KiB
Spec Delta
Purpose
Фоновая обработка принятого вложения с лабы 5. Здесь описано:
- состояния вложения и переходы между ними;
- задание в PostgreSQL и сообщение брокера;
- доставка at least once и подтверждение после устойчивого эффекта;
- публикация оригинала и thumbnail;
- идемпотентный эффект, ограниченные повторы и коды ошибок;
- worker как отдельный процесс и сохранность принятой работы.
ADDED Requirements
Requirement: Состояния вложения
Вложение, принятое ответом 202, SHALL находиться в одном из состояний
API: queued, processing, ready, failed. Переходы:
queued→processing— worker взял задание; зафиксированы номер попытки и её срок;processing→queued— временная ошибка, попытки остались; зафиксированы причина без секретов и время следующей попытки;processing→ready— оригинал и thumbnail записаны, а метаданные вариантов и состояние зафиксированы одной транзакцией;processing→failed— ошибка постоянная или попытки исчерпаны; зафиксированы код ошибки и запись для оператора.
Готовое вложение MUST NOT возвращаться в другое состояние, в том числе
из-за повторной доставки. Отправка в queued из failed (replay) на
этом уровне не входит: failed окончательно. error_code SHALL быть
null во всех состояниях, кроме failed, variants — пустым во всех,
кроме ready.
Scenario: Принятое вложение в очереди
- WHEN worker остановлен, и участник загружает настоящий PNG
- THEN ответ 202 со
statusqueued, а метаданные через несколько секунд — 200 соstatusqueued,variants[],error_codenull
Scenario: Вложение становится готовым
- WHEN worker работает, участник загружает
tests/fixtures/sample.pngи опрашивает метаданные - THEN не позже чем через 60 с
statusready,error_codenull, а вvariantsровно один элементthumbnail
Scenario: Обработка видна в API
- WHEN worker взял задание, а фиксация его результата задержана
- THEN метаданные — 200 со
statusprocessing, скачивание — 409conflict, а после фиксации метаданные —ready, скачивание — 200
Scenario: Готовое вложение не откатывается
- WHEN задание готового вложения доставлено ещё раз
- THEN метаданные совпадают с прежними во всех полях, включая
updated_at
Requirement: Задание в PostgreSQL
Вложению SHALL соответствовать одно логическое задание на
pipeline_version; в курсе pipeline_version равен 1. У задания есть
идентификатор, вложение, версия, состояние, число начатых попыток,
причина последней ошибки, время следующей попытки, срок текущей попытки
и время, когда брокер подтвердил его последнее сообщение.
Перевод вложения в queued и запись задания SHALL быть одной
транзакцией: это устойчивое намерение обработать файл. Идентификатор
задания MUST NOT меняться при повторах и повторной доставке.
Scenario: Что сохранено к ответу 202
- WHEN worker остановлен, и участник получил ответ 202
- THEN объект оригинала есть в staging, а в конечном префиксе его
нет, в PostgreSQL вложение
queuedи одно задание с нулём начатых попыток и временем подтверждения брокером, а в очереди одно сообщение
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
Worker SHALL подтверждать сообщение (ack) только после устойчивого
эффекта: в PostgreSQL зафиксировано ready или failed, либо следующая
попытка уже передана брокеру и подтверждена им. Если worker потерян до
подтверждения, брокер SHALL доставить сообщение снова, и задание
доводится до конца, в том числе если его состояние осталось
processing.
Повторная доставка завершённого задания SHALL быть no-op с подтверждением после проверки зафиксированного эффекта.
Дубль сообщения, пока попытка другого worker идёт в свой срок, MUST NOT порождать второй набор вариантов.
Ограничение называется в REPORT.md. Зависший worker, у которого живо
соединение, на этом уровне освобождает задание только по сроку
подтверждения брокера; срок аренды и его восстановление —
pipeline-reliability.
Scenario: Worker убит посреди обработки
- WHEN worker завершён сигналом KILL, пока задание в
processing, и затем снова запущен - THEN вложение становится
readyс однимthumbnail, число начатых попыток — 2, сообщений в очереди не осталось
Scenario: Повторная доставка готового
- WHEN в очередь для готового вложения снова попало сообщение его задания
- THEN сообщение подтверждено, а метаданные, число вариантов и объекты вариантов не изменились
Scenario: Дубль во время обработки
- WHEN пока попытка задания идёт, в очередь попадает ещё одно сообщение этого задания
- THEN вложение становится
readyс однимthumbnail, сообщений в очереди не осталось
Requirement: Публикация оригинала
Worker SHALL прочитать оригинал из staging по ключу из PostgreSQL, сверить
его размер и SHA-256 с метаданными вложения и записать те же байты в
конечный префикс. Оригинал SHALL оставаться неизменным: скачанные после
ready байты равны загруженным. Объект staging MUST NOT удаляться до
фиксации ready.
Объект staging другого размера или с другим SHA-256 и его отсутствие —
постоянная ошибка processing_failed. Причина SHALL быть в записи для
оператора.
Ограничение называется в REPORT.md. На этом уровне объект staging после
ready остаётся, а у failed не имеет срока хранения; очистка —
pipeline-reliability.
Scenario: Оригинал неизменен
- WHEN загруженный PNG стал
ready - THEN скачанный оригинал побайтно равен загруженному, а его SHA-256
равен
sha256метаданных, и объект есть и в конечном префиксе, и в staging
Scenario: Испорченный staging
- WHEN worker остановлен, участник загрузил файл, объект staging заменён другими байтами, и worker запущен
- THEN вложение
failedсerror_codeprocessing_failed, число начатых попыток — 1, а объекта в конечном префиксе нет
Scenario: Нет объекта staging
- WHEN worker остановлен, участник загрузил файл, объект staging удалён, и worker запущен
- THEN вложение
failedсerror_codeprocessing_failed, число начатых попыток — 1
Requirement: Thumbnail
Thumbnail SHALL быть изображением JPEG, вписанным в 256 × 256 с сохранением пропорций:
- большая сторона становится 256, меньшая вычисляется от неё и округляется вниз, но не меньше 1 px;
- изображение, которое и так вписано в 256 × 256, MUST NOT увеличиваться;
- EXIF orientation SHALL применяться: размеры и содержимое thumbnail — как у показанного с учётом ориентации;
- alpha SHALL компоноваться на белый, в том числе прозрачность палитры.
Метаданные варианта SHALL содержать name thumbnail, content_type
image/jpeg, size_bytes, sha256, width и height записанного
объекта. Формат декодируется только как PNG или JPEG. Память декодирования
SHALL укладываться в лимит контейнера worker на изображении в лимит
контракта при настроенной конкуренции.
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 — настоящий JPEG
Scenario: Изображение в лимите пикселей
- WHEN участник загружает столько PNG с альфа-каналом 8000 × 5000, сколько заданий worker обрабатывает одновременно
- THEN каждое вложение становится
ready, thumbnail 256 × 160, а контейнер worker не завершён из-за памяти
Requirement: Идемпотентный эффект
Ключ эффекта SHALL быть (attachment_id, pipeline_version, variant). Из
него однозначно следует ключ объекта варианта, а метаданные варианта
уникальны по нему в PostgreSQL. Повтор задания MUST NOT создавать второй
набор вариантов: он пишет те же ключи объектов. Метаданные вариантов и
состояние ready SHALL фиксироваться одной транзакцией: вложение ready
без метаданных варианта MUST NOT появляться.
Scenario: Повтор после записи объектов
- WHEN объекты вложения записаны, а фиксация
readyне удалась, и worker выполняет следующую попытку - THEN вложение
ready, у него один вариантthumbnail, а объект варианта в bucket один, и его SHA-256 равенsha256варианта
Requirement: Ограниченные повторы
Временная ошибка — недоступность или отказ S3, истёкший срок попытки или
другая непредвиденная ошибка — SHALL вести к новой попытке, пока их число
не достигло [worker] max_attempts (service-configuration, «Параметры
worker»). Между попытками вложение SHALL быть в queued, новая попытка
начинается не раньше паузы [worker] retry_delay_seconds. Сообщение новой
попытки несёт тот же job_id и attempt на единицу больше.
Каждая начатая попытка считается, в том числе та, в которой worker был
потерян. Когда попытки исчерпаны, вложение SHALL стать failed с
error_code retry_exhausted. Бесконечный немой повтор MUST NOT
происходить. Пока недоступен PostgreSQL, исход записать нельзя: задание
остаётся в очереди, попытки не считаются, а журнал worker называет отказ.
Ограничение называется в REPORT.md. Пауза постоянна, поэтому отказ S3
дольше суммы пауз и сроков переводит взятые задания в failed; backoff с
jitter и replay — pipeline-reliability.
Scenario: Временная ошибка
- WHEN S3 остановлен, worker взял задание, и S3 возвращается раньше, чем исчерпаны попытки
- THEN вложение становится
ready, число начатых попыток больше 1, а у задания тот же идентификатор
Scenario: Состояние между попытками
- WHEN попытка задания закончилась временной ошибкой, и попытки остались
- THEN до следующей попытки метаданные —
queuedсerror_codenull, а в записи задания есть причина и время следующей попытки
Scenario: Попытки исчерпаны
- WHEN S3 остановлен дольше, чем длятся все попытки задания
- THEN вложение становится
failedсerror_coderetry_exhausted, число начатых попыток равноmax_attempts, сообщений в очереди не осталось, а после возврата S3 состояние прежнее
Scenario: PostgreSQL недоступен при обработке
- WHEN PostgreSQL останавливается, пока в очереди есть задание, а затем снова запускается
- THEN worker без перезапуска доводит задание до
ready, сообщений в очереди не осталось
Requirement: Постоянные ошибки и коды
Ошибка, которую повтор не исправит, SHALL сразу вести к failed, без
новых попыток. Коды error_code:
invalid_image— изображение прошло проверку при загрузке, но не декодируется;processing_failed— объект staging отсутствует или испорчен;retry_exhausted— попытки исчерпаны.
error_code MUST NOT содержать stack trace, пути, ключи и адреса. Причину
SHALL называть запись задания и журнал worker, доступные оператору.
Scenario: Изображение не декодируется
- WHEN участник загружает JPEG с 12 битами на компоненту, который проходит проверку структуры, но не декодируется
- THEN ответ 202, затем вложение
failedсerror_codeinvalid_image, число начатых попыток — 1, вариантов нет, а скачивание — 409conflict
Requirement: Worker — отдельный процесс
Обработку SHALL выполнять worker — отдельный процесс стенда (container-run).
Реплики API MUST NOT декодировать изображения и создавать варианты ни при
каких обстоятельствах, в том числе когда worker недоступен. Worker SHALL
обрабатывать одновременно не больше [worker] concurrency заданий, а брокер
выдаёт ему не больше стольких неподтверждённых сообщений.
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с ним