# 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 со `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` #### 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. У задания есть идентификатор, вложение, версия, состояние, число начатых попыток, причина последней ошибки, время следующей попытки, срок текущей попытки и время, когда брокер подтвердил его последнее сообщение. Перевод вложения в `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_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. Память декодирования 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_code` null, а в записи задания есть причина и время следующей попытки #### Scenario: Попытки исчерпаны - **WHEN** S3 остановлен дольше, чем длятся все попытки задания - **THEN** вложение становится `failed` с `error_code` `retry_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_code` `invalid_image`, число начатых попыток — 1, вариантов нет, а скачивание — 409 `conflict` ### 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` с ним