From 045d631c12e25c869537c1e3681349e87203f819 Mon Sep 17 00:00:00 2001 From: Artyom Date: Thu, 29 Oct 2026 01:44:02 +0300 Subject: [PATCH] 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) --- .../.openspec.yaml | 2 + .../add-lab5-variants-and-recovery/design.md | 117 ++++++++++++++++++ .../proposal.md | 34 +++++ .../specs/lab4-attachments/spec.md | 50 ++++++++ .../specs/lab5-attachment-pipeline/spec.md | 82 ++++++++++++ .../specs/lab5-image-variants/spec.md | 48 +++++++ .../specs/lab5-job-recovery/spec.md | 62 ++++++++++ .../add-lab5-variants-and-recovery/tasks.md | 45 +++++++ 8 files changed, 440 insertions(+) create mode 100644 openspec/changes/add-lab5-variants-and-recovery/.openspec.yaml create mode 100644 openspec/changes/add-lab5-variants-and-recovery/design.md create mode 100644 openspec/changes/add-lab5-variants-and-recovery/proposal.md create mode 100644 openspec/changes/add-lab5-variants-and-recovery/specs/lab4-attachments/spec.md create mode 100644 openspec/changes/add-lab5-variants-and-recovery/specs/lab5-attachment-pipeline/spec.md create mode 100644 openspec/changes/add-lab5-variants-and-recovery/specs/lab5-image-variants/spec.md create mode 100644 openspec/changes/add-lab5-variants-and-recovery/specs/lab5-job-recovery/spec.md create mode 100644 openspec/changes/add-lab5-variants-and-recovery/tasks.md diff --git a/openspec/changes/add-lab5-variants-and-recovery/.openspec.yaml b/openspec/changes/add-lab5-variants-and-recovery/.openspec.yaml new file mode 100644 index 00000000..5c99d6d7 --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-29 diff --git a/openspec/changes/add-lab5-variants-and-recovery/design.md b/openspec/changes/add-lab5-variants-and-recovery/design.md new file mode 100644 index 00000000..6f389720 --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/design.md @@ -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` новых вложений продолжают отдаваться прежним кодом (он читает все строки опубликованной версии). diff --git a/openspec/changes/add-lab5-variants-and-recovery/proposal.md b/openspec/changes/add-lab5-variants-and-recovery/proposal.md new file mode 100644 index 00000000..8f95db40 --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/proposal.md @@ -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 брокера. diff --git a/openspec/changes/add-lab5-variants-and-recovery/specs/lab4-attachments/spec.md b/openspec/changes/add-lab5-variants-and-recovery/specs/lab4-attachments/spec.md new file mode 100644 index 00000000..9085a3c1 --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/specs/lab4-attachments/spec.md @@ -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`, событие пишется в журнал без ключа объекта diff --git a/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-attachment-pipeline/spec.md b/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-attachment-pipeline/spec.md new file mode 100644 index 00000000..8a317a8b --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-attachment-pipeline/spec.md @@ -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` diff --git a/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-image-variants/spec.md b/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-image-variants/spec.md new file mode 100644 index 00000000..d7836139 --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-image-variants/spec.md @@ -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` diff --git a/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-job-recovery/spec.md b/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-job-recovery/spec.md new file mode 100644 index 00000000..ac360cec --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/specs/lab5-job-recovery/spec.md @@ -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 ` 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 снова запущены без точек отказа diff --git a/openspec/changes/add-lab5-variants-and-recovery/tasks.md b/openspec/changes/add-lab5-variants-and-recovery/tasks.md new file mode 100644 index 00000000..6be0e7f1 --- /dev/null +++ b/openspec/changes/add-lab5-variants-and-recovery/tasks.md @@ -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`