397 lines
25 KiB
Markdown
397 lines
25 KiB
Markdown
# 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` с ним
|