Propose crop, optimized, worker limits and job recovery as an openspec change

Level 4 of the lab 5 rubric: crop and optimized variants, byte, pixel,
time and memory limits of the worker, crash points for the failure
windows 2-5 with automatic recovery, backoff with jitter and error
classification, a failed registry with an explicit replay, lease renewal
and failed staging retention. New capabilities lab5-image-variants and
lab5-job-recovery, deltas to lab5-attachment-pipeline and lab4-attachments.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Artyom
2026-10-29 01:44:02 +03:00
co-authored by Claude Opus 5.5
parent adb29a2afc
commit 045d631c12
8 changed files with 440 additions and 0 deletions
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-29
@@ -0,0 +1,117 @@
## Context
Мотивация — в `proposal.md`. После изменения `add-lab5-async-attachments` в зоне `attachments` есть домен заданий (`Job`, `Lease`, `Claim`, `RetryPolicy`, `FailureCode`, `Outcome`), обработчики `ProcessJob`, `PublishOutbox`, `RecoverExpiredLeases`, `CleanStaging`, порты `JobPublisher`, `VariantRenderer`, `Faults`, адаптеры FastStream, Pillow (рендер в потоке под семафором) и PostgreSQL, сборки `relay.py` и `worker.py`. Захват с арендой и fencing по `lease_token`, монотонная публикация `published_version < v`, `ON CONFLICT DO NOTHING` по ключу эффекта уже работают. Harness `scripts/pipeline_suite.py` из `.prep/lab5` содержит сценарии уровня «4» и рассчитан на точки `FAULT_POINT`, CLI оператора и `infra/compose.faults.yaml` (короткие аренда и backoff, `restart: "no"`).
Замеры в образе приложения (Python 3.14, Pillow 13, forkserver): процесс рендера после импорта Pillow — 46 МБ адресного пространства; рендер трёх вариантов PNG 8000×5000 — пик 258 МБ (RGB) и 398 МБ (RGBA, компоновка на белый); с `RLIMIT_AS` 300 МБ RGBA-рендер получает `MemoryError`, процесс жив.
## Goals / Non-Goals
**Goals:**
- Все пределы обработки недоверенного изображения выражены конфигурацией и проверяются на стенде, их превышение даёт наблюдаемый `failed`, а не смерть worker или вечный повтор.
- Каждое окно отказа 2–5 воспроизводится одной переменной окружения и восстанавливается без оператора.
- Оператор видит неуспешную работу и повторяет её так, что уже успешный эффект не исполняется второй раз.
**Non-Goals:**
- `pipeline_version` 2 и `reprocess` — трек 2; рендер уже получает версию, но профиль кодирования один.
- Освобождение аренды при штатной остановке worker: прерванное SIGTERM задание возвращает relay по истечении аренды, как после падения.
- Окно 1 (после staging до записи задания) — закрыто компенсацией и уборкой лабы 4, точки отказа в API нет.
## Decisions
### D1. Три варианта из одного декодирования
`render_variants(data, limits)` (модуль `infrastructure/images.py`, функция уровня модуля для пула процессов): проверка байтов и пикселей по заголовку → для JPEG `draft(None, fit(w, h, 1280))` (декодер libjpeg сразу уменьшает в 2/4/8 раз, не ниже размера optimized) → `load()` → `ImageOps.exif_transpose(in_place=True)` (без копии, если ориентации нет) → компоновка альфы на белый / приведение к RGB → три `resize(LANCZOS, reducing_gap=3.0)`:
| Вариант | Геометрия | Кодирование |
| --- | --- | --- |
| `thumbnail` | `fit(W, H, 256)` вниз, без увеличения | JPEG `quality=85`, `optimize=True` |
| `crop` | `ImageOps.fit(…, (128, 128), centering=(0.5, 0.5))`, увеличение разрешено | JPEG `quality=85`, `optimize=True` |
| `optimized` | `fit(W, H, 1280)` вниз, без увеличения | WebP с потерями `quality=80`, `method=4` |
`W, H` — размеры после ориентации, посчитанные по заголовку (draft меняет только декодированный размер). Метаданные (EXIF, ICC, XMP) кодерам не передаются: в Pillow 13 JPEG и WebP пишут их только из явных параметров `save`. Альфа в `optimized` тоже компонуется на белый — один источник для трёх вариантов и одинаковый вид везде. Получаем: одно декодирование на задание, пик памяти — декодированный оригинал плюс RGB-копия для RGBA. Стоит: `optimized` теряет прозрачность; draft даёт для больших JPEG чуть иной результат, чем полное декодирование (детерминированно).
`ready` выставляет та же транзакция, что пишет строки трёх вариантов (`complete`), поэтому частичного набора в API не бывает.
### D2. Пул процессов рендера: время, память, конкурентность
Порт `VariantRenderer` не меняется; адаптер `ProcessVariantRenderer` заменяет поточный. Внутри — очередь из `WORKER_CONCURRENCY` слотов, слот — `ProcessPoolExecutor(max_workers=1, max_tasks_per_child=RENDER_TASKS_PER_CHILD, initializer=limit_memory)` (forkserver по умолчанию в 3.14). Рендер берёт свободный слот, ждёт результат `asyncio.wait_for(…, RENDER_TIMEOUT_SECONDS)`:
- таймаут → `kill_workers()` этого слота, новый слот, `ImageTooDemanding` (постоянная, `processing_failed`);
- `MemoryError` из процесса (предел `RLIMIT_AS = RENDER_MEMORY_MB`, только Linux) → `ImageTooDemanding`;
- `BrokenProcessPool` (процесс убит снаружи, например OOM killer cgroup) → новый слот, `Unavailable` (временная);
- байты больше `MAX_UPLOAD_BYTES` или пиксели больше `MAX_IMAGE_PIXELS` по заголовку → `ImageTooDemanding` / `UnreadableImage` до декодирования.
Слот на процесс, а не общий пул: убийство по таймауту не задевает соседнюю задачу. Предел памяти контейнера: `WORKER_MEMORY ≥ WORKER_CONCURRENCY · RENDER_MEMORY_MB + память процесса worker` — 2 × 448 МБ + ~120 МБ, поэтому `WORKER_MEMORY` 1g (было 768m). 448 МБ покрывают замеренный пик 398 МБ любого 8-битного изображения до 40 Мпикс. Получаем: зависание и перерасход памяти одного изображения не убивают worker и не превращаются в вечный повтор. Стоит: старт процесса рендера (~0,3 с) раз в `RENDER_TASKS_PER_CHILD` задач и копирование байтов оригинала (до 10 МиБ) и вариантов через pickle. `RLIMIT_AS` на macOS не применяется — поэтому пределы памяти проверяются на стенде, а в собственных тестах — таймаут и падение процесса.
Классификация остаётся в `ProcessJobHandler`: `UnreadableImage` → `invalid_image`; `ImageTooDemanding`, `ObjectMissingError` и прочие — `processing_failed`; `Unavailable` → повтор.
### D3. Backoff с equal jitter
`RetryPolicy.delay(attempt, spread)`: `d = min(cap, base · 2^(attempt−1))`, задержка `d/2 + spread · d/2`, `spread ∈ [0, 1)` от порта `Jitter` (адаптер — `random.random`). Equal, а не full jitter: у full jitter все пять попыток могут уложиться в доли секунды и короткий отказ S3 превратится в `retry_exhausted`; нижняя граница `d/2` сохраняет суммарное окно повторов (база 2 с: 15–30 с). Задержка пишется в `job_events.detail.delay_seconds` — по ней suite проверяет jitter. Получаем: развод синхронных повторов многих заданий после общего отказа. Стоит: недетерминированное время в тестах — тесты подставляют свой `Jitter`.
### D4. Продление аренды
`JobRepository.renew(lease, duration) -> bool`:
```sql
UPDATE jobs SET lease_until = now() + make_interval(secs => $3), updated_at = now()
WHERE job_id = $1 AND lease_token = $2 AND status = 'processing'
```
(поиск по PK). `ProcessJobHandler` запускает побочные эффекты задачей и раз в `JOB_TIMEOUT_SECONDS / 3` продлевает аренду; первое продление — до первого побочного эффекта. `False` → задача отменяется, событие `fenced`, исход `FENCED`, `ack`: новую попытку несёт своё сообщение. Ошибка PostgreSQL при продлении — отмена и временная ошибка. Получаем: долгий рендер не теряет аренду, а держатель, которого признали мёртвым, узнаёт об этом до записи в S3. Стоит: один `UPDATE` на задание плюс по одному на каждую треть аренды. Fencing при фиксации (`lease_token` в `WHERE`) остаётся последним рубежом: между продлением и `COMMIT` аренду всё ещё могут забрать.
### D5. Точки отказа
Порт `Faults.reach(point)` становится асинхронным; адаптер `EnvironmentFaults(point, stall)` по имени: `transient_error` — `Unavailable` на каждой попытке; `stall_after_claim` — один раз за жизнь процесса `asyncio.sleep(FAULT_STALL_SECONDS)`; прочие — `flush` журналов и `os._exit(137)`. Места вызова — в обработчиках зоны (имена точек объявлены в `application/pipeline.py`):
| Окно | Точка | Где | Что остаётся |
| --- | --- | --- | --- |
| 2 | `after_commit_before_publish` | `PublishOutbox`, строка взята `FOR UPDATE`, до publish | строка без `published_at`, очередь пуста |
| 3 | `after_publish_before_confirm` | после подтверждённого publish, до `UPDATE published_at` | сообщение в очереди, строка не помечена |
| — | `after_claim_before_side_effect` | после `COMMIT` захвата | `processing`, живая аренда, S3 пуст |
| 4 | `after_s3_write_before_commit` | после записи объектов, до `complete` | объекты есть, строк нет |
| 5 | `after_commit_before_ack` | после `COMMIT` результата, до возврата в точку входа | `ready`, сообщение не подтверждено |
| — | `stall_after_claim` | после захвата, до продления аренды | аренда истекает |
Окно 3 честно названо: FastStream ждёт confirm внутри `publish`, поэтому падение происходит после confirm, но до записи `published_at`; для системы это то же состояние — брокер знает о сообщении, PostgreSQL нет. `FAULT_POINT` задаёт только `infra/compose.faults.yaml`; в API точек нет. В override добавлены `FAULT_RENDER_TIMEOUT_SECONDS`, `FAULT_RENDER_MEMORY_MB`, `FAULT_STAGING_RETENTION_SECONDS` для сценариев пределов и retention.
### D6. Реестр failed, replay, DLQ
Новая сборка процесса `messenger/admin.py` (рядом с `relay.py`, знает только зону `attachments`): контейнер dishka из `PlatformProvider` и UoW зоны, без брокера и S3. Точка входа `attachments/entrypoints/admin.py` (argparse) → команды `ReplayAttachment(attachment_id, operator)` и запрос `failed`. Запуск — `docker compose run --rm --no-deps -T worker python -m messenger.admin …`, последняя строка stdout — JSON.
Replay — одна транзакция под `SELECT … FOR UPDATE` строки вложения:
- `failed` и `staging_key IS NOT NULL` → последнее `failed`-задание: `status='queued', attempt=1`, аренда и `next_attempt_at` сброшены; вложение `queued`, `error_code = NULL`; новая строка outbox с тем же `job_id`; событие `replayed` (`detail`: оператор, прежний `error_code`) → `replayed`;
- `failed` без staging (retention) → `expired`; `ready`/`queued`/`processing` → `noop` и событие `replay_noop`; нет вложения → `not_found`.
`attempt = 1`, потому что replay — новая серия попыток по решению оператора; `bounded_attempts` держится в пределах серии. Прежний эффект защищён тем же ключом: `job_id` и `(attachment_id, pipeline_version)` не меняются, строки вариантов — `ON CONFLICT DO NOTHING`, публикация — `published_version < v`. Получаем безопасную кнопку «повторить». Стоит: отдельный процесс и права на БД у оператора (через секрет worker).
Реестр — `jobs` + `job_events`; запрос оператора `WHERE status = 'failed' ORDER BY updated_at DESC LIMIT $1` обслуживает частичный индекс миграции `0005_failed_registry.sql`: `CREATE INDEX jobs_failed_idx ON jobs (updated_at DESC) WHERE status = 'failed'` (expand, совместим с работающей версией). DLQ остаётся у брокера: туда уходит то, что не стало заданием; worker её не читает, оператор смотрит `scripts/broker.sh dlq` (`rabbitmqadmin get … ack_requeue_true`, без извлечения).
### D7. Retention staging у failed
`CleanStaging(limit, retention)`: выборка
```sql
SELECT id, staging_key FROM attachments
WHERE staging_key IS NOT NULL
AND (status = 'ready' OR (status = 'failed' AND updated_at < now() - make_interval(secs => $2)))
ORDER BY updated_at LIMIT $1 FOR UPDATE SKIP LOCKED
```
по частичному индексу `attachments_staged_idx (updated_at) WHERE staging_key IS NOT NULL`. `updated_at` у `failed` — момент перехода в `failed`. Удаление объекта и обнуление ключа — в одной транзакции под блокировкой строки, replay берёт ту же блокировку: replay либо видит staging и ставит `queued` (уборка эту строку больше не выберет), либо видит `NULL` и отвечает `expired`. `queued` и `processing` не выбираются никогда. Нижняя граница `STAGING_RETENTION_SECONDS` снижена до 1 с ради сценария; штатно — 86400.
### D8. Проверка одной командой
`make level4` = `pipeline_suite.py --level 4 --output evidence/level4.json`; цель лабы 4 с тем же именем переименована в `lab4-level4`. В suite добавлены сценарии `worker_limits` (таймаут и предел памяти через override, затем 40 Мпикс со штатными пределами и `memory.peak` cgroup), `retry_backoff_jitter` (задержки из журнала), `failed_retention` (relay с retention 1 с → staging удалён → replay `expired`); CLI по умолчанию — `python -m messenger.admin`. Остальные сценарии уровня «4» взяты из `.prep/lab5` без изменения проверок.
## Risks / Trade-offs
- [Два 40-Мпикс RGBA одновременно на пределе памяти контейнера] → предел контейнера рассчитан на сумму пределов процессов; если OOM killer всё же убьёт процесс рендера — `BrokenProcessPool`, временная ошибка, повтор с backoff.
- [SIGTERM во время рендера] → задание вернётся по истечении аренды (до 60 с), не сразу; эффекта нет, дубля нет.
- [Replay сбрасывает `attempt`] → оператор может зациклить повторы вручную; каждый replay оставляет `replayed` в журнале с оператором.
- [Окно 3 после confirm] → воспроизводится состояние, а не точный момент; описано в отчёте.
- [Новые кодеры меняют байты thumbnail] → касается только новых заданий; опубликованные строки и объекты прежних вложений не переписываются.
## Migration Plan
`0005_failed_registry.sql` — только индекс; работающий релиз им не пользуется. Порядок: миграция → relay → worker → API (API не меняется, кроме доступности `crop`/`optimized`). Откат — прежний образ; индекс остаётся безвредным, варианты `crop`/`optimized` новых вложений продолжают отдаваться прежним кодом (он читает все строки опубликованной версии).
@@ -0,0 +1,34 @@
## Why
Уровень «3» закрыт: задание доходит до `ready` с одним thumbnail, повторы ограничены, аренда возвращается relay. Рубрика «4» требует большего: crop и optimized, пределы worker по байтам, пикселям, времени и памяти, внедрённые падения в окнах 2–5 с автоматическим восстановлением, backoff с jitter и классификацию ошибок, реестр `failed` и явный replay, продление аренды для долгой работы и защиту от зависшего держателя, retention staging у `failed`. Изменение закрывает уровень «4» и строки 4.1–4.4 таблицы доказательств `REPORT.md`, а также пункт 4 сценария защиты.
## What Changes
- Worker строит три варианта: thumbnail, crop 128×128 JPEG по центру (увеличение разрешено), optimized WebP в 1280×1280 без увеличения (`quality` 80, `method` 4, без EXIF, ICC, XMP). `ready` — только после записи оригинала и всех трёх вариантов.
- Рендер — в пуле процессов: по одному процессу на слот `WORKER_CONCURRENCY`, таймаут `RENDER_TIMEOUT_SECONDS` с убийством процесса, предел адресного пространства `RENDER_MEMORY_MB` на процесс, предел байтов и пикселей по заголовку до декодирования. Превышение — `failed` с `processing_failed`, worker жив.
- Классификация: `invalid_image` и `processing_failed` — постоянные, без повторов; недоступный S3/PostgreSQL и падение процесса рендера — временные. Backoff с equal jitter.
- Аренда продлевается, пока идёт работа; потерянная аренда прерывает обработку до побочных эффектов (`fenced`).
- `FAULT_POINT` для окон 2–5 и зависания: relay `after_commit_before_publish`, `after_publish_before_confirm`; worker `after_claim_before_side_effect`, `after_s3_write_before_commit`, `after_commit_before_ack`, `stall_after_claim`. Только через `infra/compose.faults.yaml`.
- Операторская CLI `python -m messenger.admin`: `failed` (реестр) и `replay --attachment-id` (`failed → queued` с audit, `noop` для `ready`, `expired` после retention). DLQ видна оператору через `scripts/broker.sh dlq`.
- Retention staging у `failed`: `STAGING_RETENTION_SECONDS`, затем relay удаляет объект.
- `make level4` — сценарии уровней «3» и «4» suite с инвариантами одной командой; цель лабы 4 переименована в `lab4-level4`.
## Capabilities
### New Capabilities
- `lab5-image-variants`: crop и optimized по контракту, пределы обработки изображения в worker.
- `lab5-job-recovery`: точки внедрения отказов окон 2–5 и восстановление, реестр `failed`, DLQ и явный replay, проверка уровня «4» одной командой.
### Modified Capabilities
- `lab5-attachment-pipeline`: «Worker публикует оригинал и thumbnail» — `ready` после всех вариантов; «Ограниченные повторы и финальная ошибка» — jitter и классификация; «Аренда захваченного задания» — продление и прерывание; «Staging убирается после публикации» — retention `failed`.
- `lab4-attachments`: «Метаданные и скачивание только участникам» — `crop` и `optimized` отдаются, `404` только для варианта, которого нет в опубликованной версии.
## Impact
- Код: зона `attachments` (рендер, пул процессов, продление аренды, точки отказа, replay, retention), сборка `admin.py`; миграция `0005` — частичный индекс реестра `failed`.
- Стенд: переменные worker и relay в `compose.yaml`, `.env.example`, `infra/compose.faults.yaml`; `WORKER_MEMORY` 1g; `scripts/broker.sh dlq`, цели Makefile `level4`, `replay`, `failed`, `dlq`.
- Тесты и доказательства: рендер трёх вариантов, пул процессов, jitter, продление аренды, replay и retention против PostgreSQL; `evidence/level4.json`, строки уровня «4» `REPORT.md`.
## Non-goals
`pipeline_version` 2, монотонная публикация как доказательство и fault-injection трека — следующее изменение (трек 2). Из Out of scope ничего: метрики и трассировка (лаба 6), TLS (лаба 7), admission control (трек 1), HTTP-эндпоинты оператора, HA брокера.
@@ -0,0 +1,50 @@
## MODIFIED Requirements
### 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`, `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: Второй участник скачивает оригинал
- **WHEN** второй участник чата запрашивает `/content` готового вложения с `Accept: application/json`
- **THEN** ответ `200`, `Content-Type: image/png`, байты совпадают с загруженными, SHA-256 равен `sha256` метаданных
#### Scenario: Второй участник скачивает thumbnail
- **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`
- **THEN** ответ `409` с кодом `conflict`
#### Scenario: Вложение в failed
- **WHEN** участник запрашивает `/content?variant=original` вложения в `failed`
- **THEN** ответ `409` с кодом `conflict`, метаданные показывают `failed` и `error_code`
#### Scenario: Посторонний
- **WHEN** пользователь вне чата запрашивает метаданные или `/content`
- **THEN** оба ответа `404` с кодом `not_found`
#### Scenario: Варианта нет
- **WHEN** запрошен `/content?variant=crop` вложения, ставшего `ready` в лабе 4 без вариантов
- **THEN** ответ `404` с кодом `not_found`
#### Scenario: Неизвестный вариант
- **WHEN** запрошен `/content?variant=preview`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Объект пропал из хранилища
- **WHEN** метаданные готового вложения есть, а объекта в bucket нет
- **THEN** `/content` отвечает `404`, событие пишется в журнал без ключа объекта
@@ -0,0 +1,82 @@
## MODIFIED Requirements
### Requirement: Worker публикует оригинал и 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` и по одному `crop` и `optimized`, `/content?variant=thumbnail` отдаёт настоящий JPEG 256×160 длиной `size_bytes` с SHA-256 из метаданных, `/content` оригинала побайтно равен загруженному файлу
#### Scenario: Маленький и вытянутый исходник
- **WHEN** обработаны PNG 64×64 и PNG 17×1000
- **THEN** thumbnail 64×64 и 4×256 соответственно
#### Scenario: Прозрачность и ориентация
- **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. Задержка перед попыткой `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 недоступен во время обработки
- **WHEN** worker обрабатывает задание при остановленном `s3`, а через несколько секунд `s3` запускают
- **THEN** вложение возвращается в `queued`, `attempt` растёт, после возврата S3 вложение становится `ready` без ручных действий
#### Scenario: Попытки исчерпаны
- **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 не может декодировать изображение задания
- **THEN** вложение становится `failed` с `invalid_image` после первой попытки
### Requirement: Аренда захваченного задания
Захват задания 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: 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 @@
## Purpose
Определяет варианты crop и optimized уровня «4» по контракту и пределы, которыми worker ограничивает обработку недоверенного изображения: байты, пиксели по заголовку, время и память одного рендера.
## ADDED 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 @@
## Purpose
Определяет, как система восстанавливает задание после внедрённого падения relay или worker в каждом окне отказа, как оператор видит и безопасно повторяет неуспешную работу и как уровень «4» проверяется одной командой.
## ADDED 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 снова запущены без точек отказа
@@ -0,0 +1,45 @@
## 1. Варианты crop и optimized
- [ ] 1.1 `render_variants`: проверка байтов и пикселей по заголовку, draft для JPEG, ориентация без копии, компоновка на белый, `thumbnail`, `crop` 128×128 JPEG, `optimized` WebP в 1280×1280 без метаданных; ошибка `ImageTooDemanding` в домене зоны
- [ ] 1.2 Тесты рендера и pipeline: три варианта у fixture, геометрия crop и optimized (вытянутые, маленькие, EXIF 6, альфа), отсутствие EXIF, `ready` только с полным набором, `404` на вариант вложения лабы 4
- [ ] 1.3 Проверка группы: `make lint`, `make student-test`
## 2. Пределы worker
- [ ] 2.1 Адаптер `ProcessVariantRenderer`: слоты-процессы по `WORKER_CONCURRENCY`, таймаут с `kill_workers()`, `RLIMIT_AS` в процессе рендера, `BrokenProcessPool` → временная ошибка; настройки `RENDER_TIMEOUT_SECONDS`, `RENDER_MEMORY_MB`, `RENDER_TASKS_PER_CHILD`; закрытие пула при остановке worker
- [ ] 2.2 Классификация в `ProcessJobHandler`: `ImageTooDemanding` и отсутствующий оригинал → `processing_failed` без повторов
- [ ] 2.3 Проверка группы: тесты пула — результат, таймаут с восстановлением слота, падение процесса рендера → `Unavailable`, `MemoryError` → `ImageTooDemanding`, предел памяти применяется (Linux)
## 3. Повторы и аренда
- [ ] 3.1 `RetryPolicy.delay(attempt, spread)` с equal jitter, порт `Jitter` и адаптер, задержка в журнале задания
- [ ] 3.2 `JobRepository.renew`, продление аренды на время побочных эффектов, проверка аренды до первой записи, отмена при потере аренды → `fenced`
- [ ] 3.3 Проверка группы: unit-тесты границ jitter; тесты против PostgreSQL — долгий рендер не теряет аренду, потерянная аренда не пишет объектов
## 4. Точки отказа
- [ ] 4.1 Асинхронный порт `Faults`, адаптер с падением `os._exit(137)`, однократным зависанием и временной ошибкой; `FAULT_STALL_SECONDS`
- [ ] 4.2 Точки в `PublishOutbox` (окна 2 и 3) и `ProcessJob` (после захвата, зависание, окна 4 и 5); `Faults` в провайдере relay
- [ ] 4.3 Проверка группы: тесты — каждая точка вызывается в своём месте и порядке, после «падения» состояние совпадает с таблицей окон
## 5. Реестр, replay, retention
- [ ] 5.1 Миграция `0005_failed_registry.sql` (частичный индекс `failed`-заданий)
- [ ] 5.2 Команда `ReplayAttachment` и запрос реестра в зоне `attachments`, событие `JobReplayed` в журнале аудита
- [ ] 5.3 Точка входа `attachments/entrypoints/admin.py` и сборка `messenger/admin.py` (`failed`, `replay`), тест графа импортов
- [ ] 5.4 `CleanStaging` с retention `failed`, `STAGING_RETENTION_SECONDS` от 1 с
- [ ] 5.5 Проверка группы: тесты против PostgreSQL — replay `failed` → `ready` с тем же `job_id` и `attempt` 1, replay `ready` → `noop` без outbox, после retention → `expired`, staging `queued` не трогается; тест миграций
## 6. Стенд и обвязка
- [ ] 6.1 `compose.yaml`: переменные рендера, `WORKER_MEMORY` 1g; `.env.example`; `infra/compose.faults.yaml` — `FAULT_STALL_SECONDS`, пределы рендера и retention для сценариев
- [ ] 6.2 `scripts/broker.sh dlq`; цели Makefile `level4`, `replay ID=…`, `failed`, `dlq`, переименование `lab4-level4`
- [ ] 6.3 `scripts/pipeline_suite.py`: CLI `python -m messenger.admin`, сценарии `worker_limits`, `retry_backoff_jitter`, `failed_retention`, задержки в журнале
- [ ] 6.4 CI-job: `make level4` вместо `make level3`
- [ ] 6.5 Проверка группы: `make up` из пересобранного образа, `make test`, `make suite-preflight`, `make level3`, `make level4`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` и `make restore`
## 7. Отчёт
- [ ] 7.1 `evidence/`: level4, level3, smoke, topology, persistence, failover, student-tests, contract-checks
- [ ] 7.2 `REPORT.md`: решения уровня «4» (варианты, пределы, jitter, аренда, точки отказа, replay, retention), строки 4.1–4.4, таблица отказов уровня «4», сценарий защиты п. 4
- [ ] 7.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test`