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>
84 KiB
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 |
Что найдено до решений
- Лимит памяти брокера и имя узла — таблица: без явного предела и постоянного
hostnameстенд выглядит рабочим, а теряет данные приup --force-recreateи уходит в OOM под нагрузкой. - Повтор сообщения и
failed. Контракт разом требует «failed прикреплять нельзя (409)» и «повтор с тем же ключом — тот же 201». Сегодняшний порядок («вложения, затем ключ») дал бы 409 на повтор сообщения, чьё вложение сталоfailedпосле отправки. - Смешанные версии. Реплика лабы 4 падает с 500 на чтении строки в новом статусе:
AttachmentStatus(...)—ValueError. Переход 201 → 202 всё равно ломает контракт для клиента на время замены, и это ограничение называется, а не лечится. - Объекты вариантов под
<база>/attachments/сверка без правки считала бы чужими: код 3 навсегда (решение 11). - Сценарий нельзя переименовать правкой дельты.
openspec validate --strictотказывает MODIFIED, которая теряет сценарий основного спека. Поэтому «Фиксация ready не удалась» осталась и теперь про фиксацию worker, а фиксацию API описывает новый сценарий «Фиксация задания не удалась». - Цепочка сроков LB: прежняя сумма 26 с после тела с новым шагом должна остаться
меньше
timeout server30 с, иначе растут и он, и срок дренажа (решение 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(имя узла и каталог данных постоянны), volumerabbitmq_data:/var/lib/rabbitmq,RABBITMQ_DEFAULT_USER,RABBITMQ_DEFAULT_PASS,RABBITMQ_NODE_PORT: ${RABBITMQ_PORT}, порт на127.0.0.1:${RABBITMQ_OUT_PORT:-5673}, алиас в сети, healthcheckrabbitmq-diagnostics -q check_port_connectivity(interval10 с,start_interval1 с),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):
- GET staging в память; нет объекта — постоянная
source_missing; размер или SHA-256 не сходятся сsize_bytesиsha256строки — постояннаяsource_corrupted. Обе даютprocessing_failedв API. - PUT
object_keyтеми же байтами (content_typeиз строки). render_thumbnailв потоке (решение 8); не декодируется — постоянная,invalid_image.- PUT ключа варианта.
- Фиксация: блокировка задания →
attachmentsвreadyпри статусеqueuedилиprocessing(0 строк — откат,ACK: итог уже есть) → вставка вариантаON CONFLICT DO NOTHING→ заданиеsucceeded,finished_at. Commit. 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 декодер в память не загружают.
Image.open(BytesIO(data), formats=("PNG", "JPEG"));width × height > ATTACHMENT_MAX_PIXELS—InvalidImage.- Orientation из
getexif()до декодирования. Размер — своим вычислением по показанным сторонам:Image.thumbnailокругляет к ближайшей пропорции, а контракт — вниз.w ≤ 256 и h ≤ 256→ как есть; иначе большая сторона 256, меньшаяmax(1, меньшая × 256 // большая). Для orientation 5–8 стороны меняются местами до вычисления и обратно после. - JPEG:
image.draft("RGB", цель)— масштаб DCT, пик памяти на порядок меньше. - Режимы:
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молча брал бы ближайшего соседа. resize(цель, LANCZOS, reducing_gap=2.0): уRGBAPillow сам премультиплицирует.- Альфа —
alpha_compositeна белый уже на малом изображении, затемRGB. - Transpose по orientation — тоже на малом: на полном размере он удвоил бы пик памяти.
- 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(409conflict, новая строка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-keyhook и тест прежние. - Сверку объектов вариантов и 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, volumerabbitmq_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.cfg26 с и 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_*, лимиты; поляProfilebroker_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
make env_setupдописывает секреты брокера и ключи worker в существующий.env.- Рабочий стенд без простоя:
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. - Откат:
make rolling_update COMMIT=<прежний> MIGRATE=0,docker compose stop worker, прежний образ уборщика. Схема остаётся. Незавершённыеqueuedиprocessingостанутся и дают 500 на чтении прежней версией; вперёд — сноваmake rolling_update. - Прежние строки
readyне трогаются:variantsпуст,variant=thumbnail— 404. Данные миграция не меняет; рабочий стенд лабы 5 создан недавно, таких строк на нём нет или они тестовые.
Open Questions
Вопросы преподавателю в QUESTIONS.md (раздел async-attachments): ни один не меняет спеки, подход или задачи; при другом ответе правка ограничена одной веткой кода и сценарием.
Уточнения apply
JobOutcome: третий исходDROPрядом сACKиREQUEUEрешения 7: сообщение не по схеме —reject(requeue=False), а его решает сервис, а неmain.py.request_idзаписей задания ставит сервис обработки сразу после разбора, а неmain.py(задача 7.3): разбор — его шаг, задача доставки своя, контекст не течёт. Сообщение не по схемеrequest_idне получает: задания нет.- Сообщение с
attachment_idне той строки задания — как неизвестное:ACKбез эффекта. Такого API не публикует; ключи берутся только из строки. - Издатель проверяет
is_closedканала перед публикацией (_get_channel), вопреки решению 5, которое запрещало верить признаку: нашёлdriver.py defense-scenario. Запрет относится к соединению. После рестарта брокера без единой загрузки издатель держал закрытый канал, и первая загрузка на каждой реплике получала 503 (ChannelInvalidStateError, 0 мс). В закрытый канал ничего не ушло, поэтому новое соединение — не повтор публикации. Проверяетtest_worker_survives_broker_restart: загрузка только после возврата брокера. Image.Transpose.FLIP_LEFT_RIGHTравен 0: проверкаif transpose := …пропускала orientation 2. Нашла проба задачи 5.1, сверка сImageOps.exif_transpose; тестtest_thumbnail_every_orientationдержит все восемь значений.rabbitmqctl delete_queueотсутствующей очереди — код 64 и «No such queue was found», а неnot_found: так проверяютrun_isolated.pyи hook. Нашёл первыйmake test_isolated.delete-rowhook удаляет и задание с вариантами одной транзакцией: FK без каскада иначе не дал бы удалить строку готового вложения. Новое действиеworker-log— записьerrorжурнала worker, которой требует спек, иначе тесту негде её увидеть.- Две прежние проверки отказов сформулированы иначе, worker теперь параллельно доводит задания прежних тестов, и равенство множеств стало бы гонкой:
ready_ids(after) == ready_ids(before)вtest_upload_with_object_storage_stopped→ «новая строка одна,pending, задания нет»; «новых объектов нет» не считает объекты уid, известных до теста (new_objects). - Дубль во время фиксации результата таблица решения 7 не называет: фиксация держит строку задания, поэтому дубль ждёт блокировку и видит итог (
finished), а неbusy.test_duplicate_during_processingпроверяет обе ветки:busyпри замороженном S3 иfinishedпри задержанной фиксации,attempt1. - Сверка фиксирует объект варианта строки, удалённой вручную: у вложения без строки находка — и
original, иv1-thumbnail, обаorphan_object; проверяют тесты расхождений. - Время
make failure_checks: 99 проверок, pytest 1304 с, вся команда 1326 с (было 56, ~15 мин). Плюс больше ожидаемых ~5 мин design: 43 новые проверки, из них часть ждёт паузы повтора и grace. - Регрессии задачи 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красный.
- ack до фиксации →
- 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 старой метки не воспроизводится (там же). - Пик памяти 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. make test_isolated— код 2 до группы 15: smokePASS, 205 passed, 6 skipped (реплики), единственный failed —test_exclusion_evidence_exists; уборка полная. Проверено иKEEP_TEST_DB=1(остаются база, префикс, очередь;broker-check --require-test-queue— код 0), и прерывание SIGINT (код 130, ни контейнеров, ни базы, ни очереди).