Files
mtusi2026lab5/openspec/changes/async-attachments/specs/attachment-processing/spec.md
T
2026-10-31 04:06:09 +03:00

25 KiB
Raw Blame History

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 с ним