{
  "index": 274,
  "slug": "editorial-2020-05-field-background-jobs",
  "title": "Фоновая задача продублировала экспорт: порядок записи, ack и карантин ошибок",
  "excerpt": "Разбираем два сбоя фонового worker: повторный внешний эффект после потери ack и бесконечный requeue для постоянной ошибки. Показываем порядок действий, журнал и критерий готовности.",
  "contentHtml": "<p>Пользователь запускает экспорт и через несколько минут получает два одинаковых файла. В той же очереди задача с неизвестным типом отчёта появляется снова сразу после отказа worker. Первая ошибка создаёт лишний внешний эффект: приходится выяснять, какой файл считать правильным, и чистить дубликаты. Вторая забивает worker одинаковыми исключениями. Полезные задачи ждут, а журнал растёт быстрее, чем его успевает читать дежурный инженер.</p>\n<p>Тезис такой: доставка сообщения и выполнение бизнес-операции — разные факты. Broker может доставить одну бизнес-задачу повторно, если не увидел подтверждение. Worker обязан сделать повтор безопасным по устойчивому ключу. Он также обязан отличать временный сбой от постоянной ошибки входных данных. Для первой ошибки нужен идемпотентный результат и правильный порядок записи. Для второй — ограничение попыток и карантин, а не безусловный <code>requeue</code>.</p>\n<h2>Что именно повторяется</h2>\n<p>Пусть запрос создаёт задачу с <code>jobId = export-42-2020-05</code>. Producer публикует сообщение, а worker получает delivery с отдельным <code>deliveryTag</code>. Первый идентификатор относится к бизнес-операции. Второй относится к конкретной доставке на канале. Новый <code>deliveryTag</code> не означает новый экспорт.</p>\n<p>Worker начинает работу, сохраняет файл и переводит задачу в <code>succeeded</code>. Затем соединение с broker обрывается до <code>ack</code>. Для broker доставка осталась неподтверждённой. После восстановления consumer получает её снова. Если обработчик каждый раз вызывает экспорт, он создаёт второй файл. Если имя строится из текущего времени, по имени файла невозможно доказать, что это повтор.</p>\n<p>Вторая задача содержит <code>reportKind = unknown</code>. Worker не может обработать её ни сейчас, ни через секунду: причина находится во входных данных. Если обработчик на любое исключение отвечает <code>nack(requeue=true)</code>, broker снова выдаёт то же сообщение. Так возникает hot loop. Повтор помогает только тогда, когда новая попытка может изменить исход.</p>\n<figure><img src=\"/assets/editorial/2020/background-job-diagnosis-2020.svg\" alt=\"Схема диагностики фоновой задачи по jobId: запись задачи, outbox, доставка, журнал worker, результат и карантин\" /><figcaption>Проверяйте один jobId от публикации до результата. Так видно, на каком переходе возник повтор или остановилась задача.</figcaption></figure>\n<h2>Порядок подтверждения</h2>\n<p>Подтверждение не является сигналом «код вошёл в функцию». Для ручного ack оно должно означать, что consumer выполнил работу, за которую берёт ответственность. Если ack отправить до записи результата, сбой после ack может потерять работу. Если записать результат, но не сделать повтор безопасным, сбой до ack создаст дубль. Поэтому сначала фиксируют бизнес-результат, затем подтверждают delivery.</p>\n<p>Одного порядка недостаточно. Повтор должен найти тот же объект по <code>jobId</code>, прочитать terminal state и вернуть уже сохранённый результат. Внешний ключ результата тоже должен быть детерминированным: например, <code>reports/export-42-2020-05.csv</code>. Это защищает путь к файлу, но не любой внешний эффект. Email-провайдер или другой HTTP-сервис должен поддерживать собственный idempotency key либо получать вызов через отдельный надёжный протокол.</p>\n<h2>Учебный обработчик</h2>\n<p>Ниже — учебный псевдокод. Он показывает границу ответственности, но не является готовым клиентом RabbitMQ, не задаёт транзакционный API базы и не сообщает показатели production-нагрузки.</p>\n<pre><code>async function handle(delivery) {\n  const { jobId, reportKind } = delivery.payload;\n  const job = await jobs.lockById(jobId);\n\n  if (job.state === 'succeeded') {\n    await delivery.ack();\n    return job.resultKey;\n  }\n\n  if (!isKnownReport(reportKind)) {\n    await jobs.markQuarantined(jobId, {\n      reason: 'unknown_report_kind',\n      payloadVersion: delivery.payload.version,\n    });\n    await delivery.nack({ requeue: false });\n    return;\n  }\n\n  const resultKey = `reports/${jobId}.csv`;\n  await exportReport({ reportKind, resultKey });\n  await jobs.markSucceeded(jobId, resultKey);\n  await delivery.ack();\n}</code></pre>\n<p>Проверка terminal state стоит до внешнего действия. Блокировка или другой механизм защиты строки должен охватывать чтение состояния и резервирование работы. В реальной системе нужно решить, что происходит при падении между записью файла и <code>markSucceeded</code>. Обычно результат пишут во временный объект, затем атомарно публикуют его по детерминированному ключу и сохраняют состояние. Конкретный storage может потребовать иной протокол.</p>\n<p>Ветвь постоянной ошибки не вызывает экспорт и не отправляет сообщение обратно в основную очередь. Она сохраняет причину и версию входных данных до отрицательного подтверждения. Затем transport направляет сообщение в настроенный dead-letter route либо в другой согласованный карантин. Если такого маршрута нет, <code>requeue=false</code> не создаёт архив для разбора автоматически: сообщение может быть отброшено в зависимости от конфигурации.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<table><thead><tr><th>Симптом</th><th>Причина</th><th>Проверка</th><th>Действие</th></tr></thead><tbody><tr><td>Для одного jobId появились два файла</td><td>Результат создаётся по случайному имени или проверка состояния стоит после эффекта</td><td>Сопоставить jobId, resultKey, порядок <code>result_saved</code>, <code>succeeded</code> и <code>ack_sent</code></td><td>Читать terminal state до экспорта и сохранять результат по детерминированному ключу</td></tr><tr><td>Повторная доставка приходит после успешной записи</td><td>Соединение оборвалось до ack</td><td>Сверить журнал broker, delivery tag и запись задачи</td><td>Обработать повтор как тот же jobId, не запускать внешний эффект снова</td></tr><tr><td>attempt растёт с одной и той же причиной</td><td>Постоянную ошибку приняли за временную</td><td>Сравнить payload и код причины на соседних попытках</td><td>Сохранить причину, перевести задачу в <code>quarantined</code>, отключить requeue</td></tr><tr><td>После nack сообщение исчезло</td><td>Для очереди не настроен dead-letter маршрут или сообщение не должно храниться</td><td>Проверить policy, binding, routing key и журнал публикации</td><td>Настроить проверяемый карантин либо явно принять потерю как контракт</td></tr><tr><td>Задача долго стоит в очереди</td><td>Не сработал outbox, producer публикует не туда или worker не читает binding</td><td>Найти запись job, marker публикации и факт первой доставки</td><td>Проверить dispatcher и маршрут до handler; не менять handler без delivery</td></tr></tbody></table>\n<p>Таблица задаёт порядок расследования. Сначала привяжите наблюдение к одному <code>jobId</code>. Не начинайте с увеличения timeout или числа retry. Эти изменения не исправят случайное имя результата, неизвестный <code>reportKind</code> или неверный binding.</p>\n<h2>Почему ack не даёт exactly-once</h2>\n<p>Ручное подтверждение помогает выбрать границу ответственности, но не превращает распределённую систему в exactly-once механизм. Между записью результата и ack остаётся окно сбоя. Между отправкой ack и получением его broker тоже есть сеть. Система с повторной доставкой обычно даёт at-least-once обработку: сообщение могут обработать снова, поэтому handler должен быть идемпотентным.</p>\n<p>Признак <code>redelivered</code> полезен для диагностики, но он не заменяет бизнес-ключ. При повторной публикации похожее сообщение может выглядеть как новая доставка. Бизнес-правило должно опираться на <code>jobId</code>, уникальный ключ результата и состояние операции. Если worker выполняют несколько экземпляров, lock и уникальное ограничение должны защищать одну и ту же область.</p>\n<p>Для временной ошибки используйте ограниченный retry с задержкой. Временной может быть недоступность хранилища, краткий сетевой отказ или ещё не созданная зависимая запись. Сохраняйте <code>attempt</code>, код причины и время следующей попытки. После лимита не отправляйте сообщение в бесконечный цикл. Оставьте его в карантине, чтобы инженер мог исправить данные или код и принять решение о повторном запуске.</p>\n<h2>Порядок действий</h2>\n<ol><li>Выберите один повторившийся или застрявший <code>jobId</code>. Соберите запись задачи, payload, outbox, delivery и журнал worker в одной временной шкале.</li><li>Разделите идентификаторы: бизнес-ключ операции, delivery tag, attempt и ключ внешнего результата. Не считайте новый delivery новой операцией.</li><li>Проверьте порядок переходов. Зафиксируйте, когда появились <code>result_saved</code>, terminal state и <code>ack_sent</code>. Не запускайте экспорт повторно, пока не проверили сохранённый результат.</li><li>Проверьте идемпотентность: повторная доставка того же jobId должна прочитать terminal state и завершиться без нового файла, письма или внешнего вызова.</li><li>Классифицируйте ошибку. Если вход невалиден или тип неизвестен, сохраните постоянную причину и не делайте requeue. Если зависимость может восстановиться, задайте конечный лимит и задержку.</li><li>Проверьте карантин на выбранном broker: policy, exchange, binding, routing key и права публикации. Отрицательное подтверждение без проверенного маршрута не считается обработанным исходом.</li><li>Проверьте отрицательный путь на интеграционном стенде: оборвите соединение после записи результата и до ack, затем подайте повтор. Отдельно отправьте невалидный payload и убедитесь, что после лимита он перестаёт возвращаться в основную очередь.</li><li>Добавьте наблюдаемость: jobId, attempt, delivery tag, event, resultKey, reason и длительность. Не записывайте в журнал секреты и полное содержимое пользовательского отчёта.</li></ol>\n<h2>Ограничения</h2>\n<p>Описанный алгоритм не говорит, какая база или очередь нужна проекту. Row lock защищает только выбранную запись и не заменяет уникальное ограничение во внешнем хранилище. Состояние в базе и файл в object storage не откатываются одной транзакцией. Если процесс остановился после загрузки файла, нужна проверка существующего ключа и политика очистки незавершённых объектов.</p>\n<p>Лимит retry нельзя выбрать одинаковым для всех задач. Слишком малый лимит превращает краткий сбой в карантин. Слишком большой растягивает задержку и маскирует постоянную ошибку. Backoff и лимит должны учитывать стоимость работы, срок жизни входных данных и допустимую задержку пользователя.</p>\n<p>Учебный код не доказывает поведение конкретной версии broker, client library или policy. Проверяйте ack, redelivery, nack, dead-lettering и восстановление соединения на той конфигурации, которую действительно запускает сервис. Не называйте результат готовым, если проверили только in-memory переходы.</p>\n<h2>Критерий готовности</h2>\n<p>Решение готово, когда два независимых сценария проходят на выбранном окружении. После сбоя между сохранением результата и ack повторная доставка того же <code>jobId</code> не создаёт второй внешний эффект и возвращает один проверяемый <code>resultKey</code>. После постоянной ошибки payload задача достигает <code>quarantined</code> не позднее заданного лимита, причина сохраняется, а сообщение не возвращается в основную очередь. В журнале можно восстановить порядок событий без догадок.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://www.rabbitmq.com/docs/reliability\" target=\"_blank\" rel=\"noopener\">RabbitMQ: Reliability Guide</a> — ответственность producer и consumer, acknowledgements, повторная передача и at-least-once доставка.</li><li><a href=\"https://www.rabbitmq.com/docs/next/confirms\" target=\"_blank\" rel=\"noopener\">RabbitMQ: Consumer Acknowledgements and Publisher Confirms</a> — семантика consumer ack, requeue и восстановление неподтверждённых delivery.</li><li><a href=\"https://www.rabbitmq.com/docs/next/dlx\" target=\"_blank\" rel=\"noopener\">RabbitMQ: Dead Letter Exchanges</a> — условия dead-lettering и настройка маршрута для сообщений, которые нельзя возвращать в основную очередь.</li></ul>"
}