Upload answers 202 after staging, a queued job in PostgreSQL and a broker confirm; a separate worker publishes the original and a thumbnail with bounded retries. Adds the job and variant tables, the broker service, the worker S3 user, cleanup and reconcile support for staging and variants, the failure stand with broker and worker, bench and driver updates. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
602 lines
84 KiB
Markdown
602 lines
84 KiB
Markdown
# Design
|
||
|
||
## Context
|
||
|
||
Мотивация — `proposal.md`, раздел Why. Требования — `specs/`. Контракт —
|
||
`contracts/README.md` («Фоновая обработка (с lab5)»),
|
||
`contracts/attachment-states.md`, `contracts/jobs.schema.json`,
|
||
`contracts/openapi.json`, рубрика — `README.md`, уровень «3».
|
||
|
||
### Код
|
||
|
||
Состояние — перенос лабы 4 (`04f8592`) с правкой меток стенда (`cc33a03`):
|
||
- `AttachmentService.upload` (`src/core/services/attachment.py`): проверки →
|
||
место загрузки → тело → структура и SHA-256 → строка `pending` с `object_key`
|
||
(tx1) → PUT в конечный ключ → `mark_ready` с компенсацией (tx2) → 201;
|
||
- `attachments`: `status` — `pending` или `ready` (CHECK), `object_key` уникален,
|
||
`lost_at`. Прочитав неизвестный статус, `_to_dto` падает с `ValueError`;
|
||
- `AttachmentCleanupService` убирает `pending` старше grace, удаляет `object_key`;
|
||
- `AttachmentReconcileService` читает только `<база>/attachments/`, строки не `ready`
|
||
не проверяет (`_row_with_object`), а ключ не вида `<id>/original` без строки
|
||
считает чужим объектом: код 3 на каждом проходе;
|
||
- `MessageService._require_ready_attachments` — проверка до захвата ключа;
|
||
- Pillow только в dev-группе, брокера и worker нет.
|
||
|
||
### Пробы (2026-10-31, scratchpad, проект compose `asyncprobe`)
|
||
|
||
Стенд пробы: `rabbitmq:4.3.7` с лимитом 1 CPU / 512 МБ, volume, порт на loopback;
|
||
клиент — `aio-pika 10.2.1` на хосте; Pillow 13.0.0 в `python:3.12.14-slim-trixie` с
|
||
лимитом 1 CPU и `MALLOC_MMAP_THRESHOLD_` образа. Рабочий стенд не затронут. После
|
||
проб контейнер и сеть удалены; volume `asyncprobe_rabbitmq_data` оставлен: удаление
|
||
проекта вместе с volume запретил автоматический классификатор прав. Удалить его можно
|
||
вручную: `docker volume rm asyncprobe_rabbitmq_data`.
|
||
|
||
| Проверка | Результат |
|
||
|---|---|
|
||
| Индекс образа `rabbitmq:4.3.7` | `sha256:bd88985187aa73cd598fa0d8b31d49b2f814a6d9e58f6d5a89bae588669d946a`, amd64 и arm64; `Config.Volumes` — `/var/lib/rabbitmq`; процесс — UID 999 |
|
||
| Старт на пустом volume до `healthy` (`check_port_connectivity`) | 5 с, после SIGKILL — 4 с; 134–157 МиБ в простое, 147 МиБ при 3000 сообщениях в очереди; проверка ~0,6 с |
|
||
| Предел памяти по умолчанию при лимите контейнера 512 МБ | **4760 МиБ из 7933 МиБ ВМ: лимит cgroup брокер не видит**, контейнер убило бы ядро раньше сигнала брокера. `vm_memory_high_watermark.absolute = 400MiB` в `conf.d` применяется |
|
||
| `log.console.use_colors` в `conf.d` | брокер не стартует (`transform_datatypes`): настройки этого файла проверять запуском |
|
||
| Публикация с подтверждением, durable, persistent | 4 потока: p50 0,8 мс, p99 1,5 мс; одиночные: p50 4,6 мс, max 6,9 мс |
|
||
| 200 подтверждённых, сразу `docker kill`, старт | 200 в очереди |
|
||
| `docker compose stop` | 1,4 с, код 0 |
|
||
| `up --force-recreate` при `hostname: rabbitmq` и том же volume | 200 в очереди: имя узла постоянно, каталог данных тот же |
|
||
| `redelivered` | сообщение без ack после смерти потребителя — true; после SIGKILL брокера — true у **всех**, даже недоставленных: завышение, но не занижение |
|
||
| Нет маршрута при `mandatory` | `PublishError` (подкласс `DeliveryError`) за 0,6 мс, канал жив |
|
||
| Живое соединение, `docker stop` брокера | следующие публикации сразу `ChannelInvalidStateError`, при этом `connection.is_closed` — false: признак «соединение закрыто» верить нельзя |
|
||
| Новое соединение: брокер остановлен / заморожен | `AMQPConnectionError` за 1 мс / `TimeoutError` по сроку 2 с |
|
||
| Живое соединение, `docker pause` | `TimeoutError` за 2 с. **Сообщения, опубликованные во время заморозки, после `unpause` оказались в очереди**: исход публикации по сроку неизвестен |
|
||
| Quorum-очередь | p50 1,3 мс; nack с requeue 40 раз подряд — сообщение на месте |
|
||
| `rabbitmqctl -q list_queues … --formatter json`, `delete_queue` | работают внутри контейнера: состояние очереди и уборка без management API |
|
||
| Лок с `aio-pika>=10.2.1,<11` и `pillow>=13,<14` в основной группе | `uv add` на копии проекта проходит: aio-pika 10.2.1, aiormq 7.2.4, pamqp 4.0.1, Pillow 13.0.0 (колёса amd64 и arm64) |
|
||
| `Image.thumbnail((256, 256))` | **округляет к ближайшей пропорции**: 1000 × 601 → 256 × 154, 3000 × 1999 → 256 × 171, контракт требует вниз (153, 170) |
|
||
| EXIF orientation 1–8, eXIf в PNG, tRNS палитры, LA, серый 16 бит, CMYK, прогрессивный, Adam7, 1 бит | своё вычисление размера, resize и transpose дают верные размеры и пиксели, сверка с `ImageOps.exif_transpose` |
|
||
| Пик RSS на 40 Мпкс (8000 × 5000), один процесс | PNG RGBA 323 МиБ, RGBA 16 бит 324, палитра с tRNS 323, RGB 170, серый 16 бит 207, 1 бит 92; JPEG с `draft`: baseline 20, CMYK 23, прогрессивный 134 |
|
||
| Проходит `inspect_image`, не декодируется Pillow | JPEG с точностью SOF 12 и 7 — `UnidentifiedImageError` при открытии; SOF3, SOF5, SOF11 — `OSError`. Искажённые байты скана и SOF9 декодируются в мусор без ошибки: такое вложение станет `ready` |
|
||
|
||
### Что найдено до решений
|
||
|
||
1. **Лимит памяти брокера и имя узла** — таблица: без явного предела и постоянного
|
||
`hostname` стенд выглядит рабочим, а теряет данные при `up --force-recreate` и
|
||
уходит в OOM под нагрузкой.
|
||
2. **Повтор сообщения и `failed`.** Контракт разом требует «failed прикреплять нельзя
|
||
(409)» и «повтор с тем же ключом — тот же 201». Сегодняшний порядок («вложения, затем
|
||
ключ») дал бы 409 на повтор сообщения, чьё вложение стало `failed` после отправки.
|
||
3. **Смешанные версии.** Реплика лабы 4 падает с 500 на чтении строки в новом статусе:
|
||
`AttachmentStatus(...)` — `ValueError`. Переход 201 → 202 всё равно ломает контракт
|
||
для клиента на время замены, и это ограничение называется, а не лечится.
|
||
4. **Объекты вариантов под `<база>/attachments/`** сверка без правки считала бы чужими:
|
||
код 3 навсегда (решение 11).
|
||
5. **Сценарий нельзя переименовать правкой дельты.** `openspec validate --strict`
|
||
отказывает MODIFIED, которая теряет сценарий основного спека. Поэтому «Фиксация
|
||
ready не удалась» осталась и теперь про фиксацию worker, а фиксацию API описывает
|
||
новый сценарий «Фиксация задания не удалась».
|
||
6. **Цепочка сроков LB:** прежняя сумма 26 с после тела с новым шагом должна остаться
|
||
меньше `timeout server` 30 с, иначе растут и он, и срок дренажа (решение 3).
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
|
||
- Уровень «3» рубрики и сценарий защиты, шаги 1–3, с доказательствами.
|
||
- Схема и ключи, на которые `pipeline-reliability` и `track1-queue-overload` кладут
|
||
механизмы без переделки контракта данных (таблица в решении 1).
|
||
- Прежние механизмы лабы 4 не ломаются: компенсация, уборщик, сверка, места загрузки,
|
||
лимиты, цепочка таймаутов.
|
||
|
||
**Non-Goals** (следующие изменения, сознательно):
|
||
|
||
- transactional outbox, relay и внедрённый crash COMMIT/publish;
|
||
- backoff с jitter, различие временных и постоянных ошибок сверх минимума уровня 3;
|
||
- DLQ и replay, переход `failed → queued`;
|
||
- lease и восстановление зависшего `processing`, кроме повторной доставки брокером;
|
||
- crop и WebP, ограничение времени декодирования;
|
||
- очистка staging после фиксации и по retention;
|
||
- сверка объектов вариантов и staging;
|
||
- отдельная настройка prefetch и замеры перегрузки;
|
||
- разделение прав пользователей брокера и trace context в сообщении (лабы 7 и 6).
|
||
|
||
## Decisions
|
||
|
||
### 1. Схема данных и ключ идемпотентности
|
||
|
||
Одна ревизия, только расширение (`migrations.md`), первой строкой `SET LOCAL
|
||
lock_timeout = '2s'`.
|
||
|
||
**`attachments`** — новые колонки и ограничения:
|
||
|
||
| Что | Тип | Смысл |
|
||
|---|---|---|
|
||
| `staging_key` | `text NULL` | ключ объекта в staging. NULL — строка прежней версии; с `pipeline-reliability` — staging уже убран |
|
||
| `error_code` | `text NULL` | код `failed` в API |
|
||
| CHECK `status` | `pending, queued, processing, ready, failed` | замена ослабленным, `NOT VALID` в той же транзакции, как `ck_messages_text_length` |
|
||
| CHECK `error_code_failed` | `(status = 'failed') = (error_code IS NOT NULL)` | `NOT VALID`: прежние строки ему удовлетворяют, прежняя версия колонку не пишет |
|
||
|
||
`object_key` остаётся конечным ключом оригинала и назначается при вставке: для новых
|
||
строк объекта там сначала нет. Конечное место одно и известно заранее, а уникальность и
|
||
логика сверки не меняются.
|
||
|
||
**`attachment_jobs`** — логическая работа; она же будущий outbox и реестр `failed`:
|
||
|
||
| Колонка | Тип | Для чего |
|
||
|---|---|---|
|
||
| `id` | `uuid` PK | `job_id` контракта, при повторах не меняется |
|
||
| `attachment_id` | `uuid` FK → `attachments`, без каскада | |
|
||
| `pipeline_version` | `integer`, CHECK ≥ 1 | сейчас 1 (`ATTACHMENT_PIPELINE_VERSION`) |
|
||
| `state` | `text`, CHECK `queued, processing, succeeded, failed` | |
|
||
| `attempt` | `integer NOT NULL DEFAULT 0`, CHECK ≥ 0 | начатые попытки, источник истины счёта |
|
||
| `last_error_code` | `text NULL` | причина без секретов: `source_missing`, `source_corrupted`, `undecodable`, `storage_unavailable`, `timeout`, `unexpected` |
|
||
| `next_attempt_at` | `timestamptz NULL` | время следующей попытки (строка таблицы состояний контракта) |
|
||
| `lease_expires_at` | `timestamptz NULL` | срок текущей попытки |
|
||
| `published_at` | `timestamptz NULL` | когда брокер подтвердил последнее сообщение; NULL — намерение не передано |
|
||
| `created_at`, `updated_at` | `timestamptz NOT NULL` | `created_at` — поле сообщения |
|
||
| `finished_at` | `timestamptz NULL` | конец работы, для времени до `ready` в треке 1 |
|
||
| UNIQUE `(attachment_id, pipeline_version)` | | одна логическая работа на эффект |
|
||
|
||
**`attachment_variants`** — эффект, ключ эффекта — первичный ключ:
|
||
|
||
| Колонка | Тип |
|
||
|---|---|
|
||
| `attachment_id` | `uuid` FK → `attachments`, без каскада |
|
||
| `pipeline_version` | `integer` |
|
||
| `variant` | `text`, CHECK `thumbnail, crop, optimized` |
|
||
| `object_key` | `text`, UNIQUE, CHECK длины |
|
||
| `content_type` | `text`, CHECK `image/jpeg, image/png, image/webp` |
|
||
| `size_bytes`, `width`, `height` | `integer`, CHECK > 0 |
|
||
| `sha256` | `bytea`, CHECK 32 байта |
|
||
| `created_at` | `timestamptz` |
|
||
| PK `(attachment_id, pipeline_version, variant)` | |
|
||
|
||
**Ключи объектов:** `<база>/staging/<id>/original`, `<база>/attachments/<id>/original`,
|
||
`<база>/attachments/<id>/v<версия>-<вариант>`. Имя варианта плоское, без лишнего уровня
|
||
каталога: hook разбирает `fs.tree` по уровням, а сверке достаточно одного выражения.
|
||
|
||
Оригинал — не строка `attachment_variants`: схема контракта `Variant` не знает имени
|
||
`original`, и у него один ключ на вложение. Идемпотентность его записи — тот же ключ при
|
||
каждом повторе, а итог — поля самого вложения.
|
||
|
||
Что следующие изменения добавляют без правки этой схемы:
|
||
|
||
| Механизм | На что ложится |
|
||
|---|---|
|
||
| Transactional outbox | `attachment_jobs` со `state = 'queued' AND published_at IS NULL` и есть outbox: строка пишется в одной транзакции с `queued`. Добавляется relay и частичный индекс `CONCURRENTLY` |
|
||
| Backoff с jitter | `next_attempt_at` считается иначе, relay публикует по сроку |
|
||
| DLQ и replay | `state = 'failed'` с `last_error_code` — реестр; replay возвращает ту же строку, эффект защищён ключом. Аудит — новая таблица |
|
||
| Lease зависшего | `lease_expires_at`, проход по `state = 'processing'` с истёкшим сроком |
|
||
| Crop и WebP | новые строки вариантов: значения и типы CHECK уже допускают, API уже отдаёт их по `variant` |
|
||
| Очистка staging | `staging_key IS NOT NULL` у `ready` и старых `failed`; права удаления уже у уборщика; после удаления — `staging_key = NULL` |
|
||
| Перегрузка | `[worker] concurrency` уже настройка; `finished_at`, `created_at` дают время до `ready` |
|
||
|
||
*Альтернатива:* состояние только в `attachments`, без таблицы заданий. Отвергнута: негде
|
||
держать попытки, `published_at` и `job_id` контракта, а outbox уровня 4 потребовал бы таблицу
|
||
и правку потока. *Альтернатива:* отдельная таблица outbox уже сейчас. Отвергнута: на уровне 3
|
||
её некому читать (решение пользователя «не входит»), а `attachment_jobs` её заменяет.
|
||
*Альтернатива:* `variants` колонкой `jsonb` в `attachments`. Отвергнута: уникальность ключа
|
||
эффекта тогда держит код, а не БД; CHECK размера и SHA-256 негде поставить.
|
||
*Альтернатива:* писать в `object_key` ключ staging и менять его при `ready`. Отвергнута: тогда
|
||
после `ready` неизвестно, где лежит staging, а правило «ключ берётся из строки» нарушается ровно для
|
||
очистки. *Альтернатива:* отдельный префикс `<база>/variants/`. Отвергнута: объект варианта без
|
||
строки никто бы не нашёл, а список у уборщика разрешён только под `attachments/`.
|
||
|
||
### 2. Состояния
|
||
|
||
`attachments.status` — то, что видит API. `attachment_jobs.state` — состояние работы; они
|
||
меняются одной транзакцией, а `pending` — только у `attachments` и наружу не виден (404).
|
||
|
||
| Переход | Кто | Транзакция | Условие |
|
||
|---|---|---|---|
|
||
| нет → `pending` | API | tx1: вставка | |
|
||
| `pending` → `queued`, + job `queued` | API | tx2 | строка не помечена уборщиком (`updated_at = created_at`) |
|
||
| `queued` → `pending`, − job | API | tx-отмена | брокер не подтвердил, job ещё `queued` и попыток не было |
|
||
| `queued` → `processing` | worker | claim: job и вложение | решение 7 |
|
||
| `processing` → `queued` | worker | повтор | своя попытка: `attempt` совпал |
|
||
| `processing` → `ready` | worker | фиксация: вложение, вариант, job | вложение не `ready`/`failed`; принимается и результат старой попытки: эффект тот же |
|
||
| `processing` → `failed` | worker | фиксация ошибки с `error_code` | своя попытка |
|
||
|
||
Откат `queued → pending` наружу не виден: клиент ещё не получил `id`. Контрактная таблица
|
||
описывает состояния после 202, а до него вложения для клиента нет.
|
||
|
||
Порядок блокировок везде один — сначала строка задания, затем вложения: иначе claim и
|
||
фиксация дублей могли бы встать друг за другом. Уборщик и сверка строк заданий не касаются:
|
||
`pending` задания не имеет, а `mark_lost` — только `ready`.
|
||
|
||
`updated_at` пишет `greatest(:now, updated_at)`: CHECK `updated_at >= created_at` иначе падал бы на
|
||
расхождении часов консольного API на macOS и worker в ВМ Docker.
|
||
|
||
### 3. Приём: что значит 202 и отказ брокера
|
||
|
||
Порядок (`AttachmentService._store`), место загрузки держится до ответа:
|
||
|
||
| Шаг | Что устойчиво после шага |
|
||
|---|---|
|
||
| проверки, тело, структура и SHA-256 | ничего |
|
||
| tx1: `pending`, `object_key`, `staging_key` | строка |
|
||
| PUT в staging тем же `BytesIO`, затем буфер закрывается | объект staging |
|
||
| tx2: `queued` и job (`attempt` 0) | **намерение обработать** |
|
||
| publish и publisher confirm | сообщение в durable-очереди |
|
||
| tx3: `published_at` | отметка; сбой — `warning`, ответ всё равно 202 |
|
||
| 202, снимок DTO из tx2 | |
|
||
|
||
**Поведение при недоступном брокере — 503 `unavailable`, а не 202.** Намерение в БД само
|
||
по себе работу не доставит: relay появится только в `pipeline-reliability`. Ответ 202 без
|
||
подтверждения при упавшем брокере обещал бы то, что никто не выполнит. Контракт требует «только
|
||
после durable handoff» — на этом уровне handoff включает confirm. API 503 на этом пути контракт
|
||
допускает. Отказ брокера при этом не трогает остальное API (решение 10).
|
||
|
||
Сбой на шаге publish — один путь на любой исход: нет соединения, срок, `nack`, нет маршрута. Срок
|
||
`[broker] publish_timeout_seconds` (2 с) покрывает соединение, канал, публикацию и confirm.
|
||
Проба показала: сообщение по сроку может дойти позже, поэтому исход считается неизвестным, и
|
||
решает условная транзакция отмены:
|
||
|
||
```
|
||
DELETE attachment_jobs WHERE id = :job AND state = 'queued' AND attempt = 0 RETURNING id
|
||
→ 0 строк: worker уже взял задание, сообщение дошло → как успех, 202
|
||
UPDATE attachments SET status = 'pending', updated_at = … WHERE id = :id AND status = 'queued'
|
||
```
|
||
|
||
`attempt = 0` нужен стенду с короткой паузой повтора: задание, которое уже вернулось в `queued` после первой попытки, тоже значит «сообщение дошло». Запоздавшее сообщение worker подтверждает без эффекта: задания нет. Объект staging после отмены
|
||
не удаляется: строка `pending` с `updated_at > created_at` уже считается помеченной, и её убирает
|
||
уборщик. Удаление здесь вывело бы молчание после тела за 30 с, а объект безвреден.
|
||
|
||
Окна отказа контракта на этом уровне:
|
||
|
||
| Окно | Что происходит | Что видит клиент |
|
||
|---|---|---|
|
||
| после staging до записи задания | `pending` и объект staging; уборщик убирает | 503 или обрыв, 202 нет |
|
||
| после COMMIT до publish (падение процесса) | **разрыв**: `queued`, job `published_at IS NULL`, сообщения нет, никто не публикует | обрыв, 202 нет |
|
||
| после publish до confirm | неизвестный исход: отмена, запоздавшее сообщение — no-op | 503 или 202 по итогу отмены |
|
||
| после confirm до tx3 или ответа | работа идёт; `published_at` NULL | обрыв; вложение станет `ready`, а клиент о нём не знает, как и в лабе 4 |
|
||
| после записи S3 до COMMIT результата | повторная доставка, те же ключи | опрос `processing` |
|
||
| после COMMIT результата до ack | повторная доставка — no-op | опрос `ready` |
|
||
|
||
**Что честно остаётся открытым.** Падение процесса API (или отказ PostgreSQL при отмене) между tx2 и
|
||
confirm оставляет вложение `queued` с заданием без подтверждения. Клиент 202 не получил, поэтому принятая
|
||
работа не теряется, но строка и объект staging висят, и `id` никому не известен. Их видно запросом
|
||
`state = 'queued' AND published_at IS NULL`. Закрывает это `pipeline-reliability`: relay публикует такие
|
||
строки, а API перестаёт зависеть от брокера при ответе (тогда 202 будет и при упавшем брокере). Внедрённого
|
||
crash в этом change нет: это предмет проверки уровня 4.
|
||
|
||
Цепочка LB: после тела `проверка ~4 + tx1 6 + PUT 5 + tx2 6 + publish 2 + tx3 или отмена 6 ≈ 29 с` < 30;
|
||
ветка компенсации после неудачной tx2 — прежние 26 с. Длительность загрузки `17 + 30 + 29 ≈ 76 с` < дренаж
|
||
90 с. Отсюда и срок публикации 2 с: на пробе подтверждение занимает единицы миллисекунд, запас в сотни раз,
|
||
а 3 с уже упёрлись бы в 30.
|
||
|
||
*Альтернатива:* 202 сразу после tx2, публикация «как получится». Отвергнута: без relay принятая работа
|
||
пропала бы молча, а это ровно то, что запрещает рубрика. *Альтернатива:* минимальный relay уже сейчас.
|
||
Отвергнута: это outbox, он вынесен в следующее изменение решением пользователя. *Альтернатива:* сначала
|
||
publish, потом COMMIT. Отвергнута: worker увидел бы задание раньше строки, а окно «сообщение есть, строки нет»
|
||
хуже нынешнего. *Альтернатива:* publish внутри транзакции tx2. Отвергнута: соединение пула и блокировка на время
|
||
ожидания брокера, срок 6 с и `idle_in_transaction`. *Альтернатива:* job в tx2, а `queued` после confirm. Отвергнута:
|
||
разрыв закрывался бы уборщиком, но worker пришлось бы принимать `pending`, состояний стало бы больше, и уровень 4 всё
|
||
равно переделал бы поток. *Альтернатива:* очистка объекта staging при отмене. Отвергнута выше.
|
||
|
||
### 4. Брокер
|
||
|
||
- **Образ:** `rabbitmq:4.3.7@sha256:bd88985187aa73cd598fa0d8b31d49b2f814a6d9e58f6d5a89bae588669d946a`. Ветка 4.4
|
||
на момент выбора — 4.4.0, вышла несколько дней назад, а 4.3 — зрелая седьмая правка той же мажорной версии, какую
|
||
выбрал пользователь.
|
||
- **Сервис `rabbitmq`:** `hostname: rabbitmq` (имя узла и каталог данных постоянны), volume `rabbitmq_data:/var/lib/rabbitmq`,
|
||
`RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`, `RABBITMQ_NODE_PORT: ${RABBITMQ_PORT}`, порт на
|
||
`127.0.0.1:${RABBITMQ_OUT_PORT:-5673}`, алиас в сети, healthcheck `rabbitmq-diagnostics -q check_port_connectivity` (`interval`
|
||
10 с, `start_interval` 1 с), `stop_grace_period: 20s`, лимиты 1 CPU / 512 МБ.
|
||
- **`infra/rabbitmq/rabbitmq.conf`** → `/etc/rabbitmq/conf.d/90-messenger.conf`, read-only длинной записью:
|
||
`vm_memory_high_watermark.absolute = 400MiB`. Срабатывание предела блокирует публикацию, API отвечает 503 по сроку: это и
|
||
есть backpressure, которую мерит трек 1.
|
||
- **Очередь:** классическая durable `<база>.attachment.process.v1`, без аргументов, default exchange, persistent-сообщения,
|
||
`mandatory`. Имя с базой — как объекты S3 и ключи кэша: `make test_isolated` не смешивается с рабочим стендом. Объявляют и
|
||
издатель, и потребитель при каждом соединении: одноразовый сервис тут не нужен, а `restart.sh`, `rolling-update.sh`, стенды
|
||
проверок и `bench/` не получают нового шага.
|
||
- **Один пользователь** на API и worker, с правами на весь vhost: разделение ролей брокера — лаба 7
|
||
(`COURSE.md`, «минимальные привилегии»). Секреты получают только `rabbitmq`, `api`, `worker`.
|
||
- **Без management-плагина:** состояние очереди — `rabbitmqctl` в контейнере, а порт метрик Prometheus 15692 образа остаётся только в
|
||
сети compose и пригодится треку 1.
|
||
|
||
*Альтернатива:* quorum-очередь. Отвергнута: на одном узле реплик нет, задержка на пробе выше, а её плюсы (at-least-once dead-lettering, счётчик
|
||
доставок) не нужны: реестр `failed` — в БД, попытки считает БД. *Альтернатива:* аргументы очереди (`x-dead-letter-exchange`, `x-max-length`) уже сейчас.
|
||
Отвергнута: они неизменяемы, и следующее изменение упёрлось бы в `PRECONDITION_FAILED`. Такие настройки на уровнях 4 и 5 ставятся политиками, у которых
|
||
этого ограничения нет. *Альтернатива:* сервис `broker-bootstrap` или `load_definitions`. Отвергнута: при импорте определений брокер не создаёт пользователя
|
||
по умолчанию, а хэш пароля в файле — второй источник секрета.
|
||
|
||
### 5. Клиент брокера
|
||
|
||
`aio-pika` (асинхронный, как всё приложение). Пакет `src/infra/broker/` по образцу `s3/`: `client.py` (фабрики и типы), `instance.py` (глобал издателя
|
||
процесса API, имя базы — namespace; импортируют только `main.py` и `dependencies.py`), новое исключение `BrokerUnavailable(ServiceUnavailable)` → 503.
|
||
|
||
- **`JobPublisher.publish(body, *, message_id)`:** соединение лениво, при первом вызове; всё под `asyncio.timeout(publish_timeout_seconds)`; канал
|
||
`publisher_confirms=True, on_return_raises=True`; объявление очереди при новом соединении. **Любая** ошибка — соединение сбрасывается и закрывается в
|
||
фоне (ответ этого не ждёт: при замороженном брокере закрытие само зависло бы), запись `warning` «Broker is unavailable» с классом ошибки, `BrokerUnavailable`.
|
||
Признак `is_closed` не используется: проба показала закрытый канал при «живом» соединении. Повторов нет: загрузку повторяет клиент.
|
||
- **`JobConsumer`:** своё соединение (издатель и потребитель не делят TCP-соединение: блокировка публикации брокером не должна останавливать ack),
|
||
`set_qos(prefetch_count=concurrency)`, ack и nack вручную. Ошибка ack (канал уже закрыт) — `info` и продолжение: сообщение вернётся, повтор безвреден.
|
||
- Адрес и пароль — отдельными аргументами из `[broker]`, строка URL с паролем не собирается. `aio_pika` и `aiormq` — на `WARNING` в `src/infra/logger.py`.
|
||
|
||
*Альтернатива:* `connect_robust`. Отвергнута: фоновый reconnect поверх ожидания подтверждения скрывает, что исход публикации неизвестен, а цикл worker и так короткий и читается целиком.
|
||
*Альтернатива:* `pika`. Отвергнута: синхронный клиент в asyncio-приложении нужен был бы в отдельном потоке.
|
||
|
||
### 6. Процесс worker
|
||
|
||
`python -m src.worker` → `src/worker/__main__.py` (ранний обработчик `early_stop.install("worker")`, запись о неверных настройках и код 2, как у уборщика, `os._exit` в конце) → `src/worker/main.py`. Свои engine, клиент S3 и клиенты брокера; глобалы API не импортируются.
|
||
|
||
Сервис compose: образ API, `entrypoint: ["python", "-m", "src.worker"]`, `restart: unless-stopped`, без портов, `healthcheck: disable: true`, окружение `<<: [*db-env, *s3-env, *broker-env]`, `DATABASE__POOL_SIZE: "2"`, ключи `S3_WORKER_*`, `depends_on`: PostgreSQL и брокер healthy, `migrate` и `s3-bootstrap` completed, `stop_grace_period: 10s`, лимиты 1 CPU / 1 ГБ.
|
||
|
||
- **Лимит памяти:** худший случай при конкуренции 2 — две задачи PNG RGBA на 40 Мпкс: по замеру пик процесса 323 МиБ на одну задачу, с клиентами и двумя телами оценка ≈ 800 МиБ < 1 ГБ. Оценку проверяет сценарий «Изображение в лимите пикселей»: столько таких загрузок, сколько заданий worker обрабатывает одновременно.
|
||
- **Цикл:** соединение, объявление очереди, потребление до сигнала или обрыва. При обрыве — `warning`, дождаться своих задач прежнего соединения (иначе своя же повторная доставка), пауза `reconnect_seconds`, новое соединение. Worker не падает, счётчик перезапусков контейнера остаётся 0.
|
||
- **Конкуренция:** `prefetch_count = concurrency`, отдельной настройки prefetch нет; появится в `track1-queue-overload`. Декодирование — `anyio.to_thread.run_sync` со своим `CapacityLimiter(concurrency)`.
|
||
- **SIGTERM:** новые сообщения не принимаются, начатые задачи ждут не дольше `graceful_shutdown_seconds`, остальные отменяются, соединения закрываются, неподтверждённое брокер вернёт в очередь, «Stopped worker», `os._exit(0)`. Поток декодирования отменить нельзя, поэтому именно `os._exit`: он укладывается в 10 с контейнера.
|
||
- **Запись в журнал:** `request_id` контекста — `job_id`: так записи одного задания связаны, как записи запроса.
|
||
- **Worker вне `rolling-update.sh`** и `restart.sh`: как уборщик, он не реплика за LB и не хранилище.
|
||
|
||
*Альтернатива:* worker в репликах API. Запрещена рубрикой и `AGENTS.md`. *Альтернатива:* процессы вместо потоков для декодирования. Отвергнута на этом уровне: нужна для жёсткого срока и лимита памяти на задание, это уровень 4 («ограничены по пикселям, времени и памяти»). *Альтернатива:* healthcheck по файлу-пульсу. Отвергнута: никто не ждёт `healthy` worker, а живость видна в журнале и по очереди.
|
||
|
||
### 7. Обработка задания
|
||
|
||
`AttachmentProcessingService.handle(message, *, redelivered) -> JobOutcome` (`ACK` или `REQUEUE`); ack и nack делает `src/worker/main.py`. Каждый шаг с БД — своя короткая транзакция через `session_scope` (фабрика процесса), как у уборщика; вызовов S3 внутри транзакций нет.
|
||
|
||
**Разбор.** Pydantic-модель контракта (`extra="forbid"`, константы `schema_version` и `type`, `attempt ≥ 1`, необязательные `traceparent` с его форматом и `tracestate` до 512 символов: их приложение на этом уровне не пишет и не читает, но принимает). Не прошло — `error` без содержимого, `reject(requeue=False)`: повтор тем же телом не поможет. На уровне 4 такие сообщения пойдут в DLQ.
|
||
|
||
**Claim** (блокировка строки задания `FOR UPDATE`):
|
||
|
||
| `state` | `redelivered` | срок попытки | Действие |
|
||
|---|---|---|---|
|
||
| строки нет | любой | — | `ACK`, `info` «unknown»: отменённое или чужое |
|
||
| `succeeded` | любой | — | проверить: вложение `ready`, вариант есть; `ACK` без записи |
|
||
| `failed` | любой | — | `ACK` |
|
||
| `queued` | любой | — | взять: `attempt + 1`, `lease_expires_at`, `processing` |
|
||
| `processing` | да | любой | прежний потребитель потерян: взять так же |
|
||
| `processing` | нет | истёк | взять так же |
|
||
| `processing` | нет | идёт | дубль при живой попытке: пауза `retry_delay_seconds`, `REQUEUE` без записи. Следующая доставка придёт с `redelivered`, а попытка к тому времени обычно закончена, и это `ACK` |
|
||
|
||
Перед взятием: `attempt ≥ max_attempts` → `failed` с `retry_exhausted`, `ACK`. Именно это ограничивает задание, которое роняет worker (OOM, SIGKILL): брокер его снова доставит, а попытка уже посчитана.
|
||
|
||
**Обработка** под `asyncio.timeout(job_timeout_seconds)`:
|
||
1. GET staging в память; нет объекта — постоянная `source_missing`; размер или SHA-256 не сходятся с `size_bytes` и `sha256` строки — постоянная `source_corrupted`. Обе дают `processing_failed` в API.
|
||
2. PUT `object_key` теми же байтами (`content_type` из строки).
|
||
3. `render_thumbnail` в потоке (решение 8); не декодируется — постоянная, `invalid_image`.
|
||
4. PUT ключа варианта.
|
||
5. Фиксация: блокировка задания → `attachments` в `ready` при статусе `queued` или `processing` (0 строк — откат, `ACK`: итог уже есть) → вставка варианта `ON CONFLICT DO NOTHING` → задание `succeeded`, `finished_at`. Commit.
|
||
6. `ACK`.
|
||
|
||
Срок на поток не распространяется: отмена дождётся конца декодирования. Его длительность ограничена лимитом контракта (не больше 0,2 с CPU на пробе с плоскими данными 40 Мпкс, шумный файл дольше), а жёсткий срок — уровень 4.
|
||
|
||
**Временная ошибка** (S3 недоступен, срок, непредвиденное исключение): при `attempt < max_attempts` транзакция: `processing → queued`, `last_error_code`, `next_attempt_at = now + retry_delay`, `published_at = NULL` (условие — своя попытка: `attempt` совпал, иначе `ACK` без записи). Затем пауза (сигнал её прерывает → `REQUEUE`), публикация с подтверждением сообщения `attempt + 1` с тем же `job_id`, `published_at`, `ACK` старого. Отказ брокера на этом шаге — `REQUEUE`: старое сообщение вернётся, а claim возьмёт `queued`. Падение между публикацией и ack даёт дубль; его разбирает таблица выше. При `attempt = max_attempts` — `failed` с `retry_exhausted`.
|
||
|
||
**Постоянная ошибка:** транзакция `failed` с кодом API и причиной в `last_error_code`, `ACK`.
|
||
|
||
**PostgreSQL недоступен** (`ServiceUnavailable` из `session_scope`) на любом шаге — записать нельзя: пауза, `REQUEUE`, попытка не считается. Следующая доставка придёт с `redelivered` и возьмёт задание. Запись в журнал на каждый отказ: не немой повтор.
|
||
|
||
Пауза в worker держит место конкуренции и неподтверждённое сообщение: при отказе S3 это естественно сдерживает расход попыток очереди. Уровень 4 заменит паузу на `next_attempt_at` и relay.
|
||
|
||
*Альтернатива:* `nack(requeue=True)` вместо новой публикации. Отвергнута: `attempt` в теле застыл бы на 1, а контракт требует «отражает управляемую попытку». *Альтернатива:* считать попытки заголовком брокера. Отвергнута: источник истины — БД, а после KILL брокера доставки завышены. *Альтернатива:* ack и дубль без проверки при `processing` без `redelivered`. Отвергнута: при редком сбое он потерял бы работу. *Альтернатива:* брать при `processing` всегда. Отвергнута: дубль при живой попытке тратил бы её номер и CPU, хотя пара строк кода этого избегает.
|
||
|
||
### 8. Thumbnail
|
||
|
||
`src/utils/thumbnail.py`, чистая функция `render_thumbnail(data) -> RenderedVariant` (байты, ширина, высота), бросает `InvalidImage`. Импортирует Pillow, поэтому импортируется только из worker: реплики API декодер в память не загружают.
|
||
|
||
1. `Image.open(BytesIO(data), formats=("PNG", "JPEG"))`; `width × height > ATTACHMENT_MAX_PIXELS` — `InvalidImage`.
|
||
2. Orientation из `getexif()` до декодирования. Размер — своим вычислением по показанным сторонам: `Image.thumbnail` округляет к ближайшей пропорции, а контракт — вниз. `w ≤ 256 и h ≤ 256` → как есть; иначе большая сторона 256, меньшая `max(1, меньшая × 256 // большая)`. Для orientation 5–8 стороны меняются местами до вычисления и обратно после.
|
||
3. JPEG: `image.draft("RGB", цель)` — масштаб DCT, пик памяти на порядок меньше.
|
||
4. Режимы: `I;16`, `I;16B`, `I` — масштаб к 8 битам `point(lambda v: v / 256)`, затем `L`; с альфой (`RGBA`, `LA`, `PA`, tRNS в `info`) — `RGBA`; `1` — `L`; `P` и `CMYK` — `RGB`. Без этого `resize` по `1` и `P` молча брал бы ближайшего соседа.
|
||
5. `resize(цель, LANCZOS, reducing_gap=2.0)`: у `RGBA` Pillow сам премультиплицирует.
|
||
6. Альфа — `alpha_composite` на белый уже на малом изображении, затем `RGB`.
|
||
7. Transpose по orientation — тоже на малом: на полном размере он удвоил бы пик памяти.
|
||
8. JPEG, `quality=85` (`THUMBNAIL_JPEG_QUALITY`), без EXIF и ICC: `save` их не переносит, а цвет у учебных данных — sRGB. При том же входе и версии Pillow результат детерминирован, поэтому повтор пишет те же байты.
|
||
|
||
Ошибки `UnidentifiedImageError`, `OSError`, `ValueError`, `SyntaxError`, `DecompressionBombError` — `InvalidImage`. Искажения данных скана JPEG libjpeg не считает ошибкой: thumbnail будет с мусором. Это граница спека `attachments` («не обнаруживает»), она называется в `REPORT.md`.
|
||
|
||
*Альтернатива:* `ImageOps.exif_transpose` до resize. Отвергнута: поворот полного изображения держит два буфера пикселей разом и поднимает пик. *Альтернатива:* pyvips. Отвергнута: системная библиотека в образе; Pillow уже в проекте и закреплён.
|
||
|
||
### 9. API
|
||
|
||
- `POST …/attachments` — `status_code=202`.
|
||
- `GET …/{id}`: `pending` — тот же 404; остальные — 200. Вариантов — из `attachment_variants` второй функцией repo только у `ready`: строка читается раньше вариантов, поэтому `ready` без них увидеть нельзя.
|
||
- `GET …/content?variant=`: `Literal["original", "thumbnail", "crop", "optimized"]`, как перечисление контракта. Порядок: 401 → 400 → доступ (404) → статус не `ready` — `AttachmentNotReady` (409 `conflict`, новая строка `DOMAIN_ERRORS`) без обращения к S3 → `original`: прежняя логика, в том числе `lost_at` → остальные: нет строки варианта — 404; объект потерян или другого размера — 500, как у оригинала.
|
||
- `Attachment` в `src/api/schemas/attachment.py`: `status` — четыре значения, `variants: list[Variant]`, `error_code: str | None`.
|
||
- `src/main.py`: версия приложения — `1.5.0` (`info.version` контракта лабы; комментарий там об этом и говорит).
|
||
|
||
**Сообщение.** `_require_ready_attachments` → проверка без `failed`: неизвестное, чужое и `pending` — 404 до ключа, как сейчас. `failed` запоминается и проверяется **после** захвата ключа: `claim_key` вернул «занят» — это повтор, и он идёт по прежней ветке (сохранённое сообщение или 409 другого тела), на текущее состояние вложения не глядя; захватили новый ключ — откат транзакции и `AttachmentFailed` (409). Откат освобождает ключ: требование «ключ фиксируется только вместе с сообщением» выполнено. Гонка «вложение стало `failed` сразу после проверки» даёт сообщение со ссылкой на `failed` — тот же итог, что и `failed` чуть позже отправки.
|
||
|
||
*Альтернатива:* проверить `failed` до ключа, а при нём отдельно прочитать ключ. Отвергнута: второй разбор срока и хэша тела рядом с `claim_key`. *Альтернатива:* 409 и на повтор. Отвергнута: контракт идемпотентности прямой и без исключений.
|
||
|
||
### 10. `/health/ready` и недоступность
|
||
|
||
В готовность входит только PostgreSQL. Брокер — как S3: путь загрузки его использует, обязательный синхронный путь без него работает, а отказ брокера иначе разом вывел бы все реплики из LB, и остановились бы текст и история. Worker к синхронному пути не относится вовсе. API без worker принимает и ставит в очередь; resize синхронно не делается ни при каких условиях: код Pillow в процесс API не импортируется.
|
||
|
||
`depends_on` реплик API включает брокер (`service_healthy`, как Valkey): в штатном стенде он есть с первого запроса. Стенды с `--no-deps` стартуют и без него.
|
||
|
||
### 11. Уборщик и сверка
|
||
|
||
**Уборщик.** Выборки — только `pending`, поэтому `queued`, `processing`, `ready` и `failed` он не видит. `_STALE_COLUMNS` и `AttachmentInListDTO` получают `staging_key`; шаг 2 удаляет `staging_key or object_key`: строка прежней версии — конечный объект, новая — staging. Граница живой загрузки B прежняя, 17 с: от `created_at` до фиксации `queued`, а публикация идёт после неё. Защита загрузки, пережившей grace: `mark_queued` — те же условие и пометка, что были у `mark_ready`.
|
||
|
||
**Сверка.**
|
||
- Staging — вне `<база>/attachments/`: список его не видит, а права списка на него у уборщика и нет.
|
||
- Текущая работа: шаг строк и так берёт только `ready`, `_row_with_object` пропускает всё не `ready`, поэтому объект конечного ключа у `processing` не находка, а `mark_lost` условен по `ready`.
|
||
- `parse_variant_key` рядом с `parse_original_key`. Объект варианта: строка `id` есть → пропуск; строки нет → объект без метаданных (удаление с `--apply`), чужим считается только то, что не разобрано ни так, ни так. Перепроверка `_recheck_orphan` работает без правки: она ищет строку по `id`.
|
||
- Находка «зависшая загрузка» называет ключ staging, если он есть. Чужая зависшая по-прежнему определяется по `object_key`: `set-key` hook и тест прежние.
|
||
- Сверку объектов вариантов и staging добавляет следующее изменение; пока вариант без объекта даёт 500 на скачивание и `error` в журнале.
|
||
|
||
### 12. Пользователь S3 worker
|
||
|
||
`infra/s3/bootstrap.sh`: `apply_user worker worker-objects`, политика `s3:GetObject`, `s3:PutObject` на `<bucket>/*`. Ключи `S3_WORKER_ACCESS_KEY`, `S3_WORKER_SECRET_KEY`. Удаления нет: чистить staging будет уборщик, у которого право уже есть. Ожидание ключа — записью проверочного объекта, как у API. Проверки: `apply` — запись и чтение, отказ на удаление, список и создание bucket; `check` и `make s3_check` — ещё административные запросы и чужой bucket.
|
||
|
||
Запись по `<bucket>/*`, а не по префиксу: `make test_isolated` работает под `test_<db>/` с теми же ключами, а префикс в политике пришлось бы заводить на каждую базу. Сузить права API (запись только в staging) можно, только когда реплик прежней версии не останется; в этом change не делается.
|
||
|
||
### 13. Настройки и секреты
|
||
|
||
| Секция | Поля (по умолчанию) | Откуда |
|
||
|---|---|---|
|
||
| `[broker]` | `host` (127.0.0.1), `port` (5672), `user`, `password`, `connect_timeout_seconds` (2), `publish_timeout_seconds` (2) | адрес и учётные данные — `.env` и `environment`, сроки — `config.toml` |
|
||
| `[worker]` | `concurrency` (2), `max_attempts` (5), `job_timeout_seconds` (60), `retry_delay_seconds` (10), `graceful_shutdown_seconds` (8, ≤ 9), `reconnect_seconds` (2) | `config.toml`, подмена `WORKER__*` |
|
||
|
||
`.env.example`: `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS` (пустой, `make env_setup` подставит), `RABBITMQ_HOST`, `RABBITMQ_PORT`, `RABBITMQ_OUT_PORT` (5673), мосты `BROKER__HOST=127.0.0.1`, `BROKER__PORT=${RABBITMQ_OUT_PORT}`, `BROKER__USER`, `BROKER__PASSWORD`; `S3_WORKER_ACCESS_KEY`, `S3_WORKER_SECRET_KEY`. Пароль задаётся при первом создании volume, как у PostgreSQL.
|
||
|
||
| Имя skeleton | Реальность |
|
||
|---|---|
|
||
| `BROKER_URL_FILE` | `[broker]` мостами из `RABBITMQ_*`: значения, а не файл, как `DATABASE_URL_FILE` |
|
||
| `WORKER_CONCURRENCY` | `[worker] concurrency` |
|
||
| `JOB_MAX_ATTEMPTS` | `[worker] max_attempts` |
|
||
| `JOB_TIMEOUT_SECONDS` | `[worker] job_timeout_seconds` |
|
||
| `STAGING_RETENTION_SECONDS` | поля пока нет: появляется с очисткой staging в `pipeline-reliability`; на этом уровне staging не удаляется |
|
||
|
||
Бюджет повторов: 5 попыток и пауза 10 с выдерживают отказ S3 40–65 с (четыре паузы плюс от мгновенного отказа до срока вызова 5 с на попытку), этого хватает на рестарт S3 (~25 с). Соединений PostgreSQL: `API_REPLICAS × 10 + migrate + cleaner + worker 2`; при замене реплик — 34 при `max_connections` 100.
|
||
|
||
### 14. Стенд
|
||
|
||
- **`docker-compose.yml`:** сервисы `rabbitmq` и `worker`, якорь `x-broker-env`, volume `rabbitmq_data`, строка у `s3-bootstrap`, `depends_on` реплик.
|
||
- **`scripts/restart.sh`:** `restart postgres valkey s3 rabbitmq`, `up -d --wait --no-recreate …` с брокером. `make test-persistence` ждёт `ready` до hook и читает оригинал после. Worker hook не трогает, поэтому защита может вызывать hook при остановленном worker: он и останется остановленным.
|
||
- **`scripts/rolling-update.sh`:** код не меняется, только комментарий (там и в `infra/haproxy/haproxy.cfg` 26 с и 73 с становятся 29 с и 76 с). Порядок обновления с прежней версии — `docker compose up -d --wait rabbitmq`, `docker compose up -d s3-bootstrap`, `make rolling_update`, `docker compose up -d --no-deps cleaner worker` (`balancer.md`). Bootstrap и брокер скрипт не запускает по той же причине, что раньше: профиль `rollout` не должен получать лишние сервисы.
|
||
- **Миграция и смешанные версии:** прежний образ работает на новой схеме. Прежняя реплика: загружает по-старому (201, `ready`, конечный ключ) и падает 500 на чтении строки нового статуса; новая читает её строку как `ready` без вариантов. Окно замены ограничено, смешанный контракт называется в `REPORT.md`. Откат (`MIGRATE=0`) оставляет такие 500 у незавершённых строк.
|
||
- **CI:** `.github/ci/compose.yml` — `rabbitmq` (`ports: !reset []`, конфиг через `configs`, volume данных заново `!override`), `worker` с образом прогона и `configs`; `.github/ci/stand-env.sh` — `CI_RABBITMQ_CONF`; workflow — без новых шагов, стенд поднимается `make run_docker`.
|
||
- **`Makefile`:** `start_broker`, `stop_broker`, `run_worker` (консоль: ключи worker из `.env` в окружение, команда без эха: секреты), `run_dev` и `test_isolated` зависят от брокера; `ENV_SECRETS`, `ENV_FILLED`.
|
||
|
||
### 15. Тесты
|
||
|
||
**Клиент.** `Api.upload` — 202, `queued`, `variants` `[]`, `error_code` null, размер, SHA-256, владелец. Новые: `wait_attachment(actor, id, *, status="ready", timeout=60)` (опрос раз в 0,2 с, падение с последним состоянием), `upload_ready`. Правки сценариев — только там, где нужны байты или итог: `upload` → `upload_ready`. Проверки не ослабляются (спек `student-tests`, «Готовность вложения в тестах»). `test_meta_equals_upload` сравнивает поля оригинала и отдельно — поля состояния.
|
||
|
||
**Новый модуль `test_attachment_processing.py`** — то, что видно по HTTP на любом стенде с worker: thumbnail (fixture, маленькие, округление, EXIF с проверкой пикселей Pillow, alpha, разновидности), скачивание варианта, 404 отсутствующего, `failed` от недекодируемого JPEG (`images.jpeg_precision_12`).
|
||
|
||
**Стенд отказов.** `failures.compose.yml`: `rabbitmq` без порта, `worker` с `restart: "no"`, `WORKER__MAX_ATTEMPTS: "4"`, `WORKER__RETRY_DELAY_SECONDS: "5"`, `WORKER__JOB_TIMEOUT_SECONDS: "10"`, `WORKER__GRACEFUL_SHUTDOWN_SECONDS: "2"`. Сумма пауз 15 с больше времени возврата S3 (~8 с): «Временная ошибка» успевает, а «Попытки исчерпаны» укладывается в 20 с. Точные значения проверяет прогон, итог — в «Уточнениях apply». `run_failures.py` поднимает брокер и worker, передаёт значения (`FAULT_WORKER_*`), печатает журнал worker при падении, убирает всё. Ожидаемое время прогона — плюс ~5 мин.
|
||
|
||
**Hook** (`fault_hook.py`): `stop|start|pause|unpause|kill|recreate rabbitmq`, `stop|start|kill worker`, `worker-state` (`RestartCount`, `OOMKilled`), `queue-state`, `peek-job` (чтение с возвратом, тело JSON), `publish-job <json>`, `delete-queue` — Python в контейнере API его настройками, пароль в hook не попадает; `job <attachment_id>`, `staging-ids`, `variant-object-count <id>`; `put-object`, `delete-object` разрешены и под `<база>/staging/`; `fail-attachments` — режимы `insert`, `queued`, `stall`, `commit`, `outlive`, `undeletable`, `mark` срабатывают на `pending → queued`; новые `ready-fail`, `ready-stall` — на `→ ready`. Прежний режим `ready` исчезает: такого перехода у API нет.
|
||
|
||
**`make test_isolated`:** контейнер `<проект>-test-worker` с той же подменой `DATABASE__NAME`, уборка — ещё и `rabbitmqctl delete_queue` (отсутствие очереди — не ошибка), журналы обоих контейнеров.
|
||
|
||
**Тесты старого поведения,** привязанные к `ready` API (`test_ready_failure_compensated`, `test_killed_between_put_and_ready`, `test_ready_commit_outcome_unknown`, `test_upload_outlives_grace`, `test_cleaner_failure_after_object_delete`), переходят на `queued` и `staging-ids`. Поведение то же, меняется только шаг: это разрешённая правка вместе со спеком.
|
||
|
||
**Сверка покрытия:** `attachment-processing` и `message-broker` в `CAPABILITIES`. Таблица — раздел «Покрытие сценариев».
|
||
|
||
### 16. `bench/`
|
||
|
||
- `bench.compose.yml`: `rabbitmq` (`container_name: mtusi-bench-rabbitmq`, `restart: "no"`, порт сброшен, лимиты `BENCH_BROKER_*`), `worker` (образ стенда, `volumes: !reset []`, лимиты `BENCH_WORKER_*`) описаны и не запускаются, кроме брокера в профиле загрузок; `bench.env` — `RABBITMQ_HOST`, `RABBITMQ_PORT`, `RABBITMQ_DEFAULT_USER`.
|
||
- `run.py`: `compose_env` — `RABBITMQ_DEFAULT_PASS`, `S3_WORKER_*`, лимиты; поля `Profile` `broker_cpus` (1), `broker_memory` (512m), `worker_cpus`, `worker_memory`; `start_s3` рядом — `start_broker`; `recycle_uploads` — новый volume брокера на прогон: иначе очередь копилась бы между прогонами; остатки и уборка.
|
||
- `k6/uploads.js`: успех — 201 или 202 (`expectedStatuses(201, 202)`), разогрев требует один из них; у варианта «до» с `04f8592` останется 201. `uploads.py`: столбец `s201` не переименовывается (`bench.md`, «Результаты»), в него считается код успеха варианта, а код называет новый столбец `success_code` в конце `runs.csv` и раздел `uploads` паспорта.
|
||
- Паспорт: брокер в ролях, образ и лимиты. Прежние профили методику не меняют: брокер они не запускают, реплика подключается лениво. Окружение приложения получает `BROKER__*` без пароля: метки лабы 5 снимаются уже с ним.
|
||
|
||
### 17. Драйвер и защита
|
||
|
||
`driver.py`: `start` — ещё `start_broker` и процесс worker в той же группе, `upload` и `flow` — 202 и ожидание `ready`, все команды вложений — то же, заглушка реплики в `lb-upload-timeouts` — 202. Новые команды:
|
||
|
||
- `defense-scenario` — сценарий защиты на рабочем стенде (спек `student-tests`): `docker compose stop worker`, загрузка 202, сообщение, 409, текст 201, `scripts/restart.sh`, `docker compose start worker`, ожидание `ready`, проверка оригинала и thumbnail (`jpeg_size` без Pillow: драйвер на stdlib), таблица шагов, ID, `StartedAt` контейнеров до и после. Worker запускается в `finally`, по сигналу тоже. → `evidence/attachments/defense.md`.
|
||
- `broker-check` — закрепление образа, volume, порты, предел памяти, очередь (`rabbitmqctl`), остановка с кодом 0. → `evidence/broker/stand.md`.
|
||
- `worker-process` — PID 1, нет healthcheck, Pillow нет в процессе API, версия Pillow в образе, запись о старте, неверные `WORKER__*`, остановка простаивающего и на старте, «Worker переживает рестарт хранилищ». → `evidence/worker/process.md`.
|
||
|
||
### 18. Журнал
|
||
|
||
Модуль `attachment_processing_service`, записи — спек `service-logging`, «Журнал worker». API: `info` «Uploaded attachment» — ещё `job_id`; `warning` «Attachment job was not published» (`attachment_id`, `job_id`, итог `cancelled` или `taken`); `warning` «Attachment job publish mark failed». Модуль `broker`: `warning` «Broker is unavailable», `info` «Broker is available again», `debug` на публикацию. «Started API» — ещё `broker_host`, `broker_port`, `broker_queue`, `broker_publish_timeout_seconds`.
|
||
|
||
### 19. Evidence и документы
|
||
|
||
Коммиты делает основная сессия, поэтому `tasks.md` делится: группы кода и тестов проверяются на рабочем дереве, а группа снятия evidence запускается основной сессией после коммита кода. Файлы старых исключений `chat-cache`, `sessions`, `users`, `idempotency` снимаются на последнем шаге всего прогона (`QUESTIONS.md`, «Перенос из лабы 4»), поэтому до него `test_exclusion_evidence_exists` ожидаемо красный, и только на них.
|
||
|
||
Новое правило `.claude/rules/worker.md` (`src/worker/**`, `src/core/services/attachment_processing.py`, `src/utils/thumbnail.py`); остальные правила и `AGENTS.md` — по слоям в задачах.
|
||
|
||
## Покрытие сценариев
|
||
|
||
Новые и изменённые по сути сценарии спеков из `CAPABILITIES`. `fault` — `make failure_checks`; без пометки — `make student_test`. Изменённые только кодом ответа 201 → 202 проверяют прежние тесты.
|
||
|
||
| Capability, сценарий | Проверка |
|
||
|---|---|
|
||
| `attachment-processing` «Принятое вложение в очереди» | `test_queued_while_worker_stopped`, fault |
|
||
| «Вложение становится готовым» | `test_attachment_becomes_ready` |
|
||
| «Обработка видна в API» | `test_processing_visible`, fault |
|
||
| «Готовое вложение не откатывается», «Повторная доставка готового» | `test_redelivery_of_ready_is_noop`, fault |
|
||
| «Что сохранено к ответу 202» | `test_durable_state_at_202`, fault |
|
||
| «Повторы под одним заданием», «Временная ошибка» | `test_transient_error_retried`, fault |
|
||
| «Сообщение по схеме» | `test_job_message_matches_schema`, fault |
|
||
| «Сообщение не по схеме» | `test_malformed_message_dropped`, fault |
|
||
| «Неизвестное задание» | `test_unknown_job_acked`, fault |
|
||
| «Worker убит посреди обработки» | `test_worker_killed_during_processing`, fault |
|
||
| «Дубль во время обработки» | `test_duplicate_during_processing`, fault |
|
||
| «Оригинал неизменен» | `test_original_published_unchanged`, fault |
|
||
| «Испорченный staging», «Нет объекта staging» | `test_staging_corrupted`, `test_staging_missing`, fault |
|
||
| «Fixture 320 × 200», «Маленькое изображение не увеличивается», «Округление вниз и минимум», «EXIF orientation», «Alpha на белый», «Разновидности форматов» | `test_thumbnail_*` |
|
||
| «Изображение в лимите пикселей» | `test_max_pixels_fit_worker_memory`, fault |
|
||
| «Повтор после записи объектов» | `test_ready_failure_retried`, fault |
|
||
| «Состояние между попытками» | `test_queued_between_attempts`, fault |
|
||
| «Попытки исчерпаны» | `test_attempts_exhausted`, fault |
|
||
| «PostgreSQL недоступен при обработке» | `test_database_outage_during_processing`, fault |
|
||
| «Изображение не декодируется» | `test_undecodable_becomes_failed`, fault |
|
||
| «Worker недоступен» | `test_worker_down_api_serves`, fault |
|
||
| «Ограниченная конкуренция» | `test_concurrency_bounded`, fault |
|
||
| «Реплика API убита после ответа» | `test_api_killed_after_202`, fault |
|
||
| «Рестарт брокера с volume» | `test_broker_restart_keeps_job`, fault |
|
||
| «Принудительное завершение брокера» | `test_broker_kill_keeps_confirmed`, fault |
|
||
| «Сценарий защиты» | `test_defense_scenario`, fault |
|
||
| `message-broker` «Сервис брокера запущен», «Предел памяти брокера», «Остановка брокера» | исключения: `driver.py --port <LB> broker-check` → `evidence/broker/stand.md` |
|
||
| «Очередь и сообщения устойчивы» | `test_queue_durable`, fault |
|
||
| «Очереди разных баз разделены» | исключение: `make test_isolated` и `broker-check` → `evidence/broker/isolated.md` |
|
||
| «Брокер остановлен при загрузке», «Брокер вернулся» | `test_upload_with_broker_stopped`, fault |
|
||
| «Брокер завис» | `test_upload_with_broker_paused`, fault |
|
||
| «Очередь удалена» | `test_queue_deleted`, fault |
|
||
| «Подтверждённые сообщения после KILL» | `test_broker_kill_keeps_confirmed`, fault |
|
||
| «Пересоздание контейнера» | `test_broker_recreated`, fault |
|
||
| «Старт без брокера» | `test_start_without_broker`, fault |
|
||
| «Рестарт брокера при работающем worker» | `test_worker_survives_broker_restart`, fault |
|
||
| `attachments` «Фиксация задания не удалась» | `test_queued_failure_compensated`, fault |
|
||
| «Фиксация ready не удалась» | `test_ready_failure_retried`, fault |
|
||
| «Исход фиксации неизвестен» | `test_queued_commit_outcome_unknown`, fault |
|
||
| «Брокер не подтвердил задание» | `test_upload_with_broker_stopped`, fault |
|
||
| «Скачивание до готовности» | `test_content_before_ready`, fault |
|
||
| «Скачивание thumbnail», «Отсутствующий вариант», «Вариант для постороннего» | `test_download_thumbnail`, `test_missing_variant`, `test_variant_outsider` |
|
||
| `messages` «Вложение в обработке», «Вложение стало failed после отправки» | `test_message_with_queued_attachment`, `test_attachment_failed_after_message`, fault |
|
||
| «Вложение failed» | `test_message_with_failed_attachment` |
|
||
| `idempotency` «Повтор после failed вложения» | `test_replay_after_attachment_failed`, fault |
|
||
| `health` «Брокер и worker недоступны» | `test_readiness_without_broker_and_worker[stop\|pause]`, fault |
|
||
| `data-storage` «Принятое вложение видно сразу» | `test_accepted_attachment_visible_on_other_replica` |
|
||
| «Ограничения обработки в схеме» | исключение: `driver.py --port <LB> attachment-storage`, пробы ограничений в откатываемой транзакции → `evidence/attachments/storage.md` |
|
||
| `storage-consistency` «Загрузка без подтверждения брокера убрана» | `test_upload_with_broker_stopped`, fault |
|
||
| «Текущая работа не тронута» | `test_cleaner_keeps_current_work`, fault |
|
||
| «Объекты вариантов своих вложений», «Объект варианта без метаданных», «Текущая работа не считается расхождением» | `test_reconcile_variant_objects`, `test_reconcile_orphan_variant`, `test_reconcile_keeps_current_work`, fault |
|
||
|
||
Спеки вне сверки — evidence с закоммиченного кода: `container-run`, `container-image`, `graceful-shutdown`, `service-configuration` → `driver.py worker-process`, `broker-check`, `evidence/replicas/`; «docker stop во время обработки» — ещё `test_worker_stop_during_processing`, fault (сценарий в докстринге); `object-storage` → `make s3_check`, `evidence/s3/worker-key.md`; `service-logging` → `evidence/worker/logs.md`; `db-migrations` → `evidence/migrations/async-attachments.md`; `load-balancing` → `driver.py lb-upload-timeouts`; `load-benchmark` → `make bench_uploads_quick`, регресс быстрых профилей; `student-tests` → `evidence/tests/`.
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [Разрыв COMMIT и publish: падение API оставляет `queued` без сообщения] → клиент 202 не получил, принятая работа цела; запись видна запросом; закрывает `pipeline-reliability`; названо в спеке, `REPORT.md` и в окнах отказа.
|
||
- [503 при отказе брокера: приём встаёт вместе с брокером] → текст и чтение работают; ответ быстрый при упавшем брокере и ≤ 2 с при зависшем; на уровне 4 приём отвяжется от брокера.
|
||
- [Пауза повтора постоянна, поэтому отказ S3 дольше ~минуты переводит взятые задания в `failed`, а replay нет] → назван в спеке; уровень 4 даёт backoff и replay; задания в очереди не тратят попытки, пока места заняты паузой.
|
||
- [Отказ S3 после ответа 202 у `failed` без replay — итог окончателен для клиента] → как выше, для уровня 3 это граница рубрики («финальное failed»).
|
||
- [Оригинал лежит дважды до очистки, а у `failed` и незавершённых staging не удаляется на этом уровне] → очистка в `pipeline-reliability`; контракт требует документированный retention: записано в `REPORT.md`, вопрос в `QUESTIONS.md`.
|
||
- [Объект staging без строки возможен, если процесс API заморожен дольше grace посреди записи] → как и раньше с конечным ключом, но сверка staging не видит; закрывает очистка staging следующего изменения; записано в спеке.
|
||
- [Зависший worker с живым соединением держит задание до `consumer_timeout` брокера, 30 мин] → срок попытки покрывает всё, кроме потока декодирования; уровень 4 — lease.
|
||
- [Поток декодирования не прерывается сроком] → вход ограничен лимитом контракта и проверен при загрузке; жёсткий срок — уровень 4.
|
||
- [Потребитель не узнает об удалении очереди мимо приложения] → такого на стенде нет, кроме уборки своей очереди после остановки своего worker; оператору — перезапуск worker; записано в `REPORT.md`.
|
||
- [Один пользователь брокера на API и worker] → секрет только у трёх сервисов; разделение — лаба 7.
|
||
- [Смесь версий при замене реплик: 500 на чтении новых статусов старой репликой] → окно ограничено, переход 201 → 202 всё равно несовместим; в `REPORT.md`.
|
||
- [Новые зависимости и размер образа: Pillow ~30 МБ колесом, aio-pika ~1 МБ] → декодер не загружается в процесс API, память реплики не растёт; проверяет регресс `make bench_uploads_quick`.
|
||
- [Предел памяти брокера 400 МиБ при большой очереди блокирует публикацию] → это backpressure, а не потеря: загрузки получают 503; трек 1 это и мерит.
|
||
|
||
## Migration Plan
|
||
|
||
1. `make env_setup` дописывает секреты брокера и ключи worker в существующий `.env`.
|
||
2. Рабочий стенд без простоя: `docker compose up -d --wait rabbitmq`, `docker compose up -d s3-bootstrap`, `make rolling_update`, `docker compose up -d --no-deps cleaner worker`. С простоем — `make run_docker`.
|
||
3. Откат: `make rolling_update COMMIT=<прежний> MIGRATE=0`, `docker compose stop worker`, прежний образ уборщика. Схема остаётся. Незавершённые `queued` и `processing` останутся и дают 500 на чтении прежней версией; вперёд — снова `make rolling_update`.
|
||
4. Прежние строки `ready` не трогаются: `variants` пуст, `variant=thumbnail` — 404. Данные миграция не меняет; рабочий стенд лабы 5 создан недавно, таких строк на нём нет или они тестовые.
|
||
|
||
## Open Questions
|
||
|
||
Вопросы преподавателю в `QUESTIONS.md` (раздел `async-attachments`): ни один не меняет спеки, подход или задачи; при другом ответе правка ограничена одной веткой кода и сценарием.
|
||
|
||
## Уточнения apply
|
||
|
||
1. **`JobOutcome`: третий исход `DROP`** рядом с `ACK` и `REQUEUE` решения 7: сообщение не по схеме — `reject(requeue=False)`, а его решает сервис, а не `main.py`.
|
||
2. **`request_id` записей задания ставит сервис обработки** сразу после разбора, а не `main.py` (задача 7.3): разбор — его шаг, задача доставки своя, контекст не течёт. Сообщение не по схеме `request_id` не получает: задания нет.
|
||
3. **Сообщение с `attachment_id` не той строки задания** — как неизвестное: `ACK` без эффекта. Такого API не публикует; ключи берутся только из строки.
|
||
4. **Издатель проверяет `is_closed` канала перед публикацией** (`_get_channel`), вопреки решению 5, которое запрещало верить признаку: нашёл `driver.py defense-scenario`. Запрет относится к соединению. После рестарта брокера без единой загрузки издатель держал закрытый канал, и первая загрузка на каждой реплике получала 503 (`ChannelInvalidStateError`, 0 мс). В закрытый канал ничего не ушло, поэтому новое соединение — не повтор публикации. Проверяет `test_worker_survives_broker_restart`: загрузка только после возврата брокера.
|
||
5. **`Image.Transpose.FLIP_LEFT_RIGHT` равен 0:** проверка `if transpose := …` пропускала orientation 2. Нашла проба задачи 5.1, сверка с `ImageOps.exif_transpose`; тест `test_thumbnail_every_orientation` держит все восемь значений.
|
||
6. **`rabbitmqctl delete_queue` отсутствующей очереди** — код 64 и «No such queue was found», а не `not_found`: так проверяют `run_isolated.py` и hook. Нашёл первый `make test_isolated`.
|
||
7. **`delete-row` hook удаляет и задание с вариантами** одной транзакцией: FK без каскада иначе не дал бы удалить строку готового вложения. Новое действие `worker-log` — запись `error` журнала worker, которой требует спек, иначе тесту негде её увидеть.
|
||
8. **Две прежние проверки отказов сформулированы иначе,** worker теперь параллельно доводит задания прежних тестов, и равенство множеств стало бы гонкой: `ready_ids(after) == ready_ids(before)` в `test_upload_with_object_storage_stopped` → «новая строка одна, `pending`, задания нет»; «новых объектов нет» не считает объекты у `id`, известных до теста (`new_objects`).
|
||
9. **Дубль во время фиксации результата** таблица решения 7 не называет: фиксация держит строку задания, поэтому дубль ждёт блокировку и видит итог (`finished`), а не `busy`. `test_duplicate_during_processing` проверяет обе ветки: `busy` при замороженном S3 и `finished` при задержанной фиксации, `attempt` 1.
|
||
10. **Сверка фиксирует объект варианта строки, удалённой вручную:** у вложения без строки находка — и `original`, и `v1-thumbnail`, оба `orphan_object`; проверяют тесты расхождений.
|
||
11. **Время `make failure_checks`:** 99 проверок, pytest 1304 с, вся команда 1326 с (было 56, ~15 мин). Плюс больше ожидаемых ~5 мин design: 43 новые проверки, из них часть ждёт паузы повтора и grace.
|
||
12. **Регрессии задачи 10.10** (каждая откачена, хэши `src` совпали со снимком до них):
|
||
- ack до фиксации → `test_worker_killed_during_processing` красный: не `ready` за 60 с, последний статус `processing`;
|
||
- публикация без подтверждения → `test_upload_with_broker_paused` красный: 202 вместо 503; `test_upload_with_broker_stopped` зелёный, обрыв соединения публикация видит и так;
|
||
- очередь не `durable` → `test_broker_restart_keeps_job` красный, но раньше сценария: на входе `wait_queue_empty` очереди нет; причину (отказ брокера в объявлении или иное) не разбирал. На верном коде тот же запуск — зелёный;
|
||
- `Image.thumbnail` вместо своего расчёта → `test_thumbnail_rounding` красный на 1000 × 601;
|
||
- `failed` до захвата ключа → `test_replay_after_attachment_failed` красный: 409 вместо 201;
|
||
- сверка без ветки варианта → `test_reconcile_variant_objects` красный.
|
||
13. **S4 профиля `reconcile` с commit «до» лабы 5:** `make bench_reconcile_quick` падал на `S4-300-before-r1: missing_object found 101, injected 300`. Дефект с `cc33a03`, а не этого change: commit «до» стал `04f8592`, в нём ранний отказ по пределу уже есть, а проверка ждала все находки. В `run.py` обе ячейки теперь ждут `min(count, max_changes + 1)`; вердикт S4 «до и после» на этих commit ничего не показывает, правило `bench.md` это называет. Вариант «до» профиля `uploads` тоже уже с местами загрузок: H2 старой метки не воспроизводится (там же).
|
||
14. **Пик памяти thumbnail:** первая версия давала 484 МиБ на PNG RGBA 8000 × 5000 вместо ~323 пробы: `convert("RGBA")` в тот же режим копирует все пиксели. `_prepared` теперь отдаёт RGBA как есть, пик в контейнере образа с лимитом 1 ГБ — 332 МиБ. Правка внесена после полного `make failure_checks`, после неё перепроверены `-k "max_pixels or redelivery"` и `test_attachment_processing.py`.
|
||
15. **`make test_isolated` — код 2 до группы 15:** smoke `PASS`, 205 passed, 6 skipped (реплики), единственный failed — `test_exclusion_evidence_exists`; уборка полная. Проверено и `KEEP_TEST_DB=1` (остаются база, префикс, очередь; `broker-check --require-test-queue` — код 0), и прерывание SIGINT (код 130, ни контейнеров, ни базы, ни очереди).
|