Files
mtusi2026lab5/openspec/specs/attachment-processing/spec.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

397 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` → `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` с ним