Files
mtusi2026lab5/openspec/changes/async-attachments/design.md
T
2026-10-31 09:13:33 +03:00

87 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 да любой сообщение уже доставлялось: прежний потребитель потерян или дубль вернулся после busy (флаг стоит и после nack(requeue=True)), этого не различить: взять так же, ограничение — ниже
processing нет истёк взять так же
processing нет идёт дубль при живой попытке: пауза retry_delay_seconds, REQUEUE без записи. Следующая доставка придёт с redelivered, а попытка к тому времени обычно закончена, и это ACK

Перед взятием: attempt ≥ max_attempts → failed с retry_exhausted, ACK. Именно это ограничивает задание, которое роняет worker (OOM, SIGKILL): брокер его снова доставит, а попытка уже посчитана.

Ограничение до lease. Дубль, вернувшийся после busy, приходит с redelivered. Если живая попытка длится дольше паузы, он возьмёт задание параллельно ей и потратит её номер, а на последней попытке даст retry_exhausted, пока первая ещё идёт: её результат тогда не фиксируется. Эффект не дублируется: ключи те же, фиксация условна. Закрывает pipeline-reliability (QUESTIONS.md, «Предложения на потом»).

Обработка под 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, задания нет» и ready_ids(before) <= ready_ids(after): ready не откатывается, гонки с worker нет; «новых объектов нет» не считает объекты у 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 красный, но раньше сценария. Причина (журналы verify, строки test_failures.py — на ff1a83b): RabbitMQ 4.3.7 отказывает на durable=False (541 INTERNAL_ERROR - Feature transient_nonexcl_queues is deprecated), очередь не создаётся, и все 4 теста брокера падают на входе, test_failures.py:1666. Регрессия NOT_PERSISTENT при durable-очереди красная в самом сценарии: test_broker_restart_keeps_job на test_failures.py:2552 (assert 0 == 1), test_broker_kill_keeps_confirmed (0 == 5), test_broker_recreated (0 вместо 2), test_queue_durable (delivery_mode 1). durable=False с deprecated_features.permit.transient_nonexcl_queues = true падает на строке 2552: после рестарта очереди нет. На верном коде тот же запуск — зелёный;
    • 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, ни контейнеров, ни базы, ни очереди).
  16. Группа 15: evidence/uploads/baseline/summary.md задача 15.2 и решение 19 не называли, а на него ссылаются два исключения attachments, и test_exclusion_evidence_exists падал и по нему. Снят make bench_uploads на ff1a83b: копировать файл лабы 4 запрещено (student-tests.md). Вариант «до» — 04f8592, поэтому H2 в сводке — «нет»; поправки к чтению — evidence/uploads/README.md.
  17. Паспорта меток с dirty: false: git_info считает неотслеживаемые файлы изменением, а новых файлов evidence/ к замеру коммитить было нельзя. На время make bench_rollout и make bench_uploads они вынесены в scratchpad и возвращены; код, tasks.md и REPORT.md в это время не менялись, git status --porcelain перед каждым замером пуст.