Files
mtusi2026lab5/openspec/changes/pipeline-reliability/proposal.md
T
2026-10-31 10:08:03 +03:00

130 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 на маленьком файле, проба).