docs: propose pipeline-reliability

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-31 10:08:03 +03:00
co-authored by Claude Opus 5.5
parent 7f38948294
commit 99a222eee2
22 changed files with 4398 additions and 0 deletions
+35
View File
@@ -123,3 +123,38 @@
3. Допустим ли на уровне 3 ответ 503 при недоступном брокере? Контракт требует 202 только после устойчивой передачи; на уровне 3 нет
relay, поэтому намерение в БД само не доставится. Сделано: 503 с понятным отказом, на уровне 4 с relay станет 202. Другой ответ
требует relay уже здесь.
## pipeline-reliability
Подробности и отвергнутые варианты — `openspec/changes/pipeline-reliability/design.md`; пробы — его таблица «Пробы» (проект compose `plprobe`, volumes не создавались, после проб ничего не осталось).
### Решения
- **Вопросы №2 и №3 раздела `async-attachments` закрывает это изменение.** №3: отказ брокера больше не даёт 503, на загрузке 503 только от S3 и PostgreSQL; реплики API вообще не обращаются к брокеру и не получают его пароль. №2: срок хранения `[cleaner] staging_retention_seconds`, 86400 с — значение из `.env.example` skeleton.
- **Relay — отдельный сервис** на образе API (`python -m src.relay`, 0,25 CPU / 256 МБ, пул 1), а не задача реплик, worker или уборщика: остановка worker на защите не должна останавливать публикацию, плановая сверка уборщика не должна её задерживать. Намерения — те же строки `attachment_jobs`, отдельной таблицы outbox нет.
- **Публикация внутри транзакции** — исключение из правила «брокера в транзакции нет», как DELETE уборщика: `FOR UPDATE SKIP LOCKED` на пакет и есть защита двух relay от дублей. Срок 2 с меньше срока шага 6 с и простоя транзакции 10 с.
- **Опрос 0,25 с, а не LISTEN/NOTIFY:** опрос всё равно нужен для сроков, а пустая выборка стоит 0,05 мс (проба).
- **Сообщение — подсказка, истина в строке задания.** Worker больше не публикует и не ждёт паузу в месте конкуренции: следующую попытку публикует relay по `next_attempt_at`. Дубль при живой аренде и сообщение раньше срока подтверждаются без эффекта. Это закрывает W2 и S6.
- **Аренда без пульса:** срок = `job_timeout_seconds` + `lease_margin_seconds` (70 с). Попытка теперь жёстко ограничена сроком, поэтому истёкшая аренда значит «мёртв или заморожен». Цена — после KILL worker следующая попытка ждёт до 70 с.
- **Fencing номером попытки:** результат прежней попытки больше не принимается (на уровне 3 принимался). Поэтому номер `attempt` монотонен, а бюджет после replay — колонка `attempt_base`.
- **Backoff:** случайная величина из `[d / 2, d]`, `d = min(300, 5 × 2^(N−1))`. Полный jitter отвергнут: нижняя граница суммы пауз стремилась бы к нулю, и рестарт S3 (~25 с) мог бы исчерпать попытки; сейчас сумма 37,5–75 с.
- **Реестр `failed` — в PostgreSQL, DLQ брокера нет:** всё принятое живёт в БД, а сообщение не по схеме работы не несёт. Replay — операторская команда `make replay` (dry-run по умолчанию, с `--apply` выбор обязателен), аудит — таблица `attachment_job_replays`.
- **Декодирование — новый процесс на задание:** без секретов в окружении, с `RLIMIT_AS`, `RLIMIT_CPU` и сроком. Проба нашла JPEG в пределах контракта, который не декодируется за 60 с: 10 MiB повторённых сканов. Цена — ~100 мс CPU на маленьком файле; forkserver (9 мс) отвергнут сейчас, граница — один модуль, если трек 1 покажет необходимость.
- **Лимиты по умолчанию:** память 450 МиБ (наибольший `VmPeak` на пробе 417), CPU 15 с (наибольшее законное 0,55 с), срок 40 с, меньше срока попытки. Лимит памяти не действует на хосте macOS: `setrlimit` отказывает, в журнале это видно.
- **Новых значений `error_code` нет:** лимиты дают `invalid_image`, причина — в `last_error_code`. Реплика прежней версии упала бы на незнакомом значении enum.
- **Варианты:** `thumbnail` и `crop` — JPEG, `quality` 85; `optimized` — WebP, `quality` 80, `method` 4 (`method` 6 на пробе в 3,5 раза дольше без выигрыша), без EXIF, XMP и ICC. Crop из основы 1280 только при короткой стороне не меньше 256, иначе из декодированного: у 5000 × 10 иначе квадрат в 2 px. Профиль ICC отбрасывается, ограничение в отчёте.
- **Staging удаляет уборщик, не worker:** право удаления у него уже есть, а worker читает и пишет весь bucket. Цена — объект живёт до следующего прохода, 60 с.
- **Сверка** видит объекты staging: `orphan_staging` с порогом срока хранения, а не grace: база, восстановленная из копии, иначе быстро сделала бы staging живых строк «объектами без метаданных». Наличие объектов вариантов не проверяет: действия нет, рубрика не требует; ограничение остаётся в отчёте.
- **Точек сбоя в коде нет:** самое узкое окно «после COMMIT до ack» снимается снаружи: отложенный триггер, `pg_stat_activity`, `docker kill -s STOP`, `docker kill` (проба).
- **Остановка worker (S5):** верхняя граница `graceful_shutdown_seconds` — 8, закрытие клиентов одним сроком, худший случай 9,5 с.
- **`bench/`:** профиль загрузок больше не запускает брокер, `Profile.rollout_from` → `7f38948`, образ в паспорте — метка `com.docker.compose.image`.
- **Сценарии «Брокер не подтвердил задание» и «Загрузка без подтверждения брокера убрана» сохранены именем:** `openspec validate --strict` не даёт убрать сценарий правкой дельты. Первый теперь про 202 при остановленном брокере, второй — про реплику прежней версии на время замены.
### Вопросы
Вопросы преподавателю, переносятся в `REPORT.md` (`tasks.md`, задача 15.5). Прогон не останавливают: взята самая строгая трактовка, которая проходит публичные тесты, контракт и тесты не менялись.
1. Контракт требует применять EXIF orientation и компоновать alpha на белый только у thumbnail. Как с `crop` и `optimized`? Сделано: ориентация применяется у обоих (иначе EXIF, удалённый из WebP, повернул бы изображение), `crop` компонуется на белый (JPEG), а `optimized` сохраняет прозрачность (WebP её умеет). Другой ответ правит одну функцию и сценарий.
2. Контракт называет replay «явным операторским», но не говорит, как его вызывать, а новые возможности просит добавлять в `contracts/extensions.openapi.json`. Достаточно ли команды в контейнере? Сделано: `make replay`, HTTP-ручки нет: в API нет роли оператора. Другой ответ добавляет ручку поверх той же транзакции.
3. Изображение, которое не уложилось в лимиты времени или памяти обработки, — это `invalid_image` или отдельный код? Контракт приводит коды как пример. Сделано: `invalid_image`, точная причина — в записи для оператора. Другой ответ добавляет значение enum и требует порядка обновления реплик раньше worker.
4. Контракт требует retention для «неуспешных и непривязанных исходников», но молчит о конечных объектах, которые успела записать неудачная попытка. Сделано: по истечении срока удаляются и они, метаданные `failed` остаются. Другой ответ убирает один шаг очистки.
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-31
@@ -0,0 +1,543 @@
# Design
## Context
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. Контракт —
`contracts/README.md` («Фоновая обработка (с lab5)»),
`contracts/attachment-states.md`, `contracts/jobs.schema.json`, рубрика — `README.md`,
уровень «4» (она главнее любого списка здесь). Основа — design архива
`2026-10-31-async-attachments`: его схема уже содержит `published_at`, `next_attempt_at`,
`lease_expires_at`, значения вариантов `crop` и `optimized`.
### Код
Состояние — `7f38948` (архив `async-attachments`, ветка `feat/pipeline-reliability`):
- `AttachmentService._store`: staging → `queued` с заданием (tx2) → публикация с
подтверждением → `published_at` (tx3) → 202. Отказ брокера — условная отмена, 503;
- `AttachmentProcessingService`: claim по `redelivered` и сроку, декодирование в потоке
(`anyio.to_thread` + `CapacityLimiter(concurrency)`), `retry_delay_seconds` — пауза в месте
конкуренции, сообщение следующей попытки публикует сам worker;
- `src/worker/main.py`: `prefetch_count = concurrency`; сумма сроков остановки 8 + 5 × 0,5 = 10,5 с
при обещании «меньше 10» (замечание S5);
- `AttachmentCleanupService` убирает только `pending`; у worker права удаления нет, у уборщика есть;
- сверка видит только `<база>/attachments/`, класс `orphan_object` покрывает варианты с любым именем
(`parse_variant_key` читает все значения enum);
- `bench/`: брокер запускает только профиль загрузок; паспорт пишет `.Image`.
### Пробы (2026-10-31, scratchpad, проект compose `plprobe`)
Образы — пины рабочего стенда и образ `mtusi-messenger:lab5` (arm64, Docker 29.9.2, контейнер 1 CPU / 1 ГБ
как у worker); данные — tmpfs, volumes не создавались. Рабочий стенд не затронут. После проб контейнеры и
сеть удалены, ничего не осталось.
| Проверка | Результат |
|---|---|
| Pillow 13.0.0 в образе | `features.check('webp')` — да, libwebp 1.6.0, libjpeg-turbo 3.2.0: новой зависимости не нужно |
| Три варианта из одного декодирования, 40 Мпкс, новый процесс: CPU и `VmPeak` | PNG RGBA 0,36–0,55 с, 370 МиБ; RGB 0,46 с, 217 МиБ; палитра с tRNS 0,39 с, 408 МиБ; серый 16 бит 0,25 с, 417 МиБ; 1 бит 0,17 с, 133 МиБ; JPEG с `draft`: baseline 0,18 с, 66 МиБ, прогрессивный 0,22 с, 160 МиБ, CMYK 0,20 с, 77 МиБ. PNG из шума 10 MiB (3,5 Мпкс) 0,33 с, 105 МиБ, WebP из него 181 мс и 913 КиБ; fixture 0,11 с, 47 МиБ |
| `ru_maxrss` против `VmHWM` | `ru_maxrss` дочернего процесса наследует пик родителя через fork (452 МиБ у всех строк); верный пик — `VmHWM` из `/proc/self/status`: 363 МиБ у PNG RGBA 40 Мпкс |
| `RLIMIT_AS`, PNG RGBA 40 Мпкс | 300 МиБ — `MemoryError` ловится, код процесса свой; от 400 МиБ проходит. Серый 16 бит и палитра с tRNS падают на 350, проходят на 450. JPEG при 150 МиБ — `OSError`, а не `MemoryError` (пройдёт как «не декодируется»). Аварий и core нет |
| «Дорогой» JPEG в пределах контракта: прогрессивный 8000 × 5000, самый маленький скан (23 байта) повторён 445 227 раз, 10 485 757 байт | `inspect_image` принимает; за 60 с на 1 CPU не декодирован, родитель убивает за ~14 мс. Это настоящий случай «ограничено по времени», поток так не прервать |
| `RLIMIT_CPU` на этом файле | 2 и 5 с: код −24 (SIGXCPU) ровно на лимите, 2157 и 5015 мс по стене |
| Убийство ядром: четыре процесса PNG RGBA 40 Мпкс одновременно в контейнере 1 ГБ | три −9, один 0, родитель (PID 1) жив: ядро выбирает самых больших, worker переживает |
| Цена процесса на задание | `python -I` 21 мс, с `PIL.Image` 52 мс, с плагинами JPEG/PNG/WebP 90 мс; весь рендер fixture — 120 мс по стене. Forkserver с предзагрузкой — 9 мс (первый запуск 212 мс) |
| Детерминизм | два запуска fixture и PNG RGBA 40 Мпкс — одинаковые SHA-256 всех трёх вариантов |
| Метаданные | из JPEG и PNG с EXIF и ICC: `info` после `resize` их хранит, но `save` не пишет: WebP — один чанк `VP8 `, JPEG — маркеры без APP1/APP2, строки производителя в байтах нет. RGBA: `VP8X`, `ALPH`, `VP8 `, альфа 0 на прозрачных; непрозрачный RGBA — `VP8 `. L, 1, P, LA, CMYK, I;16 сохраняются |
| WebP: `quality`, `method`, 1280 × 800 | шум: q80 m4 702 КБ 129 мс, m6 704 КБ 343 мс, m2 1183 КБ 78 мс; мягкий шум: q80 m4 402 КБ 91 мс, m6 404 КБ 464 мс |
| macOS | `setrlimit(RLIMIT_AS)` — `ValueError`: на хосте лимит памяти не действует |
| План выборки relay, 208 тыс. заданий, из них 8 тыс. живых | индекс `(COALESCE(next_attempt_at, created_at), id) WHERE state='queued' AND published_at IS NULL`: Index Scan + LockRows, 0,05 мс на 100 строк, и в общем плане с параметром времени. **Состояние параметром — Seq Scan, 7,4 мс**: константа обязательна, как у уборщика. Счёт опубликованных — Index Only Scan, 0,35 мс на 5000; истёкшие аренды и потерянные — Index Scan, 0,007 мс |
| Публикация с подтверждением, один канал, `asyncio.gather` | 100 сообщений — 7 мс, 1000 — 101 мс |
| `declare_queue(...).declaration_result.message_count` | считает только готовые: 1111 → 1109 при двух неподтверждённых; потребителей называет отдельно |
| Очередь удалена мимо приложения | публикация на том же канале — `PublishError` за 2 мс, канал жив; новое соединение с объявлением — успех |
| Предел памяти (`rabbitmqctl set_vm_memory_high_watermark absolute 1MiB`) | публикация висит до срока, `TimeoutError`; часть сообщений уже в очереди: исход неизвестен, дубль возможен |
| Окно «после COMMIT до ack» без кода: отложенный триггер `pg_sleep(3)`, `pg_stat_activity` показывает `PgSleep active COMMIT;`, `docker kill -s STOP` клиента, строка `succeeded` в БД при замороженном клиенте, `docker kill` | статус контейнера `running`, не `paused`, поэтому SIGKILL работает; журнал клиента без строки о фиксации; выход 137; очередь: ready 1, unacked 0 за 0,64 с; следующий запуск — `redelivered`, `succeeded`, подтверждение без эффекта |
| SeaweedFS 4.48, `s3:prefix` с двумя значениями в `StringLike` | `<база>/attachments/`, `<база>/staging/` — 200 с ключами; `<база>/`, чужая база, `.s3-check/`, пустой — 403; удаление ключом уборщика — 204 |
### Что найдено до решений
1. **Живая попытка теперь по-настоящему ограничена сроком.** На уровне 3 поток декодирования сроком не
прерывался, поэтому lease пришлось бы продлевать; с отдельным процессом срок попытки жёсткий, и
аренда получается без пульса (решение 3).
2. **Сообщение перестаёт быть носителем работы.** Как только следующую попытку и возврат зависшей публикует
relay, а истина — в строке задания, любой лишний или потерянный дубль решается одной таблицей claim. Отсюда
и закрытие W2, и S6: паузы в worker больше нет.
3. **Сценарий нельзя убрать правкой дельты** (`openspec validate --strict`, как на уровне 3): потеря сценария у
MODIFIED — ошибка. Поэтому «Брокер не подтвердил задание» и «Загрузка без подтверждения брокера убрана» сохранены
именем, а их поведение описано заново; второй честно относится к смеси версий при замене реплик.
4. **Частично записанные объекты `failed`** контракт не называет, но они мусор: скачать их нельзя (409), а без
исходника replay невозможен. Удаляются вместе со staging по сроку (решение 9).
5. **Цепочка LB после отказа от публикации возвращается к числам лабы 4** (26 с и 73 с): самым долгим снова становится
путь компенсации (решение 11).
## Goals / Non-Goals
**Goals:**
- Уровень «4» рубрики целиком и шаг 4 сценария защиты, с доказательствами на закоммиченном коде.
- Настройки и счётчики, на которых `track1-queue-overload` измерит ≥3 настройки concurrency и prefetch на разных
размерах, throughput, queue lag, p95 до `ready`, RSS, backpressure и ограничение принятой работы (решение 8).
- Прежние механизмы не ломаются: компенсация, уборщик, сверка, места загрузки, цепочка таймаутов, `rolling_update`.
**Non-Goals** (сознательно):
- замеры перегрузки и ограничение принятой работы на входе API — `track1-queue-overload`;
- сверка наличия и размера объектов вариантов (решение 9);
- DLX и очереди с TTL в брокере: реестр и сроки — в PostgreSQL (решения 4 и 5);
- versioned pipeline и несколько `pipeline_version` — это трек 2, не выбран;
- разделение прав пользователей брокера и trace context — лабы 7 и 6;
- файлы исключений старых лаб — последний шаг всего прогона.
## Decisions
### 1. Outbox на `attachment_jobs`, брокера в пути запроса нет
`AttachmentService._store` после `_mark_queued` сразу отвечает 202. Убираются `_publish_job`, `_cancel_job`, параметр
`publisher`, `attachment_job_repo.delete_unstarted`, `attachment_repo.return_to_pending`, `src/infra/broker/instance.py`,
зависимости в `src/api/dependencies.py` и `src/main.py`, поля брокера в «Started API», `*broker-env` и `depends_on: rabbitmq`
у сервиса `api`.
Outbox — те же строки: `state = 'queued' AND published_at IS NULL`. Строка уже пишется в одной транзакции с `queued`
(решение 1 архива). **Что стало с 503** (вопрос преподавателю №3): отказ брокера больше не даёт 503; на загрузке 503 только от
S3 и PostgreSQL. Контракт требует к 202 «полный проверенный оригинал в staging, метаданные, намерение обработки» — всё это есть
без брокера.
Окна отказа контракта после изменения:
| Окно | Что происходит | Что видит клиент |
|---|---|---|
| после staging до записи задания | `pending` и объект staging; их убирает уборщик | 503 или обрыв |
| после COMMIT `queued` до ответа | работа идёт: relay опубликует | обрыв; вложение станет `ready`, клиент о нём не знает, как и в лабе 4 |
| после COMMIT до publish (relay упал) | намерение в БД, следующий проход публикует | 202 уже получен |
| после publish до confirm | исход неизвестен: новая публикация, возможен дубль | опрос `queued` |
| после confirm до отметки `published_at` | откат отметки, новая публикация, дубль | опрос `queued` или `processing` |
| после записи S3 до COMMIT результата | аренда истекает, новая попытка пишет те же ключи | опрос `processing`, затем `queued` |
| после COMMIT результата до ack | повторная доставка — no-op | опрос `ready` |
*Альтернатива:* попытка публикации в API «на удачу» и relay как страховка. Отвергнута: два пути публикации, зависший брокер
снова держит ответ до срока и место загрузки, пароль остаётся у реплик; выигрыш — до 0,25 с до `ready`. *Альтернатива:*
отдельная таблица outbox. Отвергнута: второе состояние той же работы и транзакция на две строки там, где уже есть одна.
*Альтернатива:* LISTEN/NOTIFY вместо опроса. Отвергнута: отдельное соединение мимо пула и свой путь переподключения, а опрос всё
равно нужен для сроков и после пропущенного уведомления. Опрос на пустой выборке — 0,05 мс (проба).
### 2. Relay
`python -m src.relay` → `src/relay/__main__.py` (`early_stop.install("relay")`, «Invalid relay settings» и код 2, `os._exit`) →
`src/relay/main.py` → `AttachmentRelayService` (`src/core/services/attachment_relay.py`). Свой engine (пул 1) и `JobPublisher`; S3 и
Pillow нет.
**Где живёт.** Отдельный сервис compose на образе API:
| Вариант | Почему нет |
|---|---|
| в репликах API | N издателей, клиент брокера и его пароль снова у реплик, фоновая работа в event loop обязательного пути; правило «реплики не держат фоновой работы» |
| в worker | остановка worker на защите остановила бы и публикацию: сообщения в очереди при остановленном worker исчезли бы из сценариев уровня 3 и `test_job_message_matches_schema`; масштабирование worker множит издателей без нужды |
| в уборщике | плановая сверка длится минуты и заняла бы единственный цикл; срок до `ready` зависел бы от неё |
**Проход** (`publish_pass`), повторяется сразу, пока пакет полон, иначе пауза `poll_interval_seconds` или сигнал:
1. **Истёкшие аренды.** `UPDATE attachment_jobs … WHERE id IN (SELECT … state='processing' AND lease_expires_at < :now ORDER BY
lease_expires_at LIMIT :n FOR UPDATE SKIP LOCKED)`: `state='queued'`, `last_error_code='lease_expired'`, `lease_expires_at`,
`next_attempt_at`, `published_at` — NULL. Вложения тех же `id` — `processing → queued`. Одна транзакция, порядок блокировок: задание, затем
вложение.
2. **Потерянные сообщения.** Если есть `queued` с `published_at < :now - republish_after_seconds`, `JobPublisher.ready_messages()` (активное
объявление очереди, `message_count`). Ноль готовых — таким заданиям `published_at = NULL`. Не ноль — ничего: длинная очередь не обрастает
копиями. Объявление ещё и создаёт удалённую очередь.
3. **Публикация.** Транзакция: `room = max_published_backlog - count_published()` (0 — без предела; места нет — конец прохода, запись один раз на
смену состояния); выборка до `min(batch_size, room)` due-строк `ORDER BY COALESCE(next_attempt_at, created_at), id FOR UPDATE SKIP LOCKED`;
`JobPublisher.publish_many()` с подтверждением под одним сроком `publish_timeout_seconds`; `published_at = :now` подтверждённым; COMMIT.
Статусы в выборках — `literal(..., literal_execute=True)`: иначе общий план не докажет условие индекса (проба: 7,4 мс и Seq Scan).
**Публикация внутри транзакции** — осознанное исключение из правила «брокера и S3 в транзакции нет», как DELETE у уборщика: блокировка строки
и есть признак «это задание публикует другой relay». Срок ограничен `publish_timeout_seconds` (2 с) < `request_timeout_seconds` (6 с), срока всего
шага, < `idle_in_transaction_session_timeout` (10 с): замороженный relay блокировок не удержит. Worker, получивший сообщение раньше COMMIT, ждёт
блокировку в `lock_job` и видит отметку: окна «сообщение есть, отметки нет» в обычной работе нет.
`JobPublisher` остаётся клиентом уровня 3: соединение лениво, сброс после любой ошибки, закрытие в фоне, `mandatory`, `on_return_raises`. Новые
`publish_many(items) -> set[UUID]` (задача на сообщение и `asyncio.wait` с общим сроком: подтверждённые до срока считаются, остальные отменяются; вернул подмножество — ошибка уже записана, соединение сброшено, а отметка и COMMIT идут для подтверждённых) и
`ready_messages()`.
**Сообщение:** `build_job_body(job, attempt=job.attempt + 1)`. `job_id` тот же, тело по схеме контракта.
**Несколько экземпляров** безопасны (`SKIP LOCKED`), на стенде один; второй появляется только на время замены образа. Порядок — по сроку, повтор
стоит в той же очереди, что новые: при пределе опубликованных он не голодает. Гарантии порядка обработки нет и не нужно: задания независимы.
**Задания уровня 3** без `published_at` подбираются тем же запросом; строки `queued` с `published_at` — сообщения уже в очереди; `processing` — истечёт
аренда. Отдельного шага нет.
*Альтернатива:* без блокировки, выборка и условная отметка. Отвергнута: два relay дублировали бы каждое задание в обычной работе. *Альтернатива:*
колонка «публикует relay X до T». Отвергнута: вторая аренда ради того, что строка блокировки делает даром. *Альтернатива:* транзакция на сообщение. Отвергнута:
20 подтверждений вместо пакета, а под нагрузкой один COMMIT на задание; пакет 100 подтверждается за 7 мс.
### 3. Claim, аренда и fencing
Worker больше не публикует: из `AttachmentProcessingService` уходит `publisher`, `redelivered` пишется только в журнал. Claim под `lock_job`, сравнение времени —
часами приложения (`utcnow()`), как у остальных отметок; запас аренды закрывает расхождение часов консольного процесса и ВМ:
| `state` | условие | действие | сообщение |
|---|---|---|---|
| строки нет или чужое вложение | | `Skipped job message`, `unknown` | ACK |
| `succeeded` | | проверка: вложение `ready`, `thumbnail` есть (строки уровня 3 других вариантов не имеют), `finished` | ACK |
| `failed` | | `finished`: replay публикует своё сообщение | ACK |
| `queued` | `published_at IS NULL` и `next_attempt_at > now` | `not_due`: relay опубликует в срок (S6) | ACK |
| `queued` | иначе | бюджет исчерпан — `failed` `retry_exhausted`; иначе взять | ACK после итога |
| `processing` | `lease_expires_at > now` | `busy`, без записи (W2) | ACK |
| `processing` | аренда истекла | бюджет исчерпан — `failed`; иначе взять | ACK после итога |
Бюджет: `attempt - attempt_base >= max_attempts`. Взятие: `attempt + 1`, `lease_expires_at = now + job_timeout_seconds + lease_margin_seconds`.
**Почему ACK у `busy`.** Лишнее сообщение не нужно: если живая попытка умрёт, работу вернёт relay по аренде. Возврат в очередь занимал бы место prefetch и крутился бы
паузами, а `redelivered` живого от потерянного не отличает: брокер ставит его и после `nack`. Цена — после KILL worker следующая попытка начнётся не сразу, а по истечении аренды
(по умолчанию до 70 с). Это честный ответ на вопрос защиты: отличить мёртвого от живого можно только сроком.
**Почему без пульса.** Шаги попытки прерывает `asyncio.timeout(job_timeout_seconds)`, процесс обработки убивается (решение 7), поэтому попытка не может жить дольше срока. Истёкшая
аренда — значит, процесс мёртв или заморожен. Пульс сократил бы восстановление до десятков секунд, но добавил бы запись на задание каждые несколько секунд, зависимость от event loop
и ложные срабатывания под перегрузкой — ровно там, где их будет мерить трек 1.
**Fencing.** Фиксация под `lock_job`: `state = 'processing' AND attempt = :своя`, иначе `Skipped job message`, `superseded`, ACK. То же уже есть у `_fail` и `_retry`. Уровень 3 принимал результат
старой попытки; теперь замороженный процесс после разморозки ничего не меняет. Объект он всё же может дописать теми же байтами: ключ тот же, версия декодера та же (ограничение, `REPORT.md`).
**Worker** подтверждает всегда, кроме `DROP` (сообщение не по схеме) и `REQUEUE`: PostgreSQL недоступен (записать нельзя, пауза `reconnect_seconds`) или остановка.
*Альтернатива:* пульс (см. выше). *Альтернатива:* взять задание сразу при `redelivered`. Отвергнута: это и есть W2, дубль параллельно живой попытке. *Альтернатива:* опознавать потерянного по
имени процесса в строке. Отвергнута: второй worker и перезапуск неотличимы без реестра живых, а срок всё равно нужен.
### 4. Повторы: backoff с jitter, постоянные и временные ошибки
Пауза перед попыткой `N + 1`: `d = min(retry_max_delay_seconds, retry_base_delay_seconds × 2^(N−1))`, `random.uniform(d / 2, d)` — чистая функция в модуле сервиса; `N` считается от последнего replay.
При 5 / 300 и пяти попытках сумма пауз 37,5–75 с: рестарт S3 (~25 с) укладывается, как на уровне 3. Транзакция `processing → queued` пишет `next_attempt_at`, `published_at = NULL`; сообщение
подтверждается сразу. Ожидание не занимает место конкуренции и не держит сообщение, остановка worker его не прерывает, а claim соблюдает срок (S6 закрыт).
| Класс | Причина (`last_error_code`) | Итог |
|---|---|---|
| постоянная | `undecodable`, `limit_pixels`, `limit_memory`, `limit_cpu` | `failed`, `invalid_image` |
| постоянная | `source_missing`, `source_corrupted` | `failed`, `processing_failed` |
| временная | `storage_unavailable`, `timeout`, `render_killed`, `render_crashed`, `lease_expired`, `unexpected` | `queued`, затем `retry_exhausted` |
| не попытка | PostgreSQL недоступен | сообщение в очередь после паузы |
Новых значений `error_code` нет: реплика прежней версии падает на незнакомом значении enum (`_to_dto`), а клиенту различие лимита и порчи ничего не даёт. Причина — для оператора.
*Альтернатива:* полный jitter `uniform(0, d)`. Отвергнута: нижняя граница суммы пауз стремится к нулю, и рестарт S3 мог бы исчерпать попытки. *Альтернатива:* очереди с TTL и DLX, плагин отложенной доставки.
Отвергнуты: срок и счёт попыток контракт просит хранить устойчиво, они уже в БД; аргументы очереди неизменяемы, плагин — ещё одна зависимость образа. *Альтернатива:* не считать попытки при отказе S3. Отвергнута:
«бесконечный немой retry недопустим»; `failed` при долгом отказе лечит replay.
### 5. Реестр `failed` и replay
Реестр — строки `attachment_jobs` с `state = 'failed'`, причина и код уже есть. **DLQ брокера не нужна**: всё принятое живёт в БД, а сообщение не по схеме работы не несёт и отбрасывается с записью `error`.
Команда: `python -m src.relay replay [--attachment-id ID]... [--error-code C] [--reason R] [--limit N] [--apply] [--operator NAME]`, цель `make replay`, в контейнере `docker compose run --rm --no-deps relay replay …`. Нужен только PostgreSQL. По умолчанию
dry-run: журнал показывает реестр. С `--apply` выбор обязателен, иначе код 2: случайно повторить всё нельзя. HTTP-ручки нет: контракт её не описывает, у API нет роли оператора (вопрос преподавателю, `QUESTIONS.md`).
`AttachmentReplayService.replay_one` — одна транзакция, порядок блокировок общий: `lock_job`, `lock_attachment`, проверки, `attachments`: `failed → queued`, `error_code` NULL; задание: `queued`, `attempt_base = attempt`, `last_error_code`, `next_attempt_at`, `lease_expires_at`, `published_at`, `finished_at` — NULL; запись `attachment_job_replays`. Сообщение
публикует relay. Отказы, без изменений: `not_found`, `already_ready`, `not_failed`, `source_gone` (`staging_key IS NULL`). Код выхода 3 при любом отказе. Гонка с очисткой исключена блокировкой строки вложения.
Replay `invalid_image` разрешён: оператор мог поправить декодер; попытка упадёт снова, ограниченно. Номер `attempt` растёт монотонно: это fencing-токен, поэтому бюджет — отдельной колонкой, а не сбросом.
*Альтернатива:* сбрасывать `attempt` в 0. Отвергнута: попытка до replay с тем же номером смогла бы зафиксировать результат. *Альтернатива:* HTTP-ручка в `contracts/extensions.openapi.json`. Отвергнута: роль оператора и её проверка — вне контракта этой лабы, CLI в контейнере на защите проще и безопаснее. *Альтернатива:* DLQ сообщений. Отвергнута: второй реестр той же работы.
### 6. Варианты
`src/utils/image_variants.py` вместо `thumbnail.py`. Чистая функция `render_variants(data, *, max_pixels) -> RenderedVariants`; `thumbnail_size` — частный случай `fit_size(width, height, max_side)`. Pillow импортирует только этот модуль, а его — только `src/worker/render.py`.
Одно декодирование, порядок:
1. `Image.open(formats=("PNG", "JPEG"))`, пиксели сверх лимита — `TooManyPixels`; orientation из EXIF; размеры считаются по показанным сторонам, как у thumbnail (своё округление вниз).
2. JPEG: `draft("RGB", (max(opt_w, min(w, 128)), max(opt_h, min(h, 128))))` — масштаб DCT под самый большой нужный размер.
3. `_prepared` прежний; `base = resize(opt, LANCZOS, reducing_gap=2.0)` — основа для optimized и thumbnail.
4. Crop: центрированный квадрат короткой стороны. Источник — `base`, если её короткая сторона не меньше 256, иначе декодированное (у 5000 × 10 основа 1280 × 2, из неё квадрата не получить): `resize((128, 128), LANCZOS, box=…, reducing_gap=2.0)`.
Центр при повороте тот же, поэтому квадрат считается в хранимых координатах; расхождение смещения в 1 px при нечётной разности не имеет значения.
5. Transpose по orientation — на малых изображениях.
6. Thumbnail и crop: альфа на белый, JPEG `quality=85`. Optimized: без компоновки, `save("WEBP", quality=80, method=4)`; метаданные не передаются.
| Вариант | Формат | Размер | Параметры | Метаданные |
|---|---|---|---|---|
| `thumbnail` | JPEG | вписан в 256 × 256, без увеличения | `quality=85` | EXIF и ICC не пишутся |
| `crop` | JPEG | 128 × 128, центр, маленькие растягиваются | `quality=85` | то же |
| `optimized` | WebP | вписан в 1280 × 1280, без увеличения | `quality=80`, `method=4`: `m6` на пробе в 3,5 раза дольше без выигрыша | EXIF, XMP, ICC нет; ориентация применена; прозрачность сохранена |
Цвет: профиль ICC отбрасывается, учебные данные — sRGB (ограничение, `REPORT.md`). Результат детерминирован (проба). Ключ — `variant_key(…, name)`; фиксация — три строки `attachment_variants` и `ready` одной транзакцией.
*Альтернатива:* декодировать на каждый вариант. Отвергнута: три раза по 0,5 с и три пика. *Альтернатива:* crop всегда из основы. Отвергнута: у вытянутых изображений квадрат в 2 px. *Альтернатива:* альфа на белый и у WebP. Отвергнута: контракт требует белый только у thumbnail, WebP прозрачность умеет. *Альтернатива:* pyvips. Отвергнута на уровне 3.
### 7. Лимиты: дочерний процесс на задание
`src/infra/render/client.py` — `ImageRenderer.render(data) -> RenderedVariants`: `asyncio.create_subprocess_exec(sys.executable, "-m", "src.worker.render", …)`, рабочий каталог — корень приложения. Окружение — только `PATH`, `PYTHONDONTWRITEBYTECODE`, `PYTHONUNBUFFERED`,
`MALLOC_MMAP_THRESHOLD_`: секретов в нём нет. Вход — байты в stdin, параметры — аргументы. Выход — строка JSON (размеры, длины, `VmHWM`), затем байты вариантов; SHA-256 считает родитель по тому, что запишет. `src/worker/render.py` первым делом ставит лимиты, а Pillow импортирует после них.
| Лимит | Механизм | Превышение | Итог |
|---|---|---|---|
| байты | `stored.size != size_bytes` до чтения тела; `size_bytes` ограничен CHECK контракта | `source_corrupted` | постоянная |
| пиксели | `width × height` до декодирования | код 5, `limit_pixels` | постоянная |
| память | `RLIMIT_AS = render_memory_limit_mib` | `MemoryError`, код 4, `limit_memory` | постоянная |
| CPU | `RLIMIT_CPU = render_cpu_limit_seconds`, жёсткий на секунду больше; `RLIMIT_CORE = 0` | сигнал SIGXCPU, `limit_cpu` | постоянная |
| время | родитель: `asyncio.timeout(render_timeout_seconds)`, `kill` | `timeout` | временная |
| не декодируется | ошибка Pillow, код 3 | `undecodable` | постоянная |
| убит ядром | код −9, родитель не убивал | `render_killed` | временная |
| иное | другой код или испорченный вывод | `render_crashed` | временная |
Различие CPU и стены: CPU — свойство файла, повтор не поможет; стена — ещё и свойство нагрузки стенда. `finally` у клиента всегда убивает процесс и дожидается его с коротким сроком: отмена попытки при остановке или по сроку процесс не оставит.
**Значения.** `render_memory_limit_mib` 450: наибольший `VmPeak` на пробе 417 МиБ. Бюджет контейнера: пик `VmHWM` не больше ~410 МиБ на процесс × 2 + worker ~130 МиБ с двумя телами ≈ 950 МиБ < 1 ГБ (число worker уточняет задача 5.2). Сумма самих лимитов, 2 × 450 + 130 = 1030 МиБ, чуть больше 1024, но `VmHWM` меньше адресного пространства; а если памяти всё же не хватит, ядро убьёт самый большой процесс обработки, а не worker (проба), и это временная ошибка. `render_cpu_limit_seconds` 15: наибольшее законное на пробе — 0,55 с, запас от шумного файла и слабого хоста в десятки раз. `render_timeout_seconds` 40: при конкуренции 2 на 1 CPU два дорогих файла получают по половине ядра, 15 с CPU — это 30 с по стене, и постоянная ошибка наступает раньше временной; меньше `job_timeout_seconds` (валидатор), чтобы осталось время на запись. При большей конкуренции на том же CPU срок сработает раньше лимита: файл получит временную ошибку и кончится `retry_exhausted`, это видно в причине и мерит трек 1.
На macOS `setrlimit(RLIMIT_AS)` — `ValueError`: процесс продолжает, вывод отмечает, что лимит не применён, в журнале это видно (ограничение консольного запуска). `VmHWM` там нет — поле `null`.
*Альтернатива:* потоки (уровень 3). Отвергнута: поток не прервать, `MemoryError` и падение декодера роняют worker, лимит памяти — только на весь контейнер. *Альтернатива:* `ProcessPoolExecutor`. Отвергнута: убитый процесс ломает весь пул, `RLIMIT_CPU` накапливается на процесс. *Альтернатива:* forkserver с предзагрузкой — 9 мс вместо ~70 мс на задание. Отвергнута сейчас: секреты родителя в окружении, блокирующие каналы поверх asyncio, свой жизненный цикл сервера; граница — один модуль, и если трек 1 покажет, что запуск ограничивает маленькие файлы, это точка замены. *Альтернатива:* постоянный процесс на слот. Отвергнута: лимит CPU накапливается, память не возвращается, а сброс после убийства — та же сложность.
### 8. Prefetch, backpressure и что есть для трека 1
`[worker] prefetch` отдельно от `concurrency`. `src/worker/main.py`: `set_qos(prefetch_count=prefetch)`, каждая доставка — задача, `asyncio.Semaphore(concurrency)` вокруг `service.handle`: сообщение сверх конкуренции ждёт без взятия и без аренды. `CapacityLimiter` не нужен. `prefetch < concurrency` допустим и наблюдаем: это рабочая конкуренция.
Цепочка сдерживания: места загрузки API (есть) → БД как буфер намерений → `max_published_backlog` → предел памяти брокера (relay получает отказ по сроку) → `prefetch` → `concurrency` → лимит контейнера. Ничто в этой цепочке не отказывает клиенту: приём ограничен только местами загрузки и диском. **Само ограничение принятой работы вводит `track1-queue-overload`.** Дорогу не закрывает: одно место в `_store` до строки `pending`, счёт по индексам решения 10 — миллисекунды.
| Что мерит трек 1 | Откуда брать |
|---|---|
| настройки | `WORKER__CONCURRENCY`, `WORKER__PREFETCH`, `WORKER__RENDER_*`, `RELAY__MAX_PUBLISHED_BACKLOG`, `RELAY__BATCH_SIZE`, `DATABASE__POOL_SIZE` у worker; лимиты контейнера `BENCH_WORKER_*`; всё — окружением без пересборки |
| throughput | `finished_at` заданий по окну; записи «Attachment became ready» |
| queue lag | возраст старейшего `queued`; `driver.py pipeline-state`; `rabbitmqctl list_queues messages_ready messages_unacknowledged`; `queue_wait_ms` в «Started job attempt» |
| p95 до `ready` | `finished_at - created_at` строки задания |
| RSS | cgroup контейнера worker (сэмплер `bench/`, режим `scan`), он считает родителя и дочерние; `render_peak_kib` на задание |
| backpressure | «Relay pass»: `published_backlog`, смена состояния предела; `messages_ready`; число `queued` без отметки |
| разделение затрат | `duration_ms`, `render_ms`, `queue_wait_ms` |
`driver.py pipeline-state` — только чтение: JSON с числом заданий по состояниям, due, ждущих срока, опубликованных и не взятых, истёкших аренд, возрастом старейшего, состоянием очереди.
### 9. Очистка staging, сверка и права
**Кто удаляет.** Уборщик: право `s3:DeleteObject` у него есть, а у worker нет и не появляется: worker читает и пишет весь bucket, и случайное удаление у него было бы опаснее пропущенной очистки (решение 12 архива). Цена — объект staging живёт до следующего прохода (`interval_seconds`, 60 с).
**`AttachmentCleanupService.clean_staging(*, retention_before, batch_size, stop_requested)`** — в том же цикле после `clean_stale_pending`, и в `--once`. Кандидаты keyset по индексу `(status, updated_at, id) WHERE staging_key IS NOT NULL`: сначала `ready`, затем `failed` с `updated_at < :retention_before`. Каждая строка — транзакция: `FOR NO KEY UPDATE SKIP LOCKED` с теми же условиями → DELETE в S3 → `staging_key = NULL` → COMMIT. Вызов S3 внутри транзакции, как шаг 2 уборки: не дольше срока шага (6 с). **Именно `NO KEY`** (`with_for_update(key_share=True, skip_locked=True)`): отправка сообщения со ссылкой на вложение берёт `FOR KEY SHARE` проверкой внешнего ключа, и обычный `FOR UPDATE` заставил бы её ждать DELETE в S3, а при зависшем S3 — получить 503, хотя сообщение от S3 не зависит. У строк `pending` этой проблемы не было: на них сообщения не ссылаются. Та же блокировка — у replay.
- `failed`: сначала объекты вариантов всех имён (`variant_key`) и `object_key`, затем staging. Отсутствие объекта — не ошибка. Все DELETE укладываются в срок шага; не уложились — откат, ключ на месте, следующий проход повторит.
- ключ вне `<база>/staging/` (`is_own_staging_key`): `warning`, строка не меняется;
- сбой S3 или PostgreSQL прерывает проход, итог — `Finished staging cleanup pass`.
Сбой после DELETE до COMMIT: ключ в строке есть, объекта нет. Для `ready` это ничего не значит, для `failed` replay получит `source_missing` и снова `failed` — безопасно.
Срок: `[cleaner] staging_retention_seconds`, 86400 — значение из `.env.example` skeleton (`STAGING_RETENTION_SECONDS=86400`). Закрывает вопрос преподавателю №2.
**Что видит сверка:**
| Объект | S3 → БД | БД → S3 |
|---|---|---|
| `<база>/attachments/<id>/original` | как раньше | только `ready`, как раньше |
| `<база>/attachments/<id>/v<N>-<имя>` | строки нет — `orphan_object`; есть — свой | **не проверяется** |
| `<база>/staging/<id>/original` | новый шаг: строка этого `id` с этим `staging_key` — пропуск; иначе `orphan_staging` старше срока хранения, моложе — свежий | не проверяется: отсутствие у `queued` даст `processing_failed` |
| другой ключ под `<база>/staging/` | `unknown_object` | — |
`orphan_staging` — в `LIMITED_KINDS` и `ACTION_ORDER` после `orphan_object`, перепроверка в БД и HEAD перед действием. `listed_objects` остаётся про префикс вложений (её сверяет модель `bench/reconcile.py`), новое поле `listed_staging`. Список — обёрткой `_list_staging`: тот же сигнал и предел скорости. Закрывает объект, дописанный замороженным API: спек `storage-consistency` обещал это здесь. Порог — срок хранения, а не grace: база, восстановленная из копии, иначе превратила бы staging живых строк в «объекты без метаданных» быстрее, чем оператор заметит.
Варианты БД → S3 сверка не проверяет. Рассмотрено: `variant_missing` только в отчёте. Отвергнуто на этом уровне: действия нет (байты можно получить только replay `ready`, а он запрещён), рубрика этого не требует, API и так пишет `error` при скачивании; лишний запрос на страницу и класс ради отчёта. Ограничение остаётся в `REPORT.md`.
**Права.** `infra/s3/bootstrap.sh`: список уборщика с условием `s3:prefix` на два значения, `<база>/attachments/*` и `<база>/staging/*` (проба: работает). `S3_CLEANER_LIST_PREFIX` прежний, staging выводится из проверенного имени базы. `apply` и `check` — новые строки. У worker и API прав не прибавилось.
*Альтернатива:* удалять staging в worker после фиксации. Отвергнута: право удаления шире, чем задача. *Альтернатива:* очистка отдельным сервисом. Отвергнута: у уборщика уже есть ключ, цикл и остановка. *Альтернатива:* lifecycle-правило bucket. Отвергнута: не знает состояния вложения и удалит текущую работу.
### 10. Схема
Две ревизии поверх `a1d4c7e90b23`, только расширение (`migrations.md`):
1. `added_job_replays_and_attempt_base`, первой строкой `SET LOCAL lock_timeout = '2s'`:
- `attachment_jobs.attempt_base integer NOT NULL DEFAULT 0`, CHECK `attempt_base BETWEEN 0 AND attempt` `NOT VALID`;
- `attachment_job_replays`: `id uuid` PK, `job_id` FK → `attachment_jobs` без каскада, `operator text` (CHECK длины 1–64), `error_code text`, `reason text`, `attempt integer` CHECK ≥ 0, `created_at timestamptz`, индекс по `job_id`.
2. `added_job_outbox_indexes`, `autocommit_block`, `SET lock_timeout`, `CONCURRENTLY`, `if_not_exists`:
- `ix_attachment_jobs_outbox` — `(COALESCE(next_attempt_at, created_at), id) WHERE state = 'queued' AND published_at IS NULL`;
- `ix_attachment_jobs_published` — `(published_at) WHERE state = 'queued' AND published_at IS NOT NULL`;
- `ix_attachment_jobs_lease` — `(lease_expires_at) WHERE state = 'processing'`;
- `ix_attachments_staging_cleanup` — `(status, updated_at, id) WHERE staging_key IS NOT NULL`.
Индексы — отдельной ревизией: `CONCURRENTLY` не живёт в транзакции, а ревизия с колонкой и таблицей обязана быть атомарной. Модели — `Index(..., postgresql_where=text(...))`, индекс по выражению autogenerate не сравнивает; `alembic check` проверяет колонки и таблицы. Индекс по реестру `failed` не нужен: выбор оператора редок, а строк `failed` мало.
**Смесь версий** (`make rolling_update` с уровня 3): новых статусов и `error_code` нет, поэтому 500 на чтении, как при переходе 201 → 202, здесь нет.
| Кто | На новой схеме |
|---|---|
| прежняя реплика API | загружает и публикует сама; отмена при отказе брокера — прежняя; relay может опубликовать ту же строку: дубль, no-op |
| прежний worker | берёт сообщения, делает только thumbnail (`ready` без `crop` и `optimized`, скачивание — 404): поэтому worker обновляется раньше relay |
| новая реплика и прежний relay | relay ещё нет: задания ждут, загрузка отвечает 202 |
| новый worker и старые строки `ready` | не трогает, `ready` с одним thumbnail остаются как есть |
| прежний уборщик | staging не чистит, ничего не ломает |
| новый уборщик на прежней политике | `AccessDenied` на списке staging: сверка прервана, уборка работает; поэтому `s3-bootstrap` первым |
### 11. Цепочка LB
После тела: `проверка ~4 + tx1 6 + PUT 5 + tx2 6 ≈ 21 с`, а ветка компенсации `… + DELETE 5 ≈ 26 с`, и это теперь наибольшее молчание. Длительность загрузки `17 + 30 + 26 ≈ 73 с` < дренаж 90 с. Значения `timeout server` 30 с и `ROLLOUT_DRAIN_TIMEOUT` 90 с не меняются: запас вырос. Правятся комментарии `infra/haproxy/haproxy.cfg`, `scripts/rolling-update.sh`, `balancer.md`, `settings.md` и `REPORT.md`. `driver.py lb-upload-timeouts` не меняется: заглушка отвечает 202.
### 12. Настройки
| Секция | Поля (по умолчанию) |
|---|---|
| `[worker]` | `concurrency` (2), `prefetch` (2), `max_attempts` (5), `job_timeout_seconds` (60), `lease_margin_seconds` (10), `retry_base_delay_seconds` (5), `retry_max_delay_seconds` (300), `render_timeout_seconds` (40, меньше `job_timeout_seconds`), `render_cpu_limit_seconds` (15), `render_memory_limit_mib` (450), `graceful_shutdown_seconds` (8, ≤ 8), `reconnect_seconds` (2) |
| `[relay]` | `poll_interval_seconds` (0,25), `batch_size` (100), `max_published_backlog` (1000, 0 — без предела), `republish_after_seconds` (300), `failure_pause_seconds` (2) |
| `[cleaner]` | ещё `staging_retention_seconds` (86400) |
| `[broker]` | поля прежние; читают relay и worker |
Все новые `float` — `allow_inf_nan=False`. Проверка соотношений — на полях через `info.data`, как `idle_longer_than_request`, чтобы в ошибке не было значений секции. Прежний ключ `retry_delay_seconds` в существующем `config.toml` молча игнорируется: `extra` секции — по умолчанию; шага оператора нет. `STAGING_RETENTION_SECONDS` → `[cleaner] staging_retention_seconds` в шапке `.env.example` и `REPORT.md`. Новых секретов нет.
### 13. Стенд
- **`docker-compose.yml`:** сервис `relay`: образ API, `pull_policy: never`, `entrypoint: ["python", "-m", "src.relay"]`, `restart: unless-stopped`, `<<: [*db-env, *broker-env]`, `DATABASE__POOL_SIZE: "1"`, `depends_on` PostgreSQL и брокер healthy, `migrate` completed, `healthcheck: disable: true`, `stop_grace_period: 10s`, лимиты 0,25 CPU / 256 МБ. У `api` убираются `*broker-env` и `rabbitmq`. Комментарии об окружении и соединениях.
- **Суммы:** постоянные 9,0 CPU, 4992 МБ; с разовыми 10,0 CPU, 5376 МБ. Соединения PostgreSQL: `API_REPLICAS × 10 + migrate 1 + cleaner 1 + worker 2 + relay 1` = 25, при замене 35.
- **`scripts/restart.sh`:** relay не трогает, как worker и уборщика; строка в шапке. **`rolling-update.sh`:** только комментарий; порядок обновления — Migration Plan.
- **CI:** `.github/ci/compose.yml` — `relay` с образом прогона и `configs`; шаги workflow те же.
- **`Makefile`:** `run_relay` (консоль, те же мосты `.env`), `replay`. `run_dev` по-прежнему поднимает брокер: он нужен `run_worker` и `run_relay`.
- **`make test_isolated`:** `<проект>-test-relay` рядом с `-test-worker`, журналы и уборка. Уборщика там нет: очистка staging проверяется на стенде отказов.
### 14. Внедрение сбоев без кода приложения
Точек сбоя в коде нет: всё снаружи, через `fault_hook.py` и команду драйвера. Таблица окон:
| Окно | Как держим | Как рвём |
|---|---|---|
| после COMMIT `queued` до publish | relay убит до загрузки | `kill relay`, `start relay` |
| после confirm до отметки | `fail-attachments relay-stall <filename>`: `BEFORE UPDATE OF published_at` на `attachment_jobs`, `pg_sleep(3)` по `filename` вложения; ждём `queue-state`: сообщение есть, `published_at` пуст | `kill relay`, транзакция откатывается |
| после записи S3 до COMMIT | `ready-stall`: оператор ждёт `pg_sleep(4)`, объекты уже записаны (`object-sha256`) | `kill worker` |
| после COMMIT до ack | `ready-commit-stall`: отложенный триггер ограничения, `pg_sleep(3)` в COMMIT; `wait-commit-stall` ждёт `PgSleep`/`COMMIT` в `pg_stat_activity`; `freeze worker` — `docker kill -s STOP`; ждём `succeeded` | `kill worker`: контейнер не `paused`, сигнал проходит (проба) |
| зависший worker | `pause s3`, попытка в вызове S3; `pause worker`; срок аренды; `unpause s3`; `run-worker` — второй процесс | `unpause worker` |
| дорогое изображение | `images.jpeg_scan_bomb()` — настоящий файл | лимит CPU |
| предел памяти, короткий срок, prefetch | `run-worker WORKER__…=…`: второй worker с окружением, основной остановлен | лимиты |
| убитый процесс обработки | `kill-render`: `docker exec` в контейнере worker, SIGKILL процессу `src.worker.render` | — |
| предел памяти брокера | `broker-memory-limit <значение>`: `rabbitmqctl set_vm_memory_high_watermark` | снятие |
Новые действия hook: `stop|start|kill|pause|unpause relay`, `freeze worker`, `run-worker K=V…`, `run-relay K=V…`, `stop-extra`, `kill-render`, `render-env`, `wait-commit-stall`, `object-sha256 <ключ>`, `broker-memory-limit`, режимы `ready-commit-stall`, `relay-stall`, `set-sha256`, `set-staging-key`, `set-next-attempt`, `delete-variant`, `cancel-to-pending` (как отмена прежней версии), `replay <аргументы>` (записи и `exit_code=`), `reconcile … --staging-retention S`, `replays <id>`. `peek-job` и `publish-job` переходят из контейнера API в одноразовый контейнер relay: у API больше нет настроек брокера. `delete-row` удаляет и записи аудита.
*Альтернатива:* переменная `FAULT_POINT` в коде, выключенная по умолчанию. Отвергнута: проба показала, что самое узкое окно снимается снаружи, а точка сбоя в коде — это код продакшн-пути, который рабочий стенд мог бы включить одной строкой окружения.
### 15. Тесты
**Клиент и генераторы:** `api_client.wait_job`-хелперы не меняются; `assert_one_thumbnail` → `assert_variants` (три варианта, по объекту на каждый, `variant-object-count` 3, байты и поля); `contract.py` — содержимое WebP; `images.py` — `jpeg_scan_bomb`, полосы, `jpeg_with_metadata`. Сценарии уровня 3 меняют только ожидания, описанные дельтами. `test_missing_variant` переходит на стенд отказов с `delete-variant`: иначе варианта без метаданных не получить.
**Стенд отказов:** `failures.compose.yml` — `relay` (`restart: "no"`, `RELAY__POLL_INTERVAL_SECONDS: "0.2"`, `RELAY__REPUBLISH_AFTER_SECONDS: "5"`); `worker`: `WORKER__MAX_ATTEMPTS: "4"`, `WORKER__RETRY_BASE_DELAY_SECONDS: "4"`, `WORKER__RETRY_MAX_DELAY_SECONDS: "16"`, `WORKER__JOB_TIMEOUT_SECONDS: "10"`, `WORKER__LEASE_MARGIN_SECONDS: "2"`, `WORKER__RENDER_TIMEOUT_SECONDS: "8"`, `WORKER__RENDER_CPU_LIMIT_SECONDS: "3"`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS: "2"`; уборщик: `CLEANER__STAGING_RETENTION_SECONDS: "60"`. Сумма пауз 14–28 с больше возврата S3 (~8 с): «Временная ошибка» успевает. `run_failures.py` — relay в запуске, `FAULT_RELAY_*`, `FAULT_WORKER_*` по новым именам, журнал relay при падении, уборка `<проект>-worker-extra`, `<проект>-relay-extra`. Ожидаемое время: плюс ~35 проверок, ~12 мин; итог — «Уточнения apply».
**Ожидаемая смена старых тестов** (разрешённая дельтами): `test_durable_state_at_202`, `test_upload_with_broker_stopped` и `_paused`, `test_queue_deleted`, `test_duplicate_during_processing` (`busy` теперь ACK), `test_worker_killed_during_processing` (ждёт аренду), `test_ready_failure_retried`, `test_attempts_exhausted`, `test_transient_error_retried`, `test_original_published_unchanged`, `test_defense_scenario`, тесты `peek-job`.
**Сверка покрытия:** `job-outbox` в `CAPABILITIES`; таблица — ниже. Исключения прежние, у `data-storage` «Ограничения обработки в схеме» проба расширяется.
### 16. `bench/`
- **Паспорт (`.Image`):** `app_containers` и `image()` пишут метку `com.docker.compose.image`, а при её отсутствии — `.Image`; поле `id` остаётся именем. Сравнение образов профиля замены — по ней (`docker.md`).
- **`bench.compose.yml`, `bench.env`:** `relay` описан, как `worker`, не запускается, лимиты `BENCH_RELAY_*`; `Profile.relay_cpus`, `relay_memory`. Реплики стенда больше не получают окружения брокера.
- **Профиль загрузок:** брокер не запускается, `start_broker` и новый volume брокера из прогона, пометка `broker_down` и образ брокера в паспорте убираются, сводка без брокера. Смена методики названа в спеке; метка `baseline` снята на `ff1a83b` и не сравнивается, а регресс показывает `make bench_uploads_quick`. Метод `start_broker` и поля `Profile` остаются: их возьмёт трек 1.
- **Профиль замены:** `Profile.rollout_from` → `7f38948`, метка для отчёта `pipeline-reliability`.
- **Профиль сверки:** `reconcile_before` прежний; модель: `listed_objects` не меняется, одна страница списка staging — в счёте LIST обоих источников.
- **Спек:** «на образе до change» → «на образе commit из методики».
### 17. Драйвер и защита
- **`defense-faults`** (шаг 4, рабочий стенд через LB, ~4 мин: аренда 70 с): (а) `ready-stall`, объекты записаны, SHA-256 до сбоя, `kill worker`, запуск, ожидание аренды, те же SHA-256, `attempt` 2; (б) `ready-commit-stall`, заморозка, `succeeded`, `kill worker`, запуск, `redelivered`, тот же `updated_at`, `attempt` 1, очередь пуста; (в) `kill relay`, загрузка 202, сообщения нет, запуск, `ready`; `relay-stall`, сообщение есть, отметки нет, `kill relay`, запуск, два сообщения при остановленном worker, запуск, `ready`, `attempt` 1; (г) замена staging → `failed` `processing_failed` → реестр → возврат объекта → replay → `ready`; replay готового — отказ, код 3. Триггеры — только на уникальный `filename` прогона, снимаются в `finally`, worker и relay запускаются при любом исходе, по сигналу тоже (`WorkerGuard` → общий сторож). → `evidence/attachments/defense-faults.md`. Тем же порядком на стенде отказов — `test_defense_faults`.
- **`relay-process`** — как `worker-process`: PID 1, нет healthcheck, лимиты, запись о старте, неверные `RELAY__*`, остановка простаивающего и на старте, рестарт хранилищ. → `evidence/relay/process.md`.
- **`pipeline-state`** — решение 8.
- **`defense-scenario`:** relay не трогает, ждёт сообщение в очереди с опросом, проверяет три варианта. `worker-process`: `_imaging` нет и в процессе 1 worker, новые поля. `attachment-storage`: `staging_key` может быть уже пуст; `data-storage` — проба аудита. `broker-check`, `s3-check`, `upload-consistency`, `reconcile-*` — по изменениям. `start` — ещё `make run_relay`.
### 18. Журнал
- Модуль `relay` (`src/relay/main.py`): «Started relay» со всеми значениями, «Stopped relay», «Invalid relay settings», «Stopped relay before startup».
- Модуль `attachment_relay_service`: «Relay pass» (`published`, `unconfirmed`, `recovered`, `republished`, `published_backlog`, `duration_ms`; `info`, пустой — `debug`), `warning` «Recovered expired lease», `info` «Relay backlog is full» / «Relay backlog has room» на смену состояния.
- Модуль `attachment_replay_service`: «Found failed job», «Replayed job» (`operator`, прежние `error_code`, `reason`), `warning` «Refused job replay» (`refusal`), «Finished replay pass».
- Модуль `attachment_processing_service`: «Started job attempt» — ещё `queue_wait_ms`, `message_attempt`, `redelivered`; «Attachment became ready» — `variants` (имя, ширина, высота, размер), `render_ms`, `render_peak_kib`, `render_memory_limit_applied`, `duration_ms`; «Retrying job» — `delay_seconds`, `next_attempt_at`; «Skipped job message» — ещё `not_due`, `superseded`. «Started worker» — все значения.
- Модуль `attachment_service`: «Uploaded attachment» — `content_type` значением, а не enum (запись `KNOWN_ISSUES.md`); записей о публикации нет. «Started API» — без брокера.
- Модуль `attachment_cleanup_service`: «Finished staging cleanup pass» (`removed_ready`, `removed_failed`, `skipped`, `interrupted_by`, `duration_ms`), `warning` «Staging key is not own».
- Итог сверки — ещё `listed_staging`.
### 19. Остановка worker (S5)
Закрытие клиентов — не по очереди, а `asyncio.gather` под одним `_CLOSE_TIMEOUT_SECONDS` (0,5 с): издателя у worker больше нет, остаются engine и S3, и сумма не растёт с их числом. Худший случай: `graceful_shutdown_seconds` 8 + отмена задач 0,5 + закрытие потребителя 0,5 + engine и S3 0,5 = 9,5 с < 10 с; верхняя граница настройки — 8. Комментарий и `worker.md` называют эту сумму. Отмена задачи убивает процесс обработки в `finally` клиента; `os._exit` прежний: поток декодирования отпал, но быстрый выход и незавершённые клиенты остаются. Задание, прерванное остановкой, получает следующую попытку по аренде: release при остановке не делается: окно редкое, а код на пути отмены `await` ненадёжен.
### 20. Evidence, отчёт и записи
Как на уровне 3: группы кода проверяются на рабочем дереве, завершающая группа — на закоммиченном коде отдельным запуском. `REPORT.md`: разделы уровня 4 (таблица критериев, эксперименты и отказы, параметры вариантов, лимиты и бюджет памяти, retention, ответы на вопросы защиты по новому поведению); то, что на уровне 3 было ограничением и закрыто, обновляется. Вопросы преподавателю №4 и №5 раздела отчёта помечаются закрытыми с ответом кода. `KNOWN_ISSUES.md`: записи «Разрыв COMMIT и publish» и «`content_type`» удаляются. `QUESTIONS.md`: раздел `## pipeline-reliability`.
## Покрытие сценариев
Новые и изменённые по сути сценарии спеков из `CAPABILITIES`. `fault` — `make failure_checks`; без пометки — `make student_test`.
| Capability, сценарий | Проверка |
|---|---|
| `job-outbox` «Загрузка при остановленном брокере» | `test_upload_with_broker_stopped`, fault |
| «Загрузка при замороженном брокере» | `test_upload_with_broker_paused`, fault |
| «Ответ не ждёт публикации», «Crash между фиксацией и публикацией», «Задание без отметки от прежней версии» | `test_relay_killed_before_publish`, fault |
| «Crash после подтверждения до отметки» | `test_relay_killed_after_confirm`, fault |
| «Отказ брокера во время работы relay» | `test_relay_survives_broker_outage`, fault |
| «Отказ PostgreSQL во время работы relay» | `test_relay_survives_database_outage`, fault |
| «Два relay» | `test_two_relays`, fault |
| «Следующая попытка не раньше срока» | `test_relay_respects_next_attempt`, fault |
| «Очередь удалена вместе с сообщением» | `test_lost_message_republished`, fault |
| «Очередь с сообщениями не обрастает копиями» | `test_no_copies_while_queue_has_messages`, fault |
| «Очередь ограничена пределом» | `test_published_backlog_limit`, fault |
| «Брокер сдерживает публикацию» | `test_broker_memory_alarm`, fault |
| `attachment-processing` «Вложение становится готовым» | `test_attachment_becomes_ready` |
| «Что сохранено к ответу 202» | `test_durable_state_at_202`, fault |
| «Worker убит посреди обработки» | `test_worker_killed_during_processing`, fault |
| «Дубль во время обработки» | `test_duplicate_during_processing`, fault |
| «Crash после записи объектов до фиксации» | `test_crash_after_objects_before_commit`, fault |
| «Crash после фиксации до подтверждения» | `test_crash_after_commit_before_ack`, fault |
| «Оригинал неизменен» | `test_original_published_unchanged`, fault |
| «Разновидности форматов» | `test_thumbnail_format_variants` |
| «Изображение в лимите пикселей» | `test_max_pixels_fit_worker_memory`, fault |
| «Повтор после записи объектов» | `test_ready_failure_retried`, fault |
| «Пауза растёт со случайной добавкой» | `test_retry_backoff_with_jitter`, fault |
| «Попытка не раньше срока», «Пауза не занимает место конкуренции» | `test_retry_waits_outside_worker`, fault |
| «Crop большого изображения», «Crop маленького изображения», «Crop с ориентацией и прозрачностью» | `test_crop_center`, `test_crop_small`, `test_crop_orientation_alpha` |
| «Optimized большого изображения», «Optimized маленького изображения», «Optimized без метаданных», «Optimized сохраняет прозрачность» | `test_optimized_fit`, `test_optimized_small`, `test_optimized_no_metadata`, `test_optimized_alpha` |
| «Пикселей больше лимита», «Объект больше лимита не читается» | `test_limit_pixels`, `test_limit_oversized_staging`, fault |
| «Дорогое изображение» | `test_limit_cpu_scan_bomb`, fault |
| «Предел памяти процесса обработки», «Срок процесса обработки» | `test_limit_memory`, `test_limit_render_timeout`, fault |
| «Процесс обработки убит», «Секретов нет у процесса обработки» | `test_render_killed`, fault |
| «Зависший worker» | `test_hung_worker_lease_fencing`, fault |
| «Долгая живая попытка» | `test_long_attempt_keeps_lease`, fault |
| «Последняя попытка потеряна» | `test_last_attempt_lost`, fault |
| «Реестр показан без изменений» | `test_replay_registry_dry_run`, fault |
| «Replay возвращает работу» | `test_replay_returns_work`, fault |
| «Replay готового не создаёт дубль» | `test_replay_ready_refused`, fault |
| «Replay идущей работы» | `test_replay_in_progress_refused`, fault |
| «Replay без исходника» | `test_replay_without_source_refused`, fault |
| «Новый бюджет попыток» | `test_replay_new_budget`, fault |
| «Replay по причине» | `test_replay_by_code`, fault |
| «Prefetch больше конкуренции» | `test_prefetch_bounded`, fault |
| `message-broker` «Брокер остановлен при загрузке», «Брокер вернулся» | `test_upload_with_broker_stopped`, fault |
| «Брокер завис» | `test_upload_with_broker_paused`, fault |
| «Очередь удалена» | `test_queue_deleted`, fault |
| «Старт без брокера», «Рестарт брокера при работающем worker» | `test_start_without_broker`, `test_worker_survives_broker_restart`, fault |
| `attachments` «Брокер не подтвердил задание» | `test_upload_with_broker_stopped`, fault |
| «Скачивание crop и optimized» | `test_download_crop_optimized` |
| «Отсутствующий вариант» | `test_missing_variant`, fault |
| `health` «Брокер и worker недоступны» | `test_readiness_without_broker_and_worker`, fault |
| `data-storage` «Ограничения обработки в схеме» | исключение: `driver.py --port <LB> attachment-storage` → `evidence/attachments/storage.md` |
| `storage-consistency` «Загрузка без подтверждения брокера убрана» | `test_cancelled_upload_of_previous_version`, fault |
| «Готовые вложения не тронуты», «Текущая работа не тронута» | прежние тесты, fault |
| «Объекты вариантов своих вложений», «Текущая работа не считается расхождением» | `test_reconcile_variant_objects`, `test_reconcile_keeps_current_work`, fault |
| «Объект staging без метаданных» | `test_reconcile_orphan_staging`, fault |
| «Staging готового вложения убран» | `test_staging_removed_after_ready`, fault |
| «Staging неудачного вложения хранится до срока», «Срок хранения прошёл» | `test_staging_retention`, fault |
| «Текущая работа не убирается» | `test_staging_keeps_current_work`, fault |
| «Очистка при отказе S3» | `test_staging_cleanup_survives_outage`, fault |
| «Ключ staging другого вида не удаляется» | `test_staging_foreign_key_kept`, fault |
Спеки вне сверки — evidence с закоммиченного кода: `container-run`, `container-image`, `graceful-shutdown`, `service-configuration` → `driver.py relay-process`, `worker-process`, `broker-check`; «docker stop во время обработки» и «во время декодирования» — ещё `test_worker_stop_during_processing`, `test_worker_stop_during_render`, fault (сценарий в докстринге); `object-storage` → `make s3_check`, `evidence/s3/cleaner-staging.md`; `service-logging` → `evidence/worker/logs.md`, `evidence/relay/logs.md`; `db-migrations` → `evidence/migrations/pipeline-reliability.md`; `load-balancing` → `driver.py lb-upload-timeouts`; `load-benchmark` → `make bench_uploads_quick`, `make bench_rollout`, регресс быстрых профилей; `student-tests` → `evidence/tests/`, `evidence/attachments/defense-faults.md`, шаг 4 защиты на стенде отказов — `test_defense_faults`, fault (сценарий в докстринге).
## Risks / Trade-offs
- [Relay — ещё один процесс, без него задания ждут] → `restart: unless-stopped`, журнал, очередь намерений видна; принятая работа цела; приём не страдает.
- [Публикация внутри транзакции] → срок 2 с < срока шага 6 с < простоя транзакции 10 с; блокируются только строки пакета; worker ждёт COMMIT.
- [Дубли сообщений: неизвестный исход публикации, crash до отметки, потерянные] → каждый дубль — один `SELECT … FOR UPDATE` и ACK; эффект защищён ключом и fencing; это и есть at least once, названо в ответе на вопрос защиты.
- [После KILL worker следующая попытка ждёт аренду, до 70 с] → настройка; пульс отвергнут (решение 3); повторная доставка готового — мгновенно.
- [Процесс на задание — ~100 мс CPU на маленьком файле] → честная цена изоляции; мерит трек 1; замена — один модуль (решение 7).
- [Дорогие файлы тратят CPU до лимита] → 15 с CPU на файл, одна попытка; при конкуренции 2 атакующий займёт worker на время лимита на каждый файл: места загрузки ограничивают скорость такой подачи, ограничение принятой работы — трек 1.
- [Отказ S3 дольше ~минуты переводит взятые задания в `failed`] → replay по коду; пауза растёт только в пределах бюджета.
- [Лимит памяти процесса обработки не действует на macOS] → только консольный запуск; стенд — Linux; названо в отчёте.
- [Старые `ready` без `crop` и `optimized`] → скачивание 404, контракт это допускает; replay `ready` запрещён намеренно; рабочие данные лабы тестовые.
- [Смесь версий: прежний worker делает `ready` только с thumbnail] → порядок обновления: worker раньше relay; окно ограничено сообщениями, уже лежавшими в очереди.
- [Объект staging живёт до прохода уборщика, 60 с] → на диске меньше минуты лишнего; под нагрузкой уборщик 0,25 CPU может отставать, отставание видно по числу строк с `staging_key` у `ready`, его мерит трек 1.
- [Копии при потере части сообщений] → republish только при нуле готовых: частичная потеря лечится, когда очередь опустеет. Сообщения, которые держит большой prefetch дольше порога, брокер готовыми не считает: они получат копию, а копия — лишний ACK; это видно трек 1 и не меняет эффекта.
- [Удаление очереди при работающем worker: потребитель не узнаёт] → прежнее ограничение; relay создаст очередь заново, а worker нужно перезапустить; названо в `REPORT.md`.
## Migration Plan
1. Шага оператора нет: секретов не прибавилось, `config.toml` читается как есть.
2. Без простоя: `docker compose up -d s3-bootstrap`, `make rolling_update` (две ревизии, затем реплики), `docker compose up -d --no-deps worker cleaner`, затем `docker compose up -d --no-deps relay`. До запуска relay новые загрузки отвечают 202 и ждут. С простоем — `make run_docker`.
3. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0` (прежние реплики публикуют сами), `docker compose up -d --no-deps` прежних worker и уборщика, relay останавливается, когда нет заданий `queued` без отметки. Схема остаётся.
4. Прежние строки `ready` не трогаются, кроме объекта staging: его уберёт первый проход уборщика.
## Open Questions
Вопросы преподавателю в `QUESTIONS.md` (раздел `pipeline-reliability`): ни один не меняет подход и задачи; другой ответ правит одну функцию и её сценарий.
## Уточнения apply
Заполняет стадия apply.
@@ -0,0 +1,129 @@
# Proposal
## Why
Лаба 5, уровень «4» (`README.md`): конвейер обработки вложений должен переживать
сбои сам, а не только доносить работу при удачном стечении окон. Сейчас, на уровне
3, отказ брокера останавливает приём (503), падение API между фиксацией задания и
подтверждением брокера оставляет `queued` без сообщения, зависшая попытка
держит задание до срока подтверждения брокера, декодирование ничем не ограничено
по времени и памяти, а `failed` окончателен. Это второе из трёх изменений пути к
оценке 5: `async-attachments` (3, в архиве) → `pipeline-reliability` (4) →
`track1-queue-overload` (5).
## What Changes
- **BREAKING (внутри лабы, контракт не меняется):** отказ брокера больше не даёт
503 на загрузке. Ответ 202 означает: оригинал в staging, вложение `queued` и
задание зафиксированы в PostgreSQL. Брокера в пути запроса нет, у реплик API нет
ни клиента брокера, ни его пароля. 503 на загрузке остаётся только для отказа S3 и
PostgreSQL (закрывает вопрос преподавателю №3 раздела `## async-attachments`).
- **Transactional outbox и relay:** `attachment_jobs` со `state = 'queued' AND
published_at IS NULL` — outbox; новый сервис `relay` (`python -m src.relay`)
публикует намерения с publisher confirm и отмечает `published_at`. Доставка at
least once: сбой после confirm даёт дубль, он ничего не меняет. Подбираются и
строки уровня 3, и сообщения, потерянные вместе с очередью. Внедрённый crash между
COMMIT и publish и после confirm до отметки — на стенде отказов, без точек сбоя в
коде.
- **Варианты:** `crop` — JPEG 128 × 128, центрированный квадрат; `optimized` — WebP,
вписан в 1280 × 1280 без увеличения, `quality` 80, без EXIF и ICC. `ready` — только
когда записаны все три варианта и оригинал.
- **Лимиты обработки:** байты, пиксели, CPU и память; декодирование идёт в отдельном
дочернем процессе на задание, с `RLIMIT_AS` и `RLIMIT_CPU`, без секретов в
окружении, родитель убивает его по сроку. «Дорогое» изображение в пределах контракта
(JPEG с сотнями тысяч сканов — проба: > 60 с CPU) больше не держит worker.
- **Повторы:** экспоненциальный backoff с jitter вместо фиксированной паузы; ожидание
— в PostgreSQL (`next_attempt_at`), а не в месте конкуренции worker; следующую попытку
публикует relay, когда подошёл срок. Постоянные и временные ошибки разделены явно.
- **Реестр `failed` и replay:** реестр — строки `attachment_jobs`; операторская команда
`make replay` (`python -m src.relay replay`, по умолчанию dry-run) возвращает `failed`
в `queued` с записью аудита и новым бюджетом попыток. Replay готовой работы — отказ, а
не дубль; без исходника — отказ.
- **Lease зависшего `processing`:** срок аренды = жёсткий срок попытки + запас; истекшую
аренду возвращает relay; дубль при живой аренде подтверждается без эффекта, номер
попытки — fencing: результат прежней попытки не фиксируется. Закрывает замечание W2.
- **Ограниченный prefetch:** `[worker] prefetch` отдельно от `[worker] concurrency`, предел
опубликованных и не взятых заданий `[relay] max_published_backlog`; значения и счётчики
видны в журнале и PostgreSQL для замеров `track1-queue-overload`.
- **Очистка staging:** уборщик удаляет staging после фиксации `ready` и у `failed` по
сроку `[cleaner] staging_retention_seconds` (`STAGING_RETENTION_SECONDS`, сутки) — вместе
с частично записанными объектами; сверка находит объект staging без строки. Закрывает
вопрос преподавателю №2 там же.
- **Замечания проверки уровня 3:** S5 (срок закрытия worker), S6 (пауза повтора и сигнал),
W2 (дубль после `busy`), неточность спека `load-benchmark` «Профиль сверки», `.Image` в
паспорте `bench/run.py`; записи `KNOWN_ISSUES.md` о разрыве COMMIT/publish и о
`content_type` в журнале.
- **Защита:** шаг 4 сценария (crash после side effect до ack, разрыв COMMIT/publish, replay
failed) — команда драйвера с записью в `evidence/` и проверка на стенде отказов.
**Не входит** (следующее изменение `track1-queue-overload`): замеры перегрузки, сравнение
настроек concurrency и prefetch, ограничение принятой работы на входе API. Здесь — только
настройки и счётчики, на которые оно ляжет. Сверка наличия объектов вариантов остаётся
названным ограничением (design, решение 9). Файлы исключений старых лаб
`evidence/cache/hits.md`, `evidence/auth/passwords-and-tokens.md`,
`evidence/idempotency/replay-after-restart.md` — последний шаг всего прогона.
Не меняются: `contracts/`, `tests/`, `README.md`, `COURSE.md`, `lab.json`,
`CONTRIBUTING.md`, `MAINTAINERS.md`.
Шага оператора нет: новых секретов нет; существующий `config.toml` остаётся рабочим, новые
поля берут значения по умолчанию.
## Capabilities
### New Capabilities
- `job-outbox`: transactional outbox заданий и relay: публикация с подтверждением, at least
once, несколько экземпляров, срок следующей попытки, потерянные сообщения, предел
опубликованных, отказы брокера и PostgreSQL.
### Modified Capabilities
- `attachment-processing`: варианты `crop` и `optimized`, лимиты обработки в дочернем
процессе, backoff с jitter, постоянные и временные ошибки, реестр `failed` и replay, lease и
fencing, prefetch, staging после фиксации.
- `attachments`: порядок записи без брокера, все варианты на скачивании, 503 только от S3 и
PostgreSQL.
- `message-broker`: издатель — relay; приём загрузки от брокера не зависит.
- `storage-consistency`: очистка staging и retention, объект staging без метаданных в сверке,
отменённая загрузка прежней версии.
- `health`: брокер и relay не влияют на готовность, загрузка без них — 202.
- `data-storage`: журнал replay и бюджет попыток в схеме.
- `db-migrations`: совместимость новых колонок, таблицы и индексов.
- `object-storage`: список уборщика ещё и по префиксу staging своей базы, проверки bootstrap.
- `container-run`: сервис `relay`, порядок старта, секреты брокера без реплик API, лимиты.
- `container-image`: relay на образе API, Pillow только в дочернем процессе рендера.
- `graceful-shutdown`: остановка relay, честный бюджет остановки worker.
- `service-configuration`: секция `[relay]`, новые поля `[worker]` и `[cleaner]`.
- `service-logging`: журнал relay и replay, поля замеров в журнале worker, очистка staging.
- `student-tests`: сверка покрытия `job-outbox`, relay в `make test_isolated` и на стенде
отказов, новые действия hook, шаг 4 сценария защиты.
- `load-balancing`: цепочка сроков пути загрузки без публикации.
- `load-benchmark`: брокер больше не нужен профилю загрузок, relay на стенде, образы в паспорте
по метке compose, commit профиля замены, формулировка профиля сверки.
## Impact
- **API:** коды и схемы контракта те же. `POST …/attachments` — 202 и при отказе брокера;
`GET …/content?variant=crop|optimized` — 200 у вложений этого уровня; `error_code` — прежние
значения.
- **Код:** `src/relay/` (новый), `src/worker/render.py` (новый, дочерний процесс),
`src/infra/render/` (новый), `src/utils/image_variants.py` (вместо `thumbnail.py`),
`src/core/services/attachment.py`, `attachment_processing.py`, `attachment_cleanup.py`,
`attachment_reconcile.py`, новые `attachment_relay.py` и `attachment_replay.py`, repo заданий,
вложений, объектов и новый repo журнала replay, `src/worker/main.py`, `src/config/settings.py`,
`src/api/dependencies.py`, `src/main.py`, `src/infra/broker/` (без `instance.py`), две ревизии.
- **Зависимости:** новых нет: WebP уже в колёсах Pillow 13.0.0 (libwebp 1.6.0, проба).
- **Стенд:** `docker-compose.yml`, `infra/s3/bootstrap.sh`, `infra/haproxy/haproxy.cfg`
(комментарии), `scripts/rolling-update.sh` (комментарии), `.env.example`, `config_example.toml`,
`Makefile`, `.github/ci/compose.yml`.
- **Тесты и инструменты:** `student-tests/` (клиент, генераторы, `fault_hook.py`,
`run_failures.py`, `failures.compose.yml`, `run_isolated.py`, `spec_coverage.py`, новые проверки),
`bench/` (`bench.compose.yml`, `bench.env`, `run.py`, `uploads.py`),
`.claude/skills/run-mtusi-messenger/`.
- **Документы:** правила `.claude/rules/`, `AGENTS.md`, `KNOWN_ISSUES.md`, `QUESTIONS.md`,
`REPORT.md` (разделы уровня 4), evidence.
- **Ресурсы стенда:** плюс relay 0,25 CPU / 256 МБ, соединений PostgreSQL плюс одно; оригинал
больше не лежит в S3 дважды после `ready`. Загрузка быстрее на шаг публикации и не держит
место на брокере; цена — задержка до `ready` до `[relay] poll_interval_seconds` (0,25 с) и
дочерний процесс на задание (~100 мс CPU на маленьком файле, проба).
@@ -0,0 +1,611 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Состояния вложения
Вложение, принятое ответом 202, SHALL находиться в одном из состояний
API: `queued`, `processing`, `ready`, `failed`. Переходы:
- `queued` → `processing` — worker взял задание; зафиксированы номер
попытки и срок её аренды;
- `processing` → `queued` — временная ошибка, попытки остались;
зафиксированы причина без секретов и время следующей попытки;
- `processing` → `queued` — истёк срок аренды (требование «Аренда попытки»);
- `processing` → `ready` — оригинал, thumbnail, crop и optimized записаны, а
метаданные вариантов и состояние зафиксированы одной транзакцией;
- `processing` → `failed` — ошибка постоянная или попытки исчерпаны;
зафиксированы код ошибки и запись для оператора;
- `failed` → `queued` — явный replay оператора (требование «Реестр failed и
replay»).
Готовое вложение MUST NOT возвращаться в другое состояние, в том числе
из-за повторной доставки и replay. `error_code` SHALL быть null во всех
состояниях, кроме `failed`, `variants` — пустым во всех, кроме `ready`.
#### Scenario: Принятое вложение в очереди
- **WHEN** worker остановлен, и участник загружает настоящий PNG
- **THEN** ответ 202 со `status` `queued`, а метаданные через несколько
секунд — 200 со `status` `queued`, `variants` `[]`, `error_code` null
#### Scenario: Вложение становится готовым
- **WHEN** worker работает, участник загружает `tests/fixtures/sample.png`
и опрашивает метаданные
- **THEN** не позже чем через 60 с `status` `ready`, `error_code` null,
а в `variants` ровно по одному элементу `thumbnail`, `crop` и `optimized`
#### Scenario: Обработка видна в API
- **WHEN** worker взял задание, а фиксация его результата задержана
- **THEN** метаданные — 200 со `status` `processing`, скачивание — 409
`conflict`, а после фиксации метаданные — `ready`, скачивание — 200
#### Scenario: Готовое вложение не откатывается
- **WHEN** задание готового вложения доставлено ещё раз
- **THEN** метаданные совпадают с прежними во всех полях, включая
`updated_at`
### Requirement: Задание в PostgreSQL
Вложению SHALL соответствовать одно логическое задание на
`pipeline_version`; в курсе `pipeline_version` равен 1. У задания есть
идентификатор, вложение, версия, состояние, число начатых попыток, число
попыток до последнего replay, причина последней ошибки, время следующей
попытки, срок аренды текущей попытки и время, когда брокер подтвердил его
последнее сообщение.
Перевод вложения в `queued` и запись задания SHALL быть одной
транзакцией: это устойчивое намерение обработать файл (`job-outbox`).
Идентификатор задания MUST NOT меняться при повторах, повторной доставке и
replay.
#### Scenario: Что сохранено к ответу 202
- **WHEN** worker и relay остановлены, и участник получил ответ 202
- **THEN** объект оригинала есть в staging, а в конечном префиксе его
нет, в PostgreSQL вложение `queued` и одно задание с нулём начатых
попыток без времени подтверждения брокером, а в очереди сообщения нет
- **AND** после запуска relay в очереди одно сообщение, а у задания есть время
подтверждения
#### Scenario: Повторы под одним заданием
- **WHEN** обработка вложения прошла две попытки и закончилась `ready`
- **THEN** задание у вложения одно, с тем же идентификатором, что после
первой попытки, а число начатых попыток — 2
### Requirement: Доставка at least once
Сообщение брокера SHALL быть подсказкой: истина о задании — в PostgreSQL. Worker
SHALL подтверждать сообщение (ack) только после того, как устойчиво записано, что
делать с заданием дальше:
- зафиксировано `ready` или `failed`;
- задание возвращено в `queued` со временем следующей попытки, и следующее сообщение
опубликует relay (`job-outbox`);
- задание уже завершено, или его ведёт попытка с живой арендой, или его срок ещё не
наступил: сообщение лишнее, и записывать нечего.
Если worker потерян до подтверждения, брокер SHALL доставить сообщение снова, и задание
SHALL быть доведено до конца: сразу, если аренда уже истекла, иначе — когда её вернёт
relay (требование «Аренда попытки»).
Повторная доставка завершённого задания SHALL быть no-op с подтверждением
после проверки зафиксированного эффекта.
Дубль сообщения, пока идёт попытка с живой арендой, MUST NOT начинать новую попытку и
тратить её номер.
#### Scenario: Worker убит посреди обработки
- **WHEN** worker завершён сигналом KILL, пока задание в `processing`, и
затем снова запущен
- **THEN** вложение становится `ready` со всеми вариантами не позже срока аренды с
запасом, число начатых попыток — 2, сообщений в очереди не осталось
#### Scenario: Повторная доставка готового
- **WHEN** в очередь для готового вложения снова попало сообщение его
задания
- **THEN** сообщение подтверждено, а метаданные, число вариантов и объекты
вариантов не изменились
#### Scenario: Дубль во время обработки
- **WHEN** пока попытка задания идёт, в очередь дважды попадает сообщение этого
задания, и попытка длится дольше времени их доставки
- **THEN** сообщения подтверждены без новой попытки, вложение становится `ready` с
одним набором вариантов, число начатых попыток — 1, сообщений в очереди не
осталось
#### Scenario: Crash после записи объектов до фиксации
- **WHEN** worker записал оригинал и все варианты, фиксация `ready` задержана, worker
завершён сигналом KILL и снова запущен
- **THEN** вложение становится `ready`, число начатых попыток — 2, у каждого варианта
один объект, а его SHA-256 равен SHA-256 объекта, записанного до сбоя
#### Scenario: Crash после фиксации до подтверждения
- **WHEN** фиксация `ready` дошла до COMMIT, worker заморожен до ответа PostgreSQL, фиксация
завершена, worker завершён сигналом KILL без подтверждения сообщения и снова запущен
- **THEN** брокер доставляет сообщение снова, worker подтверждает его без эффекта, метаданные
совпадают с зафиксированными во всех полях, включая `updated_at`, число начатых попыток —
1, а сообщений в очереди не осталось
### Requirement: Публикация оригинала
Worker SHALL прочитать оригинал из staging по ключу из PostgreSQL, сверить
его размер и SHA-256 с метаданными вложения и записать те же байты в
конечный префикс. Оригинал SHALL оставаться неизменным: скачанные после
`ready` байты равны загруженным. Объект staging MUST NOT удаляться до
фиксации `ready`; worker его не удаляет: это делает уборщик
(`storage-consistency`, «Очистка staging»).
Объект staging другого размера или с другим SHA-256 и его отсутствие —
постоянная ошибка `processing_failed`. Причина SHALL быть в записи для
оператора.
#### Scenario: Оригинал неизменен
- **WHEN** загруженный PNG стал `ready`
- **THEN** скачанный оригинал побайтно равен загруженному, а его SHA-256
равен `sha256` метаданных, объект есть в конечном префиксе, а объекта в
staging нет не позже следующего прохода уборщика с запасом
#### Scenario: Испорченный staging
- **WHEN** worker остановлен, участник загрузил файл, объект staging
заменён другими байтами, и worker запущен
- **THEN** вложение `failed` с `error_code` `processing_failed`, число
начатых попыток — 1, а объекта в конечном префиксе нет
#### Scenario: Нет объекта staging
- **WHEN** worker остановлен, участник загрузил файл, объект staging
удалён, и worker запущен
- **THEN** вложение `failed` с `error_code` `processing_failed`, число
начатых попыток — 1
### Requirement: Thumbnail
Thumbnail SHALL быть изображением JPEG, вписанным в 256 × 256 с
сохранением пропорций:
- большая сторона становится 256, меньшая вычисляется от неё и
округляется вниз, но не меньше 1 px;
- изображение, которое и так вписано в 256 × 256, MUST NOT увеличиваться;
- EXIF orientation SHALL применяться: размеры и содержимое thumbnail — как
у показанного с учётом ориентации;
- alpha SHALL компоноваться на белый, в том числе прозрачность палитры.
Метаданные варианта SHALL содержать `name` `thumbnail`, `content_type`
`image/jpeg`, `size_bytes`, `sha256`, `width` и `height` записанного
объекта. Формат декодируется только как PNG или JPEG. Ограничения памяти и
времени — требование «Лимиты обработки».
#### Scenario: Fixture 320 × 200
- **WHEN** `tests/fixtures/sample.png` стал `ready`, и участник скачивает
`variant=thumbnail`
- **THEN** ответ 200 `image/jpeg`, настоящие размеры JPEG 256 × 160, а
`width`, `height`, `size_bytes` и `sha256` варианта совпадают со
скачанным объектом
#### Scenario: Маленькое изображение не увеличивается
- **WHEN** участник загружает PNG 100 × 50 и PNG 256 × 256
- **THEN** размеры thumbnail — 100 × 50 и 256 × 256
#### Scenario: Округление вниз и минимум
- **WHEN** участник загружает изображения 1000 × 601, 601 × 1000,
5000 × 10 и 10 × 5000
- **THEN** размеры thumbnail — 256 × 153, 153 × 256, 256 × 1 и 1 × 256
#### Scenario: EXIF orientation
- **WHEN** участник загружает JPEG 400 × 200 с левой половиной красной и
правой синей и EXIF orientation 6
- **THEN** thumbnail 128 × 256, его верхняя половина красная, а нижняя
синяя
#### Scenario: Alpha на белый
- **WHEN** участник загружает PNG с прозрачной половиной и PNG с палитрой
и прозрачностью
- **THEN** на месте прозрачных пикселей thumbnail белый
#### Scenario: Разновидности форматов
- **WHEN** участник загружает PNG с палитрой, с альфа-каналом, серый с
альфа-каналом, серый 16 бит, RGB 16 бит, 1 бит, чересстрочный и JPEG
прогрессивный, серый, CMYK, с EXIF и без таблиц Хаффмана
- **THEN** каждое вложение становится `ready`, его thumbnail и crop —
настоящие JPEG, а optimized — настоящий WebP
#### Scenario: Изображение в лимите пикселей
- **WHEN** участник загружает столько PNG с альфа-каналом 8000 × 5000, сколько
заданий worker обрабатывает одновременно
- **THEN** каждое вложение становится `ready`, thumbnail 256 × 160, crop 128 × 128,
optimized 1280 × 800, а контейнер worker не завершён из-за памяти
### Requirement: Идемпотентный эффект
Ключ эффекта SHALL быть `(attachment_id, pipeline_version, variant)`. Из
него однозначно следует ключ объекта варианта, а метаданные варианта
уникальны по нему в PostgreSQL. Повтор задания MUST NOT создавать второй
набор вариантов: он пишет те же ключи объектов теми же байтами при той же версии
декодера. Метаданные всех вариантов и состояние `ready` SHALL фиксироваться одной
транзакцией: вложение `ready` без метаданных любого варианта уровня MUST NOT
появляться.
#### Scenario: Повтор после записи объектов
- **WHEN** объекты вложения записаны, а фиксация `ready` не удалась, и
worker выполняет следующую попытку
- **THEN** вложение `ready`, у него по одному варианту `thumbnail`, `crop` и
`optimized`, а объект каждого варианта в bucket один, и его SHA-256 равен
`sha256` варианта
### Requirement: Ограниченные повторы
Временная ошибка — недоступность или отказ S3, истёкший срок попытки или процесса
обработки, процесс обработки убит или упал, другая непредвиденная ошибка — SHALL вести к
новой попытке, пока число попыток с последнего replay не достигло `[worker] max_attempts`
(`service-configuration`, «Параметры worker»). Между попытками вложение SHALL быть в
`queued`.
Пауза перед попыткой N + 1 SHALL быть экспоненциальной со случайной добавкой: это случайная
величина из `[d / 2, d]`, где `d = min([worker] retry_max_delay_seconds, [worker]
retry_base_delay_seconds × 2^(N − 1))`. Она записывается временем следующей попытки. На время
паузы задание MUST NOT занимать место конкуренции worker: сообщение прежней попытки
подтверждено, а новое сообщение с тем же `job_id` и `attempt` на единицу больше публикует relay,
когда срок наступил (`job-outbox`). Сообщение, пришедшее раньше срока, worker подтверждает без
новой попытки.
Каждая начатая попытка считается, в том числе та, в которой worker был
потерян. Когда попытки исчерпаны, вложение SHALL стать `failed` с
`error_code` `retry_exhausted`. Бесконечный немой повтор MUST NOT
происходить. Пока недоступен PostgreSQL, исход записать нельзя: сообщение
возвращается в очередь после паузы, новые попытки не начинаются, а журнал worker называет
отказ.
Ограничение называется в `REPORT.md`. Отказ S3 дольше суммы пауз и сроков переводит взятые
задания в `failed`; после возврата S3 их возвращает replay (требование «Реестр failed и
replay»).
#### Scenario: Временная ошибка
- **WHEN** S3 остановлен, worker взял задание, и S3 возвращается раньше,
чем исчерпаны попытки
- **THEN** вложение становится `ready`, число начатых попыток больше 1, а
у задания тот же идентификатор
#### Scenario: Состояние между попытками
- **WHEN** попытка задания закончилась временной ошибкой, и попытки остались
- **THEN** до следующей попытки метаданные — `queued` с `error_code` null,
а в записи задания есть причина и время следующей попытки
#### Scenario: Попытки исчерпаны
- **WHEN** S3 остановлен дольше, чем длятся все попытки задания
- **THEN** вложение становится `failed` с `error_code` `retry_exhausted`,
число начатых попыток равно `max_attempts`, сообщений в очереди не
осталось, а после возврата S3 состояние прежнее
#### Scenario: PostgreSQL недоступен при обработке
- **WHEN** PostgreSQL останавливается, пока в очереди есть задание, а затем
снова запускается
- **THEN** worker без перезапуска доводит задание до `ready`, сообщений в
очереди не осталось
#### Scenario: Пауза растёт со случайной добавкой
- **WHEN** S3 остановлен, и два задания проходят все попытки
- **THEN** пауза каждой попытки лежит в границах формулы, у следующей попытки верхняя
граница вдвое больше, а паузы двух заданий на одной попытке различаются
#### Scenario: Попытка не раньше срока
- **WHEN** задание ждёт следующую попытку, в очередь попало его сообщение, а worker
перезапущен
- **THEN** сообщение подтверждено без новой попытки, число начатых попыток прежнее, а
следующая попытка начинается не раньше записанного времени
#### Scenario: Пауза не занимает место конкуренции
- **WHEN** задание ждёт следующую попытку, S3 доступен, и участник загружает другой файл
- **THEN** другое вложение становится `ready` раньше срока следующей попытки первого, а первое
в это время `queued`
### Requirement: Постоянные ошибки и коды
Ошибка, которую повтор не исправит, SHALL сразу вести к `failed`, без
новых попыток. Коды `error_code`:
- `invalid_image` — изображение прошло проверку при загрузке, но не
декодируется или не укладывается в лимиты обработки (требование «Лимиты
обработки»);
- `processing_failed` — объект staging отсутствует или испорчен;
- `retry_exhausted` — попытки исчерпаны.
`error_code` MUST NOT содержать stack trace, пути, ключи и адреса. Причину
SHALL называть запись задания и журнал worker, доступные оператору. Причины
постоянных ошибок: не декодируется, больше лимита пикселей, памяти или CPU, объект
staging отсутствует или испорчен. Причины временных: S3 недоступен, истёк срок попытки
или процесса обработки, процесс обработки убит или упал, истёк срок аренды, непредвиденная
ошибка.
#### Scenario: Изображение не декодируется
- **WHEN** участник загружает JPEG с 12 битами на компоненту, который
проходит проверку структуры, но не декодируется
- **THEN** ответ 202, затем вложение `failed` с `error_code` `invalid_image`,
число начатых попыток — 1, вариантов нет, а скачивание — 409 `conflict`
### Requirement: Worker — отдельный процесс
Обработку SHALL выполнять worker — отдельный процесс стенда (`container-run`).
Реплики API MUST NOT декодировать изображения и создавать варианты ни при
каких обстоятельствах, в том числе когда worker недоступен. Worker SHALL
обрабатывать одновременно не больше `[worker] concurrency` заданий, а брокер
выдаёт ему не больше `[worker] prefetch` неподтверждённых сообщений.
#### Scenario: Worker недоступен
- **WHEN** worker остановлен, и участник загружает файл, отправляет текст и
читает историю
- **THEN** загрузка — 202, вложение `queued`, вариантов нет, отправка — 201,
история — 200, `/health/ready` — 200
#### Scenario: Ограниченная конкуренция
- **WHEN** в очереди заданий больше, чем `[worker] concurrency`, и фиксация
результатов задержана
- **THEN** неподтверждённых сообщений и вложений в `processing` не больше
`concurrency`, а остальные задания — `queued`, и все они затем становятся
`ready`
## ADDED Requirements
### Requirement: Вариант crop
Crop SHALL быть изображением JPEG 128 × 128: центрированный квадрат по короткой стороне
показанного изображения, сжатый или растянутый до 128 × 128. Маленькое изображение
увеличивается. EXIF orientation SHALL применяться, alpha — компоноваться на белый.
Параметры кодирования (`quality`, отсутствие EXIF и ICC) SHALL быть описаны в `REPORT.md`.
Метаданные варианта SHALL содержать `name` `crop`, `content_type` `image/jpeg`,
`size_bytes`, `sha256`, `width` и `height` записанного объекта.
#### Scenario: Crop большого изображения
- **WHEN** участник загружает PNG 400 × 200: полосы шириной 100, 200 и 100 красного, синего и
зелёного
- **THEN** вариант `crop` — настоящий JPEG 128 × 128, синий в центре и по краям, а поля варианта
совпадают со скачанным объектом
#### Scenario: Crop маленького изображения
- **WHEN** участник загружает PNG 50 × 20
- **THEN** вариант `crop` — настоящий JPEG 128 × 128
#### Scenario: Crop с ориентацией и прозрачностью
- **WHEN** участник загружает JPEG 400 × 200 с левой половиной красной и правой синей и EXIF
orientation 6 и PNG с прозрачной половиной
- **THEN** у первого crop верхняя половина красная, а нижняя синяя, а у второго на месте
прозрачных пикселей белый
### Requirement: Вариант optimized
Optimized SHALL быть изображением WebP, вписанным в 1280 × 1280 с сохранением пропорций:
большая сторона становится 1280, меньшая округляется вниз, но не меньше 1 px; изображение,
которое и так вписано, MUST NOT увеличиваться. EXIF orientation SHALL применяться, потому что
EXIF, XMP и ICC в результат MUST NOT попадать. Прозрачность SHALL сохраняться. Уменьшение
каждого маленького файла MUST NOT обещаться. Параметры кодирования SHALL быть описаны в
`REPORT.md`.
Метаданные варианта SHALL содержать `name` `optimized`, `content_type` `image/webp`,
`size_bytes`, `sha256`, `width` и `height` записанного объекта.
#### Scenario: Optimized большого изображения
- **WHEN** участник загружает изображения 2000 × 1000, 5000 × 3001 и 5000 × 10
- **THEN** варианты `optimized` — настоящие WebP 1280 × 640, 1280 × 768 и 1280 × 2, а поля
варианта совпадают со скачанным объектом
#### Scenario: Optimized маленького изображения
- **WHEN** участник загружает PNG 100 × 50
- **THEN** вариант `optimized` — настоящий WebP 100 × 50
#### Scenario: Optimized без метаданных
- **WHEN** участник загружает JPEG 400 × 200 с EXIF orientation 6, строкой производителя в EXIF
и профилем ICC
- **THEN** вариант `optimized` — WebP 200 × 400 с верхней половиной цвета левой половины
исходника, а чанков EXIF, XMP и ICC и строки производителя в его байтах нет
#### Scenario: Optimized сохраняет прозрачность
- **WHEN** участник загружает PNG с прозрачной половиной
- **THEN** на месте прозрачных пикселей у варианта `optimized` альфа-канал равен нулю
### Requirement: Лимиты обработки
Декодирование и преобразование изображения SHALL выполняться в отдельном процессе на задание,
а не в процессе worker. У этого процесса в окружении MUST NOT быть секретов приложения. Лимиты:
- байты: объект staging другого размера, чем в метаданных, MUST NOT читаться: это постоянная
ошибка `processing_failed`. Размер в метаданных ограничен контрактом;
- пиксели: изображение больше лимита контракта MUST NOT декодироваться, постоянная ошибка
`invalid_image`;
- память: адресное пространство процесса ограничено `[worker] render_memory_limit_mib`,
превышение — постоянная ошибка `invalid_image`;
- CPU: время процессора ограничено `[worker] render_cpu_limit_seconds`, превышение — постоянная
ошибка `invalid_image`;
- время: процесс, не закончивший за `[worker] render_timeout_seconds`, SHALL быть убит, это
временная ошибка.
Процесс, убитый ядром или упавший, — временная ошибка. Сам worker SHALL продолжать работу в
каждом из этих случаев, без перезапуска контейнера. Пик памяти процессов обработки на изображении
в лимите контракта при настроенной конкуренции вместе с памятью самого worker SHALL укладываться в
лимит контейнера; расчёт SHALL быть в `REPORT.md`.
Ограничение называется в `REPORT.md`. Лимит адресного пространства не действует там, где его не
поддерживает ядро (worker на хосте macOS).
#### Scenario: Пикселей больше лимита
- **WHEN** worker остановлен, объект staging заменён PNG с заголовком на 50 млн пикселей, размер и
SHA-256 в метаданных приведены в соответствие с ним, и worker запущен
- **THEN** вложение `failed` с `error_code` `invalid_image`, причина — лимит пикселей, число начатых
попыток — 1
#### Scenario: Объект больше лимита не читается
- **WHEN** worker остановлен, объект staging заменён объектом больше 10 MiB, и worker запущен
- **THEN** вложение `failed` с `error_code` `processing_failed`, причина — испорченный объект, число
начатых попыток — 1
#### Scenario: Дорогое изображение
- **WHEN** участник загружает JPEG в пределах лимитов контракта, декодирование которого занимает
больше лимита CPU: прогрессивный, с сотнями тысяч повторённых сканов
- **THEN** ответ 202, вложение `failed` с `error_code` `invalid_image`, причина — лимит CPU, число
начатых попыток — 1, у контейнера worker счётчик перезапусков 0, а следующий файл становится `ready`
#### Scenario: Предел памяти процесса обработки
- **WHEN** worker запущен с пределом памяти 200 МиБ, и участник загружает PNG с альфа-каналом 8000 × 5000
- **THEN** вложение `failed` с `error_code` `invalid_image`, причина — лимит памяти, число начатых
попыток — 1, а процесс worker работает
#### Scenario: Срок процесса обработки
- **WHEN** worker запущен со сроком процесса обработки короче времени декодирования, и участник загружает
файл
- **THEN** каждая попытка заканчивается временной ошибкой, вложение `failed` с `error_code`
`retry_exhausted`, причина — срок, а процессов обработки после этого не осталось
#### Scenario: Процесс обработки убит
- **WHEN** во время попытки процесс обработки завершён сигналом KILL
- **THEN** worker продолжает работу, у контейнера счётчик перезапусков 0, а задание получает новую попытку
с причиной «процесс обработки убит»
#### Scenario: Секретов нет у процесса обработки
- **WHEN** идёт декодирование, и проверяющий смотрит окружение процесса обработки
- **THEN** в нём нет переменных настроек PostgreSQL, S3 и брокера
### Requirement: Аренда попытки
При взятии задания SHALL фиксироваться срок аренды: `[worker] job_timeout_seconds` + `[worker]
lease_margin_seconds`. Живая попытка SHALL укладываться в этот срок: по `job_timeout_seconds` её шаги
прерываются, а процесс обработки убивается. Поэтому истёкшая аренда значит, что worker потерян или завис,
а долго работающий, но живой worker свою аренду не теряет.
Relay SHALL возвращать задание с истёкшей арендой в `queued` с причиной «истёк срок аренды», без паузы, а
worker SHALL брать такое задание и сам, если сообщение пришло раньше. Пока аренда жива, новая попытка MUST
NOT начинаться: сообщение подтверждается без эффекта.
Номер попытки SHALL защищать итог: `ready`, `failed` и возврат в очередь фиксирует только та попытка, номер
которой равен текущему у задания в `processing`. Прежняя попытка, которая пережила срок аренды, MUST NOT
менять итог, в том числе после разморозки процесса.
Попытка, потерянная при исчерпанном бюджете, SHALL вести к `failed` с `retry_exhausted` при следующем взятии.
#### Scenario: Зависший worker
- **WHEN** worker заморожен посреди попытки, срок аренды истёк, второй worker довёл задание до `ready`, и
первый разморожен
- **THEN** число начатых попыток — 2, причина возврата записана в журнал relay, а метаданные после разморозки
совпадают с зафиксированными вторым worker во всех полях
#### Scenario: Долгая живая попытка
- **WHEN** фиксация результата задержана дольше всех пауз, но попытка укладывается в срок
- **THEN** вложение становится `ready`, а число начатых попыток — 1
#### Scenario: Последняя попытка потеряна
- **WHEN** worker с `max_attempts` 1 завершён сигналом KILL посреди попытки, снова запущен, и срок аренды истёк
- **THEN** вложение `failed` с `error_code` `retry_exhausted`, а число начатых попыток — 1
### Requirement: Реестр failed и replay
Реестр неудач SHALL быть записями заданий `failed` в PostgreSQL: идентификатор задания и вложения, код, причина,
число попыток, время. Операторская команда SHALL показывать реестр и возвращать из него работу: по умолчанию
ничего не меняет и называет, что сделала бы; с `--apply` выполняет. Выбор — по `id` вложения, по коду или причине,
не больше заданного числа заданий. С `--apply` выбор обязателен. Публичному API replay MUST NOT быть доступен.
Replay задания SHALL одной транзакцией:
- вернуть вложение из `failed` в `queued` с `error_code` null, а задание — в `queued` без причины и времени
окончания;
- начать новый бюджет: следующие `max_attempts` попыток считаются заново, а сам номер попытки продолжает расти;
- записать аудит: кто, когда, прежние код и причина, число попыток.
Идентификатор задания SHALL оставаться прежним, сообщение публикует relay, а ключи объектов и варианты защищены ключом
эффекта. Команда SHALL отказывать и ничего не менять, если задание:
- завершено успешно: «повторить» не значит исполнить дубль готовой работы;
- ещё идёт или ждёт в очереди;
- потеряло исходник: объект staging убран по сроку хранения;
- не найдено.
Код выхода: 0 — всё выбранное выполнено или показано, 3 — есть отказы, 1 — отказ PostgreSQL, 2 — неверные аргументы или
конфигурация.
#### Scenario: Реестр показан без изменений
- **WHEN** есть вложение `failed`, и выполняется команда без `--apply`
- **THEN** журнал называет его задание, код и причину, код выхода 0, а вложение и задание не изменились
#### Scenario: Replay возвращает работу
- **WHEN** объект staging был заменён, вложение стало `failed` с `processing_failed`, объект возвращён, и выполняется
команда с `--apply`
- **THEN** вложение становится `ready`, задание то же, число начатых попыток — 2, в журнале аудита одна запись с прежним
кодом, а оригинал скачивается с тем же SHA-256
#### Scenario: Replay готового не создаёт дубль
- **WHEN** выполняется команда с `--apply` для готового вложения
- **THEN** код выхода 3, отказ называет причину, метаданные совпадают с прежними во всех полях, включая `updated_at`,
число начатых попыток и объекты вариантов не изменились, а записи аудита нет
#### Scenario: Replay идущей работы
- **WHEN** выполняется команда с `--apply` для вложения в `queued` и для вложения в `processing`
- **THEN** код выхода 3, отказ называет причину, а новых сообщений и попыток нет
#### Scenario: Replay без исходника
- **WHEN** срок хранения staging вложения `failed` истёк, объект убран, и выполняется команда с `--apply`
- **THEN** код выхода 3, отказ называет причину, вложение остаётся `failed` с прежним кодом
#### Scenario: Новый бюджет попыток
- **WHEN** вложение стало `failed` с `retry_exhausted`, S3 возвращён, и выполняется команда с `--apply`
- **THEN** вложение становится `ready`, а число начатых попыток больше `max_attempts`
#### Scenario: Replay по причине
- **WHEN** несколько вложений стали `failed` с `retry_exhausted`, другое — с `invalid_image`, и выполняется команда с
выбором по коду `retry_exhausted` и `--apply`
- **THEN** первые становятся `ready`, а второе остаётся `failed`
### Requirement: Ограниченный prefetch
Брокер SHALL выдавать worker не больше `[worker] prefetch` неподтверждённых сообщений. Сообщение, для которого нет места
конкуренции, SHALL ждать в процессе worker без взятия: попытка и её аренда начинаются, когда место есть. Значения
конкуренции и prefetch SHALL быть в записи о старте worker, а время ожидания в очереди, длительность обработки и пик памяти
процесса обработки — в записях задания (`service-logging`, «Журнал worker»), чтобы их можно было мерить.
#### Scenario: Prefetch больше конкуренции
- **WHEN** worker запущен с конкуренцией 1 и prefetch 3, в очереди 5 заданий, и фиксация результатов задержана
- **THEN** неподтверждённых сообщений не больше 3, вложений в `processing` не больше 1, а все вложения затем становятся `ready`
@@ -0,0 +1,206 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Метаданные вложения
`GET /api/v1/attachments/{attachment_id}` SHALL отвечать 200 с объектом
`Attachment` во всех состояниях `queued`, `processing`, `ready` и `failed`
(`attachment-processing`, «Состояния вложения»). Поля `id`, `chat_id`,
`owner_id`, `filename`, `content_type`, `size_bytes`, `sha256` и `created_at`
SHALL совпадать с ответом на загрузку. `size_bytes`, `sha256` и `content_type`
всегда описывают оригинал, у вариантов — свои поля. `status`, `variants`,
`error_code` и `updated_at` SHALL отражать текущее состояние. У готового вложения
`variants` содержит каждый записанный вариант: у вложений этого уровня — `thumbnail`,
`crop` и `optimized`. Вложение, ставшее готовым до обработки вариантов, вариантов не
имеет, а ставшее готовым на уровне 3 — только `thumbnail`.
#### Scenario: Метаданные равны ответу загрузки
- **WHEN** Алиса загрузила вложение, а Боб запрашивает его метаданные
- **THEN** ответ 200, поля, описывающие оригинал, совпадают с ответом на
загрузку, а когда вложение становится `ready`, — `error_code` null и
непустые `variants`
### Requirement: Где хранятся вложения
Метаданные вложения SHALL храниться в PostgreSQL, байты — объектами в
приватном bucket S3 (`object-storage`). Байты MUST NOT храниться ни в
PostgreSQL, ни в файлах реплики API и worker. Ключ объекта назначает
сервер, `filename` в него MUST NOT входить:
- устойчивый staging — `<база>/staging/<id>/original`, живёт до фиксации `ready`, а
у `failed` — до конца срока хранения (`storage-consistency`, «Очистка staging»);
- конечный оригинал — `<база>/attachments/<id>/original`;
- вариант — `<база>/attachments/<id>/v<pipeline_version>-<вариант>`.
Staging и конечный префикс — один и тот же сервер S3 и bucket. Устойчивость
staging — устойчивость этого сервера. Граница называется в `REPORT.md`:
отказ диска или ВМ теряет и то, и другое.
Каждая загрузка SHALL создавать новое вложение и новые объекты, в том
числе повтор той же загрузки: прозрачных повторов загрузки нет
(`contracts/README.md`).
#### Scenario: Байты не в БД и не на диске API
- **WHEN** после загрузок через балансировщик вложения стали `ready`, и
проверяющий смотрит схему таблиц вложений, ключи объектов в PostgreSQL,
объекты в bucket и изменения файловой системы контейнеров реплик API и
worker
- **THEN** в таблицах нет колонки с байтами изображения, ключи объектов
имеют вид из требования и не содержат `filename`, объекты с этими
ключами есть в bucket, анонимный GET их ключей — 403, а в контейнерах
реплик и worker нет файлов оригиналов и вариантов
#### Scenario: Повторная загрузка
- **WHEN** участник дважды загружает один и тот же файл
- **THEN** оба ответа 202 с разными `id` и одинаковым `sha256`, и оба
вложения становятся `ready` и скачиваются
### Requirement: Порядок записи
Загрузка SHALL выполняться по шагам:
1. проверки и чтение тела;
2. запись метаданных в статусе «загружается» (`pending`) вместе с
ключами объектов, фиксация в PostgreSQL;
3. запись оригинала в staging;
4. статус `queued` и задание обработки — одной транзакцией;
5. ответ 202.
К брокеру загрузка MUST NOT обращаться: задание до него доводит relay
(`job-outbox`).
Объект, который записал API, SHALL быть известен PostgreSQL до записи в
S3: без зафиксированных метаданных объект не записывается. Вложение в
статусе `pending` MUST NOT быть видно через API: его метаданные и байты
— 404, ссылка на него в сообщении — 404.
Сбой после шага 2 из-за отказа хранилища SHALL давать 503
`unavailable`, а не 500. Отказ — S3 или PostgreSQL недоступен, не ответил
за срок или отказал. Метаданные «загружается» при этом
остаются. Их и объект убирает уборщик после grace period (capability
`storage-consistency`). Компенсация — сверх этого:
- объект записан, а шаг 4 не удался до того, как фиксация отправлена в
PostgreSQL. API SHALL удалить записанный объект до ответа. Удаление не
гарантировано: если оно не удалось, объект убирает уборщик;
- исход фиксации шага 4 неизвестен: связь оборвалась во время фиксации.
API MUST NOT удалять объект — вложение могло стать `queued`, и тогда его
доведёт до `ready` relay и worker, хотя клиент получил 503;
- к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их
уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть
503 `unavailable`, и API SHALL удалить записанный объект.
Если запись метаданных на шаге 2 не удалась, объект MUST NOT
записываться; отказ PostgreSQL при этом — 503 `unavailable`. Загрузка,
которую отклонили до шага 2 (401, 400, 404, 413, 415) или клиент оборвал
посреди тела, MUST NOT оставлять ни метаданных, ни объекта.
#### Scenario: Запись в S3 не удалась
- **WHEN** S3 остановлен, и участник загружает настоящий PNG
- **THEN** ответ 503 `unavailable`, в PostgreSQL появилось одно новое
вложение — в статусе «загружается», заданий и принятых не прибавилось
- **AND** текстовое сообщение в тот же чат — 201, а после возврата S3
та же загрузка — 202
#### Scenario: Отклонённая загрузка ничего не оставляет
- **WHEN** участник и посторонний отправляют загрузки, которые
отклоняются с 404, 413 по `Content-Length`, 413 по счётчику, 413 по
пикселям, 415 по типу и 415 по целостности
- **THEN** в PostgreSQL не появилось ни одного нового вложения, а в
bucket — ни одного нового объекта вложения
#### Scenario: Незавершённая загрузка не видна
- **WHEN** загрузка при остановленном S3 оставила вложение в статусе
«загружается», и участник чата по его `id` запрашивает метаданные и
байты и отправляет сообщение со ссылкой на него
- **THEN** все три ответа 404 `not_found` с тем же `message`, что у
неизвестного `id`
#### Scenario: Сбой записи метаданных
- **WHEN** PostgreSQL отказывает при записи метаданных новой загрузки
- **THEN** ответ 503 `unavailable`, а нового вложения нет ни в
PostgreSQL, ни в bucket
#### Scenario: Фиксация задания не удалась
- **WHEN** объект вложения записан в staging, а PostgreSQL отказывает при
переводе вложения в `queued`
- **THEN** ответ 503 `unavailable`, а не 500, и объекта этого вложения
в bucket уже нет, а задания у него нет
- **AND** вложение остаётся в статусе «загружается» до уборщика, а по
API его не видно
#### Scenario: Фиксация ready не удалась
- **WHEN** worker записал объекты вложения, а PostgreSQL отказывает при
фиксации `ready`
- **THEN** вложение не готово: метаданные — `queued` или `processing`,
скачивание — 409 `conflict`, а следующая попытка доводит его до `ready`
#### Scenario: Исход фиксации неизвестен
- **WHEN** объект вложения записан в staging, а фиксация перевода в
`queued` обрывается отказом PostgreSQL
- **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и
по API не видно, а его объект в bucket остаётся: API его не удаляет
- **AND** после grace уборщик убирает и метаданные, и объект, а в bucket
нет объектов вложений без метаданных
#### Scenario: Брокер не подтвердил задание
- **WHEN** брокер остановлен, и участник загружает настоящий PNG
- **THEN** ответ 202, а не 503, вложение `queued`, у его задания нет времени
подтверждения брокером, а объект — в staging
- **AND** после запуска брокера вложение становится `ready`
#### Scenario: Обрыв передачи тела
- **WHEN** клиент обрывает соединение посреди тела загрузки
- **THEN** нового вложения нет ни в PostgreSQL, ни в bucket, а следующая
загрузка того же участника — 202
### Requirement: Скачивание варианта
`GET /api/v1/attachments/{attachment_id}/content?variant=<имя>` у готового вложения
SHALL отвечать 200 с байтами варианта `thumbnail`, `crop` или `optimized` через API, без
перенаправления. Заголовки ответа: `Content-Type` — `content_type` варианта,
`Content-Length` — его размер, `X-Content-Type-Options: nosniff`. Размер и
SHA-256 байтов равны полям варианта в метаданных. Доступ — как у оригинала
(требование «Доступ к вложению»).
Вариант, которого у готового вложения нет, SHALL давать 404 `not_found`. Это вложения,
ставшие готовыми раньше: до обработки вариантов — любой вариант, на уровне 3 — `crop` и
`optimized`. Нет объекта варианта в S3 или размер другой — 500 `internal_error` без деталей,
причина в журнале.
#### Scenario: Скачивание thumbnail
- **WHEN** Боб скачивает `variant=thumbnail` готового вложения, загруженного
Алисой
- **THEN** ответ 200, не перенаправление, `Content-Type: image/jpeg`,
`Content-Length` равен `size_bytes` варианта, есть `X-Content-Type-Options:
nosniff`, а SHA-256 равен `sha256` варианта
#### Scenario: Скачивание crop и optimized
- **WHEN** Боб скачивает `variant=crop` и `variant=optimized` готового вложения,
загруженного Алисой
- **THEN** оба ответа 200, не перенаправление, `Content-Type` — `image/jpeg` и
`image/webp`, `Content-Length` равен `size_bytes` варианта, есть
`X-Content-Type-Options: nosniff`, а SHA-256 равен `sha256` варианта
#### Scenario: Отсутствующий вариант
- **WHEN** у готового вложения нет метаданных варианта `crop`, потому что оно стало
готовым раньше этого уровня, и участник скачивает `variant=crop`
- **THEN** ответ 404 `not_found` в формате ошибки, а остальные варианты скачиваются
#### Scenario: Вариант для постороннего
- **WHEN** Ева скачивает `variant=thumbnail` вложения чата Алисы и Боба
- **THEN** ответ 404 `not_found` с тем же `message`, что у неизвестного `id`
@@ -0,0 +1,49 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Worker на образе приложения
Worker SHALL запускаться из того же образа, что и API, своей командой. Процессом
с PID 1 контейнера worker SHALL быть сам worker (`python -m src.worker`), без
оболочки между Docker и им. Декодер изображений SHALL входить в образ зависимостью
времени выполнения из `uv.lock`, без компиляторов в runtime. Healthcheck образа
проверяет HTTP и worker не подходит: у контейнера worker он SHALL быть выключен, и
живость видна по журналу.
Реплики API и сам процесс worker MUST NOT загружать декодер изображений в память: его
загружает только дочерний процесс обработки (`attachment-processing`, «Лимиты обработки»).
#### Scenario: PID 1 worker
- **WHEN** в работающем контейнере worker читается командная строка процесса 1
- **THEN** это `python -m src.worker`, а `docker inspect` не показывает у контейнера
проверки здоровья
#### Scenario: Декодер в образе
- **WHEN** в образе, собранном из чистого clone, импортируется декодер изображений
и запрашивается версия
- **THEN** импорт проходит, версия совпадает с `uv.lock`, поддержка WebP есть, а `uv` и
компиляторов в образе нет
#### Scenario: Декодера нет в процессе API
- **WHEN** в работающей реплике API и в процессе 1 контейнера worker проверяются
загруженные модули
- **THEN** декодера изображений среди них нет
## ADDED Requirements
### Requirement: Relay на образе приложения
Relay SHALL запускаться из того же образа, что и API, своей командой. Процессом с PID 1
контейнера relay SHALL быть сам relay (`python -m src.relay`), без оболочки между Docker
и им. Healthcheck образа проверяет HTTP и relay не подходит: у контейнера он SHALL быть
выключен, живость видна по журналу.
#### Scenario: PID 1 relay
- **WHEN** в работающем контейнере relay читается командная строка процесса 1
- **THEN** это `python -m src.relay`, а `docker inspect` не показывает у контейнера проверки
здоровья
@@ -0,0 +1,248 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать стенд через
`docker compose`. В стенд входят:
- PostgreSQL и Valkey;
- сервер S3 (capability `object-storage`);
- брокер (capability `message-broker`);
- одноразовые сервисы миграций и bootstrap S3;
- `API_REPLICAS` реплик API (capability `load-balancing`);
- уборщик незавершённых загрузок (capability `storage-consistency`) —
один долгоживущий процесс на образе API со своей командой;
- relay (capability `job-outbox`) — долгоживущий процесс на образе API со своей
командой;
- worker (capability `attachment-processing`) — долгоживущий процесс на образе
API со своей командой;
- балансировщик (LB).
Реплики API SHALL стартовать после готовности PostgreSQL и Valkey,
успешных миграций и успешного bootstrap S3. Брокера реплики не ждут: они к нему не
обращаются. Миграции и bootstrap SHALL выполняться один раз за запуск отдельными
сервисами, а не репликами. Уборщик SHALL стартовать после готовности PostgreSQL,
успешных миграций и успешного bootstrap S3. Relay SHALL стартовать после готовности
PostgreSQL и брокера и успешных миграций. Worker SHALL стартовать после готовности
PostgreSQL и брокера, успешных миграций и успешного bootstrap S3. Реплики API их не ждут,
а фоновую уборку, публикацию заданий и обработку изображений MUST NOT выполнять сами.
Уборщик, relay и worker MUST NOT публиковать порты и SHALL перезапускаться после сбоя.
Перед этим цель SHALL создавать недостающие `.env` и `config.toml` из
шаблонов (`make env_setup`) и MUST NOT перезаписывать существующие: в
существующий `.env` она только дописывает переменные шаблона, которых в
нём нет (capability `service-configuration`, «Подключение к S3»).
`make stop` SHALL останавливать сервисы, `make down` — удалять
контейнеры, сохраняя volumes, `make logs` — показывать журнал всех
реплик API.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает через LB на
`http://localhost:8080/health/ready`, работают две реплики API,
уборщик, relay и worker, сервер S3 и брокер в состоянии `healthy`, bootstrap S3
завершился с кодом 0, и `make student_test` проходит
#### Scenario: Миграции один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал сервиса миграций содержит один прогон, а в журналах
реплик API, relay и worker нет запуска миграций
#### Scenario: Bootstrap S3 один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал bootstrap S3 содержит один прогон, завершённый до
старта реплик, уборщика и worker, а в журналах реплик API нет создания
bucket
### Requirement: Порты из .env
Порты стенда и консольного запуска SHALL браться из одного `.env`:
- внутренний порт API — `APP__PORT`: параметр приложения `[app] port` в
формате настроек. Его слушает каждая реплика, на нём работают
healthcheck и проверки LB, на нём же LB принимает запросы внутри
своего контейнера;
- внешний порт стенда — `APP_OUT_PORT`: порт LB на `127.0.0.1` хоста,
приложение его не читает;
- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает
сам сервер и использует API в docker;
- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1`
хоста для запуска в консоли;
- порт Valkey внутри сети compose — `VALKEY_PORT`, внешний —
`VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли;
- порт API S3 внутри сети compose — `S3_PORT`, его слушает сам сервер
S3, используют API в docker и bootstrap; внешний — `S3_OUT_PORT` на
`127.0.0.1` для запуска в консоли;
- порт AMQP брокера внутри сети compose — `RABBITMQ_PORT`, его слушает сам
брокер, используют relay и worker в docker; внешний — `RABBITMQ_OUT_PORT` на
`127.0.0.1` для запуска в консоли.
Если переменная порта API не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL, Valkey, S3 и брокера
MUST NOT быть записаны в compose литералами.
#### Scenario: Другой внешний порт
- **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен
`make run_docker`
- **THEN** API доступно через LB на `localhost:8090`, а внутри
контейнеров реплики слушают `APP__PORT`
#### Scenario: Другой внутренний порт
- **WHEN** в `.env` задано `APP__PORT=9090`
- **THEN** реплики внутри контейнеров слушают 9090 и становятся
`healthy`, LB проверяет их на 9090, а API доступно на
`localhost:$APP_OUT_PORT`
#### Scenario: Другой порт Postgres
- **WHEN** в `.env` заданы `POSTGRES_PORT=5544` и
`POSTGRES_OUT_PORT=5545`, а compose не правился
- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает
200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545`
#### Scenario: Другой порт Valkey
- **WHEN** в `.env` заданы другие `VALKEY_PORT` и `VALKEY_OUT_PORT`, а
compose не правился
- **THEN** `make run_docker` и `make run_dev` подключаются к Valkey на
новых портах, и кэш работает
#### Scenario: Другой порт S3
- **WHEN** в `.env` заданы другие `S3_PORT` и `S3_OUT_PORT`, а compose
не правился
- **THEN** сервер S3 слушает `S3_PORT` и становится `healthy`, bootstrap
проходит, `make s3_check` проходит, а приложение в консоли обращается
к S3 на `127.0.0.1:$S3_OUT_PORT`
#### Scenario: Другой порт брокера
- **WHEN** в `.env` заданы другие `RABBITMQ_PORT` и `RABBITMQ_OUT_PORT`, а
compose не правился
- **THEN** брокер слушает `RABBITMQ_PORT` и становится `healthy`, загрузка
через LB становится `ready`, а relay и worker в консоли обращаются к брокеру на
`127.0.0.1:$RABBITMQ_OUT_PORT`
### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
способа запуска стенда:
- `make run_docker` — всё в compose;
- `make run_dev` — PostgreSQL, Valkey, S3 с bootstrap и брокер в compose,
сервис на хосте; relay на хосте — `make run_relay`, worker на хосте —
`make run_worker`.
Для каждого SHALL быть указаны подготовка (`make env_setup`), команды,
которые выполняет цель Makefile, применение миграций и bootstrap S3,
ожидание готовности, проверки и остановка.
#### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make student_test` и
`make s3_check` проходят
### Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey, порт API S3 и порт AMQP брокера SHALL
публиковаться в compose только на `127.0.0.1` хоста. Адрес публикации SHALL быть
записан литералом, а не переменной. Другие порты сервера S3 (консоль,
UI, внутренние серверы хранилища) и другие порты брокера (метрики, связь узлов)
MUST NOT публиковаться. Реплики API, relay, worker и одноразовые сервисы MUST NOT
публиковать порты на хосте: к репликам ходят только LB и контейнеры сети compose.
Учебный стенд MUST NOT быть доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенных контейнеров LB, API, relay, worker, Postgres, Valkey, S3 и
брокера выполняется `docker port`
- **THEN** порты LB, Postgres, Valkey, порт API S3 и порт AMQP брокера
опубликованы на `127.0.0.1`, а не на `0.0.0.0`; других портов у S3 и брокера
не опубликовано, а у контейнеров API, relay и worker опубликованных портов нет
### Requirement: Данные переживают рестарт стенда
Данные PostgreSQL, S3 и брокера SHALL храниться в именованных volumes. Скрипт
`scripts/restart.sh` SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL, Valkey, S3 и брокер. Volumes, схема,
bucket, учётные записи S3, очередь, её сообщения и данные SHALL сохраняться: без
удаления volumes, очистки и повторного наполнения. Bootstrap S3, который снова
выполняется при старте реплик, состояние хранилища не меняет. Число
реплик после рестарта SHALL оставаться прежним. Relay, worker и уборщика скрипт не
трогает: они переживают рестарт хранилищ сами, а остановленный worker остаётся
остановленным. Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после
перезапуска, укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка
`make test-persistence ACTION_SCRIPT=scripts/restart.sh` SHALL проходить через LB.
#### Scenario: Рестарт hook-ом
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
`scripts/restart.sh`
- **THEN** контейнеры LB, всех реплик API, Postgres, Valkey, S3 и брокера
перезапущены: те же ID и новое время старта в `docker inspect`. После
готовности запрос с прежним токеном через LB получает 200 и видит
своё сообщение, а bootstrap S3 после рестарта сообщает, что bucket и
пользователи уже есть
#### Scenario: Публичная проверка сохранности
- **WHEN** на запущенном стенде выполняется `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`
- **THEN** команда завершается с кодом 0 и печатает `PASS`
#### Scenario: Worker переживает рестарт хранилищ
- **WHEN** relay и worker работают, выполнен `scripts/restart.sh`, и участник загружает
файл
- **THEN** вложение становится `ready`, а у контейнеров relay и worker прежнее время
старта и счётчик перезапусков 0
### Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
уборщик, relay, worker, сервисы миграций и bootstrap S3, PostgreSQL, Valkey, сервер
S3 и брокер. Сумма лимитов и расчёт соединений PostgreSQL для заявленного числа
реплик, уборщика, relay и worker SHALL быть описаны в `REPORT.md`. Секреты SHALL
передаваться только тем сервисам, которым они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API, уборщику, relay, worker и сервису
миграций;
- пароль Valkey — Valkey и репликам API;
- пароль брокера — брокеру, relay и worker;
- административные ключ и секрет S3 — только серверу S3;
- ключ подписи служебных вызовов S3 — серверу S3 и bootstrap;
- ключи пользователя API в S3 — bootstrap и репликам API;
- ключи пользователя уборщика в S3 — bootstrap и уборщику;
- ключи пользователя worker в S3 — bootstrap и worker;
- LB MUST NOT получать ни одного секрета, а сервис миграций, PostgreSQL,
Valkey и брокер MUST NOT получать секретов S3. Реплики API MUST NOT получать пароль
брокера. Уборщик MUST NOT получать пароли Valkey и брокера, ключи API и worker,
административные ключи S3 и ключ подписи. Relay MUST NOT получать пароль Valkey и секреты
S3. Worker MUST NOT получать пароль Valkey, ключи API и уборщика, административные ключи
S3 и ключ подписи.
#### Scenario: Лимиты у всех контейнеров
- **WHEN** для каждого контейнера запущенного стенда выполняется
`docker inspect` (`HostConfig.NanoCpus`, `HostConfig.Memory`)
- **THEN** у LB, каждой реплики API, уборщика, relay, worker, сервисов миграций и
bootstrap S3, PostgreSQL, Valkey, сервера S3 и брокера оба значения больше нуля
#### Scenario: Секреты по сервисам
- **WHEN** проверяющий смотрит окружение сервисов в
`docker compose config`
- **THEN** у LB нет ни одного секрета; у сервиса миграций нет паролей
Valkey и брокера и секретов S3; пароль Valkey есть только у Valkey и реплик
API; пароль брокера — только у брокера, relay и worker; административные
ключи S3 — только у сервера S3, ключ подписи — у сервера S3 и bootstrap, ключи
API в S3 — у bootstrap и реплик API, ключи уборщика в S3 — у bootstrap и
уборщика, ключи worker в S3 — у bootstrap и worker
@@ -0,0 +1,58 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Целостность данных в БД
Ограничения SHALL проверяться самой БД, а не только сервисом:
- уникальность `username`;
- существование пользователей и чатов, на которые ссылаются участники
и сообщения;
- уникальность участника в чате;
- членство отправителя в чате сообщения.
С лабы 4 БД SHALL проверять и вложения:
- владелец вложения — участник его чата;
- связь сообщения с вложением ссылается на существующие сообщение и
вложение;
- вложение не повторяется в одном сообщении, у каждого места в порядке
одно вложение, мест не больше 10;
- вложение, на которое ссылается сообщение, удалить нельзя;
- допустимые значения размера, SHA-256, типа, статуса и длины
`filename`; ключ объекта уникален.
С лабы 5 БД SHALL проверять и обработку:
- код ошибки есть только у вложения `failed`, и у `failed` он есть;
- на вложение и версию конвейера одно задание, оно ссылается на существующее
вложение; вложение с заданием удалить нельзя;
- допустимые значения состояния и числа попыток задания; число попыток до
последнего replay не больше числа начатых;
- вариант уникален по вложению, версии конвейера и имени; он ссылается на
существующее вложение; допустимые значения имени, типа, размера, ширины,
высоты и SHA-256; ключ объекта варианта уникален;
- запись аудита replay ссылается на существующее задание; задание с такой записью
удалить нельзя.
Порядок `member_ids`, заданный при создании чата, и порядок
`attachment_ids` сообщения SHALL сохраняться. Принадлежность вложения
чату сообщения проверяет сервис в той же транзакции: чат вложения и
чат сообщения не меняются после записи.
#### Scenario: Порядок участников
- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]`
- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в
том же порядке, в том числе после рестарта стенда
#### Scenario: Порядок вложений
- **WHEN** сообщение отправлено с `attachment_ids` `[C, A, B]`
- **THEN** ответ на отправку, история чата и повтор с тем же ключом
возвращают `[C, A, B]`
#### Scenario: Ограничения обработки в схеме
- **WHEN** проверяющий пытается вставить второе задание той же версии конвейера,
второй вариант с тем же именем, `error_code` у вложения не `failed` и запись аудита
replay с неизвестным заданием
- **THEN** PostgreSQL отклоняет каждую вставку нарушением ограничения
@@ -0,0 +1,93 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Совместимость миграции с работающей версией
Миграция SHALL только расширять схему:
- новая таблица со своими ограничениями и внешними ключами;
- новая колонка, допускающая NULL или со значением по умолчанию;
- новый индекс; на таблице, в которую идёт запись, — без блокировки записи на время
сборки;
- ослабление ограничения: новое условие пропускает всё, что пропускало
прежнее, поэтому прежняя версия не пишет значений, которые новое
условие запретит.
Ослабленное ограничение SHALL добавляться без проверки существующих
строк под эксклюзивной блокировкой таблицы: эти строки уже
удовлетворяли более строгому условию. Новое ограничение на новые колонки
существующей таблицы SHALL добавляться так же: прежняя версия эти колонки не
пишет, а значения прежних строк ему удовлетворяют.
Удаление и переименование таблицы, колонки или ограничения (кроме
замены ограничения ослабленным), а также новое ограничение, которое
нарушит запись прежней версии, MUST NOT входить в ту же поставку, что и
код, которому они нужны. Такое изменение выполняется отдельной миграцией
после того, как реплик прежней версии не осталось (expand/contract).
Если так сделать нельзя, ограничение SHALL описываться в `REPORT.md`.
Реплики прежнего образа SHALL обслуживать обязательные запросы на
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
требовать отката схемы. Новые значения статуса вложения прежний образ
прочитать не может; это ограничение смешанных версий при переходе 4 → 5 SHALL
быть в `REPORT.md`.
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
Долгая транзакция приложения не должна заставить миграцию держать
очередь за собой и остановить запись остальных реплик. Срок SHALL быть
меньше срока запроса приложения к БД (`statement_timeout`): запросы,
вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
проходить.
#### Scenario: Старый образ на новой схеме
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
образа применены, а реплики не заменены
- **THEN** проверки, которые прежний образ проходил на прежней схеме,
проходят и на новой: запись сообщений через прежние реплики — 201,
история — 200, ответов 5xx нет (замер замены реплик —
`evidence/rollout/pipeline-reliability/summary.md`)
- **AND** проверки, которых прежний образ не проходил и на прежней схеме
(новые требования контракта, например вложения лабы 4 для образа лабы
4 до `attachments`), совместимостью схемы не считаются
#### Scenario: Запись прежней версии
- **WHEN** после новой миграции сообщение отправлено через реплику
прежнего образа
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
образа
#### Scenario: Блокировка не получена
- **WHEN** таблицу, которую меняет миграция, держит открытая
транзакция дольше срока ожидания блокировки
- **THEN** миграция завершается ошибкой, схема не меняется, запросы
других клиентов, ждавшие за миграцией, получают успешный ответ, а
после окончания транзакции повторный запуск применяет миграцию
#### Scenario: Ослабленное ограничение
- **WHEN** миграция вложений заменяет ограничение длины текста
сообщения (было 1–4000, стало 0–4000) на таблице с сообщениями, а
запись идёт через реплики прежнего образа
- **THEN** миграция не проверяет существующие строки, записи прежних
реплик во время и после неё — 201, а после замены реплик сообщение с
пустым текстом и вложением — 201
#### Scenario: Новые состояния вложения
- **WHEN** миграция обработки вложений применена к базе с вложениями `pending`
и `ready`, а реплики прежнего образа ещё работают
- **THEN** миграция не проверяет существующие строки под эксклюзивной
блокировкой, их `status` прежний, загрузка через прежнюю реплику проходит,
как раньше, а повторный запуск миграций ничего не меняет
#### Scenario: Поля надёжности обработки
- **WHEN** миграции этого уровня применены к базе с заданиями всех состояний, а реплики и
worker прежнего образа ещё работают
- **THEN** индексы построены без блокировки записи, задание прежнего образа вставляется без
новых колонок, прежние строки не меняются, а повторный запуск миграций ничего не меняет
@@ -0,0 +1,71 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Остановка worker
По SIGTERM worker (capability `attachment-processing`) SHALL перестать принимать
новые сообщения и дать начатым заданиям завершиться, но не дольше `[worker]
graceful_shutdown_seconds`. Задание, которое не успело, SHALL оставаться
неподтверждённым: брокер доставит его снова (`attachment-processing`, «Доставка at
least once»), а его процесс обработки SHALL быть убит. Затем worker SHALL выйти с кодом 0
раньше срока остановки контейнера (10 с), а не по SIGKILL, в том числе если декодирование
ещё идёт.
Значение `graceful_shutdown_seconds` MUST быть не больше 8: вместе с закрытием клиентов
остановка в худшем случае укладывается в 9,5 с. Сигнал во время старта процесса SHALL
завершать его с кодом 0 без traceback, как у API (требование «Остановка во время старта»).
Остановка SHALL быть видна в журнале записью об остановке worker.
Ограничение называется в `REPORT.md`. Задание, прерванное остановкой, считается начатой
попыткой: следующую она получит, когда истечёт срок её аренды.
#### Scenario: docker stop простаивающего worker
- **WHEN** выполняется `docker compose stop worker` для worker без заданий
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале
есть запись об остановке
#### Scenario: docker stop во время обработки
- **WHEN** `docker compose stop worker` выполняется, пока фиксация результата задания
задержана дольше срока остановки worker
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, сообщение
задания снова в очереди, а после запуска worker вложение становится `ready`
#### Scenario: docker stop во время декодирования
- **WHEN** `docker compose stop worker` выполняется, пока идёт декодирование дольше срока
остановки worker
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, процесса обработки не
осталось, а задание получает следующую попытку после запуска worker
#### Scenario: docker stop во время старта worker
- **WHEN** контейнер worker остановлен в первые доли секунды после старта, пока
процесс ещё импортирует приложение
- **THEN** `docker stop` завершается не дольше чем за 1 с, код выхода контейнера 0, а в
журнале есть запись об остановке worker до старта
## ADDED Requirements
### Requirement: Остановка relay
По SIGTERM relay (capability `job-outbox`) SHALL довести текущий проход до фиксации или
отката и выйти с кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL. Новые
проходы не начинаются, а паузу между проходами сигнал прерывает сразу. Незаписанное время
подтверждения ничего не теряет: следующий запуск опубликует задание снова. Сигнал во время
старта процесса SHALL завершать его с кодом 0 без traceback. Остановка SHALL быть видна в
журнале.
#### Scenario: docker stop relay
- **WHEN** выполняется `docker compose stop relay`, в том числе при замороженном брокере
- **THEN** команда завершается быстрее 10 с, код выхода контейнера 0, а в журнале есть запись
об остановке relay
#### Scenario: docker stop во время старта relay
- **WHEN** контейнер relay остановлен в первые доли секунды после старта
- **THEN** `docker stop` завершается не дольше чем за 1 с, код выхода контейнера 0, а в журнале
есть запись об остановке relay до старта
@@ -0,0 +1,56 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Readiness
`GET /health/ready` SHALL отвечать 200 с телом `{"status": "ok"}`,
когда сервис может безопасно обслуживать обязательные запросы, и 503 с
`code` `unavailable` в формате ошибки, когда не может. Критичная
зависимость — PostgreSQL: проверка SHALL выполнять запрос к нему с
коротким таймаутом при каждом обращении.
Пять зависимостей не критичны, и их недоступность MUST NOT делать сервис
неготовым:
- Valkey — кэш: без него обязательные запросы обслуживаются из
PostgreSQL;
- S3 — хранилище байтов вложений: путь без вложений его не использует;
- брокер — доставка заданий: реплики API к нему не обращаются, загрузка отвечает
202, а задания ждут в PostgreSQL;
- relay — публикация заданий: без него задания ждут в PostgreSQL;
- worker — фоновая обработка: без него загрузки ждут в очереди.
Проверка MUST NOT обращаться к S3 и брокеру и MUST NOT требовать
идентификации. Перечень критичных и некритичных зависимостей с причинами
SHALL быть в `REPORT.md`.
#### Scenario: Сервис запущен
- **WHEN** запуск сервиса завершён, PostgreSQL доступен, и клиент
запрашивает `GET /health/ready`
- **THEN** ответ 200, тело `{"status": "ok"}`
#### Scenario: Хранилище не готово
- **WHEN** PostgreSQL недоступен
- **THEN** ответ 503 с `code` `unavailable` в формате ошибки не позже
таймаута проверки, а `GET /health/live` при этом отвечает 200
#### Scenario: Кэш недоступен
- **WHEN** Valkey остановлен, а PostgreSQL доступен
- **THEN** `GET /health/ready` отвечает 200
#### Scenario: Хранилище объектов недоступно
- **WHEN** сервер S3 остановлен или заморожен (`docker pause`), а
PostgreSQL доступен
- **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее
секунды: проверка к S3 не обращается
#### Scenario: Брокер и worker недоступны
- **WHEN** брокер остановлен или заморожен (`docker pause`), relay и worker
остановлены, а PostgreSQL доступен
- **THEN** `GET /health/ready` и `GET /health/live` отвечают 200 быстрее
секунды: проверка к брокеру не обращается
@@ -0,0 +1,169 @@
# Spec Delta
## Purpose
Transactional outbox заданий обработки вложений с лабы 5, уровень 4: намерение
обработать файл фиксируется в PostgreSQL вместе с приёмом, а до брокера его доводит
отдельный процесс relay. Здесь описано:
- что означает приём и почему он не зависит от брокера;
- публикация с подтверждением и доставка at least once;
- несколько экземпляров relay, срок следующей попытки и порядок;
- потерянные сообщения и предел опубликованных заданий.
## ADDED Requirements
### Requirement: Приём не зависит от брокера
Реплики API MUST NOT обращаться к брокеру и MUST NOT получать его пароль. Ответ 202 на
загрузку SHALL означать, что оригинал записан в staging, а вложение `queued` и его
задание зафиксированы в PostgreSQL одной транзакцией (`attachments`, «Порядок
записи»). Зафиксированное задание без времени подтверждения брокером — это намерение:
оно уже не может потеряться, его SHALL довести до брокера relay.
Ответ на загрузку MUST NOT зависеть от состояния брокера и relay: их отказ, заморозка и
остановка не меняют ни кода ответа, ни срока, в который он приходит.
#### Scenario: Загрузка при остановленном брокере
- **WHEN** брокер остановлен, и участник загружает настоящий PNG
- **THEN** ответ 202 быстрее секунды, вложение `queued`, его задание без времени
подтверждения брокером
- **AND** после запуска брокера вложение становится `ready` без действий клиента
#### Scenario: Загрузка при замороженном брокере
- **WHEN** контейнер брокера заморожен (`docker pause`), и участник загружает настоящий
PNG
- **THEN** ответ 202 быстрее секунды, а после разморозки вложение становится `ready`
#### Scenario: Ответ не ждёт публикации
- **WHEN** relay остановлен, и участник загружает настоящий PNG
- **THEN** ответ 202, в очереди нет сообщения этого задания, а метаданные — 200 со
`status` `queued`
### Requirement: Relay публикует намерения
Намерения SHALL публиковать relay — отдельный процесс стенда (`container-run`). Он MUST
NOT читать байты вложений и обращаться к S3. Relay SHALL проходить по заданиям не реже
чем раз в `[relay] poll_interval_seconds` и публиковать каждое задание `queued`, срок
которого наступил (требование «Порядок и срок публикации»), а время подтверждения брокером
записывать только после подтверждения этого сообщения брокером.
Сообщение SHALL соответствовать `contracts/jobs.schema.json`: тот же `job_id`, а `attempt`
на единицу больше числа начатых попыток задания.
Доставка at least once: сбой relay или брокера до записи времени подтверждения SHALL вести
к новой публикации того же задания. Лишнее сообщение MUST NOT создавать второго набора
вариантов и новой попытки у завершённого задания (`attachment-processing`, «Доставка at least
once»). Отказ брокера и PostgreSQL MUST NOT завершать процесс relay: он повторяет проход
после паузы `[relay] failure_pause_seconds`, а журнал называет отказ.
Задание `queued` без времени подтверждения, записанное предыдущей версией кода, SHALL
публиковаться так же.
#### Scenario: Crash между фиксацией и публикацией
- **WHEN** relay завершён сигналом KILL, участник загрузил файл (202), а затем relay снова
запущен
- **THEN** до запуска в очереди нет сообщения этого задания и у него нет времени
подтверждения, а после запуска вложение становится `ready` с тем же заданием, без создания
нового задания вручную
#### Scenario: Задание без отметки от прежней версии
- **WHEN** в базе есть вложение `queued` с заданием без времени подтверждения, а сообщения о
нём в очереди нет
- **THEN** relay публикует его сообщение, у задания появляется время подтверждения, а
вложение становится `ready`
#### Scenario: Crash после подтверждения до отметки
- **WHEN** worker остановлен, запись времени подтверждения задержана, брокер уже подтвердил
сообщение задания, relay завершён сигналом KILL и снова запущен, а затем запущен worker
- **THEN** relay публикует задание ещё раз, вложение становится `ready`, число начатых
попыток — 1, у каждого варианта один объект, а сообщений в очереди не осталось
#### Scenario: Отказ брокера во время работы relay
- **WHEN** брокер остановлен, пока relay работает, участник загружает файл, а затем брокер
запущен
- **THEN** в журнале relay есть запись об отказе брокера, вложение становится `ready`, а у
контейнера relay прежнее время старта и счётчик перезапусков 0
#### Scenario: Отказ PostgreSQL во время работы relay
- **WHEN** PostgreSQL останавливается и снова запускается, пока relay работает, а затем
участник загружает файл
- **THEN** в журнале relay есть запись об отказе, вложение становится `ready`, а у контейнера
relay прежнее время старта и счётчик перезапусков 0
### Requirement: Несколько экземпляров relay
Одновременно могут работать несколько процессов relay. Каждое задание за один проход SHALL
публиковать один из них: задание, которое публикует другой процесс, relay пропускает, а не
ждёт. Если процесс завершился до записи времени подтверждения, задание публикует следующий
проход любого из них. На стенде relay один; второй экземпляр нужен на время замены.
#### Scenario: Два relay
- **WHEN** worker остановлен, работают два процесса relay, и участник загружает несколько
файлов
- **THEN** в очереди ровно по одному сообщению на вложение
### Requirement: Порядок и срок публикации
Срок нового задания SHALL наступать при его записи, а срок следующей попытки — в момент,
записанный в задании (`attachment-processing`, «Ограниченные повторы»). Раньше срока задание
MUST NOT публиковаться. Задания SHALL выбираться в порядке наступления срока: повтор не стоит
за всеми новыми заданиями. Порядок обработки при этом не гарантирован: обработка одного
вложения не зависит от другого.
#### Scenario: Следующая попытка не раньше срока
- **WHEN** попытка задания закончилась временной ошибкой, и срок следующей попытки ещё не
наступил
- **THEN** в очереди нет сообщения этого задания, а когда срок наступил, relay публикует его с
`attempt` на единицу больше
### Requirement: Потерянное сообщение
Если задание `queued` отмечено подтверждённым брокером дольше `[relay]
republish_after_seconds` назад, а готовых сообщений в его очереди нет, сообщение считается
потерянным: очередь удалена или данные брокера утрачены. Relay SHALL опубликовать такое задание
снова. Пока в очереди есть готовые сообщения, relay MUST NOT публиковать задания повторно: так
длинная очередь не обрастает копиями.
#### Scenario: Очередь удалена вместе с сообщением
- **WHEN** worker остановлен, сообщение задания подтверждено брокером, очередь удалена мимо
приложения, срок прошёл, и worker запущен
- **THEN** relay объявляет очередь и публикует задание снова, а вложение становится `ready`
#### Scenario: Очередь с сообщениями не обрастает копиями
- **WHEN** worker остановлен, в очереди есть сообщения подтверждённых заданий, и срок прошёл
- **THEN** число сообщений в очереди не меняется, а после запуска worker все вложения становятся
`ready`
### Requirement: Предел опубликованных заданий
Relay MUST NOT публиковать новые задания, пока заданий `queued` с подтверждением брокера не
меньше `[relay] max_published_backlog`: остальные ждут в PostgreSQL. Значение 0 — без предела.
Так длина очереди брокера ограничена настройкой, а накопление видно в PostgreSQL. Срабатывание
предела памяти брокера SHALL сдерживать публикацию так же: relay получает отказ по сроку, задания
ждут в PostgreSQL, а загрузки по-прежнему отвечают 202.
Ограничение принятой работы на входе API здесь не вводится: это `track1-queue-overload`.
#### Scenario: Очередь ограничена пределом
- **WHEN** worker остановлен, relay работает с пределом 2, и участник загружает 5 файлов
- **THEN** каждый ответ 202, в очереди 2 сообщения, у остальных заданий нет времени подтверждения,
а после запуска worker все вложения становятся `ready`
#### Scenario: Брокер сдерживает публикацию
- **WHEN** сработал предел памяти брокера, и участник загружает файл
- **THEN** ответ 202 быстрее секунды, у задания нет времени подтверждения, журнал relay называет
отказ брокера, а после снятия предела вложение становится `ready`
@@ -0,0 +1,56 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Загрузки через балансировщик
Для `POST /api/v1/chats/{chat_id}/attachments` срок, в который LB ждёт
реплику (`timeout server`), SHALL быть 30 с. Это больше самого длинного
молчания живой загрузки:
- до чтения тела — вход, членство в чате и ожидание места загрузки, не
дольше `2 × [database] request_timeout_seconds + [uploads]
wait_timeout_seconds` (17 с);
- после тела — проверка изображения, запись метаданных, запись объекта в
staging, перевод в `queued` с заданием и удаление объекта при
компенсации, не дольше `2 × request_timeout_seconds + 2 × [s3]
timeout_seconds` плюс проверка изображения (около 26 с). Брокера на этом
пути нет.
У остальных путей срок SHALL оставаться прежним, 10 с: цепочка
таймаутов лабы 3 для них не меняется.
Наибольшая длительность живой загрузки — молчание до тела, срок
передачи тела (`[uploads] body_timeout_seconds`) и молчание после тела,
около 73 с при значениях по умолчанию. Она и формула SHALL быть в
`REPORT.md`.
Соединение с недочитанным телом SHALL держать в буферах ядра ограниченный
объём: буфер приёма сокетов реплики API — не больше 512 KiB, буфер
отправки LB к реплике — 256 KiB, буфер приёма LB от клиента — 128 KiB.
Так ожидающие и отклонённые загрузки не
переносят тела целиком ни в память реплики, ни в память LB.
#### Scenario: Долгая обработка загрузки
- **WHEN** реплика на пути загрузки молчит дольше 10 с, но меньше 30 с:
до чтения тела или после него
- **THEN** клиент получает ответ реплики, а не 502 или 504 от LB
#### Scenario: Прежний срок остальных путей
- **WHEN** реплика молчит дольше 10 с на любом другом пути
- **THEN** через ~10 с клиент получает 504 от LB в формате ошибки
контракта
#### Scenario: Загрузка дольше срока LB
- **WHEN** реплика на пути загрузки молчит дольше 30 с
- **THEN** через ~30 с клиент получает 504 от LB в формате ошибки
контракта
#### Scenario: Буферы соединений ограничены
- **WHEN** 40 клиентов одновременно загружают по 10 MiB через LB в одну
реплику с параметрами загрузок по умолчанию
- **THEN** пик памяти LB и буферов сокетов реплики растёт не больше чем
на 1 MiB на клиента, а реплика и LB не завершены из-за памяти
@@ -0,0 +1,371 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Фиксированный стенд
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
PostgreSQL и Valkey. В профилях загрузок и сверки к ним SHALL
добавляться S3 с его bootstrap, а в профиле сверки — разовые проходы процесса
уборщика. Брокер, relay и worker стенд не запускает: профили этого спека меряют
реплику, а не обработку, и реплика к брокеру не обращается. Число реплик SHALL
задаваться методикой, по умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
собранного из текущего checkout тем же `Dockerfile`. Исключения — профиль
поочерёдной замены и варианты «до» профилей загрузок и сверки. Они берут
образ commit, заданного методикой: образ собирается тем же `Dockerfile`
из файлов этого commit без изменения рабочего дерева. Профиль замены
заканчивается на образе текущего checkout. LB SHALL
запускаться из того же образа и с той же конфигурацией, что у рабочего
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
получает те же настройки образа плюс модуль записи планов, выключенный
вне снятия плана. S3 SHALL запускаться из того же образа и с теми же
аргументами сервера, что у рабочего стенда, а bucket и пользователей
создаёт тот же bootstrap. В профиле сверки к аргументам S3 добавляется
порт метрик шлюза: он слушает только loopback контейнера S3, и по нему
оркестратор считает запросы к S3. В сериях трека 1 предел соединений
PostgreSQL (`max_connections`) — параметр конфигурации серии, по
умолчанию 100, как у образа. Схема БД SHALL применяться миграциями до
наполнения.
Лимиты SHALL быть одинаковыми во всех прогонах профиля, а в серии трека
1 — во всех прогонах одной конфигурации:
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ, в серии трека 1 — по
конфигурации);
- у LB, PostgreSQL, Valkey, S3 и уборщика — свои лимиты CPU и памяти
без swap, заданные методикой; в серии трека 1 они одинаковы во всех
конфигурациях; у уборщика в управляемом опыте профиля сверки — другой
лимит CPU, тоже заданный методикой;
- у генератора нагрузки в профилях трека 1 — лимит CPU и памяти без
swap, заданный методикой; в остальных профилях генератор без лимита.
Буфер приёма сокетов реплик приложения SHALL быть ограничен так же, как
у рабочего стенда (`load-balancing`, «Загрузки через балансировщик»).
Значение SHALL записываться в паспорт.
Образ контейнера в паспорте SHALL называться тем значением, по которому образы
контейнеров можно сравнивать: меткой манифеста compose, а у контейнера без неё — идентификатором
образа.
Healthcheck образа приложения SHALL быть отключён: готовность реплик
проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки
приложения и хранилищ SHALL браться из методики стенда, а не из `.env`
и `config.toml` рабочего стенда. Пароли хранилищ, пароль брокера и секреты S3
SHALL генерироваться на прогон. Генератор нагрузки SHALL работать в той же
docker-сети и обращаться к приложению через LB по имени сервиса, минуя
проброс портов хоста. Стенд SHALL считаться готовым, когда LB видит
готовыми все реплики.
#### Scenario: Лимиты в паспорте
- **WHEN** прогон завершён
- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти
реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных
контейнеров, и они одинаковы для всех размеров
#### Scenario: Лимиты конфигурации серии
- **WHEN** серия трека 1 завершена
- **THEN** паспорт по каждой конфигурации содержит число реплик, лимиты
CPU и памяти каждого контейнера стенда и генератора и предел
соединений PostgreSQL, прочитанные у запущенных контейнеров, и они
одинаковы во всех повторах конфигурации
#### Scenario: Нехватка памяти
- **WHEN** процесс приложения превысил лимит памяти и был убит
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
обычный результат
#### Scenario: Настройки рабочего стенда не влияют
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
отсутствуют
- **THEN** стенд запускается с теми же настройками приложения и
хранилищ, а окружение приложения в паспорте то же
#### Scenario: Схема до наполнения
- **WHEN** начинается наполнение размера
- **THEN** миграции применены до последней ревизии, и приложение
отвечает готовностью
#### Scenario: Одна реплика за балансировщиком
- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`,
`restore_quick`) запущен с одной репликой
- **THEN** все запросы генератора проходят через LB, прогон завершается
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
разделы, что раньше
#### Scenario: Образ прежнего commit
- **WHEN** запускается профиль поочерёдной замены
- **THEN** реплики стартуют на образе commit из методики, схема — на
его последней ревизии, рабочее дерево не меняется, а commit и образы
до и после записаны в паспорт
#### Scenario: S3 в профиле загрузок
- **WHEN** запускается профиль загрузок
- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами
и лимитами, bootstrap завершился успешно, а образ и лимиты S3 и
ограничение буфера приёма реплики записаны в паспорт
#### Scenario: Брокер в профиле загрузок
- **WHEN** запускается профиль загрузок
- **THEN** брокер, relay и worker стенда не запущены, а загрузки отвечают 202: задания ждут в
PostgreSQL
#### Scenario: S3 и уборщик в профиле сверки
- **WHEN** запускается профиль сверки
- **THEN** S3 стенда запущен из образа рабочего стенда с его аргументами
и портом метрик только на loopback своего контейнера, bootstrap
завершился успешно, а аргументы S3, образы и лимиты S3 и уборщика
записаны в паспорт
### Requirement: Прежний commit профиля замены
Commit, с образа которого стартуют реплики профилей `rollout` и
`rollout_quick`, SHALL задаваться методикой профиля. Это commit
текущей лабы до изменения, которое показывает замена. Сейчас таким
изменением SHALL быть миграции надёжности обработки: commit — последний перед
change `pipeline-reliability`. Commit SHALL меняться при переходе в следующую
лабу (commit прошлой лабы в её истории нет) и когда замена показывает
новое изменение схемы. Правило и текущее значение SHALL быть в
`.claude/rules/bench.md`, commit — в паспорте метки.
Если commit методики нет в истории репозитория, команда SHALL
завершаться с ненулевым кодом до запуска стенда, назвать commit и
подмену `--from <commit>` для отладки.
#### Scenario: Замена на схему с вложениями
- **WHEN** выполнен `make bench_rollout_quick` на коде этого изменения
- **THEN** реплики стартуют на образе commit до change `pipeline-reliability`,
ревизия схемы до замены — без новых колонок и таблицы, после — с ними, а
команда завершается с кодом 0
#### Scenario: Commit вне истории
- **WHEN** commit методики не найден в репозитории
- **THEN** команда завершается с ненулевым кодом до запуска стенда, а
сообщение называет commit и `--from`
### Requirement: Профиль загрузок
Команда `make bench_uploads` (метка `UPLOADS_LABEL`, по умолчанию
`baseline`) SHALL на свежем стенде мерить память реплики при
одновременных загрузках вложений. Команда `make bench_uploads_quick` —
то же короче, метка `quick-uploads-…`, в git не идёт. Результаты SHALL
сохраняться в `evidence/uploads/<метка>/`. Занятая метка SHALL давать
отказ до запуска стенда.
Стенд — LB и одна реплика с лимитами рабочего стенда (1 CPU, 512 МБ без
swap), PostgreSQL, Valkey и S3 с лимитами рабочего стенда. Брокер, relay и
worker не запускаются: задания ждут в PostgreSQL.
Варианты кода:
- «до» — образ commit из методики; у лабы 5 это commit переноса лабы 4, в
нём места загрузки уже есть;
- «без лимита» — образ текущего checkout, мест загрузки больше, чем
клиентов, очереди нет;
- «с лимитом» — образ текущего checkout с параметрами загрузок по
умолчанию.
Успешная загрузка — 202, а у варианта с образом commit до перехода на 202 —
201. Код успеха варианта SHALL быть в паспорте. Столбец успешных загрузок считает
код успеха варианта.
Тела — настоящие PNG около 1 MiB и около 10 MiB, не больше лимита
контракта. Их строит оркестратор, детерминированно от зерна методики.
Прогон — вариант × размер × число одновременных клиентов (1, 10, 20 и
40) × повтор. Повторов в полном профиле три. Каждый прогон SHALL идти на
новом контейнере реплики и новом volume S3. Клиенты загружают без пауз
окно, заданное методикой. На 429 клиент ждёт `Retry-After`, на прочие
ошибки — секунду.
Для каждого прогона SHALL сохраняться:
- пик памяти реплики за окно — пик cgroup, сброшенный в начале окна, —
и память перед окном;
- наибольшие анонимная память и память буферов сокетов реплики;
- было ли завершение реплики из-за памяти;
- ответы по кодам, ошибка соединения — отдельным кодом;
- успешных загрузок в секунду, p50, p95 и p99 успешных;
- пик памяти S3 (в том числе анонимной) и LB.
Прогон с завершением реплики из-за памяти SHALL помечаться `oom` и
записываться как результат варианта, а не как сбой команды. Следующий
прогон идёт на новой реплике.
Граница чёрного ящика: генератор обращается к приложению только по HTTP
через LB, оркестратор управляет стендом через docker CLI. Сверх этого он
читает счётчики памяти cgroup контейнеров и пересоздаёт volume S3 с
bootstrap между прогонами. К bucket и объектам он не обращается.
В паспорте метки SHALL быть:
- лимиты и образы, в том числе commit варианта «до»;
- окружение приложения каждого варианта без секретов;
- размеры и SHA-256 тел;
- версия ядра ВМ;
- ограничение буфера приёма сокетов реплики;
- состояние хоста.
#### Scenario: Полный профиль
- **WHEN** выполнен `make bench_uploads`
- **THEN** в `evidence/uploads/<метка>/` есть паспорт, таблица прогонов
(три варианта × два размера × четыре уровня × три повтора), сводка по
ячейкам с медианой и разбросом повторов и сырые итоги генератора, код
выхода 0
#### Scenario: Быстрый профиль
- **WHEN** выполнен `make bench_uploads_quick`
- **THEN** за несколько минут проходят варианты «без лимита» и «с
лимитом» на 10 MiB при 1, 10 и 40 клиентах, по одному повтору, код
выхода 0, каталог метки в git не попадает, а успешные загрузки — 202
#### Scenario: Реплика убита из-за памяти
- **WHEN** в прогоне реплику завершило ядро из-за памяти
- **THEN** прогон помечен `oom`, в таблице есть ответы по кодам до и
после завершения, следующий прогон идёт на новой реплике, а команда
не прерывается
#### Scenario: Пик окна без памяти старта
- **WHEN** реплика при старте заняла больше памяти, чем в окне прогона
- **THEN** пик прогона отражает только окно, а не старт процесса
### Requirement: Профиль сверки
Команда `make bench_reconcile` (метка `RECONCILE_LABEL`, по умолчанию
`baseline`) SHALL на свежем стенде мерить стоимость прохода сверки
bucket и БД (capability `storage-consistency`). Команда `make
bench_reconcile_quick` — то же на малом наборе и одним повтором, метка
`quick-reconcile-…`, в git не идёт. Результаты SHALL сохраняться в
`evidence/reconcile/<метка>/`. Занятая метка SHALL давать отказ до
запуска стенда.
Стенд — LB, две реплики, PostgreSQL, Valkey и S3 с лимитами рабочего
стенда (требование «Фиксированный стенд»). Проход сверки — разовый
процесс уборщика из образа приложения с лимитами рабочего стенда
(0,25 CPU, 256 МБ без swap), в управляемом опыте — с 1 CPU. Grace
проходов — короткий, заданный методикой, но больше границы живой
загрузки (capability `service-configuration`, «Параметры уборщика»).
Данные — синтетические вложения одного чата:
- 10 000, 30 000 и 100 000 объектов по 4 KiB — один набор, который
растёт между этапами;
- 1 000 объектов по 1 MiB — на отдельном стенде, для цены чтения байтов.
Расхождения SHALL вноситься при наполнении, по 0,25 % от числа объектов
каждого класса: объект без метаданных, метаданные без объекта, другой
размер, зависшая загрузка. Класс объекта SHALL определяться его номером,
а содержимое — номером и зерном методики.
Граница чёрного ящика:
- пользователи и чат создаются через API;
- метаданные вложений оркестратор пишет в PostgreSQL стенда, объекты —
прямой записью в S3 стенда ключами пользователя API;
- проход сверки — процесс уборщика из образа приложения, его результат —
журнал этого процесса;
- фоновая нагрузка — генератор по HTTP через LB;
- сверх этого оркестратор читает счётчики cgroup контейнеров, метрики
шлюза S3 на loopback его контейнера и счётчики PostgreSQL.
Приложение оркестратор не импортирует.
Проходы:
- без фоновой нагрузки и без предела скорости:
- стратегия по умолчанию на всех размерах набора;
- стратегия HEAD на 10 000 и 30 000 объектов;
- глубокая сверка на 10 000 объектов по 4 KiB и на объектах по 1 MiB;
- глубокая сверка с уборщиком 1 CPU на объектах по 1 MiB;
- с фоновой нагрузкой, на 100 000 объектов, стратегия по умолчанию:
- лимит CPU рабочего стенда с пределом скорости по умолчанию и без
предела;
- 1 CPU без предела и с пределом по умолчанию.
Фоновая нагрузка идёт с постоянной интенсивностью, заданной методикой:
скачивания вложений набора, запись сообщений и чтение истории. До и
после каждого прохода — окна без прохода;
- отказ по пределу: `--apply` с пределом изменений 100, когда
кандидатов 1 000 и 10 000, — на образе commit из методики и на образе
текущего checkout.
Каждый проход повторяется три раза, повторы одной ячейки не идут подряд.
Исключение — группа проходов из одной ячейки (этап 100k без нагрузки —
только стратегия по умолчанию): её повторы идут подряд, потому что
остальные проходы того же набора идут под фоновой нагрузкой отдельным
блоком, и вставить их между повторами значило бы смешать проходы без
нагрузки с проходами под ней.
Варианты сравниваются внутри одной метки, на одних данных и в одной
сессии хоста. Шум — разброс повторов ячейки, а у проходов с фоновой
нагрузкой ещё отношение p95 окон до и после прохода (A/A).
Для каждого прохода SHALL сохраняться:
- итог прохода из журнала уборщика — длительность и длительность шагов,
просмотренные объекты и строки, найденные расхождения по классам,
затронутые объекты S3, запросы к S3 по операциям, прочитанные байты,
сеансы с PostgreSQL, неперепроверенные кандидаты, код выхода;
- запросы к S3 по метрикам шлюза и счётчики PostgreSQL за проход;
- CPU уборщика, S3 и PostgreSQL за проход;
- память уборщика в начале прохода и её пик;
- у проходов с фоновой нагрузкой — по каждому сценарию в окне прохода и
в окнах до и после: число ответов, ошибки, p50, p95 и p99.
Достоверность:
- найденные расхождения SHALL по каждому классу совпадать с внесёнными.
Иначе команда завершается ненулевым кодом: замер на неверных данных —
не результат;
- в проходах без фоновой нагрузки запросы к S3 по счётчикам сверки SHALL
совпадать с метриками шлюза, иначе проход помечается;
- ответ 5xx фоновой нагрузки в окнах прохода — пометка прохода; любой
неуспешный запрос фона или недосланная итерация по всему итогу
генератора — пометка всех проходов блока.
В паспорте метки SHALL быть:
- лимиты и образы, в том числе commit варианта «до»;
- аргументы S3;
- размеры набора, размеры объектов, доли расхождений и зерно;
- grace проходов и предел скорости по умолчанию;
- фоновая нагрузка;
- версия ядра ВМ;
- состояние хоста и посторонние контейнеры.
Сводка SHALL давать по каждой ячейке медиану и разброс повторов, вывод
по каждой гипотезе (требование «Стоимость сверки в отчёте») и графики:
длительность и запросы прохода от размера набора по стратегиям, p95
фоновой нагрузки по вариантам.
#### Scenario: Полный профиль сверки
- **WHEN** выполнен `make bench_reconcile`
- **THEN** в `evidence/reconcile/<метка>/` есть паспорт, таблица проходов
со всеми ячейками по три повтора, таблица окон фоновой нагрузки,
сводка с выводами по гипотезам и графики, код выхода 0
#### Scenario: Быстрый профиль сверки
- **WHEN** выполнен `make bench_reconcile_quick`
- **THEN** за несколько минут проходят все виды проходов на малом наборе
по одному повтору, код выхода 0, каталог метки в git не попадает
#### Scenario: Найдено не то, что внесено
- **WHEN** проход нашёл в каком-то классе не столько расхождений,
сколько внесено
- **THEN** команда завершается ненулевым кодом, называет класс, ячейку и
оба числа и удаляет стенд
#### Scenario: Счётчики сверки и метрики S3
- **WHEN** завершён проход без фоновой нагрузки
- **THEN** в строке прохода запросы к S3 по счётчикам сверки равны
запросам по метрикам шлюза, а при различии строка помечена
@@ -0,0 +1,85 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Устойчивая очередь заданий
Задания SHALL идти через устойчивую (durable) очередь постоянными (persistent)
сообщениями. Имя очереди SHALL содержать имя базы PostgreSQL процесса: так
прогон на временной базе не смешивается с рабочим, как объекты S3 и ключи кэша.
Очередь SHALL существовать к первой публикации, даже если worker ни разу не
запускался: её объявляет и relay, и потребитель, повторное объявление
безопасно.
#### Scenario: Очередь и сообщения устойчивы
- **WHEN** участник загрузил файл при остановленном worker, и relay опубликовал его
задание
- **THEN** очередь в брокере `durable`, в ней одно сообщение с постоянной
доставкой, а прочитанное без подтверждения сообщение возвращается в очередь
#### Scenario: Очереди разных баз разделены
- **WHEN** на рабочем стенде выполняется прогон на временной базе
- **THEN** его задания идут через очередь с именем временной базы, worker
рабочего стенда их не получает, а после прогона этой очереди нет
### Requirement: Подтверждение публикации
Relay SHALL считать сообщение принятым только после подтверждения брокера
(publisher confirm). Сообщение, которое брокеру некуда направить, отказ брокера,
обрыв соединения и истечение `[broker] publish_timeout_seconds` SHALL быть
ошибкой публикации: время подтверждения у задания не записывается, намерение остаётся в
PostgreSQL, и следующий проход публикует его снова. Исход публикации по сроку неизвестен,
поэтому сообщение может дойти дважды (`job-outbox`, «Relay публикует намерения»).
Отдельный вызов публикации MUST NOT зависать дольше этого срока.
Брокер не критичен для обязательного пути и для приёма файлов: без него SHALL работать
загрузка (202), отправка текста, история, метаданные, скачивание готового вложения и
`/health/ready` (`health`, «Readiness»).
После возврата брокера публикация SHALL проходить без перезапуска процесса.
#### Scenario: Брокер остановлен при загрузке
- **WHEN** брокер остановлен, и участник загружает файл, отправляет текст,
читает метаданные готового вложения и скачивает его
- **THEN** загрузка — 202 быстрее секунды, отправка — 201, метаданные и скачивание —
200, а новое вложение видно по API со `status` `queued`
#### Scenario: Брокер завис
- **WHEN** контейнер брокера заморожен (`docker pause`), и участник загружает файл
- **THEN** ответ 202 быстрее секунды, а после разморозки вложение становится `ready` с одним
набором вариантов, даже если сообщение, дошедшее после разморозки, опубликовано ещё раз
#### Scenario: Брокер вернулся
- **WHEN** брокер снова запущен, а relay и worker не перезапускались
- **THEN** вложение, принятое без брокера, и следующая загрузка становятся `ready`
#### Scenario: Очередь удалена
- **WHEN** worker остановлен, очередь заданий удалена мимо приложения, участник
дважды загружает файл, а затем worker запущен
- **THEN** обе загрузки — 202, очередь объявлена заново, и оба вложения становятся `ready`
### Requirement: Клиент брокера в приложении
Relay и worker SHALL обращаться к брокеру с настройками секции `[broker]`. Реплики API MUST
NOT к нему обращаться. Соединение SHALL открываться при первом вызове, а не при старте: без
брокера процесс стартует. При остановке сервиса клиент SHALL закрываться. Потерянное
соединение SHALL восстанавливаться следующим вызовом, с паузой между попытками, без
перезапуска процесса. Пароль брокера MUST NOT попадать в журнал.
#### Scenario: Старт без брокера
- **WHEN** реплика API, relay и worker запускаются при остановленном брокере
- **THEN** реплика становится готовой и принимает файл (202), relay и worker пишут в журнал об
отказе брокера и не завершаются, а после запуска брокера вложение становится `ready`
#### Scenario: Рестарт брокера при работающем worker
- **WHEN** брокер перезапущен, а relay и worker в это время работают
- **THEN** worker без перезапуска снова получает задания: новая загрузка становится
`ready`, а счётчики перезапусков контейнеров relay и worker не изменились
@@ -0,0 +1,92 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Ограниченные учётные данные уборщика
У уборщика (capability `storage-consistency`) SHALL быть свои учётные
данные S3, отдельные от учётных данных API и административных.
Пользователю уборщика SHALL быть разрешены только:
- чтение и удаление объектов своего bucket;
- список объектов своего bucket с префиксами вложений и staging своей базы,
`<имя базы>/attachments/` и `<имя базы>/staging/`, — для сверки bucket и БД.
Префиксы задаёт bootstrap по имени базы стенда.
Пользователю уборщика MUST NOT быть разрешены:
- запись объектов;
- список объектов без этих префиксов или с другим префиксом, в том числе
с префиксом другой базы;
- операции с bucket: создание, удаление, политика, ACL;
- публичный ACL объекта;
- управление учётными записями;
- любой доступ к другим bucket.
Ключи уборщика MUST NOT передаваться репликам API. Уборщик MUST NOT
получать ключи API, административные ключи S3 и ключ подписи.
#### Scenario: Работа уборщика с объектами
- **WHEN** ключом API записан объект, а ключом уборщика он прочитан,
удалён и удалён ещё раз, и запрошен список объектов с префиксом
вложений базы и с префиксом staging базы
- **THEN** чтение отдаёт те же байты, оба удаления успешны, объекта
после них нет, а оба списка отвечают 200
#### Scenario: Запрещённые операции уборщика
- **WHEN** ключом уборщика запрашиваются:
- запись объекта;
- список объектов всего bucket, с общим префиксом базы и с префиксом, не
принадлежащим его базе;
- создание и удаление bucket, политика и ACL bucket;
- публичный ACL объекта;
- объект другого bucket и его список
- **THEN** каждый запрос получает 403, а bucket и его доступ не
меняются
### Requirement: Проверка приватности вне API
Приватность bucket и права ключей API, уборщика и worker SHALL проверяться
без участия приложения двумя способами.
1. Каждый запуск bootstrap:
- ключ API записывает и читает проверочный объект и получает отказ на
список и на создание bucket;
- ключ worker записывает и читает проверочный объект и получает отказ на
удаление, на список и на создание bucket;
- ключ уборщика читает и удаляет проверочный объект. Он получает отказ на
запись и на список всего bucket, а списки с префиксами вложений и staging
своей базы у него проходят;
- аноним получает отказ на чтение существующего объекта и на список.
При нарушении bootstrap завершается с ненулевым кодом, и реплики API
не стартуют.
2. Отдельная команда `make s3_check` на запущенном стенде. Она
повторяет проверки bootstrap и добавляет:
- анонимные запросы с хоста и из сети стенда;
- запросы ключей API, уборщика и worker к чужому bucket;
- административные запросы ключей API, уборщика и worker;
- запись ключом уборщика;
- его список всего bucket и с чужим префиксом — отказ, с префиксами
вложений и staging своей базы — 200.
Команда SHALL печатать по каждой проверке ожидаемый и полученный код
ответа без секретов. При любом нарушении код выхода SHALL быть
ненулевым. Свои проверочные объекты и bucket команда SHALL удалять.
#### Scenario: Проверка командой
- **WHEN** на запущенном стенде выполняется `make s3_check`
- **THEN** каждая проверка напечатана с полученным кодом ответа, в том
числе проверки списка ключом уборщика по своим и чужому префиксу и
отказ ключу worker на удаление и список, код выхода 0, а проверочных
объектов и bucket после команды нет
#### Scenario: Bucket стал публичным
- **WHEN** на bucket открыт анонимный доступ на чтение, например
административной командой мимо bootstrap
- **THEN** `make s3_check` завершается с ненулевым кодом и называет
нарушенную проверку, а следующий запуск bootstrap снова закрывает
доступ
@@ -0,0 +1,179 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Параметры уборщика
Параметры уборщика незавершённых загрузок (capability
`storage-consistency`) SHALL задаваться в секции `[cleaner]`:
- `interval_seconds` — пауза между проходами, по умолчанию 60;
- `pending_grace_seconds` — grace period, по умолчанию 900;
- `batch_size` — сколько незавершённых загрузок или вложений с объектом staging
уборщик выбирает одним запросом к PostgreSQL, по умолчанию 100;
- `staging_retention_seconds` — срок хранения объекта staging вложения `failed` и объекта
staging без метаданных, по умолчанию 86400 (сутки, как у имени skeleton
`STAGING_RETENTION_SECONDS`).
Значения SHALL быть положительными, `batch_size` — целым. Иначе уборщик
MUST NOT стартовать (требование «Некорректное значение останавливает
запуск»).
Grace SHALL быть больше границы живой загрузки — суммы сроков её шагов
после записи метаданных: `2 × [database] request_timeout_seconds + [s3]
timeout_seconds`, по настройкам процесса уборщика (17 с по умолчанию).
Иначе уборщик MUST NOT стартовать: код выхода ненулевой, а ошибка
называет grace, оба срока и границу.
Сравнение grace с границей SHALL выполнять только уборщик при своём
старте: реплики API секцию `[cleaner]` не используют и от этой
проверки не зависят. Разовая подмена SHALL работать через окружение
`CLEANER__*` без правки файлов. Значения по умолчанию и обоснование
grace и срока хранения SHALL быть описаны в `REPORT.md`, соответствие имени skeleton
`STAGING_RETENTION_SECONDS` — ещё и в шапке `.env.example`.
#### Scenario: Параметры по умолчанию
- **WHEN** уборщик запущен без секции `[cleaner]` и без
переменных `CLEANER__*`
- **THEN** запись о его старте называет интервал 60 с, grace 900 с,
выборку 100 и срок хранения staging 86400 с
#### Scenario: Grace не больше границы
- **WHEN** уборщик запускается с `CLEANER__PENDING_GRACE_SECONDS=17`
при сроках по умолчанию
- **THEN** уборщик не стартует, код выхода ненулевой, а ошибка называет
grace, оба срока и границу 17 с
#### Scenario: Интервал не число
- **WHEN** уборщик запускается с `CLEANER__INTERVAL_SECONDS=0`,
`CLEANER__INTERVAL_SECONDS=abc` или `CLEANER__STAGING_RETENTION_SECONDS=0`
- **THEN** уборщик не стартует, в журнале — ошибка проверки настроек
### Requirement: Подключение к брокеру
Параметры брокера SHALL задаваться в секции `[broker]`:
- адрес и порт;
- пользователь и пароль;
- срок установки соединения;
- срок публикации — от начала публикации пакета заданий до подтверждений брокера,
включая установку соединения; по умолчанию 2 с.
Секцию читают relay и worker, реплики API её не используют. Пароль SHALL иметь один
источник — переменную `.env`, которую читает и контейнер брокера. Новый `.env` из `make
env_setup` SHALL получать случайный пароль. Пароль MUST NOT попадать в журнал. Сроки SHALL
быть положительными числами, иначе процесс MUST NOT стартовать (требование «Некорректное
значение останавливает запуск»). Разовая подмена SHALL работать через окружение `BROKER__*`
без правки файлов.
Соответствие имени skeleton `BROKER_URL_FILE` реальной конфигурации SHALL быть
описано в шапке `.env.example` и в `REPORT.md`.
#### Scenario: Пароль брокера в одном месте
- **WHEN** в `.env` задан пароль брокера, и стенд поднят на новом volume
- **THEN** брокер, relay и worker в консоли и в docker используют его без правки
других файлов
#### Scenario: Пароль брокера не в журнале
- **WHEN** relay и worker стартуют и обращаются к брокеру, в том числе при его
недоступности
- **THEN** в журнале нет значения пароля
#### Scenario: Запись о старте называет брокер
- **WHEN** relay и worker стартуют
- **THEN** их записи о старте называют адрес брокера и имя очереди, а срок публикации
по умолчанию в записи relay — 2 с
#### Scenario: Неверный срок публикации
- **WHEN** relay запускается с `BROKER__PUBLISH_TIMEOUT_SECONDS=0` или `abc`
- **THEN** relay не стартует, в журнале — ошибка проверки настроек с именем поля
### Requirement: Параметры worker
Параметры worker (capability `attachment-processing`) SHALL задаваться в секции
`[worker]`:
- `concurrency` — сколько заданий worker обрабатывает одновременно, по умолчанию 2;
- `prefetch` — сколько неподтверждённых сообщений выдаёт ему брокер, по умолчанию 2;
- `max_attempts` — сколько попыток у задания с последнего replay, по умолчанию 5;
- `job_timeout_seconds` — срок одной попытки, по умолчанию 60;
- `lease_margin_seconds` — запас аренды сверх срока попытки, по умолчанию 10;
- `retry_base_delay_seconds` — основа паузы перед следующей попыткой, по умолчанию 5;
- `retry_max_delay_seconds` — верхняя граница паузы, по умолчанию 300;
- `render_timeout_seconds` — срок процесса обработки, по умолчанию 40, меньше срока попытки;
- `render_cpu_limit_seconds` — лимит CPU процесса обработки в секундах, целое, по умолчанию 15;
- `render_memory_limit_mib` — лимит адресного пространства процесса обработки в МиБ, целое,
по умолчанию 450;
- `graceful_shutdown_seconds` — сколько worker ждёт начатые задания после SIGTERM,
по умолчанию 8, не больше 8;
- `reconnect_seconds` — пауза между попытками соединиться с брокером и перед возвратом сообщения
при отказе PostgreSQL, по умолчанию 2.
`concurrency`, `prefetch`, `max_attempts`, лимиты CPU и памяти SHALL быть целыми не меньше 1,
сроки — положительными конечными числами, `retry_max_delay_seconds` — не меньше
`retry_base_delay_seconds`. Иначе worker MUST NOT стартовать: код выхода ненулевой, а ошибка называет
поле. Разовая подмена SHALL работать через окружение `WORKER__*` без правки файлов. Реплики API
секцию `[worker]` не используют; relay её тоже не читает. Запись о старте worker SHALL называть
все значения.
Соответствие имён skeleton `WORKER_CONCURRENCY`, `JOB_MAX_ATTEMPTS` и
`JOB_TIMEOUT_SECONDS` этим полям SHALL быть описано в шапке `.env.example` и в `REPORT.md`.
#### Scenario: Параметры worker по умолчанию
- **WHEN** worker запущен без секции `[worker]` и без переменных `WORKER__*`
- **THEN** запись о его старте называет конкуренцию 2, prefetch 2, 5 попыток, срок 60 с, запас
аренды 10 с, основу паузы 5 с и её предел 300 с, лимиты процесса обработки 40 с, 15 с CPU и
450 МиБ, срок остановки 8 с и паузу соединения 2 с
#### Scenario: Подмена параметров worker окружением
- **WHEN** worker запущен с `WORKER__CONCURRENCY=1` и `WORKER__MAX_ATTEMPTS=2`, а
файлы не менялись
- **THEN** запись о старте называет эти значения, и одновременно обрабатывается одно
задание
#### Scenario: Неверный параметр worker
- **WHEN** worker запускается с `WORKER__CONCURRENCY=0`, `WORKER__PREFETCH=0`,
`WORKER__MAX_ATTEMPTS=abc`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS=9`,
`WORKER__RENDER_MEMORY_LIMIT_MIB=0` или `WORKER__RENDER_TIMEOUT_SECONDS=120` при сроке
попытки 60 с
- **THEN** worker не стартует, код выхода ненулевой, в журнале — запись с именем поля
без значений настроек
## ADDED Requirements
### Requirement: Параметры relay
Параметры relay (capability `job-outbox`) SHALL задаваться в секции `[relay]`:
- `poll_interval_seconds` — пауза между проходами, когда публиковать нечего, по умолчанию 0,25;
- `batch_size` — сколько заданий relay берёт за один проход, по умолчанию 100;
- `max_published_backlog` — предел опубликованных и не взятых заданий, по умолчанию 1000;
0 — без предела;
- `republish_after_seconds` — через сколько секунд отмеченное задание может считаться потерянным,
по умолчанию 300;
- `failure_pause_seconds` — пауза после отказа брокера или PostgreSQL, по умолчанию 2.
`batch_size` SHALL быть целым не меньше 1, `max_published_backlog` — целым не меньше 0, сроки —
положительными конечными числами. Иначе relay MUST NOT стартовать: код выхода ненулевой, а ошибка
называет поле. Разовая подмена SHALL работать через окружение `RELAY__*` без правки файлов. Реплики API и
worker секцию не используют. Запись о старте relay SHALL называть все значения. Значения по умолчанию и их
обоснование SHALL быть в `REPORT.md`.
#### Scenario: Параметры relay по умолчанию
- **WHEN** relay запущен без секции `[relay]` и без переменных `RELAY__*`
- **THEN** запись о его старте называет паузу 0,25 с, пакет 100, предел 1000, порог потерянного
сообщения 300 с и паузу отказа 2 с
#### Scenario: Неверный параметр relay
- **WHEN** relay запускается с `RELAY__BATCH_SIZE=0`, `RELAY__MAX_PUBLISHED_BACKLOG=-1` или
`RELAY__POLL_INTERVAL_SECONDS=abc`
- **THEN** relay не стартует, код выхода ненулевой, в журнале — запись с именем поля без значений
настроек
@@ -0,0 +1,176 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Журнал уборщика
Уборщик незавершённых загрузок (capability `storage-consistency`) SHALL
писать журнал в формате этой capability: JSON-записи в stdout, в каждой
`instance_id` процесса уборщика. Записи:
- старт — интервал, grace, размер выборки, срок хранения staging, адрес S3, bucket и
имя базы;
- каждая убранная загрузка — `id` вложения, ключ объекта и возраст
загрузки;
- проход, который убрал хотя бы одну загрузку или прервался отказом
хранилища, — сколько убрано, сколько пропущено (их держит другой
процесс), причина прерывания и длительность;
- проход очистки staging, который что-то удалил или прервался отказом хранилища, —
сколько объектов staging убрано у готовых и у неудачных вложений, сколько пропущено,
причина прерывания и длительность; ключ staging другого вида — уровень `warning` с
ключом;
- отказ S3 или PostgreSQL — уровень `warning`, непредвиденная ошибка —
`error` с traceback;
- остановка процесса.
Проход, которому нечего убирать, SHALL писаться не выше уровня `debug`.
Записи уборщика MUST NOT содержать ключи доступа и секреты S3, ключ
подписи, подписи запросов, `filename` вложений и байты объектов.
#### Scenario: Проход уборщика
- **WHEN** уборщик убирает незавершённую загрузку
- **THEN** в журнале есть запись с `id` вложения, ключом объекта и
возрастом и запись прохода с числом убранных, а секретов S3 и
`filename` в журнале нет
#### Scenario: Отказ S3 во время прохода
- **WHEN** S3 остановлен, а уборщику есть что убирать
- **THEN** в журнале запись уровня `warning` о прерванном проходе с
причиной, без секретов, а метаданные загрузки на месте
#### Scenario: Очистка staging в журнале
- **WHEN** уборщик удаляет объект staging готового вложения
- **THEN** в журнале запись прохода очистки с числом убранных объектов, а секретов S3 и
`filename` в журнале нет
### Requirement: Журнал сверки
Сверка bucket и БД (capability `storage-consistency`) SHALL писать в
журнал процесса уборщика JSON-записи в формате этой capability, в каждой
— `instance_id` процесса. Записи:
- запись о старте уборщика дополнительно называет интервал сверки,
размер страницы, предел изменений и предел скорости, а у разового
прохода — ещё стратегию обхода и глубину;
- каждое найденное расхождение — класс, ключ объекта, `id` вложения,
если он известен, возраст, размеры объекта и метаданных, если они
разные. Уровень `warning`, если расхождение осталось, и `info`, если
проход с `--apply` его исправил, с названием действия;
- итог прохода — режим, стратегия, глубина, предел скорости, сколько
объектов и строк просмотрено, сколько объектов staging просмотрено, сколько
найдено и исправлено по классам, сколько свежих и уже помеченных, сколько
кандидатов не перепроверено, длительность и причина прерывания. Ещё итог называет
стоимость прохода: сколько объектов S3 он затронул, запросы к S3 по операциям
(список, запрос метаданных, чтение, удаление), сколько байтов объектов
прочитано, сколько было сеансов с PostgreSQL и длительность каждого
шага прохода. Уровень `info`, если расхождений не осталось, иначе
`warning`;
- превышение предела изменений — `error` с пределом, числом
подтверждённых изменений и числом кандидатов, которых проход не
перепроверял;
- отказ S3 или PostgreSQL — `warning`, непредвиденная ошибка — `error` с
traceback.
Если расхождений за проход больше тысячи, отдельными записями SHALL
писаться только первые, а итог SHALL называть, сколько осталось без
записи. Скачивание потерянного оригинала реплика API SHALL писать
записью уровня `info` с `id` вложения и ключом объекта, а не `error`.
Записи сверки MUST NOT содержать ключи доступа и секреты S3, ключ
подписи, подписи запросов, `filename` вложений, байты объектов и их
SHA-256.
#### Scenario: Журнал разового прохода
- **WHEN** сверка находит объект без метаданных и метаданные без
объекта, а затем исправляет их с `--apply`
- **THEN** результат такой:
- в журнале dry-run — две записи `warning` с классом, ключом и
возрастом и итог `warning`;
- в журнале прохода с `--apply` — две записи `info` с действием и
итог `info`;
- секретов S3 и `filename` в журнале нет
#### Scenario: Предел изменений в журнале
- **WHEN** сверка с `--apply` отказывается исправлять из-за предела
- **THEN** в журнале запись `error` с пределом, числом подтверждённых
изменений и числом неперепроверенных кандидатов, а итог прохода —
`warning`
#### Scenario: Стоимость прохода в итоге
- **WHEN** выполняется разовая сверка с `--strategy head` и `--deep`
- **THEN** итог называет эту стратегию, глубину и предел скорости,
затронутые объекты S3, запросы к S3 по операциям, прочитанные байты,
сеансы с PostgreSQL и длительность каждого шага, а секретов S3,
`filename` и SHA-256 объектов в журнале нет
### Requirement: Журнал worker
Worker (capability `attachment-processing`) SHALL писать журнал в формате этой
capability: JSON-записи в stdout, в каждой `instance_id` процесса worker и `request_id`
— `id` обрабатываемого задания. Записи:
- старт — конкуренция, prefetch, число попыток, сроки и лимиты, адрес брокера и имя
очереди, адрес S3, bucket и имя базы;
- взятое задание — `id` задания и вложения, номер попытки, номер попытки из сообщения,
время ожидания от подтверждения брокером до взятия;
- готовое вложение — размеры каждого варианта, размер объекта, длительность попытки и
процесса обработки, пик памяти процесса обработки;
- новая попытка — код причины, номер попытки, пауза, время следующей попытки; уровень
`warning`;
- `failed` — код и причина; уровень `warning`;
- пропущенное сообщение — причина: задание завершено, неизвестно, идёт живая попытка, срок ещё
не наступил, задание ведёт другая попытка;
- сообщение не по схеме — уровень `error`, без содержимого сообщения;
- отказ брокера, S3 или PostgreSQL — уровень `warning`, непредвиденная ошибка — `error` с
traceback;
- остановка процесса с кодом выхода.
Записи worker MUST NOT содержать `filename` вложений, байты объектов, тела сообщений,
ключи доступа и секреты S3, пароль брокера и пароль PostgreSQL.
#### Scenario: Обработка в журнале
- **WHEN** worker доводит вложение с уникальным `filename` F до `ready`
- **THEN** все записи этого задания связаны одним `request_id` — `id` задания, в них
есть номер попытки, размеры трёх вариантов, длительность и пик памяти процесса обработки, а F и
секретов в журнале нет
#### Scenario: Постоянная ошибка в журнале
- **WHEN** вложение стало `failed` с `invalid_image`
- **THEN** в журнале есть запись `warning` с `id` задания и вложения и кодом, без
stack trace и байтов
## ADDED Requirements
### Requirement: Журнал relay и replay
Relay и команда replay (capability `job-outbox`, `attachment-processing`) SHALL писать журнал в формате этой
capability: JSON-записи в stdout, в каждой `instance_id` процесса. Записи relay:
- старт — все параметры секции, адрес брокера, имя очереди и имя базы; остановка с кодом выхода;
- проход, который что-то опубликовал или вернул, — сколько опубликовано, сколько не подтверждено,
сколько возвращено по истёкшей аренде и сколько опубликовано снова как потерянные, сколько опубликованных и не
взятых заданий и длительность; проход без работы — не выше уровня `debug`;
- достижение предела опубликованных — один раз на смену состояния, уровень `info`;
- возврат по истёкшей аренде — `id` задания и вложения и номер попытки, уровень `warning`;
- отказ брокера и PostgreSQL — уровень `warning`, возврат брокера — `info`, непредвиденная ошибка — `error` с traceback.
Записи replay: каждое задание реестра в показе — `id` задания и вложения, код, причина, число попыток и время; выполненный
replay — те же поля и оператор, уровень `info`; отказ — `id` и причина отказа, уровень `warning`; итог прохода — сколько показано,
выполнено и отказано.
Записи MUST NOT содержать `filename` вложений, тела сообщений и секреты.
#### Scenario: Проход relay в журнале
- **WHEN** relay публикует задание
- **THEN** в журнале есть запись прохода с числом опубликованных и опубликованных и не взятых заданий, а `filename`, тел сообщений
и пароля брокера в журнале нет
#### Scenario: Replay в журнале
- **WHEN** команда replay выполняет replay задания и отказывает другому
- **THEN** в журнале запись `info` с `id` задания, оператором, прежними кодом и причиной, запись `warning` с причиной отказа и итог
прохода, а `filename` и секретов нет
@@ -0,0 +1,557 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Уборщик незавершённых загрузок
Незавершённую загрузку SHALL убирать уборщик — отдельный процесс стенда
(capability `container-run`), а не реплики API. Незавершённая загрузка —
вложение, которое осталось в статусе «загружается» (capability
`attachments`, «Порядок записи»): на него ещё не ответили 202.
Уборщик SHALL проходить по незавершённым загрузкам не реже чем раз в
`[cleaner] interval_seconds`. Каждую загрузку, метаданные которой
записаны раньше чем `[cleaner] pending_grace_seconds` назад (grace
period), он SHALL убирать по шагам:
1. пометить её метаданные как убираемые и зафиксировать пометку
(требование «Безопасность уборки»);
2. удалить объект: staging по ключу из её метаданных, а у загрузки прежней
версии без ключа staging — объект конечного ключа; отсутствие объекта — не
ошибка;
3. только после подтверждённого удаления объекта — удалить метаданные.
Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на
любом шаге, доводит следующий. После уборки у вложения не остаётся ни
метаданных, ни объекта. Объект вложения без метаданных уборка MUST NOT
оставлять: метаданные удаляются последними.
Ограничение называется в `REPORT.md`. Объект может остаться без
метаданных, если процесс API заморожен дольше grace посреди записи
объекта. После разморозки он дописывает объект уже убранной загрузки, а
удалить его не может: запись объекта завершилась для API ошибкой по
сроку, или не удалось удаление при компенсации. Такой объект находит и удаляет
сверка bucket и БД (требование «Сверка bucket и БД»): под конечным префиксом —
когда он старше grace, в staging — когда он старше срока хранения staging, на
стенде — не позже следующей плановой сверки (требование «Плановая сверка»).
#### Scenario: Зависшая загрузка убрана
- **WHEN** загрузка оборвалась после записи метаданных: S3 был
остановлен или заморожен на время записи объекта, либо PostgreSQL
отказал при фиксации `queued`. С записи метаданных прошло больше grace,
S3 и PostgreSQL доступны
- **THEN** ни метаданных, ни объекта этого вложения нет, а в bucket нет
объектов вложений без метаданных
#### Scenario: Объект без фиксации убран
- **WHEN** объект вложения записан в staging, а процесс API убит до
фиксации `queued`
- **THEN** до истечения grace есть и метаданные в статусе
«загружается», и объект, а после него нет ни того, ни другого, и в
bucket нет объектов вложений без метаданных
#### Scenario: Загрузка без подтверждения брокера убрана
- **WHEN** реплика прежней версии на время замены не дождалась подтверждения брокера,
отменила задание, вернула вложение в статус «загружается» и ответила 503, и с записи
метаданных прошло больше grace
- **THEN** ни метаданных, ни объекта staging этого вложения нет, а задания у него нет
### Requirement: Безопасность уборки
Уборщик MUST NOT убирать принятые вложения (`queued`, `processing`, `ready`,
`failed`) ни в каком возрасте: на них уже ответили 202, и это либо текущая
работа, либо её итог. Их объекты staging и `failed` с частично записанными объектами
подчиняются требованию «Очистка staging». Незавершённую загрузку моложе grace он тоже
MUST NOT трогать.
Grace SHALL быть больше наибольшего времени, за которое живая загрузка
проходит путь от записи метаданных до фиксации `queued`. Это два шага с
PostgreSQL и запись объекта, у каждого свой срок (capability
`service-configuration`, «Параметры уборщика»). Возраст загрузки отсчитывается от
записи её метаданных по часам приложения. Ожидание места загрузки, чтение тела и
проверка изображения (capability `attachments`, «Одновременные загрузки реплики»,
«Срок передачи тела») SHALL идти до записи метаданных и в эту границу не входят:
очередь загрузок и медленный клиент её не удлиняют.
Загрузка, которая длится дольше grace (процесс API заморожен), и
уборщик SHALL исключать друг друга на одном вложении. Исходов два:
- вложение стало `queued` вместе с заданием, и уборщик его не трогает;
- уборщик начал его уборку, а загрузка отвечает 503 `unavailable` и
удаляет записанный ею объект.
До удаления объекта уборщик SHALL помечать метаданные вложения как
убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT
становиться `queued`. Поэтому сбой уборки после удаления объекта не даёт
принятого вложения без объекта: загрузка отвечает 503, а уборку доводит
следующий проход. Сбой — например, не удалось удалить метаданные, или
S3 выполнил удаление уже после срока вызова. Принятое вложение без
объекта staging MUST NOT появляться ни при каком порядке этих действий.
Ограничение называется в `REPORT.md`. Пока идёт поочерёдная замена
реплик API, реплики прежней версии пометку не проверяют. Для их
загрузок, переживших grace, это свойство не гарантировано.
#### Scenario: Загрузка дольше grace
- **WHEN** загрузка записала объект, а к переводу в `queued` её
метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт
перевода
- **THEN** ответ 503 `unavailable`, а не 202 и не 500, нет ни
метаданных, ни объекта этого вложения, а в bucket нет объектов
вложений без метаданных
#### Scenario: Сбой уборки после удаления объекта
- **WHEN** загрузка ждёт перевода в `queued`, её метаданным больше grace,
а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL
отказал
- **THEN** ответ загрузки 503 `unavailable`, а не 202, метаданные в
статусе «загружается», и принятого вложения без объекта нет
- **AND** когда удаление метаданных снова проходит, уборщик доводит
уборку, и в bucket нет объектов вложений без метаданных
#### Scenario: Свежая загрузка не тронута
- **WHEN** незавершённой загрузке меньше grace, а уборщик за это время
сделал несколько проходов
- **THEN** её метаданные в статусе «загружается» на месте, и убираются
они только после истечения grace
#### Scenario: Готовые вложения не тронуты
- **WHEN** готовому вложению больше grace, и уборщик всё это время
работал, в том числе убирал незавершённые загрузки и объекты staging
- **THEN** метаданные вложения — 200 в статусе `ready`, а байты оригинала и
вариантов скачиваются с теми же SHA-256
#### Scenario: Текущая работа не тронута
- **WHEN** worker остановлен, у вложений в `queued`, `processing` и `failed`
возраст больше grace, но у `failed` меньше срока хранения staging, и уборщик всё
это время работает
- **THEN** их метаданные и объекты staging на месте, а после запуска worker
вложение в `queued` становится `ready`
#### Scenario: Ожидание места не входит в возраст загрузки
- **WHEN** загрузка ждала места, пока его держала другая загрузка того
же процесса, и обе завершились 202
- **THEN** время записи метаданных ожидавшей (`created_at`) позже
перевода в `queued` той, что держала место (`updated_at` снимка из её
ответа)
### Requirement: Сверка bucket и БД
Сверка SHALL сравнивать объекты вложений в bucket — ключи с префиксами
`<имя базы>/attachments/` и `<имя базы>/staging/` — с метаданными вложений той же
базы в PostgreSQL и находить расхождения восьми классов:
- **объект без метаданных** — объект с ключом вида
`<база>/attachments/<id>/original` или ключом варианта
`<база>/attachments/<id>/v<версия>-<вариант>`, на который не ссылается ни
одна строка и для `id` которого строки нет;
- **объект staging без метаданных** — объект с ключом вида
`<база>/staging/<id>/original`, на который не ссылается строка этого `id`:
строки нет или её объект staging уже убран;
- **метаданные без объекта** — вложение `ready`, объекта по ключу из его
метаданных в bucket нет;
- **другой размер** — вложение `ready`, размер объекта не равен
`size_bytes`;
- **другой SHA-256** — вложение `ready`, размер объекта равен
`size_bytes`, а SHA-256 его содержимого не равен SHA-256 из
метаданных. Этот класс ищет только глубокая сверка;
- **зависшая загрузка** — вложение в статусе «загружается» старше grace,
то же, что убирает уборщик (требование «Уборщик незавершённых
загрузок»);
- **оригинал вернулся** — оригинал вложения помечен потерянным
(требование «Потерянный оригинал»), а объект снова есть с тем же
размером и тем же SHA-256;
- **чужой объект** — то, что сверка не меняет и оставляет оператору:
- объект под префиксом вложений или staging, ключа такого вида API не пишет;
- объект с ключом вида `<id>/original`, у строки которого другой ключ
или на который ссылается строка другого `id`;
- ключ вне префикса вложений своей базы в метаданных вложения: объект
по такому ключу сверка не читает.
Объект варианта, у `id` которого строка есть, расхождением не считается, в
каком бы состоянии ни было вложение. Объект staging, на который ссылается строка, —
текущая работа или дело очистки staging (требование «Очистка staging»): сверка его
MUST NOT читать и менять. Наличие и размер объектов вариантов сверка не проверяет; это
ограничение SHALL быть в `REPORT.md`.
Сверку SHALL выполнять процесс уборщика, а не реплики API: разовым
проходом (`make reconcile` или команда сверки в контейнере уборщика) и
плановым (требование «Плановая сверка»). Разовый проход по умолчанию
SHALL ничего не менять (dry-run). С `--apply` он SHALL исправлять:
- объект без метаданных и объект staging без метаданных — удалить объект;
- метаданные без объекта, другой размер и другой SHA-256 — пометить
оригинал вложения потерянным;
- зависшую загрузку — убрать тем же порядком, что уборщик;
- вернувшийся оригинал — снять пометку.
Чужой объект сверка MUST NOT удалять, а вложение, метаданные которого
ведут к нему, — помечать или убирать: чужой объект попадает только в
отчёт.
Разовый проход SHALL принимать стратегию обхода:
- по умолчанию — страницы списка объектов и одно обращение к PostgreSQL
на страницу. Ключи списка сверка запоминает, а строки `ready`
сравнивает с ними;
- `--strategy head` — для каждого объекта списка отдельное обращение к
PostgreSQL, для каждой строки `ready` — запрос метаданных её объекта в
S3. Ключей списка сверка не запоминает.
Обе стратегии SHALL находить на одних данных одни и те же расхождения
тех же классов и подчиняться одним правилам безопасности (требование
«Безопасность сверки»). Каждое вложение `ready` сверка SHALL сравнивать
с объектом по ключу из его метаданных, чей бы `id` ни стоял в этом
ключе: строку, которая ссылается на `<Z>/original` другого вложения,
сверка проверяет так же, как строку со своим ключом.
По умолчанию сверка поверхностная: наличие и размер объекта, байты она
не читает. С `--deep` разовый проход SHALL ещё читать каждый объект
вложения `ready` того же размера, которому больше grace, и сравнивать
SHA-256 его содержимого с метаданными. Плановая сверка глубокой не
бывает (требование «Плановая сверка»).
Отчёт SHALL называть по каждому расхождению класс, ключ объекта, `id`
вложения, если он известен, и возраст. Исключение — кандидаты, которых
проход с `--apply` не перепроверял после отказа по пределу (требование
«Безопасность сверки»): итог называет их число. Итог прохода SHALL
называть:
- стратегию, глубину и предел скорости (требование «Скорость сверки»);
- сколько объектов и строк просмотрено, объекты staging — отдельным числом;
- сколько расхождений найдено и исправлено по классам;
- сколько объектов и строк пропущено как свежие;
- сколько вложений уже помечены потерянными;
- сколько кандидатов не перепроверено;
- стоимость прохода: сколько объектов S3 он затронул, запросы к S3 по
операциям, сколько байтов объектов прочитано, сколько было сеансов с
PostgreSQL и сколько длился каждый шаг прохода.
После успешного исправления повторный проход SHALL не находить ни одного
исправимого расхождения.
Код выхода разового прохода:
- 0 — расхождений нет: dry-run их не нашёл, `--apply` исправил все, и
чужих объектов нет;
- 3 — расхождения остались: их нашёл dry-run, `--apply` отказался по
пределу изменений или в bucket есть чужие объекты;
- 1 — проход прерван отказом хранилища, ошибкой или сигналом;
- 2 — неверная конфигурация.
#### Scenario: Расхождения с обеих сторон найдены
- **WHEN** всё это старше grace, и выполняется сверка без `--apply`:
- в bucket мимо API записан объект вложения;
- у готового вложения удалён объект;
- у неиспользуемого готового вложения удалены метаданные;
- у другого в метаданных изменён размер;
- загрузка оборвалась между записью объекта и фиксацией `queued`
- **THEN** отчёт называет каждое расхождение его классом, ключом и
возрастом, код выхода 3, а в PostgreSQL и в bucket ничего не
изменилось
#### Scenario: Исправление расхождений
- **WHEN** после этого выполняется сверка с `--apply`
- **THEN** результат такой:
- объекты без метаданных удалены;
- зависшей загрузки нет — ни метаданных, ни объекта;
- оба вложения с потерянным оригиналом помечены, их метаданные на
месте;
- код выхода 0
#### Scenario: Повторная сверка
- **WHEN** сразу после исправления сверка выполняется ещё раз
- **THEN** ни одного из этих расхождений в отчёте нет, а код выхода
соответствует отчёту: 0, если расхождений в нём нет
#### Scenario: Стратегия HEAD находит то же
- **WHEN** в стенде те же расхождения, что в сценарии «Расхождения с
обеих сторон найдены», и выполняются сверка без `--apply` со
стратегией по умолчанию и с `--strategy head`
- **THEN** оба отчёта называют одни и те же расхождения тех же классов с
теми же ключами, коды выхода равны, а итог стратегии HEAD называет
больше запросов к S3 и сеансов с PostgreSQL
#### Scenario: Другой SHA-256 находит глубокая сверка
- **WHEN** объект готового вложения перезаписан мимо API байтами того же
размера, вложению и объекту больше grace, и выполняется сверка без
`--apply` — сначала без `--deep`, затем с `--deep`
- **THEN** поверхностная сверка это вложение расхождением не считает, а
глубокая называет его классом «другой SHA-256», и её итог называет
прочитанные байты; код выхода 3, а в PostgreSQL и в bucket ничего не
изменилось
- **AND** сверка с `--deep --apply` помечает оригинал потерянным:
скачивание — 404, метаданные — 200
#### Scenario: Строка ссылается на объект другого id
- **WHEN** всё это старше grace, и выполняются сверки без `--apply` с
`--deep` — стратегией по умолчанию и `--strategy head`:
- готовое вложение Y1 ссылается на ключ `<Z1>/original`, строки Z1 нет,
а объект по этому ключу другого размера, чем у Y1;
- готовое вложение Y2 ссылается на ключ `<Z2>/original`, строки Z2 нет,
а объект по этому ключу того же размера с другими байтами
- **THEN** оба отчёта называют Y1 классом «другой размер», Y2 — «другой
SHA-256», а объекты `<Z1>/original`, `<Z2>/original`, `<Y1>/original` и
`<Y2>/original` — чужими; код выхода 3
- **AND** сверка с `--deep --apply` помечает Y1 и Y2 потерянными, а все
четыре объекта на месте
#### Scenario: Объекты вариантов своих вложений
- **WHEN** готовые вложения с thumbnail, crop и optimized старше grace, и выполняется
сверка без `--apply` обеими стратегиями
- **THEN** объекты вариантов не названы расхождениями и чужими, а код выхода не
зависит от них
#### Scenario: Объект варианта без метаданных
- **WHEN** в bucket мимо API записан объект с ключом варианта, для `id` которого
строки нет, ему больше grace, и выполняется сверка с `--apply`
- **THEN** объект удалён, а отчёт называет его объектом без метаданных
#### Scenario: Объект staging без метаданных
- **WHEN** в bucket мимо API записан объект с ключом staging, для `id` которого строки нет, и
выполняется сверка: сначала без `--apply`, пока объект моложе срока хранения staging, затем без
`--apply` и с `--apply`, когда он старше, обеими стратегиями
- **THEN** молодой объект считается свежим и на месте, старший назван объектом staging без
метаданных с кодом выхода 3, а с `--apply` удалён с кодом выхода 0
### Requirement: Безопасность сверки
Сверка MUST NOT удалять:
- метаданные вложений, кроме уборки зависшей загрузки;
- объект, на который ссылаются метаданные, в любом статусе;
- объект с ключом вида `<id>/original` или ключом варианта, если строка
этого `id` есть;
- объект staging, на который ссылается строка, и объект staging моложе срока хранения
staging.
Вложение в `queued`, `processing` или `failed` сверка MUST NOT помечать
потерянным и считать зависшей загрузкой: объекта конечного префикса у него может
не быть, это текущая работа или её итог.
Вложение, на которое ссылается сообщение, MUST NOT терять из-за сверки
ни метаданные, ни объект, ни ссылку в истории. Если его оригинал
потерян, сверка его только помечает.
Свежее сверка MUST NOT трогать и не считает расхождением:
- объект, записанный или изменённый в S3 меньше grace назад; объект staging —
меньше срока хранения staging назад;
- вложение, метаданные которого записаны или переведены в `ready` меньше
grace назад.
Grace — тот же, что у уборщика (capability `service-configuration`,
«Параметры уборщика»).
Каждое расхождение SHALL перепроверяться в PostgreSQL и в S3
непосредственно перед действием:
- объект без метаданных — строки с этим ключом или `id` по-прежнему
нет, объект на месте и старше grace;
- объект staging без метаданных — строка этого `id` по-прежнему не ссылается на этот ключ,
объект на месте и старше срока хранения staging;
- метаданные без объекта и другой размер — вложение по-прежнему `ready`
с тем же ключом, а объекта по ключу нет или его размер другой;
- другой SHA-256 — вложение по-прежнему `ready` с тем же ключом, объект
того же размера, а SHA-256 заново прочитанного содержимого другой;
- вернувшийся оригинал — пометка на месте, объект того же размера и
того же SHA-256 заново прочитанного содержимого.
Объект другого размера или другого SHA-256, изменённый меньше grace
назад, — свежий и при перепроверке: расхождение не подтверждено.
Не подтвердилось — действие не выполняется. Отсутствие объекта MUST NOT
считаться подтверждённым, пока не проверено, что bucket на месте. Иначе
удалённый bucket выглядел бы как потеря всех оригиналов.
Предел изменений: если за проход нужно удалить объекты, пометить
оригиналы или снять пометки больше чем у `[reconciler] max_changes`
вложений, сверка с `--apply` MUST NOT выполнять ни одно из этих
изменений. Как только подтверждённых таких изменений больше предела, она
SHALL перестать перепроверять остальных кандидатов этих классов: отказ
уже решён, а каждая перепроверка — обращения к PostgreSQL и S3, пока
уборка зависших загрузок ждёт. Она пишет ошибку с пределом и числом
подтверждённых изменений, которое больше предела, и завершается кодом
3. Итог называет, сколько кандидатов не перепроверено. Сверка без
`--apply` перепроверяет каждого кандидата. Разовый проход SHALL
принимать больший предел аргументом. Уборка зависших загрузок пределом
не ограничена.
Сверка, уборщик и две сверки одновременно SHALL не мешать друг другу:
- каждое действие безопасно повторять;
- зависшую загрузку сверка убирает тем же порядком и под той же
блокировкой, что уборщик.
Объекты других баз и ключи вне префикса вложений своей базы сверка MUST
NOT читать и менять. Вложение, в метаданных которого такой ключ, —
готовое или зависшую загрузку — она называет в отчёте чужим объектом, не
проверяет его объект, не помечает и не убирает.
#### Scenario: Свежие не тронуты
- **WHEN** в bucket мимо API записан объект вложения, у готового
вложения удалён объект, обоим меньше grace, и выполняется сверка с
`--apply`
- **THEN** объект на месте, вложение не помечено, а отчёт считает их
свежими, а не расхождениями
#### Scenario: Недавно перезаписанный объект не тронут
- **WHEN** у двух готовых вложений старше grace объекты меньше grace
назад перезаписаны мимо API — у одного байтами другого размера, у
другого другими байтами того же размера, — и выполняются сверка с
`--deep --apply` и сверка с `--deep --strategy head` без `--apply`
- **THEN** ни одно вложение не помечено и не названо расхождением, а
итоги считают оба объекта свежими
- **AND** когда объектам больше grace, сверка с `--deep` называет первое
классом «другой размер», второе — «другой SHA-256»
#### Scenario: Используемое вложение не удаляется
- **WHEN** у вложения, на которое ссылается сообщение, удалён объект,
ему больше grace, и выполняется сверка с `--apply`
- **THEN** результат такой:
- вложение помечено потерянным;
- его метаданные — 200;
- история чата по-прежнему отдаёт его `id` в сообщении;
- ни одна строка вложений не удалена
#### Scenario: Чужой объект не удаляется
- **WHEN** под префиксом вложений базы лежит объект с ключом, которого
API не пишет, ему больше grace, и выполняется сверка с `--apply`
- **THEN** объект на месте, отчёт называет его чужим, код выхода 3
#### Scenario: Предел изменений
- **WHEN** расхождений, которые сверка исправила бы, больше предела, и
выполняется сверка с `--apply`
- **THEN** ни один объект не удалён, ни одно вложение не помечено,
ошибка называет предел и число подтверждённых изменений больше него,
код выхода 3
- **AND** с пределом не меньше их числа повтор исправляет все
#### Scenario: Отказ по пределу без лишних перепроверок
- **WHEN** расхождений, которые сверка исправила бы, вдвое больше
предела, и выполняется сверка с `--apply`
- **THEN** ошибка называет предел и число подтверждённых изменений — на
одно больше предела, итог называет остальных кандидатов
неперепроверенными, ни одно вложение не помечено, код выхода 3
- **AND** сверка без `--apply` называет каждое из этих расхождений
#### Scenario: Предел не останавливает уборку зависших
- **WHEN** загрузка оборвалась между записью объекта и фиксацией `queued`
больше grace назад, расхождений, которые сверка исправила бы, больше
предела, и выполняется сверка с `--apply`
- **THEN** код выхода 3, ни одно вложение не помечено, а зависшей
загрузки нет — ни метаданных, ни объекта
#### Scenario: Объект, на который ссылается строка, не удаляется
- **WHEN** всё это старше grace, и выполняется сверка с `--apply`:
- у готового вложения X в метаданных другой ключ под префиксом
вложений, объекта по нему нет, а объект `<X>/original` на месте;
- готовое вложение Y ссылается на ключ `<Z>/original`, строки Z нет, и
объекты `<Y>/original` и `<Z>/original` на месте
- **THEN** результат такой:
- все три объекта на месте, отчёт называет их чужими, код выхода 3;
- X помечено потерянным: объекта по его ключу нет;
- Y не помечено: объект по его ключу есть
#### Scenario: Ключ вне префикса вложений не трогается
- **WHEN** у готового вложения и у зависшей загрузки старше grace в
метаданных ключ вне префикса вложений своей базы, и выполняется сверка
с `--apply`
- **THEN** отчёт называет оба чужими, код выхода 3, вложение не помечено,
а метаданные зависшей загрузки и объекты обоих под префиксом вложений
на месте
#### Scenario: Сверка под нагрузкой
- **WHEN** выполняются все условия:
- участники дольше grace загружают вложения и отправляют сообщения с
ними;
- в это время сверка с `--apply` повторяется раз в несколько секунд;
- в стенде есть внесённые расхождения
- **THEN** внесённые расхождения исправлены, каждое вложение, загрузка
которого ответила 202, становится `ready` и скачивается с тем же SHA-256, а
каждое сообщение отдаёт свои `attachment_ids`
#### Scenario: Текущая работа не считается расхождением
- **WHEN** worker остановлен, вложения в `queued`, `processing` и `failed`
старше grace, их объекты в staging старше срока хранения, у одного из них уже есть
объект конечного ключа, и выполняется сверка с `--apply`
- **THEN** ни одно из них не названо расхождением и не помечено потерянным, а их
метаданные, объекты staging и этот объект конечного ключа на месте, код выхода
от них не зависит
## ADDED Requirements
### Requirement: Очистка staging
Объекты staging SHALL убирать уборщик; worker и реплики API их не удаляют. Не реже чем раз в
`[cleaner] interval_seconds` он SHALL:
- у вложения `ready` — удалить объект staging: результат уже безопасно зафиксирован;
- у вложения `failed`, которое не менялось дольше `[cleaner] staging_retention_seconds` (срок
хранения, имя skeleton `STAGING_RETENTION_SECONDS`), — удалить объекты конечного оригинала и
вариантов, которые успела записать прежняя попытка, затем объект staging.
После удаления ключ staging в метаданных SHALL очищаться: replay такого вложения невозможен
(`attachment-processing`, «Реестр failed и replay»). Метаданные вложения MUST NOT удаляться: на него
могут ссылаться сообщения.
Вложение в `queued` и `processing` — текущая работа: его объекты MUST NOT удаляться ни в каком
возрасте. Удаляется только ключ под префиксом staging своей базы: ключ другого вида уборщик оставляет и
называет в журнале. Шаг одного вложения SHALL быть безопасно повторяемым: сбой между удалением объекта и
записью в PostgreSQL оставляет ключ в метаданных, а следующий проход удаляет отсутствующий объект без ошибки.
При отказе S3 или PostgreSQL проход SHALL прерываться, как уборка незавершённых загрузок (требование «Уборка при
отказах хранилищ»), и доводиться следующим.
Срок хранения и его обоснование SHALL быть описаны в `REPORT.md`.
#### Scenario: Staging готового вложения убран
- **WHEN** вложение стало `ready`
- **THEN** не позже следующего прохода уборщика с запасом объекта staging нет, ключ staging в метаданных
пуст, а оригинал и варианты скачиваются с теми же SHA-256
#### Scenario: Staging неудачного вложения хранится до срока
- **WHEN** вложение стало `failed`, а срок хранения ещё не прошёл, и уборщик делает несколько проходов
- **THEN** объект staging на месте, а replay возможен
#### Scenario: Срок хранения прошёл
- **WHEN** вложение стало `failed` после записи конечного оригинала и вариантов, и его возраст больше срока
хранения
- **THEN** не позже следующего прохода уборщика с запасом ни объекта staging, ни конечного оригинала, ни объектов
вариантов нет, а метаданные — 200 с `status` `failed` и тем же `error_code`
#### Scenario: Текущая работа не убирается
- **WHEN** worker остановлен, а вложению в `queued` больше срока хранения
- **THEN** его объект staging на месте, а после запуска worker вложение становится `ready`
#### Scenario: Очистка при отказе S3
- **WHEN** вложение стало `ready`, S3 заморожен (`docker pause`), уборщик делает несколько проходов, и участник отправляет
сообщение со ссылкой на это вложение
- **THEN** отправка — 201 быстрее секунды: очистка её не держит, ключ staging в метаданных на месте, уборщик работает без
перезапуска, а после разморозки S3 не позже следующего прохода с запасом объекта staging нет
#### Scenario: Ключ staging другого вида не удаляется
- **WHEN** у готового вложения в метаданных ключ staging вне префикса staging своей базы
- **THEN** объект по этому ключу на месте, а журнал уборщика называет ключ
@@ -0,0 +1,297 @@
# Spec Delta
## MODIFIED Requirements
### Requirement: Только по HTTP
Тесты SHALL обращаться к сервису только по HTTP и MUST NOT импортировать
код приложения, запускать или останавливать сервер. Проверки отказов
SHALL действовать на хранилища стенда, брокер, relay и worker и узнавать их
состояние только через hook, который им передаёт `make failure_checks`. Без hook они
MUST завершаться ошибкой с указанием этой команды, а не обращаться к
хранилищам сами. Один и тот же набор SHALL проходить против сервера,
запущенного на хосте, и против контейнера.
#### Scenario: Консоль и контейнер
- **WHEN** набор запускается сначала против `make run_dev` с `make run_relay` и `make
run_worker`, затем против `make run_docker`
- **THEN** оба прогона проходят одинаково
#### Scenario: Проверка отказа без hook
- **WHEN** проверки отказов запущены pytest напрямую, без
`make failure_checks`
- **THEN** они завершаются ошибкой, которая называет `make
failure_checks`, и ни одно хранилище не останавливается
### Requirement: Покрытие сценариев основных спеков
Для каждого сценария основных спеков `api-conventions`,
`identification`, `sessions`, `users`, `chats`, `messages`,
`pagination`, `data-storage`, `chat-cache`, `health`, `idempotency`, с
лабы 4 `attachments` и `storage-consistency` и с лабы 5
`attachment-processing`, `message-broker` и `job-outbox`, который воспроизводится
по HTTP против работающего сервера, в том числе на стенде отказов,
SHALL быть тест. Из имени или описания теста SHALL быть понятно, какой
capability и сценарий он проверяет. Сценарий, который проверяет тест
отказа, SHALL считаться покрытым, хотя `make student_test` этот тест
не выполняет; итог сверки SHALL называть, сколько сценариев покрыто
проверками отказов. Сценарии, которые по HTTP не воспроизвести, SHALL
быть перечислены с причиной и способом проверки.
#### Scenario: Сверка покрытия
- **WHEN** проверяющий берёт любой сценарий перечисленных спеков
- **THEN** находится проверяющий его тест либо запись в списке
исключений с причиной
#### Scenario: Сценарий отказа в сверке
- **WHEN** выполняется `make student_test`
- **THEN** сверка считает сценарии проверок отказов покрытыми, не
требует для них исключений и печатает их число
### Requirement: Прогон на временной базе
`make test_isolated` SHALL проверять образ, собранный из рабочего
дерева, в связке compose на временной базе `test_<имя рабочей базы>` в
PostgreSQL стенда, с Valkey, S3 и брокером стенда. Команда SHALL по порядку:
1. поднять PostgreSQL, Valkey, S3 с bootstrap и брокер;
2. собрать образ и создать базу заново;
3. применить к ней миграции сервисом миграций compose;
4. запустить отдельный контейнер API, отдельный контейнер relay и отдельный контейнер
worker из определений сервисов compose, в которых подменено только имя базы, и
опубликовать API на `127.0.0.1:TEST_APP_PORT` из `.env`;
5. дождаться готовности и выполнить публичный smoke (`make test`) и
весь набор (`make student_test`) против этого контейнера;
6. остановить и удалить все три контейнера, удалить базу, объекты S3 под
префиксом `test_<db>/` и очередь временной базы.
Это один процесс API без балансировщика: набор SHALL запускаться с
`EXPECT_REPLICAS=1`, и тесты реплик пропускаются с причиной. Код
выхода SHALL быть ненулевым, если не прошёл smoke, набор или уборка.
Рабочая база и рабочие контейнеры стенда MUST NOT затрагиваться.
Тестовый прогон отделён от рабочего именем базы:
- карточки чатов в Valkey — именем базы в ключе (capability
`chat-cache`);
- объекты в S3 — префиксом имени базы в ключе объекта (capability
`object-storage`);
- задания — именем базы в имени очереди (capability `message-broker`).
Объекты и очередь рабочей базы при уборке MUST NOT удаляться. Параллельный
запуск двух прогонов не поддерживается.
#### Scenario: Успешный прогон
- **WHEN** в рабочей базе есть данные, рабочий стенд запущен, и
выполнен `make test_isolated`
- **THEN** smoke и набор прошли, тесты реплик пропущены с причиной,
код выхода 0, ни базы `test_<db>`, ни тестовых контейнеров, ни
объектов под префиксом `test_<db>/`, ни очереди временной базы после команды
нет, число строк в таблицах рабочей базы и объекты рабочей базы не изменились,
а рабочий стенд продолжает отвечать через балансировщик
#### Scenario: Упавшие тесты
- **WHEN** во время `make test_isolated` падает хотя бы один тест
- **THEN** код выхода ненулевой, журналы тестовых контейнеров выведены,
контейнеры удалены, база `test_<db>`, объекты под префиксом `test_<db>/` и
очередь временной базы удалены
#### Scenario: Прерывание
- **WHEN** `make test_isolated` прерван Ctrl+C
- **THEN** тестовые контейнеры остановлены и удалены, база `test_<db>`, объекты
под префиксом `test_<db>/` и очередь временной базы удалены
#### Scenario: Хвост прошлого прогона
- **WHEN** тестовые контейнеры, база `test_<db>`, объекты под префиксом
`test_<db>/` или очередь временной базы остались от прогона, убитого без уборки
- **THEN** следующий `make test_isolated` удаляет их и начинает заново
#### Scenario: Сохранить базу для разбора
- **WHEN** выполнен `make test_isolated KEEP_TEST_DB=1`
- **THEN** после прогона тестовые контейнеры удалены, база `test_<db>`, объекты под
префиксом `test_<db>/` и очередь временной базы остаются, а команда печатает имя
базы, префикс и очередь
### Requirement: Проверки отказов на отдельном стенде
Сценарии отказов SHALL проверяться автоматически одной командой
`make failure_checks`:
- `sessions`: «Истёкший токен», «Срок не продлевается», «БД остановлена при
запросе с токеном»;
- `data-storage`: «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны»;
- `health`: «Хранилище не готово», «Кэш недоступен», «Хранилище
объектов недоступно», «Брокер и worker недоступны»;
- `chat-cache`: «Valkey остановлен», «Valkey завис», «Valkey вернулся»,
«Очистка кэша»;
- `idempotency`: «Сбой при записи сообщения», «Отказ БД при отправке»,
«Ключ после срока», «Повтор после failed вложения»;
- `api-conventions`: «Лимит одновременных загрузок»;
- `messages`: «Вложение в обработке», «Вложение стало failed после отправки»;
- `attachments`: «Запись в S3 не удалась», «Отклонённая загрузка ничего
не оставляет», «S3 остановлен», «S3 завис», «Незавершённая загрузка не
видна», «Сбой записи метаданных», «Фиксация задания не удалась», «Фиксация ready не
удалась», «Исход фиксации неизвестен», «Брокер не подтвердил задание», «Обрыв
передачи тела», «Отказ раньше
очереди», «Все места заняты», «Очередь ожидания полна», «Ожидание места», «Место
освобождается», «Медленный клиент», «Медленная передача в срок», «Потерянный
оригинал», «Загрузка после простоя S3», «Скачивание до готовности», «Отсутствующий
вариант»;
- `attachment-processing`: все сценарии, которым нужны остановка worker, relay, брокера или
S3, сбой внутри обработки, запуск worker с другими параметрами или команда replay;
- `message-broker`: все сценарии, которые не названы исключениями сверки покрытия;
- `job-outbox`: все сценарии;
- `storage-consistency`: все сценарии.
Команда SHALL:
- собрать образ из рабочего дерева;
- поднять отдельный стенд со своими PostgreSQL, Valkey, S3 и брокером, применить
миграции и bootstrap S3;
- запустить четыре API:
- с настройками по умолчанию;
- «тесный» — с коротким сроком сессии и ключа идемпотентности и пулом
из одного соединения;
- «узкий по загрузкам» — с одним местом загрузки, одной загрузкой в
очереди, коротким сроком ожидания места и коротким сроком тела;
- «с коротким сроком S3» — со сроком вызова S3 в одну секунду: простой
дольше срока вызова в проверке длится полторы секунды, а не шесть.
Значения «узкого» API и API с коротким сроком S3 SHALL передаваться
проверкам, и проверки SHALL сверять с ними стенд;
- запустить уборщика с коротким grace, интервалом и сроком хранения staging, сравнимыми со
временем теста, без плановой сверки, и передать их значения
проверкам. Grace при этом SHALL проходить проверку границы живой
загрузки (`service-configuration`, «Параметры уборщика»). Сверку
проверки запускают сами, и плановая сверка не меняет стенд у них за
спиной;
- запустить relay с короткими паузой и порогом потерянного сообщения и передать их значения
проверкам;
- запустить worker с короткими сроками и малым числом попыток, сравнимыми со
временем теста, и передать их значения проверкам;
- выполнить проверки отказов;
- удалить стенд вместе с его данными при любом исходе.
Hook стенда отказов SHALL уметь:
- сообщить вложения стенда в PostgreSQL с их статусами, `id` последнего
вложения в статусе «загружается» и `id` вложений с потерянным
оригиналом;
- сообщить задание вложения: идентификатор, состояние, число начатых попыток, число
попыток до последнего replay, причину последней ошибки, время следующей попытки, срок
аренды и время подтверждения брокером, а также записи аудита replay;
- сообщить, у каких вложений есть объект в конечном префиксе и в staging bucket
стенда, и сколько у вложения объектов вариантов, — по самим объектам, а не по
каталогам хранилища, и SHA-256 объекта по ключу;
- внедрить отказ PostgreSQL:
- при записи метаданных загрузки с заданным `filename`;
- при фиксации её `queued`, и задержать такую фиксацию;
- при фиксации `ready` с заданным `filename`, и задержать такую фиксацию: оператор
перевода и сам COMMIT;
- при пометке потерянного оригинала такого вложения;
- задержать запись времени подтверждения брокером у задания вложения с заданным
`filename`;
- дождаться, пока COMMIT задержан в PostgreSQL;
- убить и снова запустить обычный API стенда;
- остановить, убить, заморозить и запустить брокер, relay и worker стенда, заморозить процесс 1
контейнера worker сигналом и убить контейнер, запустить отдельный worker или relay с заданными
значениями `WORKER__*` и `RELAY__*` и убрать его;
- сообщить состояние очереди: сообщений, готовых, неподтверждённых, потребителей,
устойчива ли она;
- прочитать сообщение из очереди без подтверждения, добавить в очередь сообщение
и удалить очередь; включить и снять предел памяти брокера;
- убить процесс обработки в контейнере worker и сообщить имена переменных его окружения;
- внести расхождения хранилищ:
- записать объект в bucket стенда мимо API и удалить объект мимо API —
только под префиксами вложений и staging базы стенда;
- удалить метаданные вложения, изменить в них размер, SHA-256, ключ staging и время
следующей попытки, сдвинуть их время в прошлое и вернуть вложение в статус «загружается» без
задания;
- удалить метаданные варианта;
- выполнить разовую сверку — без изменений или с `--apply`, с заданным
пределом изменений, стратегией обхода, глубиной, пределом скорости и сроком хранения
staging — и вернуть её записи и код выхода;
- выполнить команду replay с заданным выбором и вернуть её записи и код выхода;
- остановить и запустить уборщика стенда, а также запустить отдельного
уборщика с коротким интервалом плановой сверки на заданное время и
вернуть его журнал.
Других сведений о хранилищах проверки вложений не получают. Объекты без
метаданных проверка находит сравнением двух списков: вложений и
объектов. Ключи доступа S3 и пароль брокера hook не получает и не печатает: объект
мимо API и сообщение в очередь записывает процесс в контейнере стенда своими ключами.
Порты PostgreSQL, Valkey, S3 и брокера этого стенда MUST NOT публиковаться на
хосте, API — только на `127.0.0.1`. Рабочий стенд, его база, кэш,
хранилище объектов, брокер и контейнеры MUST NOT затрагиваться. Код выхода
SHALL быть ненулевым, если не прошла хотя бы одна проверка или уборка.
Параллельный запуск двух прогонов не поддерживается: уборка хвоста в
начале второго удаляет стенд первого.
Точек внедрения сбоя в коде приложения MUST NOT быть: сбои внедряются снаружи, средствами стенда.
#### Scenario: Успешный прогон
- **WHEN** рабочий стенд запущен, и выполнен `make failure_checks`
- **THEN** все проверки отказов прошли, код выхода 0, контейнеров и
volumes стенда отказов после команды нет, а у контейнеров рабочего
стенда прежнее время старта, и рабочий API отвечает
#### Scenario: Упавшая проверка
- **WHEN** во время `make failure_checks` падает хотя бы одна проверка
- **THEN** код выхода ненулевой, журналы API, уборщика, relay и worker стенда отказов
выведены, стенд отказов удалён
#### Scenario: Прерывание
- **WHEN** `make failure_checks` прерван Ctrl+C
- **THEN** стенд отказов остановлен и удалён вместе с volumes
#### Scenario: Хвост прошлого прогона
- **WHEN** контейнеры или volumes стенда отказов остались от прогона,
убитого без уборки
- **THEN** следующий `make failure_checks` удаляет их и начинает заново
### Requirement: Сценарий защиты автоматизирован
Сценарий защиты из `README.md` SHALL быть автоматизирован на стенде отказов и командой
драйвера на рабочем стенде. Шаги 1–3: worker остановлен → загрузка 202 → сообщение с вложением 201 →
скачивание 409 → текстовое сообщение 201 → перезапуск API и брокера с сохранёнными volumes →
worker запущен → то же вложение `ready`, оригинал равен загруженному, thumbnail — настоящий
JPEG.
Шаг 4 — отдельная команда драйвера и проверка отказа, по порядку:
- crash после записи объектов до фиксации и crash после фиксации до подтверждения
(`attachment-processing`, «Доставка at least once»): повтор завершает тот же результат;
- разрыв COMMIT и publish: relay убит, загрузка 202, сообщения нет, relay запущен, вложение `ready`;
и crash relay после подтверждения до отметки (`job-outbox`, «Relay публикует намерения»);
- replay `failed`: показ реестра, replay с `--apply`, вложение `ready`, отказ replay готового
(`attachment-processing`, «Реестр failed и replay»).
Команды драйвера SHALL печатать порядок действий и `id` без токенов и завершаться
ненулевым кодом при расхождении, а их вывод SHALL сохраняться в `evidence/`. Worker и relay SHALL
быть запущены снова, а внедрённые сбои сняты при любом исходе.
#### Scenario: Команда на рабочем стенде
- **WHEN** на запущенном рабочем стенде выполняется команда защиты драйвера
- **THEN** код выхода 0, вывод называет шаги, коды ответов, `id` вложения и сообщения и время
старта контейнеров API и брокера до и после, а токенов и секретов в выводе нет
#### Scenario: Сбой посреди сценария
- **WHEN** сценарий команды прерван расхождением или сигналом
- **THEN** worker и relay снова запущены, внедрённых триггеров нет, а код выхода ненулевой
#### Scenario: Шаг 4 на рабочем стенде
- **WHEN** на запущенном рабочем стенде выполняется команда шага 4
- **THEN** код выхода 0, вывод по каждому сбою называет окно, действие, `id` задания, число начатых
попыток и итог, а токенов и секретов в выводе нет
@@ -0,0 +1,315 @@
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться — дельты в
`specs/`. Перед первым файлом слоя прочитать его правило: `service-layer.md`,
`repo-layer.md`, `dto.md`, `infra.md`, `worker.md`, `api-layer.md`, `api-contract.md`,
`migrations.md`, `logging.md`, `settings.md`, `run-modes.md`, `docker.md`,
`balancer.md`, `student-tests.md`, `bench.md`.
**Граница коммита.** Группы 1–14 — код, тесты, инструменты и правила: проверяются на
рабочем дереве, агент apply не коммитит и в `evidence/` не пишет. Группа 15 — снятие
evidence и `REPORT.md`: её запускает основная сессия после коммита групп 1–14, на
закоммиченном коде (`bench.md`, «Измеренное состояние — commit»).
**Шага оператора нет.** Новых секретов нет, `config.toml` читается как есть. Руками `.env`
не читать и не править.
**Ожидаемо красное**, остальное разбирается по AGENTS.md:
- `make test` и сценарии вложений — до конца группы 9: API уже не публикует, а relay ещё нет;
- между задачами 10.4 и 10.8 — сверка покрытия: «marker points to unknown scenario»; sync
раньше тестов дал бы обратное, «no test and no exclusion»;
- `test_exclusion_evidence_exists` — по файлам старых исключений `evidence/cache/hits.md`,
`evidence/auth/passwords-and-tokens.md`, `evidence/idempotency/replay-after-restart.md`: они
снимаются на последнем шаге всего прогона. В группах 1–14 это не регрессия, но падать он должен
только по `missing_evidence`.
Решения по ходу работы — design, «Уточнения apply»; вопросы и решения без пользователя —
`QUESTIONS.md`, `## pipeline-reliability`; дефект, найденный попутно, — `KNOWN_ISSUES.md`.
## 1. Настройки и общие типы
- [ ] 1.1 Настройки по решению 12 и дельте `service-configuration`:
- `Worker`: новые поля, `graceful_shutdown_seconds` не больше 8, `render_timeout_seconds` меньше
`job_timeout_seconds`, `retry_max_delay_seconds` не меньше `retry_base_delay_seconds` (на полях, через
`info.data`), `retry_delay_seconds` убран;
- новый класс `Relay` и поле `relay` в `Settings`; `Cleaner.staging_retention_seconds`;
- `allow_inf_nan=False` у всех новых `float`; строки с единицами в `config_example.toml`;
- шапка `.env.example`: `STAGING_RETENTION_SECONDS` → `[cleaner] staging_retention_seconds`.
Проверка: `uv run python -c "from src.config import settings; print(settings.worker, settings.relay)"` — значения
по умолчанию из решения 12; `WORKER__PREFETCH=0`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS=9`,
`WORKER__RENDER_TIMEOUT_SECONDS=120`, `WORKER__RETRY_MAX_DELAY_SECONDS=1`, `RELAY__BATCH_SIZE=0`,
`RELAY__POLL_INTERVAL_SECONDS=inf`, `CLEANER__STAGING_RETENTION_SECONDS=0` — ошибка называет поле; существующий
`config.toml` с `retry_delay_seconds` загружается.
- [ ] 1.2 Общие типы по решениям 4 и 7:
- `AttachmentJobReason`: `limit_pixels`, `limit_memory`, `limit_cpu`, `render_killed`, `render_crashed`,
`lease_expired`; `ReconcileFinding.ORPHAN_STAGING`; докстринг `AttachmentVariantName`;
- `src/utils/constants.py`: `CROP_SIDE`, `CROP_JPEG_QUALITY`, `OPTIMIZED_MAX_SIDE`, `OPTIMIZED_WEBP_QUALITY`,
`OPTIMIZED_WEBP_METHOD`, префикс и суффикс ключей, если их ещё нет;
- `src/core/exceptions`: постоянный отказ изображения и прерванная обработка — с причиной
`AttachmentJobReason`, вне таблицы `DOMAIN_ERRORS`: наружу они не выходят.
Проверка: `make lint`; `uv run python -c "import src.api.errors"`.
## 2. Схема
- [ ] 2.1 Модели по решению 10: `AttachmentJob.attempt_base` и CHECK, `AttachmentJobReplay`, четыре индекса с
`postgresql_where`, экспорт в `models/__init__.py`.
Проверка: `make lint`; совпадение со схемой — задача 2.3.
- [ ] 2.2 Ревизия `added_job_replays_and_attempt_base` поверх `a1d4c7e90b23` руками: первой строкой `SET LOCAL lock_timeout =
'2s'`, колонка с `server_default`, CHECK `NOT VALID`, таблица, `downgrade`.
- [ ] 2.3 Ревизия `added_job_outbox_indexes`: `autocommit_block`, `SET lock_timeout`, `CONCURRENTLY`, `if_not_exists`, `RESET`; `downgrade`
так же.
Проверка 2.2–2.3 на временной базе (`createdb` в контейнере `postgres`, `DATABASE__NAME` в окружении, после — `DROP DATABASE`):
- `upgrade` с нуля, `uv run alembic check` пуст, повтор ничего не меняет, `downgrade -2`, `upgrade`;
- на базе со строками прежних состояний: вставка задания без `attempt_base` проходит, `pg_constraint.convalidated` нового CHECK — false,
`indisvalid` всех четырёх — true;
- `EXPLAIN` выборок relay и уборки на наполненной базе — индексы решения 10, как в таблице проб;
- запись аудита с неизвестным заданием и `attempt_base` больше `attempt` — нарушение ограничения; задание с записью аудита удалить нельзя;
- транзакция держит `attachment_jobs` дольше 2 с: первая ревизия падает без изменений, повтор проходит.
## 3. DTO и repo
- [ ] 3.1 DTO по `dto.md`: `AttachmentJobDTO.attempt_base`, `AttachmentInListDTO` с тем, что нужно очистке; `RelayPassDTO`, `StagingCleanupPassDTO`,
`ReplayResultDTO`, `listed_staging` в `ReconcilePassDTO`; `__init__.py`.
Проверка: `make lint`.
- [ ] 3.2 `src/core/repos/attachment_job.py` по решениям 2–5, одно выражение на функцию, состояние в выборках — константой (`literal_execute`):
выборка due-строк `FOR UPDATE SKIP LOCKED`, `count_published`, отметка пакета, возврат истёкших аренд (`RETURNING`), есть ли старше порога, сброс
потерянных; `start_attempt` с `lease_expires_at`, `return_to_queued` с `next_attempt_at`, блокировка и перевод для replay. Убрать `delete_unstarted`.
Проверка: `make lint`; план — задача 2.3, поведение — группы 7 и 10.
- [ ] 3.3 `src/core/repos/attachment.py`: блокировка строки для replay и очистки — `FOR NO KEY UPDATE` (`with_for_update(key_share=True, …)`, решение 9), `failed → queued`, выборка очистки staging keyset, `clear_staging_key`,
вложения группы `processing → queued`. Убрать `return_to_pending`. `src/core/repos/attachment_job_replay.py` — вставка и чтение по заданию.
Проверка: `make lint`; поведение — группы 5, 7, 8, 10.
- [ ] 3.4 `src/core/repos/attachment_object.py` по решению 9: `staging_prefix`, `is_own_staging_key`, `parse_staging_key`, `list_staging`, ключи вариантов всех
имён для уборки.
Проверка: разовый вызов: свой `id` — `id`; верхний регистр, чужой префикс, другой суффикс — `None`; `make lint`.
## 4. Варианты и процесс обработки
- [ ] 4.1 `src/utils/image_variants.py` вместо `thumbnail.py` по решению 6: `fit_size`, `render_variants`; константы из 1.2. Импорт Pillow — только здесь.
Проверка — разовый скрипт в scratchpad с генераторами `student-tests/images.py`:
- thumbnail: все случаи задачи 5.1 архива `async-attachments` (320 × 200, 1000 × 601, 5000 × 10, EXIF 1–8, альфа, палитра) без изменений;
- crop: 400 × 200 полосами — синий; 50 × 20 — 128 × 128; EXIF 6; альфа на белый; 5000 × 10 — квадрат из декодированного;
- optimized: 2000 × 1000 → 1280 × 640, 5000 × 3001 → 1280 × 768, 5000 × 10 → 1280 × 2, 100 × 50 без увеличения; JPEG с EXIF и ICC — без чанков `EXIF`,
`XMP `, `ICCP`, размеры повёрнуты; RGBA — альфа 0;
- все `png_variants()` и `jpeg_variants()` проходят; точность SOF 12 — ошибка декодирования; два запуска — одинаковые SHA-256;
- `grep -rn "PIL" src` — только этот модуль.
- [ ] 4.2 Процесс обработки по решению 7: `src/worker/render.py` (лимиты первыми строками, `RLIMIT_AS`, `RLIMIT_CPU`, `RLIMIT_CORE`, коды 0/3/4/5, строка JSON и байты, `VmHWM`,
отметка неприменённого лимита) и `src/infra/render/client.py` (`ImageRenderer`: окружение решения 7, срок, `kill` и ожидание в `finally`, разбор вывода, перевод кодов в
исключения 1.2).
Проверка — разовый скрипт в scratchpad, контейнер образа 1 CPU / 1 ГБ и хост macOS:
- PNG RGBA 40 Мпкс: успех, `VmHWM` не больше ~410 МиБ, в контейнере лимит применён, на macOS — отмечен неприменённым;
- JPEG с повторёнными сканами из таблицы проб: лимит CPU 2 с — `limit_cpu` за ~2 с; срок 1 с — `timeout`, процесса нет;
- лимит памяти 200 МиБ — `limit_memory`; SIGKILL извне — `render_killed`; испорченный вывод — `render_crashed`;
- отмена задачи посреди рендера — процесса нет (`pgrep`); в окружении процесса нет `DATABASE__*`, `S3__*`, `BROKER__*`.
## 5. Worker
- [ ] 5.1 `AttachmentProcessingService` по решениям 3, 4, 6, 7: таблица claim без `redelivered`, бюджет с `attempt_base`, срок аренды, три варианта через `ImageRenderer`, запись трёх
объектов, fencing в `_commit_ready`, `retry_delay` с jitter и `return_to_queued` со сроком и ACK, постоянные ошибки по таблице решения 4; без `publisher`, `limiter` и паузы повтора;
журнал по решению 18.
Проверка: `make lint`; разовый запуск `retry_delay` — границы формулы на 1000 значениях; поведение — группа 10.
- [ ] 5.2 Процесс `src/worker/main.py` по решениям 8 и 19: `prefetch` и `asyncio.Semaphore(concurrency)`, `ImageRenderer`, закрытие клиентов одним `gather` под сроком, «Started worker» со всеми значениями, без издателя.
Проверка без стенда: `WORKER__PREFETCH=0 uv run python -m src.worker` — код 2, запись называет поле без значений; `make lint`. На стенде — задача 9.6, там же RSS worker с двумя телами 10 MiB для расчёта решения 7 (итог — «Уточнения apply»).
## 6. API
- [ ] 6.1 Приём без брокера по решению 1: `_store` отвечает после `_mark_queued`; убрать `_publish_job`, `_cancel_job`, параметр `publisher`, `src/infra/broker/instance.py`, строки в `src/api/dependencies.py` и `src/main.py`, поля брокера в «Started API»; `content_type` в «Uploaded attachment» — `.value`; докстринги про разрыв.
Проверка: `make lint`; один PNG против консольного API при остановленном брокере — 202, строка `queued`, задание без `published_at`, объект только в staging; `grep -rn "aio_pika\|broker" src/api src/main.py src/core/services/attachment.py` пуст; в журнале `content_type` — `image/png`.
## 7. Relay и replay
- [ ] 7.1 `JobPublisher` по решению 2: `publish_many` и `ready_messages`; прежний `publish` убрать, если больше не нужен; докстринг модуля без API.
Проверка — разовый скрипт в scratchpad против брокера стенда: пакет 100 подтверждён; удалённая очередь — ошибка, затем новое соединение с объявлением; `docker compose stop rabbitmq` и `docker pause` — ошибка не позже срока, подмножество подтверждённых верно; `ready_messages` — только готовые; пароля в выводе нет.
- [ ] 7.2 `AttachmentRelayService` по решению 2: три шага прохода, предел опубликованных, запись на смену состояния, журнал по решению 18.
Проверка: `make lint`; поведение — группа 10.
- [ ] 7.3 Процесс `src/relay/` по решению 2 и 18: `__main__.py`, `main.py`: сигналы, свой engine и издатель, цикл с паузами, отказ брокера и PostgreSQL не роняет, «Started relay», «Stopped relay», `os._exit`.
Проверка без стенда: `RELAY__BATCH_SIZE=0 uv run python -m src.relay` — код 2, запись называет поле; при остановленном брокере процесс живёт и пишет `warning`, по SIGTERM — код 0; `make lint`.
- [ ] 7.4 Replay по решению 5: `AttachmentReplayService`, подкоманда `replay` в `src/relay/main.py`, коды 0/3/1/2, аудит одной транзакцией, отказы, с `--apply` выбор обязателен (иначе код 2).
Проверка: `make lint`; разовый запуск на временной базе: `failed` — показ без изменений, replay, повторный replay — отказ `not_failed`; поведение — группа 10.
## 8. Уборщик и сверка
- [ ] 8.1 Очистка staging по решению 9: `AttachmentCleanupService.clean_staging`, вызов в цикле `_serve` и в `--once`, порог срока хранения, удаление вариантов и оригинала у `failed`, проверка ключа, «Started cleaner» со сроком, журнал по решению 18.
Проверка: `make lint`; поведение — группа 10; разовый `python -m src.cleaner --once` на стенде после 9.6 — код 0.
- [ ] 8.2 Сверка по решению 9: шаг списка staging с той же обёрткой сигнала и скорости, класс `orphan_staging` в `LIMITED_KINDS` и `ACTION_ORDER`, перепроверка и действие, `listed_staging`, обе стратегии; `unknown_object` для другого ключа под staging.
Проверка: `make lint`; на стенде обе стратегии без `--apply` — объекты живых строк не названы; поведение — группа 10.
## 9. Стенд
- [ ] 9.1 `docker-compose.yml` по решениям 1 и 13: сервис `relay`, у `api` без `*broker-env` и `rabbitmq`, комментарии.
Проверка: `docker compose --env-file .env config --quiet`; `docker compose config` — пароль брокера только у `rabbitmq`, `relay`, `worker`; у `relay` нет секретов S3 и пароля Valkey; лимиты у `relay`.
- [ ] 9.2 `infra/s3/bootstrap.sh` по решению 9: условие списка на два префикса, staging — из проверенного имени базы; `apply` и `check` — строки «cleaner key list staging prefix»; `driver.py s3-check` их показывает.
Проверка на временном проекте compose (`-p` своё имя, `--env-file` — файл в scratchpad, порты свободные; без `down -v`: созданные volumes перечислить в отчёте и оставить основной сессии): первый запуск и повтор — код 0; список staging ключом уборщика — 200, чужой префикс и общий префикс базы — 403.
- [ ] 9.3 `Makefile`: `run_relay`, `replay [ATTACHMENT=…] [ERROR_CODE=…] [REASON=…] [LIMIT=…] [APPLY=1] [OPERATOR=…]`, комментарии; `run_dev` по-прежнему с `start_broker`.
Проверка: `make replay` на стенде — код 0, значения секретов не печатаются; с `APPLY=1` без выбора — код 2.
- [ ] 9.4 Комментарии: `scripts/restart.sh` (relay), `scripts/rolling-update.sh` и `infra/haproxy/haproxy.cfg` — 26 с и 73 с.
Проверка: `scripts/restart.sh` на стенде — код 0 не дольше 90 с, у relay и worker прежний `StartedAt`, `RestartCount` 0; `haproxy -c` закреплённым образом.
- [ ] 9.5 CI по решению 13: `relay` в `.github/ci/compose.yml`; шаги workflow не меняются.
Проверка: `COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml`, `CI_IMAGE_TAG` и `. .github/ci/stand-env.sh`, `docker compose config --quiet`; у `relay` образ прогона, нет bind mount и портов.
- [ ] 9.6 Рабочий стенд на рабочем дереве: `make run_docker`.
Проверка:
- `docker compose ps` — две реплики, уборщик, relay, worker, брокер и S3 в рабочем состоянии, bootstrap с кодом 0;
- `make test` — `PASS: lab5`;
- журнал relay: «Started relay» со всеми значениями, запись прохода; журнал worker: три варианта, `render_ms`, `render_peak_kib`; `filename` smoke в журналах нет;
- staging исчез не позже следующего прохода уборщика;
- `docker compose stop relay worker` — быстрее 10 с, код 0; `up -d --no-deps` и сразу `stop` — записи «before startup»;
- `/proc/1/cmdline` контейнера relay — `python -m src.relay`; в `/proc/1/maps` реплики API и процесса 1 worker нет `_imaging`;
- RSS процесса 1 worker при двух одновременных PNG 10 MiB — число в «Уточнениях apply» и расчёт решения 7;
- `make s3_check` — код 0, строки staging на месте.
## 10. Тесты
- [ ] 10.1 Клиент и генераторы по решению 15: `contract.py` (содержимое WebP), `assert_variants` вместо `assert_one_thumbnail`, `images.py` (`jpeg_scan_bomb`, полосы, `jpeg_with_metadata`).
Проверка: `make lint`; `jpeg_scan_bomb()` проходит загрузку по HTTP (202) на стенде.
- [ ] 10.2 Hook `student-tests/fault_hook.py` по решению 14: все новые действия и режимы, `peek-job` и `publish-job` — через одноразовый контейнер relay, `delete-row` с аудитом, `job` — ещё `attempt_base`, `updated_at`; docstring; ключи и пароль hook не получает и не печатает.
Проверка: hook отказывается работать с проектом рабочего стенда; поведение — тесты 10.5 и 10.6.
- [ ] 10.3 Стенд отказов по решению 15: `failures.compose.yml`, `run_failures.py`: relay в запуске, `FAULT_RELAY_*`, новые `FAULT_WORKER_*`, журнал relay при падении, уборка дополнительных контейнеров; docstring.
Проверка: `make failure_checks FAULT_ARGS='-k health'` — код 0, строка relay в выводе, стенд и volumes удалены; `-k no_such_test` — ненулевой код, журналы напечатаны, стенд удалён.
- [ ] 10.4 Новые тесты обычного набора по таблице «Покрытие сценариев»: `test_crop_*`, `test_optimized_*`, `test_download_crop_optimized`; `test_attachment_becomes_ready`, `test_thumbnail_format_variants`; маркеры `spec` дословно по сценариям дельт.
Проверка: `uv run pytest student-tests/test_attachment_processing.py` с `BASE_URL` стенда; настоящие размеры, байты, SHA-256 и `size_bytes` сверены с метаданными.
- [ ] 10.5 Прежние проверки отказов по решению 15 и дельтам: перечисленные там тесты меняют ожидания (202 без брокера, аренда вместо немедленного взятия, три варианта, ожидание сообщения опросом); проверки не ослабляются и не пропускаются.
Проверка: `make failure_checks FAULT_ARGS='-k "attachment or broker or worker or cleaner or reconcile or upload or defense"'` — код 0.
- [ ] 10.6 Новые проверки отказов по таблице «Покрытие сценариев», `test_worker_stop_during_render` (спек `graceful-shutdown` в докстринге) и `test_defense_faults` — шаг 4 защиты тем же порядком, что `driver.py defense-faults` (спек `student-tests` в докстринге). Отказы — в `with outage(...)`, worker и relay запускаются в `finally`, триггеры снимаются в `finally`.
Проверка: полный `make failure_checks` — код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у контейнеров рабочего стенда прежний `StartedAt`; число проверок и время — «Уточнения apply».
- [ ] 10.7 `make test_isolated` по решению 13: `run_isolated.py` — контейнер `<проект>-test-relay` с той же подменой базы, журналы, уборка.
Проверка: `make test_isolated` при работающем стенде — код 0; после него нет контейнеров, базы, объектов и очереди временной базы, у рабочего стенда прежний `StartedAt`; прерывание Ctrl+C — уборка выполнена.
- [ ] 10.8 Сверка покрытия: `job-outbox` в `CAPABILITIES`, расширение исключения `data-storage`; sync всех дельт в основные спеки (`/opsx:sync`): сверка читает только `openspec/specs/`.
Проверка: `openspec validate --specs`; `make student_test` — сверка без «no test and no exclusion» и «unknown scenario», красное только `missing_evidence`; итог называет число сценариев проверок отказов.
- [ ] 10.9 Тесты ловят нарушение: временные регрессии, каждая откатывается и не попадает в рабочее дерево:
- отметка `published_at` до подтверждения → `test_relay_killed_after_confirm` или `test_upload_with_broker_paused` красный;
- claim берёт задание при живой аренде → `test_duplicate_during_processing` красный;
- фиксация без проверки номера попытки → `test_hung_worker_lease_fencing` красный;
- ack до фиксации → `test_crash_after_objects_before_commit` красный;
- claim без проверки завершённого → `test_crash_after_commit_before_ack` красный;
- replay без проверки состояния → `test_replay_ready_refused` красный;
- очистка без условия статуса → `test_staging_keeps_current_work` красный;
- `FOR UPDATE` вместо `FOR NO KEY UPDATE` в очистке → `test_staging_cleanup_survives_outage` красный: сообщение ждёт DELETE в S3;
- рендер в процессе worker без лимита CPU → `test_limit_cpu_scan_bomb` красный;
- фиксированная пауза вместо jitter → `test_retry_backoff_with_jitter` красный.
Проверка: итог по каждой регрессии — в design, «Уточнения apply»; хэши `src` после откатов совпадают со снимком до них.
## 11. `bench/`
- [ ] 11.1 Стенд по решению 16: `bench.compose.yml` (`relay`, лимиты, реплики без окружения брокера), `bench.env`, `compose_env`, поля `Profile`; паспорт: метка `com.docker.compose.image`, при её отсутствии — `.Image`, в `app_containers` и `image()`; сравнение реплик профиля замены по ней.
Проверка: `uv run python bench/uploads.py --selftest`; `make bench_quick` — код 0, брокер, relay и worker не запущены, `stand.app_env` без секретов и без `BROKER__*`.
- [ ] 11.2 Профиль загрузок по решению 16: без брокера, `uploads.py` и сводка.
Проверка: `make bench_uploads_quick` — код 0, успешные загрузки — 202, брокера нет в паспорте, пик памяти реплики и 429 — в тех же границах, что у прежних сценариев спека.
- [ ] 11.3 `Profile.rollout_from` → `7f38948`, профиль сверки по решению 16; `make bench_rollout_quick`, `make bench_reconcile_quick`.
Проверка: обе — код 0; у замены ревизия до и после — новые две ревизии; реплики на одном образе по метке; у сверки сверка моделей сошлась. Метки `quick-*` в git не идут.
## 12. Драйвер скилла `run-mtusi-messenger`
- [ ] 12.1 Прежние команды по решению 17: `start` поднимает ещё relay, `defense-scenario`, `broker-check`, `worker-process`, `attachment-storage` (пустой `staging_key`, проба аудита), `s3-check`, `upload-consistency`, `reconcile-*` — по изменениям.
Проверка: каждая из этих команд на рабочем стенде — код 0; `driver.py lb-upload-timeouts` — код 0; `ruff format --check` драйвера.
- [ ] 12.2 Новые команды по решению 17: `defense-faults`, `relay-process`, `pipeline-state`; раздел в `SKILL.md`: шаги, что проверяется, коды выхода, gotchas.
Проверка:
- `defense-faults` на рабочем стенде — код 0, вывод по каждому окну, токенов и секретов нет, триггеров после прогона нет;
- прерывание сигналом посреди сценария — worker и relay запущены, триггеров нет, код ненулевой;
- `relay-process`, `pipeline-state` — код 0, JSON разбирается.
## 13. Правила и карта кода
- [ ] 13.1 Правила по решениям:
- `.claude/rules/worker.md`: `paths` — ещё `src/relay/**`, `src/worker/render.py`, `src/infra/render/**`, сервисы relay и replay, `image_variants.py`; claim, аренда, fencing, бюджет, лимиты, варианты, relay, replay; строка в `AGENTS.md`;
- `service-layer.md`, `repo-layer.md`, `dto.md`, `infra.md` (`broker/` без `instance.py`, `render/`), `migrations.md` (две ревизии), `logging.md`, `settings.md`, `run-modes.md` (relay), `docker.md` (relay, секреты, порядок), `balancer.md` (26 с и 73 с, порядок обновления), `student-tests.md` (hook, окна, время прогона), `bench.md` (профиль загрузок, `rollout_from`, паспорт), `api-contract.md` (503, варианты).
Проверка: `grep -rn "retry_delay_seconds\|_publish_job\|delete_unstarted\|thumbnail.py" .claude AGENTS.md src student-tests bench` — только верные упоминания; `make lint`.
- [ ] 13.2 `AGENTS.md`: текущий статус, правила лабы 5, таблица важных файлов и команд, карта кода (`src/relay/`, `src/infra/render/`, `src/worker/render.py`, новые сервисы и repo). `KNOWN_ISSUES.md`: удалить «Разрыв COMMIT и publish» и «`content_type`». `QUESTIONS.md`: решения, принятые в apply. Замечания S5, S6, W2 и пункты «Предложения на потом» отметить закрытыми. Граф кода: `graphify update .`.
Проверка: каждый новый файл `git status` назван в карте кода или таблице; `make lint`, `make check`.
## 14. Регресс на рабочем дереве
- [ ] 14.1 Смесь версий и откат по Migration Plan на рабочем стенде: `make rolling_update COMMIT=7f38948 MIGRATE=0`, затем вперёд по порядку плана.
Проверка: на прежнем образе сообщения, история и загрузка работают, строки нового кода читаются; после возврата `lb_stats` без ручных состояний, новые вложения — три варианта, вложение прежнего образа — `ready` с одним thumbnail, `variant=crop` — 404; сверка без расхождений по нему.
- [ ] 14.2 Рабочий стенд:
- `make test` — `PASS: lab5`, `make validate`, `make check`;
- `make student_test` через LB — красное только `missing_evidence`;
- `make run_dev` с `make run_relay`, `make run_worker` и `EXPECT_REPLICAS=1 make student_test` — те же итоги, кроме тестов реплик;
- `make test_isolated`, полный `make failure_checks`;
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh`;
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` дважды (`stop`, `STOP_MODE=kill`) с `make replicas` между ними;
- `make s3_check`, `make reconcile` — код 0;
- `driver.py --port <LB> defense-scenario`, `defense-faults`;
- `make wipe_data` не выполнять.
- [ ] 14.3 Регресс `bench/`: `make bench_quick`, `make bench_failover_quick`, `make bench_rollout_quick`, `make bench_restore_quick`, `make bench_uploads_quick`, `make bench_reconcile_quick` — код 0.
- [ ] 14.4 Сборка из чистого дерева: команда `git ls-files -z -co --exclude-standard | tar …` из `docker.md`; в образе импорт Pillow с WebP, версии как в `uv.lock`, `uv` и компиляторов нет. `make lint`, `openspec validate pipeline-reliability --strict`, `openspec validate --specs`.
- [ ] 14.5 Отчёт apply для основной сессии: `git status`, `git diff --stat`, предложенное сообщение коммита, созданные пробами volumes, что осталось красным и почему. Агент останавливается здесь: коммит и группу 15 выполняет основная сессия.
## 15. Evidence и отчёт (после коммита, основная сессия)
Снимать на закоммиченном коде: рабочий стенд собран из `HEAD` (`make run_docker`), рабочее дерево чистое, в шапке каждого файла команда, дата, commit и стенд. Без токенов, паролей, ключей и секретов. Новые файлы `evidence/` на время замеров `bench/` выносить из дерева, чтобы паспорта не получили ложный `dirty: true` (design архива `async-attachments`, «Уточнения apply», п. 17).
- [ ] 15.1 Коммит кода групп 1–14 на ветке `feat/pipeline-reliability`, стенд на этом commit: `make run_docker`, `make replicas`.
Проверка: `git status` чист; `docker compose ps` — как в задаче 9.6; `make test` — `PASS: lab5`.
- [ ] 15.2 Защита и стенд:
- `evidence/attachments/defense-faults.md` — `driver.py --port <LB> defense-faults`;
- `evidence/attachments/defense.md` — `driver.py --port <LB> defense-scenario`;
- `evidence/relay/process.md` — `driver.py --port <LB> relay-process`;
- `evidence/worker/process.md` — `driver.py --port <LB> worker-process`;
- `evidence/broker/stand.md`, `evidence/broker/isolated.md` — как на уровне 3;
- `evidence/attachments/storage.md`, `evidence/attachments/failover.md`, `evidence/attachments/consistency.md`, `evidence/replicas/test-persistence.md` — команды уровня 3 заново.
Проверка: `test_exclusion_evidence_exists` называет только файлы старых исключений последнего шага прогона.
- [ ] 15.3 Журнал, ключи, схема:
- `evidence/worker/logs.md`, `evidence/relay/logs.md` — журнал готового и `failed` вложения одного `request_id`, проход relay, replay с отказом; `filename` и секретов нет;
- `evidence/s3/cleaner-staging.md` — `make s3_check` и строки списка staging;
- `evidence/migrations/pipeline-reliability.md` — проба задач 2.2–2.3 и откат с возвратом задачи 14.1;
- `evidence/uploads/lb-timeouts.md` — `driver.py lb-upload-timeouts`.
Проверка: `grep` значений секретов из `.env` по `evidence/` пуст (значения не печатаются).
- [ ] 15.4 Прогоны наборов на этом commit: `evidence/tests/student-test-lb.md`, `evidence/tests/test-isolated.md`, `evidence/tests/failure-checks.md` (полный `make failure_checks`, число проверок и время, красные прогоны задачи 10.9), `evidence/failover/test-failover.md`; метка `make bench_rollout ROLLOUT_LABEL=pipeline-reliability`.
Проверка: числа в файлах совпадают с выводом команд; красное только `missing_evidence` по файлам последнего шага прогона.
- [ ] 15.5 `REPORT.md`, разделы уровня 4 (отчёт уровня 3 остаётся верным, то, что было ограничением и закрыто, обновлено):
- состояние отчёта и commit: строки таблицы уровня 3, снятые заново, называют новый commit, а метка `evidence/uploads/baseline` остаётся со своим `ff1a83b`; архитектура стенда с relay, таблица ролей и сумма лимитов, расчёт соединений PostgreSQL; запуск с `make run_relay`; `STAGING_RETENTION_SECONDS` и новые настройки;
- таблица критериев уровня 4 с командой, наблюдением и файлом — по каждому пункту рубрики;
- параметры вариантов (`quality`, `method`, отсутствие EXIF и ICC); лимиты обработки и бюджет памяти контейнера worker с числами из задачи 9.6;
- окна отказа после изменения (решение 1), отказ брокера: 202, а не 503; зависимости `/health/ready` с relay;
- ответы на вопросы защиты: confirm и ack, что сохранено к 202, повторная доставка и ключ идемпотентности, зависший и долго работающий worker: аренда и fencing; шаг 4 сценария защиты и ссылка на `evidence/attachments/defense-faults.md`;
- ограничения: отказ S3 дольше бюджета и replay, восстановление после KILL по аренде, дубли сообщений, объект, дописанный прежней попыткой теми же байтами, профиль ICC, лимит памяти на macOS, цена процесса на задание, сверка не проверяет объекты вариантов, удаление очереди при работающем worker, старые `ready` без `crop` и `optimized`, цепочка LB 73 с с формулой;
- смесь версий и порядок обновления (Migration Plan);
- вопросы преподавателю: из `QUESTIONS.md`, `## pipeline-reliability`, а №4 и №5 раздела — с отметкой, как закрыты этим уровнем; раздел «Что остаётся открытым на уровне 3» и «Следующие шаги» обновить.
Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; `make lint`, `make check`, `openspec validate pipeline-reliability --strict`.
- [ ] 15.6 Коммит evidence и `REPORT.md` основной сессией. Проверка: `git status` чист; `git log -2` — commit кода назван в шапках файлов evidence.