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

12 KiB
Raw Blame History

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 на маленьком файле, проба).