Archive the crop, optimized, worker limits and job recovery change
The change add-lab5-variants-and-recovery is archived as 2026-10-29-add-lab5-variants-and-recovery with archived and lab: 5 in .openspec.yaml. Specs are synced: lab5-image-variants and lab5-job-recovery are created, lab5-attachment-pipeline (four requirements) and lab4-attachments (metadata and download) are updated. Level 4 is closed by make level4 (evidence/level4.json) and the rows 4.1-4.4 of REPORT.md. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
573220e12a
commit
64d5c6746e
+2
@@ -1,2 +1,4 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-29
|
||||
archived: 2026-10-29
|
||||
lab: 5
|
||||
@@ -106,7 +106,7 @@
|
||||
|
||||
### Requirement: Метаданные и скачивание только участникам
|
||||
|
||||
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` с текущим состоянием любому участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с байтами, истинным `Content-Type` и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`: для `variant=original` (по умолчанию) — исходные байты оригинала, для `variant=thumbnail` — байты варианта, описанного в метаданных. Для вложения в `queued`, `processing` или `failed` `/content` SHALL отвечать `409` с кодом `conflict` для любого допустимого `variant`, включая `original`. Для `ready`-вложения без запрошенного варианта (`crop`, `optimized` на уровне «3») SHALL отвечать `404`. Посторонний и неизвестный id SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и `variant` вне `original|thumbnail|crop|optimized` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
|
||||
`GET /api/v1/attachments/{attachment_id}` SHALL возвращать `200 Attachment` с текущим состоянием любому участнику чата вложения. `GET /api/v1/attachments/{attachment_id}/content` SHALL возвращать участнику `200` с байтами, истинным `Content-Type` и `Content-Length`, через API, без redirect, вне зависимости от заголовка `Accept`: для `variant=original` (по умолчанию) — исходные байты оригинала, для `variant=thumbnail`, `crop` и `optimized` — байты варианта опубликованной версии, описанного в метаданных. Для вложения в `queued`, `processing` или `failed` `/content` SHALL отвечать `409` с кодом `conflict` для любого допустимого `variant`, включая `original`. Для `ready`-вложения, у опубликованной версии которого нет запрошенного варианта (вложение, готовое до лабы 5), SHALL отвечать `404`. Посторонний и неизвестный id SHALL получать `404` с кодом `not_found`, не раскрывающим существование вложения; невалидный UUID и `variant` вне `original|thumbnail|crop|optimized` — `400`. Все ответы, включая бинарный `200`, SHALL нести `X-Request-Id` и `X-Instance-Id`.
|
||||
|
||||
#### Scenario: Второй участник скачивает оригинал
|
||||
|
||||
@@ -118,6 +118,11 @@
|
||||
- **WHEN** второй участник чата запрашивает `/content?variant=thumbnail` готового вложения
|
||||
- **THEN** ответ `200`, `Content-Type: image/jpeg`, длина и SHA-256 равны метаданным варианта
|
||||
|
||||
#### Scenario: Crop и optimized
|
||||
|
||||
- **WHEN** второй участник запрашивает `/content?variant=crop` и `/content?variant=optimized` готового вложения
|
||||
- **THEN** ответы `200` с `Content-Type: image/jpeg` и `image/webp`, длина и SHA-256 равны метаданным вариантов
|
||||
|
||||
#### Scenario: Вложение ещё не готово
|
||||
|
||||
- **WHEN** участник запрашивает `/content` или `/content?variant=thumbnail` вложения в `queued` или `processing`
|
||||
@@ -135,7 +140,7 @@
|
||||
|
||||
#### Scenario: Варианта нет
|
||||
|
||||
- **WHEN** запрошен `/content?variant=crop` готового вложения уровня «3»
|
||||
- **WHEN** запрошен `/content?variant=crop` вложения, ставшего `ready` в лабе 4 без вариантов
|
||||
- **THEN** ответ `404` с кодом `not_found`
|
||||
|
||||
#### Scenario: Неизвестный вариант
|
||||
|
||||
@@ -19,12 +19,12 @@
|
||||
|
||||
### Requirement: Worker публикует оригинал и thumbnail
|
||||
|
||||
Worker SHALL обрабатывать задание отдельно от API: копировать проверенный оригинал из staging в конечный префикс без изменения байтов и строить один вариант `thumbnail` — JPEG, вписанный в 256×256 с сохранением пропорций, без увеличения маленьких исходников, после применения EXIF orientation, с альфа-каналом на белом фоне, с размерами, округлёнными вниз и не меньше 1 px. Метаданные варианта (`content_type`, `size_bytes`, `width`, `height`, `sha256`) SHALL совпадать с байтами, которые отдаёт `/content?variant=thumbnail`. Вложение SHALL становиться `ready` только после записи оригинала и thumbnail и фиксации их метаданных.
|
||||
Worker SHALL обрабатывать задание отдельно от API: копировать проверенный оригинал из staging в конечный префикс без изменения байтов и строить один вариант `thumbnail` — JPEG, вписанный в 256×256 с сохранением пропорций, без увеличения маленьких исходников, после применения EXIF orientation, с альфа-каналом на белом фоне, с размерами, округлёнными вниз и не меньше 1 px, — а также варианты `crop` и `optimized` уровня «4». Метаданные варианта (`content_type`, `size_bytes`, `width`, `height`, `sha256`) SHALL совпадать с байтами, которые отдаёт `/content?variant=<имя>`. Вложение SHALL становиться `ready` только после записи оригинала и всех трёх вариантов и фиксации их метаданных одной транзакцией; частичный набор вариантов SHALL NOT публиковаться.
|
||||
|
||||
#### Scenario: Fixture 320×200
|
||||
|
||||
- **WHEN** обработана `tests/fixtures/sample.png` (320×200)
|
||||
- **THEN** у вложения ровно один вариант `thumbnail` 256×160 `image/jpeg`, `/content?variant=thumbnail` отдаёт настоящий JPEG 256×160 длиной `size_bytes` с SHA-256 из метаданных, `/content` оригинала побайтно равен загруженному файлу
|
||||
- **THEN** у вложения ровно один вариант `thumbnail` 256×160 `image/jpeg` и по одному `crop` и `optimized`, `/content?variant=thumbnail` отдаёт настоящий JPEG 256×160 длиной `size_bytes` с SHA-256 из метаданных, `/content` оригинала побайтно равен загруженному файлу
|
||||
|
||||
#### Scenario: Маленький и вытянутый исходник
|
||||
|
||||
@@ -36,9 +36,14 @@ Worker SHALL обрабатывать задание отдельно от API:
|
||||
- **WHEN** обработаны PNG RGBA и JPEG с EXIF orientation 6 размером 400×200
|
||||
- **THEN** прозрачные области thumbnail белые, thumbnail JPEG 128×256
|
||||
|
||||
#### Scenario: Ready только с полным набором
|
||||
|
||||
- **WHEN** запись одного из вариантов в S3 завершается ошибкой
|
||||
- **THEN** вложение не становится `ready`, строк вариантов этой попытки нет
|
||||
|
||||
### Requirement: Ограниченные повторы и финальная ошибка
|
||||
|
||||
Временная ошибка обработки (недоступный S3 или PostgreSQL) SHALL возвращать задание и вложение в `queued` с отложенной следующей попыткой и тем же `job_id`, увеличивая `attempt` на 1. Число попыток SHALL ограничиваться `JOB_MAX_ATTEMPTS` (5); после последней неудачной попытки вложение SHALL становиться `failed` с `error_code` `retry_exhausted`. Изображение, которое не удаётся декодировать, SHALL сразу давать `failed` с `invalid_image` без повторов. До исчерпания попыток вложение SHALL NOT показывать `failed`.
|
||||
Временная ошибка обработки (недоступный S3 или PostgreSQL, падение процесса рендера) SHALL возвращать задание и вложение в `queued` с отложенной следующей попыткой и тем же `job_id`, увеличивая `attempt` на 1. Задержка перед попыткой `n + 1` SHALL выбираться случайно из `[d/2, d]`, где `d = min(JOB_BACKOFF_CAP_SECONDS, JOB_BACKOFF_BASE_SECONDS · 2^(n−1))`, и записываться в журнал задания. Число попыток SHALL ограничиваться `JOB_MAX_ATTEMPTS` (5); после последней неудачной попытки вложение SHALL становиться `failed` с `error_code` `retry_exhausted`. Постоянные ошибки SHALL давать `failed` сразу, без повторов: изображение не декодируется или больше предела пикселей — `invalid_image`; превышены пределы времени или памяти рендера, оригинала нет в хранилище или непредвиденная ошибка обработки — `processing_failed`. До исчерпания попыток вложение SHALL NOT показывать `failed`.
|
||||
|
||||
#### Scenario: S3 недоступен во время обработки
|
||||
|
||||
@@ -50,6 +55,11 @@ Worker SHALL обрабатывать задание отдельно от API:
|
||||
- **WHEN** каждая попытка завершается временной ошибкой
|
||||
- **THEN** вложение становится `failed` с `error_code` `retry_exhausted`, `attempt` задания равен `JOB_MAX_ATTEMPTS`, `/content` отвечает `409`
|
||||
|
||||
#### Scenario: Задержки с jitter
|
||||
|
||||
- **WHEN** четыре попытки подряд завершаются временной ошибкой
|
||||
- **THEN** задержка `n`-й повторной попытки лежит в `[d_n/2, d_n]`, задержки не совпадают с границами и между собой в одинаковой доле
|
||||
|
||||
#### Scenario: Постоянная ошибка
|
||||
|
||||
- **WHEN** worker не может декодировать изображение задания
|
||||
@@ -71,13 +81,23 @@ Worker SHALL обрабатывать задание отдельно от API:
|
||||
|
||||
### Requirement: Аренда захваченного задания
|
||||
|
||||
Захват задания SHALL выдавать аренду на `JOB_TIMEOUT_SECONDS`. Задание в `processing` с истёкшей арендой SHALL без участия оператора возвращаться в `queued` (или в `failed` с `retry_exhausted`, если попытки исчерпаны) не позже `SWEEP_INTERVAL_SECONDS` после истечения аренды.
|
||||
Захват задания SHALL выдавать аренду на `JOB_TIMEOUT_SECONDS`. Пока обработка идёт, держатель SHALL продлевать аренду не реже чем раз в `JOB_TIMEOUT_SECONDS / 3` и проверять её перед побочными эффектами; если продлить аренду не удалось, потому что её забрал другой держатель или задание уже вернули в очередь, обработка SHALL прерываться без записи результата с исходом `fenced`. Задание в `processing` с истёкшей арендой SHALL без участия оператора возвращаться в `queued` (или в `failed` с `retry_exhausted`, если попытки исчерпаны) не позже `SWEEP_INTERVAL_SECONDS` после истечения аренды.
|
||||
|
||||
#### Scenario: Worker убит посреди задания
|
||||
|
||||
- **WHEN** worker получает `SIGKILL` во время обработки и затем запускается снова
|
||||
- **THEN** вложение становится `ready`, у задания один набор вариантов
|
||||
|
||||
#### Scenario: Долгая обработка не теряет аренду
|
||||
|
||||
- **WHEN** обработка длится дольше `JOB_TIMEOUT_SECONDS`, а держатель жив
|
||||
- **THEN** аренда продлевается, задание не возвращается в очередь, вложение становится `ready` за одну попытку
|
||||
|
||||
#### Scenario: Аренду забрали
|
||||
|
||||
- **WHEN** аренда держателя истекла и задание вернули в очередь, пока держатель стоял
|
||||
- **THEN** держатель не пишет объектов и строк, в журнале задания событие `fenced`
|
||||
|
||||
### Requirement: Worker остановлен — приём продолжается
|
||||
|
||||
Недоступность worker SHALL NOT мешать приёму: upload SHALL отвечать `202`, `/content` такого вложения — `409`, сообщения с ним — `201`, текстовые сообщения и история SHALL работать; API SHALL NOT обрабатывать изображение синхронно. Принятое задание SHALL переживать рестарт реплик API и relay и доходить до `ready` после запуска worker.
|
||||
@@ -89,10 +109,15 @@ Worker SHALL обрабатывать задание отдельно от API:
|
||||
|
||||
### Requirement: Staging убирается после публикации
|
||||
|
||||
Оригинал SHALL оставаться в staging, пока результат не зафиксирован. После фиксации `ready` объект staging SHALL удаляться без участия оператора, а ссылка на него — обнуляться; вложения не в `ready` SHALL NOT терять staging.
|
||||
Оригинал SHALL оставаться в staging, пока результат не зафиксирован. После фиксации `ready` объект staging SHALL удаляться без участия оператора, а ссылка на него — обнуляться. Staging вложения в `failed` SHALL храниться `STAGING_RETENTION_SECONDS` с момента перехода в `failed`, чтобы оператор мог выполнить replay, и затем удаляться так же; вложения в `queued` и `processing` SHALL NOT терять staging.
|
||||
|
||||
#### Scenario: Staging после ready
|
||||
|
||||
- **WHEN** вложение стало `ready`
|
||||
- **THEN** не позже чем через `SWEEP_INTERVAL_SECONDS` у него нет ключа staging, а объект оригинала читается из конечного префикса
|
||||
|
||||
#### Scenario: Staging failed до и после retention
|
||||
|
||||
- **WHEN** вложение стало `failed`
|
||||
- **THEN** до истечения `STAGING_RETENTION_SECONDS` staging на месте и replay возможен; после — ключ staging обнулён, объект удалён, replay отвечает `expired`
|
||||
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# lab5-image-variants Specification
|
||||
|
||||
## Purpose
|
||||
Определяет варианты crop и optimized уровня «4» по контракту и пределы, которыми worker ограничивает обработку недоверенного изображения: байты, пиксели по заголовку, время и память одного рендера.
|
||||
## Requirements
|
||||
### Requirement: Crop и optimized
|
||||
|
||||
Worker SHALL строить для каждого задания, кроме `thumbnail`, вариант `crop` — JPEG, центрированный квадрат 128×128 после применения EXIF orientation, с увеличением маленьких исходников, — и вариант `optimized` — WebP, вписанный в 1280×1280 с сохранением пропорций, без увеличения, размеры округлены вниз и не меньше 1 px. Альфа-канал во всех вариантах SHALL компоноваться на белый фон. Варианты SHALL NOT содержать EXIF, ICC и XMP; параметры кодирования SHALL быть документированы (`crop` — JPEG `quality` 85, `optimized` — WebP с потерями `quality` 80, `method` 4). Метаданные каждого варианта (`content_type`, `size_bytes`, `width`, `height`, `sha256`) SHALL совпадать с байтами, которые отдаёт `/content?variant=<имя>`.
|
||||
|
||||
#### Scenario: Fixture 320×200
|
||||
|
||||
- **WHEN** обработана `tests/fixtures/sample.png`
|
||||
- **THEN** у вложения варианты `crop` 128×128 `image/jpeg`, `optimized` 320×200 `image/webp` и `thumbnail` 256×160, каждый `/content?variant=<имя>` отдаёт настоящий файл этого формата длиной `size_bytes` с SHA-256 из метаданных и реальными размерами из метаданных
|
||||
|
||||
#### Scenario: Большой и вытянутый исходник
|
||||
|
||||
- **WHEN** обработаны JPEG 4000×3000 и PNG 3000×2
|
||||
- **THEN** `optimized` 1280×960 и 1280×1 соответственно, `crop` в обоих случаях 128×128
|
||||
|
||||
#### Scenario: Ориентация и прозрачность
|
||||
|
||||
- **WHEN** обработаны JPEG 400×200 с EXIF orientation 6 и PNG RGBA с прозрачным фоном
|
||||
- **THEN** `optimized` первого 200×400, прозрачные области `crop` и `optimized` второго белые, ни в одном варианте нет EXIF
|
||||
|
||||
### Requirement: Пределы обработки изображения в worker
|
||||
|
||||
Worker SHALL ограничивать обработку одного задания: размер оригинала — `MAX_UPLOAD_BYTES`, число пикселей по заголовку до декодирования — `MAX_IMAGE_PIXELS`, время рендера — `RENDER_TIMEOUT_SECONDS`, адресное пространство процесса рендера — `RENDER_MEMORY_MB`; рендер SHALL выполняться в отдельном процессе, число одновременных рендеров SHALL не превышать `WORKER_CONCURRENCY`, а процесс worker SHALL иметь предел памяти контейнера не меньше суммы пределов рендеров и собственной памяти. Превышение предела SHALL переводить вложение в `failed` с `processing_failed` без повторов; процесс, превысивший время, SHALL принудительно завершаться. Падение процесса рендера по внешней причине SHALL считаться временной ошибкой. Worker SHALL продолжать обрабатывать другие задания после любого из этих исходов.
|
||||
|
||||
#### Scenario: Рендер дольше предела
|
||||
|
||||
- **WHEN** worker запущен с `RENDER_TIMEOUT_SECONDS` меньше времени рендера загруженного изображения
|
||||
- **THEN** вложение становится `failed` с `processing_failed` после первой попытки, процесс worker продолжает работать, следующая загрузка становится `ready`
|
||||
|
||||
#### Scenario: Рендер больше предела памяти
|
||||
|
||||
- **WHEN** worker запущен с `RENDER_MEMORY_MB` меньше пика рендера изображения 40 Мпикс
|
||||
- **THEN** вложение становится `failed` с `processing_failed`, процесс worker продолжает работать
|
||||
|
||||
#### Scenario: Изображение на пределе пикселей
|
||||
|
||||
- **WHEN** со штатными пределами загружен PNG 8000×5000
|
||||
- **THEN** вложение становится `ready` с тремя вариантами, пик памяти контейнера worker ниже его предела
|
||||
|
||||
#### Scenario: Пиксели сверх предела по заголовку
|
||||
|
||||
- **WHEN** worker получает задание на оригинал, у которого по заголовку больше `MAX_IMAGE_PIXELS` пикселей
|
||||
- **THEN** изображение не декодируется, вложение становится `failed` с `invalid_image`
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
# lab5-job-recovery Specification
|
||||
|
||||
## Purpose
|
||||
Определяет, как система восстанавливает задание после внедрённого падения relay или worker в каждом окне отказа, как оператор видит и безопасно повторяет неуспешную работу и как уровень «4» проверяется одной командой.
|
||||
## Requirements
|
||||
### Requirement: Точки внедрения отказов
|
||||
|
||||
Relay и worker SHALL поддерживать точку отказа из переменной `FAULT_POINT`, задаваемой только override-файлом `infra/compose.faults.yaml` и никогда основным стендом. Падение SHALL завершать процесс с кодом 137 без какой-либо дальнейшей работы; точки relay — `after_commit_before_publish` (строка outbox взята, публикации не было) и `after_publish_before_confirm` (сообщение в очереди, `published_at` не записан); точки worker — `after_claim_before_side_effect`, `after_s3_write_before_commit`, `after_commit_before_ack`; точка `stall_after_claim` SHALL останавливать обработку одного задания без продления аренды на `FAULT_STALL_SECONDS`, после чего обработка продолжается. После перезапуска процесса без точки отказа задание SHALL доходить до `ready` без действий оператора и без нового задания, с одним набором вариантов.
|
||||
|
||||
#### Scenario: Разрыв COMMIT и publish
|
||||
|
||||
- **WHEN** relay с `after_commit_before_publish` завершается кодом 137 после `202`
|
||||
- **THEN** строка outbox не опубликована, очередь пуста, вложение `queued`; после запуска relay без точки отказа вложение становится `ready` с тем же `job_id`
|
||||
|
||||
#### Scenario: Сообщение опубликовано, отметка не записана
|
||||
|
||||
- **WHEN** relay с `after_publish_before_confirm` завершается кодом 137
|
||||
- **THEN** после запуска relay сообщение публикуется повторно, вложение становится `ready`, вторая копия подтверждается как `duplicate_noop`
|
||||
|
||||
#### Scenario: Объекты записаны, результат не зафиксирован
|
||||
|
||||
- **WHEN** worker с `after_s3_write_before_commit` завершается кодом 137
|
||||
- **THEN** строк вариантов нет; после запуска worker вложение становится `ready`, у ключа эффекта одна строка на вариант, байты совпадают с метаданными
|
||||
|
||||
#### Scenario: Результат зафиксирован, ack не отправлен
|
||||
|
||||
- **WHEN** worker с `after_commit_before_ack` завершается кодом 137
|
||||
- **THEN** вложение уже `ready`; после запуска worker повторная доставка подтверждается как `duplicate_noop`, строки вариантов до и после совпадают
|
||||
|
||||
#### Scenario: Зависший держатель аренды
|
||||
|
||||
- **WHEN** worker с `stall_after_claim` останавливает обработку дольше `JOB_TIMEOUT_SECONDS`
|
||||
- **THEN** задание возвращается в очередь, вторая попытка доводит вложение до `ready`, проснувшийся держатель получает `fenced` и ничего не меняет
|
||||
|
||||
### Requirement: Реестр failed и явный replay
|
||||
|
||||
Задания в `failed` SHALL быть доступны оператору списком с `attachment_id`, `job_id`, `error_code`, `attempt`, классом последней ошибки и временем. Команда `python -m messenger.admin replay --attachment-id <id>` SHALL переводить вложение `failed` в `queued` тем же `job_id` с `attempt` 1 и новой публикацией, записывая в журнал задания событие `replayed` с оператором; для вложения в `ready`, `queued` или `processing` SHALL отвечать `noop` и записывать `replay_noop`, не создавая работы; для `failed`, чей staging уже удалён по retention, — `expired`. Последняя строка вывода команды SHALL быть JSON с полем `result`. Сообщения, которые не стали заданием (не по схеме или с исчерпанным `delivery-limit`), SHALL попадать в dead-letter очередь, которую оператор просматривает без извлечения.
|
||||
|
||||
#### Scenario: Replay после retry_exhausted
|
||||
|
||||
- **WHEN** вложение `failed` с `retry_exhausted`, оператор выполняет replay
|
||||
- **THEN** вывод `{"result": "replayed", ...}`, вложение становится `ready`, `attempt` не превышает `JOB_MAX_ATTEMPTS`, в журнале есть `replayed`
|
||||
|
||||
#### Scenario: Replay готового вложения
|
||||
|
||||
- **WHEN** оператор повторяет replay уже `ready`-вложения
|
||||
- **THEN** вывод `{"result": "noop", ...}`, в очередь ничего не публикуется, метаданные и строки вариантов не меняются
|
||||
|
||||
#### Scenario: Реестр
|
||||
|
||||
- **WHEN** оператор выполняет `python -m messenger.admin failed`
|
||||
- **THEN** вывод — JSON-список `failed`-заданий без текста исключений, ключей S3 и учётных данных
|
||||
|
||||
### Requirement: Проверка уровня «4» одной командой
|
||||
|
||||
`make level4` SHALL запускать против поднятого стенда сценарии уровней «3» и «4» (варианты и пределы, разрыв COMMIT/publish, повторная публикация, падения worker после записи S3 и после COMMIT, зависший держатель аренды, replay, сообщение не по схеме, backoff с jitter, retention `failed`), затем проверять инварианты (`terminal`, `single_effect`, `no_ready_rollback`, `monotonic_publication`, `bytes_match_metadata`, `bounded_attempts`, `no_orphans`, `no_lost_202`) и записывать отчёт в `evidence/level4.json`; по завершении стенд SHALL возвращаться в штатную конфигурацию.
|
||||
|
||||
#### Scenario: Прогон уровня «4»
|
||||
|
||||
- **WHEN** выполняется `make suite-preflight && make level4`
|
||||
- **THEN** каждый сценарий и инвариант имеет `result: PASS`, команда печатает `PASS: lab5 pipeline suite`, relay и worker снова запущены без точек отказа
|
||||
|
||||
Reference in New Issue
Block a user