12 KiB
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 без увеличения,quality80, без 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 на маленьком файле, проба).