125 lines
10 KiB
Markdown
125 lines
10 KiB
Markdown
# Proposal
|
||
|
||
## Why
|
||
|
||
Лаба 5, уровень «3» (`README.md`, `COURSE.md`, переход 4 → 5): приём файла и
|
||
тяжёлая обработка разделяются. Сейчас `POST …/attachments` отвечает `201
|
||
ready` после записи оригинала в конечный ключ S3, обработки изображений и
|
||
брокера в стенде нет, публичный smoke лабы 5 падает уже на коде ответа. Это
|
||
первое из трёх изменений пути к оценке 5: `async-attachments` (3), затем
|
||
`pipeline-reliability` (4), `track1-queue-overload` (5).
|
||
|
||
## What Changes
|
||
|
||
- **BREAKING (объявленный переход контракта):** загрузка отвечает `202
|
||
Attachment` со снимком `status=queued`, а не `201 ready`. Ответ 202 — только
|
||
после оригинала в устойчивом staging (приватный префикс S3), фиксации
|
||
вложения вместе с заданием в PostgreSQL и подтверждения брокера. Брокер
|
||
недоступен — 503, задания не остаётся, текст и чтение работают.
|
||
- **Состояния в API:** `queued`, `processing`, `ready`, `failed`. Внутренний
|
||
`pending` наружу не виден. Скачивание не готового вложения — 409, отсутствующий
|
||
вариант готового — 404. В сообщение можно положить `queued` и `processing`,
|
||
`failed` — 409; повтор уже отправленного сообщения с тем же ключом — по-прежнему
|
||
201.
|
||
- **Брокер:** RabbitMQ 4 с volume в общем стенде, образ закреплён тегом и digest,
|
||
durable-очередь на каждое имя базы, persistent-сообщения, publisher confirms.
|
||
В сообщении только ID и служебные поля по `contracts/jobs.schema.json`.
|
||
- **Worker:** отдельная точка входа и сервис compose на образе API, свой пользователь
|
||
S3 (чтение и запись объектов, без удаления и списка), ограниченная конкуренция,
|
||
лимиты контейнера, остановка по SIGTERM в срок. Берёт метаданные только из БД,
|
||
проверяет размер и SHA-256 staging, публикует оригинал в конечный префикс и создаёт
|
||
thumbnail 256×256 JPEG (EXIF orientation, alpha на белый, округление вниз, минимум
|
||
1 px). Ack — после устойчивого эффекта.
|
||
- **Повторы:** ограниченный retry (`[worker] max_attempts`, 5) с фиксированной паузой,
|
||
финальный `failed` с безопасным `error_code`; постоянные ошибки — сразу. Повтор job не
|
||
создаёт второго набора вариантов: ключ эффекта `(attachment_id, pipeline_version,
|
||
variant)`. Повторная доставка готовой работы — no-op с ack.
|
||
- **Схема только расширяется:** таблицы `attachment_jobs` и `attachment_variants`,
|
||
колонки `attachments.staging_key` и `error_code`, более широкий CHECK статуса.
|
||
Колонки `published_at`, `next_attempt_at`, `lease_expires_at` и значения вариантов
|
||
`crop` и `optimized` есть сразу: следующее изменение добавляет механизмы без
|
||
переделки контракта данных.
|
||
- **Существующие механизмы:** уборщик по-прежнему убирает только `pending`, но по
|
||
ключу staging; сверка не видит staging, не трогает работу в обработке и не помечает
|
||
её потерянной, а объекты вариантов считает своими.
|
||
- **Демонстрация защиты автоматизирована:** проверкой отказа и командой драйвера с
|
||
записью в `evidence/`.
|
||
- **Инфраструктура и инструменты:** `docker-compose.yml`, `infra/rabbitmq/`,
|
||
`scripts/restart.sh`, стенд отказов, `make test_isolated`, `bench/`, CI,
|
||
`make env_setup`, `.env.example` с сопоставлением имён skeleton, драйвер скилла.
|
||
|
||
**Не входит** (следующие изменения): transactional outbox и внедрённый crash между
|
||
COMMIT и publish, backoff с jitter, DLQ и replay, lease зависшего `processing`, crop и
|
||
WebP, очистка staging после фиксации и по retention, замеры перегрузки. Разрыв COMMIT и
|
||
publish на этом уровне открыт и назван честно: если процесс API умер между фиксацией
|
||
задания и подтверждением брокера, клиент 202 не получил, а строка `queued` без сообщения
|
||
ждёт `pipeline-reliability` (design, решение 3).
|
||
|
||
Не меняются: `contracts/`, `tests/`, `README.md`, `COURSE.md`, `lab.json`,
|
||
`CONTRIBUTING.md`, `MAINTAINERS.md`.
|
||
|
||
Шаг оператора не нужен: `make env_setup` сам допишет в существующий `.env` секреты брокера
|
||
и ключи worker.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `attachment-processing`: фоновая обработка вложения: состояния и переходы, задание,
|
||
сообщение брокера, доставка at least once, публикация оригинала, thumbnail,
|
||
идемпотентный эффект, ограниченные повторы, коды ошибок, worker и сохранность принятой
|
||
работы.
|
||
- `message-broker`: брокер в стенде: закрепление, volume и пределы, durable-очередь,
|
||
подтверждение публикации, сохранность при рестарте, клиент в приложении.
|
||
|
||
### Modified Capabilities
|
||
|
||
- `attachments`: 202 и `queued`, порядок записи со staging, заданием и подтверждением
|
||
брокера, 409 и 404 скачивания, варианты, метаданные, ключи объектов.
|
||
- `messages`: `attachment_ids` — `queued` и `processing` можно, `failed` — 409.
|
||
- `idempotency`: повтор отправленного сообщения, когда его вложение уже `failed`.
|
||
- `health`: брокер и worker в готовность не входят.
|
||
- `data-storage`: задания и варианты в PostgreSQL, новые ограничения БД.
|
||
- `db-migrations`: новые статусы — ослабление ограничения; старый образ на новой схеме.
|
||
- `storage-consistency`: уборка по ключу staging, текущая работа не тронута; сверка и
|
||
объекты вариантов.
|
||
- `object-storage`: пользователь worker в bootstrap, его права, проверки, ключи роли.
|
||
- `container-run`: брокер и worker в стенде, порты, лимиты, секреты, рестарт.
|
||
- `container-image`: worker на образе API.
|
||
- `graceful-shutdown`: остановка worker.
|
||
- `service-configuration`: секции `[broker]` и `[worker]`, секреты брокера и ключи worker,
|
||
консоль и docker.
|
||
- `service-logging`: журнал worker и отказов публикации, запрет пароля брокера.
|
||
- `student-tests`: ожидание `ready` в тестах, сверка покрытия новых capability, worker и
|
||
очередь в `make test_isolated`, брокер и worker на стенде отказов, действия hook,
|
||
сценарий защиты.
|
||
- `load-balancing`: цепочка сроков пути загрузки с публикацией.
|
||
- `load-benchmark`: брокер в профиле загрузок, код успеха варианта.
|
||
|
||
## Impact
|
||
|
||
- **API:** `POST …/attachments` — 202; `GET …/attachments/{id}` — четыре статуса,
|
||
`variants`, `error_code`; `GET …/content?variant=` — `original` и `thumbnail`, 409 и 404;
|
||
`POST …/messages` — 409 на `failed`. Ломается всё, что ждало 201: собственные тесты,
|
||
драйвер, `bench/k6/uploads.js`.
|
||
- **Код:** `src/worker/` (новый), `src/core/services/attachment.py`, `message.py`,
|
||
`attachment_cleanup.py`, `attachment_reconcile.py`, новый сервис обработки, repo заданий и
|
||
вариантов, `attachment_object.py`, `src/infra/broker/` (новый), `src/utils/thumbnail.py`
|
||
(новый), `src/config/settings.py`, `src/api/routers/v1/attachment.py`, `src/api/schemas/`,
|
||
`src/api/errors.py`, `src/main.py`, `src/infra/logger.py`, `src/infra/early_stop.py`,
|
||
миграция.
|
||
- **Зависимости:** `aio-pika` (новая), `pillow` — из dev-группы в основную, `uv.lock`.
|
||
- **Стенд:** `docker-compose.yml`, `infra/rabbitmq/rabbitmq.conf`, `infra/s3/bootstrap.sh`,
|
||
`.env.example`, `config_example.toml`, `Makefile`, `scripts/restart.sh`,
|
||
`.github/ci/compose.yml`, `.github/ci/stand-env.sh`; шаги `.github/workflows/application.yml`
|
||
те же: стенд поднимает `make run_docker`.
|
||
- **Тесты и инструменты:** `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`,
|
||
`k6/uploads.js`, `uploads.py`), `.claude/skills/run-mtusi-messenger/`.
|
||
- **Документы:** правила `.claude/rules/`, карта кода `AGENTS.md`, `KNOWN_ISSUES.md`,
|
||
`REPORT.md`, `QUESTIONS.md`, evidence.
|
||
- **Ресурсы стенда:** плюс RabbitMQ 1 CPU / 512 МБ и worker 1 CPU / 1 ГБ; соединений
|
||
PostgreSQL плюс два; на время уровня 3 оригинал лежит в S3 дважды (staging и конечный
|
||
префикс) до очистки в `pipeline-reliability`.
|