Идемпотентность обработчиков

Перечислим источники повторов по механике процессора. Первый — ошибка хендлера: процессор ловит возвращённую ошибку и перемещает задачу из active в retry с паузой по политике из шестого урока; следующая попытка начинает всю работу с нуля. Второй — таймаут или дедлайн из одиннадцатого урока: контекст отменяется, попытка засчитывается неудачей, и задача уходит в тот же retry, при этом хендлер к моменту отмены мог успеть списать деньги или отправить письмо — частичный эффект уже в мире. Третий источник — смерть воркера между «сделал» и «отметил»: успех фиксируется записью задачи в Redis, и если процесс умер раньше, задача остаётся в active до истечения lease; recoverer собирает задачи с истёкшим lease и возвращает их в retry, а при исчерпании попыток — в архив. Порог в тридцать секунд закладывает запас на рассинхрон часов между машинами. Тот же сценарий разворачивается на каждом деплое: девятнадцатый урок покажет, как плавная остановка возвращает недоделанные задачи в очередь. Все три источника объединяет одно: повтор — не исключение, а штатный маршрут, и проектировать хендлер нужно от него, а не от счастливого пути.

Идемпотентной называется операция, которую можно повторить сколько угодно раз с тем же результатом, что и один раз. Бытовые примеры откалибруют интуицию. Кнопка вызова лифта идемпотентна: хоть десять нажатий, лифт приедет один. «Списать тысячу рублей» — не идемпотентно: каждое исполнение уменьшает баланс, и двойной ретрай даёт двойное списание. «Довести баланс до минус тысячи, если он ещё не там» — уже идемпотентно: второй вызов видит сделанное и выходит. «Отправить письмо» — не идемпотентно: письмо уйдёт дважды, и пользователь заметит. «Убедиться, что письмо про заказ 42 отправлено» — идемпотентно, если факт отправки где-то фиксируется. Обратите внимание на форму: идемпотентность почти всегда означает проверку «уже сделано?» перед эффектом, а значит — место, где этот факт хранится. В asynq идемпотентность не добавляется опцией: библиотека честно доставляет задачу и честно ретраит, а гарантию «эффект один раз» строит только ваш хендлер — базой, ключом и порядком действий. Хорошая новость в том, что конструкция одна и та же для любых эффектов, и дальше мы её соберём на примере платежа. Заметьте и цену вопроса: проверка «уже сделано?» — это лишний запрос к базе в каждой попытке, включая первую. На нагрузках очереди это незаметно: попытка и так пишет в базу, ещё один SELECT EXISTS не меняет картину. Дешевле обойтись без проверки нельзя: альтернатива — «сначала сделать, потом узнать о повторе», и это ровно тот сценарий, ради которого всё затевалось.

Идемпотентность начинается с ключа — того, по чему повторная попытка узнаёт «свою» работу. Честных варианта два. Первый — task ID: он выдаётся на постановке и сохраняется у задачи на все ретраи, а достаётся в хендлере из контекста функцией GetTaskID; если ID задан явно опцией TaskID из четвёртого урока, он к тому же осмыслен для бизнеса. Второй — бизнес-ключ в payload: event_id вебхука, номер заказа, идентификатор записи; требования к нему те же, что к каноничному payload из двенадцатого урока, — детерминированность и нормализация без time.Now() и гуляющих порядков. Ключ сам по себе ничего не делает: нужен факт «эта работа уже сделана». Обычно это таблица processed_tasks или прямая запись в бизнес-таблице — платежи со столбцом task_id — плюс уникальный индекс на ключе. Проверка «есть ли запись», сам эффект и вставка отметки выполняются в одной транзакции: тогда две параллельные попытки не разъедутся — вторая либо увидит отметку, либо упрётся в уникальный индекс. Транзакция заодно даёт атомарность внутри попытки: упали между списанием и отметкой — откатилось всё, и повтор начнёт с чистого листа.

Пройдём по решению и разберём, почему оно именно такое. Проверка стоит до эффекта: сначала смотрим payments, потом списываем — обратный порядок сначала сделает работу, а потом узнает о повторе. Повторная попытка возвращает nil, а не ошибку: найденный платёж означает, что работа сделана, и задача честно закрывается как успешная; ошибка здесь отправила бы уже исполненную работу в вечный ретрай до исчерпания попыток и в архив. Транзакция покрывает три шага сразу: чтение, списание, вставку отметки — если попытка умерла в середине, база откатится целиком, и следующая попытка увидит чистое состояние; половинных эффектов не бывает. defer tx.Rollback() подстраховывает ранние выходы: при успешном Commit он сработает вхолостую и безвредно. Уникальный индекс — последний барьер: даже если две разные задачи несут один и тот же ключ, вторая вставка упадёт с ошибкой constraint, и её стоит трактовать как «уже сделано», а не как сбой. Этот же каркас закрывает и таймауты: хендлер, отменённый посреди работы, оставит после себя откат — и повтор начнёт заново, безопасно.

Двенадцатый урок обещал эту встречу: Unique и идемпотентность выглядят как одно и то же, но закрывают разные двери. Unique — защита на входе: дубликат постановки не попадёт в очередь, повторный вебхук и двойное нажатие кнопки отсекаются замком с TTL. Идемпотентность — защита на выходе: даже единственная постановка исполняется повторно при ретрае после сбоя, и хендлер обязан это пережить. Система, у которой есть только Unique, теряет деньги на первом же краше после списания; система только с проверкой в хендлере захламляет очередь дубликатами, которые честно исполняются и выходят по nil. Взрослый сервис ставит обе скобки: Unique или TaskID с ErrTaskIDConflict против дубликатов постановки, проверка по ключу в хендлере против повторов исполнения. Заметьте, что TaskID участвует в обеих: детерминированный ID отсекает повторную постановку ещё на Enqueue и одновременно служит ключом проверки в базе. Какая скобка важнее? Идемпотентность: она единственная стоит между ретраем и двойным списанием, а Unique — оптимизация входа, без которой можно начать.