{
  "index": 272,
  "slug": "editorial-2020-06-mechanism-retry-idempotency",
  "title": "Идемпотентный retry: как не выполнить одну команду дважды",
  "excerpt": "Клиент получил timeout, но сервер мог уже создать результат. Разбираем scope ключа, fingerprint payload, конкурентный запрос, сохранённый ответ и границу внешнего эффекта.",
  "contentHtml": "<p>Симптом знакомый: пользователь нажал «Создать», увидел timeout и нажал ещё раз. В базе появились две заявки. Иногда дубль возникает без второго клика: клиент повторяет POST после разрыва соединения, пока первый обработчик ещё работает. Цена ошибки зависит от операции. Две строки в черновике можно удалить. Два платежа, письма или заказа требуют ручного разбора и возврата денег.</p>\n<p>Timeout сообщает только об ответе, которого клиент не увидел. Он не доказывает, что сервер не принял запрос. Между принятием команды и доставкой ответа есть база, worker, proxy и сеть. Любой участок может завершить работу, а следующий участок — потерять результат.</p>\n<p>Тезис статьи простой: retry безопасен только тогда, когда сервис связывает повтор с тем же intent и хранит решение операции. Для этого нужны scope ключа, fingerprint значимых данных, атомарный захват ключа, состояние <code>in_progress</code> и сохранённый terminal-ответ. Повтор не должен снова запускать бизнес-обработчик.</p>\n<h2>Что именно делает идемпотентность</h2>\n<p>Идемпотентность не означает «ответ всегда одинаковый» и не означает «в системе не будет побочных эффектов». В HTTP это свойство намеренного эффекта метода: несколько одинаковых запросов должны дать тот же эффект, что один. RFC 9110 относит к идемпотентным PUT, DELETE и безопасные методы. POST сам по себе таким свойством не обладает.</p>\n<p>Для POST сервис может добавить собственный контракт. Клиент создаёт ключ на один пользовательский intent и сохраняет его до получения окончательного результата. При сетевом сбое он отправляет тот же payload с тем же ключом. Сервер узнаёт повтор, возвращает прежний результат и не создаёт новый объект.</p>\n<p>Ключ относится к действию, а не к сетевой попытке. <code>requestId</code> может меняться на каждом HTTP-проходе. <code>Idempotency-Key</code> должен оставаться тем же для одного intent. Если на retry сгенерировать новый ключ, сервер увидит новую команду и защита не сработает.</p>\n<h2>Scope и fingerprint</h2>\n<p>Один ключ не обязан быть уникальным во всей системе. Сервис задаёт scope. В учебном примере это <code>actor_id</code>, имя операции и <code>idem_key</code>. Одинаковая строка ключа у двух пользователей не должна открыть один результат. Одинаковая строка в другой операции не должна заблокировать её.</p>\n<p>Одного scope мало. Клиент может по ошибке повторно использовать ключ с другим payload. Поэтому при первом запросе сервис вычисляет fingerprint по каноническим значимым полям. Повтор с тем же ключом и тем же fingerprint — кандидат на replay. Тот же ключ с другим fingerprint — конфликт. Обработчик не запускается.</p>\n<p>Канонизация входит в API-контракт. Нужно заранее определить, какие поля влияют на эффект. Порядок ключей JSON, пробелы и display-поля не должны случайно превращать тот же intent в другой. Поля авторизации, которые задают scope, не смешивают с payload fingerprint: субъект проверяется отдельно.</p>\n<figure><img src=\"/assets/editorial/2020/retry-idempotency-state-contract-2020.svg\" alt=\"Диаграмма состояний записи идемпотентности: новый ключ переходит в in_progress, параллельный повтор получает конфликт, завершённый запрос возвращает сохранённый ответ, другой fingerprint останавливается до эффекта\" loading=\"lazy\" /><figcaption>Ключ связывает scope, fingerprint и одно решение. Он не кэширует успех вообще: он защищает конкретный intent.</figcaption></figure>\n<h2>Состояния записи</h2>\n<p>Минимальная запись хранит scope, fingerprint, состояние, срок действия и данные replay. Для terminal-состояния достаточно статуса, безопасного тела ответа и идентификатора результата. Сохранять в этой таблице токены, cookies и полный запрос не нужно. Слишком бедная запись тоже опасна: если в ней нет результата, повтор снова вынужден угадывать.</p>\n<table><caption>Что нужно сохранить для одного ключа</caption><thead><tr><th scope=\"col\">Поле</th><th scope=\"col\">Задача</th><th scope=\"col\">Что проверить</th></tr></thead><tbody><tr><td><code>actor_id + operation + idem_key</code></td><td>Описывает scope и захватывает intent</td><td>В базе есть составное уникальное ограничение</td></tr><tr><td><code>payload_hash</code></td><td>Отличает retry от подмены payload</td><td>Значимое изменение даёт конфликт до обработчика</td></tr><tr><td><code>state</code></td><td>Разделяет <code>in_progress</code> и terminal</td><td>Параллельный запрос не начинает второй handler</td></tr><tr><td><code>status_code + response_body</code></td><td>Возвращает тот же наблюдаемый результат</td><td>Готовый retry получает тот же result ID</td></tr><tr><td><code>expires_at</code></td><td>Задаёт окно повторного распознавания</td><td>TTL длиннее согласованного retry budget</td></tr></tbody></table>\n<p>Сервис не должен считать запись <code>seen=true</code> достаточной. Такой флаг не отвечает на три вопроса: обработчик ещё выполняется, операция завершилась ошибкой или результат уже сохранён? Разные ответы требуют разных действий. <code>in_progress</code> нельзя молча трактовать как новый запуск.</p>\n<h2>Атомарный захват в хранилище</h2>\n<p>Проверка в памяти процесса не защищает второй pod, worker или рестарт. Уникальность должна жить в устойчивом хранилище, где конкурирующие запросы видят один результат. Первый запрос вставляет запись в scope. Только тот, кто успешно вставил строку, получает право вызвать бизнес-обработчик.</p>\n<pre><code>BEGIN;\n\nINSERT INTO idempotency_keys (\n  actor_id, operation, idem_key, payload_hash, state, expires_at\n) VALUES ($1, $2, $3, $4, 'in_progress', $5)\nON CONFLICT (actor_id, operation, idem_key) DO NOTHING;\n\n-- если вставлена строка: этот запрос владеет обработкой\n-- если строка уже была: читаем state и payload_hash\n\nCOMMIT;</code></pre>\n<p>SQL — учебная иллюстрация, а не готовая схема для конкретного проекта. Драйвер должен надёжно различать вставку и конфликт. После конфликта сервис читает существующую запись и выбирает ветку. Он не вызывает основной обработчик до этого решения.</p>\n<h2>Четыре наблюдаемые ветки</h2>\n<table><caption>Симптом → причина → проверка → действие</caption><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>Первый запрос вставил запись</td><td>Ключ свободен в заданном scope</td><td>Текущая транзакция получила право обработки</td><td>Запустить один handler и завершить запись terminal-результатом</td></tr><tr><td>Повтор видит <code>completed</code></td><td>Первый запрос уже сохранил решение</td><td>Есть status, body и result ID</td><td>Вернуть сохранённый HTTP-ответ без нового эффекта</td></tr><tr><td>Повтор видит <code>in_progress</code></td><td>Первый handler ещё не завершил договор</td><td>Terminal-записи нет, ключ занят</td><td>Вернуть документированный conflict или статус ожидания; не запускать второй handler</td></tr><tr><td>Тот же ключ имеет другой hash</td><td>Ключ повторно использовали для другого intent</td><td>Сравнить hash до business action</td><td>Вернуть <code>409 Conflict</code> с машинной причиной; попросить новый intent</td></tr><tr><td>Два result ID имеют один scope/key</td><td>Захват неатомарен или часть writers обошла контракт</td><td>Сопоставить SQL, pod, время и внешние вызовы</td><td>Остановить blind retry и исправить общую границу конкурентного доступа</td></tr></tbody></table>\n<p>Для <code>in_progress</code> API выбирает одну семантику и документирует её. Можно вернуть конфликт с полем <code>code=operation_in_progress</code>. Можно дать клиенту endpoint проверки статуса. Нельзя скрыть этот случай за обычным retry без ключа: он снова создаст гонку.</p>\n<h2>Сохраняем terminal-ответ</h2>\n<p>Обработчик должен завершить запись тем результатом, который увидит клиент. Если объект и запись ключа лежат в одной базе, их можно сохранить одной транзакцией. После commit повтор найдёт оба факта и вернёт status и result ID. Если процесс упал до commit, следующий запрос увидит незавершённую транзакцию и сможет начать обработку по правилам базы.</p>\n<pre><code>async function createOnce(input, key, actorId) {\n  const hash = fingerprint(input);\n  const claim = await reserve(actorId, 'demo.create', key, hash);\n\n  if (claim.kind === 'replay') return claim.response;\n  if (claim.kind === 'conflict') throw new HttpError(409, 'key_payload_mismatch');\n  if (claim.kind === 'in_progress') throw new HttpError(409, 'operation_in_progress');\n\n  try {\n    const result = await createResultAndFinishAtomically(input, claim.id);\n    return result.response;\n  } catch (error) {\n    await markTerminalFailure(claim.id, safeError(error));\n    throw error;\n  }\n}</code></pre>\n<p>Псевдокод показывает порядок, но не обещает конкретный статус ошибки, библиотеку базы или способ восстановления. На практике нужно решить, какие ошибки считаются terminal. Если обработчик не стартовал из-за валидации, ключ можно не резервировать или сохранить отказ по отдельному контракту. Если внешний эффект уже принят, удалять запись после исключения опасно.</p>\n<h2>Внешняя система ломает локальную атомарность</h2>\n<p>Локальная таблица не делает внешний вызов exactly once. Сервис может отправить запрос поставщику, получить результат, а затем упасть до сохранения <code>completed</code>. После рестарта запись выглядит зависшей, хотя внешний объект уже создан. Очистка ключа и новый вызов могут создать дубль.</p>\n<p>Для внешнего эффекта нужен второй договор. Используйте устойчивый business ID, детерминированное имя объекта, idempotency key поставщика или endpoint проверки состояния. Восстановление <code>in_progress</code> должно сначала узнать, был ли эффект принят, и только потом решать, допустим ли повтор. Если такой проверки нет, автоматический retry нужно остановить и передать неопределённый исход в безопасный маршрут.</p>\n<p>Это отрицательный путь механизма. Идемпотентность не отменяет уже отправленное письмо и не откатывает платёж в другой системе. Она лишь даёт локальную запись, с которой можно продолжить расследование. Граница транзакции должна быть явно отмечена в архитектуре.</p>\n<h2>Порядок проверки</h2>\n<ol><li>Запишите один intent: субъект, операцию, значимые поля payload и допустимое окно retry.</li><li>Разделите идентификаторы: новый <code>requestId</code> для каждой доставки, один <code>Idempotency-Key</code> для одного intent.</li><li>Определите канонизацию и вычислите fingerprint. Проверьте, что изменение значимого поля даёт conflict до эффекта.</li><li>Добавьте составное уникальное ограничение в устойчивое хранилище. Запустите два конкурентных запроса с одним scope и одним ключом.</li><li>Проверьте все четыре ветки: claim, replay, in-progress и payload mismatch. Для каждой зафиксируйте HTTP-статус и машинную причину.</li><li>Сымитируйте потерю ответа после сохранения результата. Повторите тот же payload с тем же ключом и подтвердите один result ID.</li><li>Перезапустите процесс после начала внешнего вызова. Проверьте статус внешнего эффекта до любого повторного вызова.</li><li>Проверьте TTL только на terminal-записях. Убедитесь, что поздний повтор после очистки явно запрещён или создаёт новый intent по документации.</li></ol>\n<h2>Ограничения</h2>\n<p>Ключ не заменяет аутентификацию, авторизацию, валидацию, rate limit и защиту от перегрузки. Он не спасает, если разные writers используют разные scope или один путь вызывает внешний эффект до резервирования записи. Он также не гарантирует exactly once между двумя независимыми системами.</p>\n<p>Нельзя выбрать TTL по удобству таблицы. Он должен учитывать максимальный retry budget клиента, задержку proxy и время, после которого API запрещает поздний повтор. Слишком короткий TTL превращает поздний retry в новый эффект. Слишком длинный TTL удерживает результат и чувствительные данные без необходимости.</p>\n<p>Все адреса, SQL, ключи, result ID и ответы ниже учебные. Реальный endpoint, база, proxy, нагрузка и платёжная интеграция здесь не запускались. Перед внедрением нужно проверить конкурентные транзакции, размер response body, правила хранения данных и поведение каждого внешнего поставщика.</p>\n<h2>Критерий готовности</h2>\n<p>Механизм готов, когда два конкурентных запроса с одним scope и ключом создают один effect; повтор после искусственно потерянного ответа возвращает сохранённый result ID; другой payload с тем же ключом получает conflict до обработчика; зависший внешний вызов имеет отдельный статусный маршрут; а TTL не открывает неоговорённый поздний retry. Эти условия должны быть проверены интеграционным тестом в выбранном стеке и видны в безопасных логах.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods\" target=\"_blank\" rel=\"noopener noreferrer\">RFC 9110, раздел 9.2.2: Idempotent Methods</a> — семантика идемпотентных HTTP-методов и повтор после ошибки связи.</li><li><a href=\"https://docs.stripe.com/api/idempotent_requests\" target=\"_blank\" rel=\"noopener noreferrer\">Stripe API: Idempotent requests</a> — официальный пример сохранения status и body, проверки параметров и обработки конкурентного запроса.</li><li><a href=\"https://www.postgresql.org/docs/current/ddl-constraints.html\" target=\"_blank\" rel=\"noopener noreferrer\">PostgreSQL: Constraints</a> — официальная документация об ограничениях, включая уникальность, на которой строится учебный claim.</li></ul>"
}