Files
mtusi2026lab5/openspec/changes/async-attachments/design.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
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>
2026-10-31 06:48:20 +03:00

84 KiB
Raw Blame History

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, ни контейнеров, ни базы, ни очереди).