87 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 |
да | любой | сообщение уже доставлялось: прежний потребитель потерян или дубль вернулся после 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):
- 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, задания нет» иready_ids(before) <= ready_ids(after):readyне откатывается, гонки с worker нет; «новых объектов нет» не считает объекты у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красный, но раньше сценария. Причина (журналы 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_mode1).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красный.
- 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, ни контейнеров, ни базы, ни очереди).- Группа 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. - Паспорта меток с
dirty: false:git_infoсчитает неотслеживаемые файлы изменением, а новых файловevidence/к замеру коммитить было нельзя. На времяmake bench_rolloutиmake bench_uploadsони вынесены в scratchpad и возвращены; код,tasks.mdиREPORT.mdв это время не менялись,git status --porcelainперед каждым замером пуст.