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