Серверный state machine: четыре состояния idempotency key

POST с Idempotency-Key K1 прилетает на сервер. Через две секунды тот же ключ прилетает снова — но поле amount изменилось. Проиграть старый ответ? Обработать новое списание? Отказать? Неправильный выбор — либо потерянное изменение, либо двойное списание.

Четыре состояния

Когда запрос с Idempotency-Key приходит, сервер ищет ключ в кеше дедупликации (таблица Postgres или запись Redis). Ровно четыре исхода:

1. New — строки для этого ключа нет. Сервер вставляет (key, fingerprint, status=in_progress, expires_at) в той же транзакции, что бизнес-логика, обрабатывает работу, затем обновляет строку: (response_body, response_status, status=completed).

2. In-flight — строка с status=in_progress существует. Другой запрос уже обрабатывает этот ключ конкурентно. Сервер возвращает 409 Conflict с {"error": "idempotency key in use"} немедленно. Клиент откатывается и ретраит.

3. Replay — строка с status=completed и сохранённым ответом. Сервер возвращает кешированный body и status code без повторного запуска бизнес-логики. Клиент получает одно подтверждение. Клиент списан один раз.

4. Mismatch — строка для этого ключа есть, но fingerprint входящего запроса не совпадает. Клиент переиспользовал ключ с другим намерением (другая сумма, другой получатель). Сервер возвращает 422 Unprocessable Entity. Клиент должен сгенерировать новый ключ для новой операции.

Почему fingerprint запроса важен

Fingerprint — это хеш тела запроса (и опционально метода, пути и ключевых заголовков). Stripe хеширует body; платёжные API, зависящие от Stripe-Account, включают его явно.

Без fingerprint клиент, случайно переиспользовавший ключ для другой суммы, молча получит исходный ответ — новая сумма потеряна навсегда. Fingerprint превращает это в явную ошибку (422) вместо молчаливой потери данных.

Стоимость: одна SHA-256 на запрос — микросекунды. Дешёвая страховка.

Где хранить кеш

Таблица Postgres (простая, durable):

CREATE TABLE idempotency_keys (
  key          TEXT PRIMARY KEY,
  fingerprint  TEXT NOT NULL,
  response_body JSONB,
  response_status INT,
  status       TEXT NOT NULL DEFAULT 'in_progress',
  expires_at   TIMESTAMPTZ NOT NULL
);
CREATE INDEX ON idempotency_keys (expires_at);

Дневная cleanup-задача удаляет строки с истёкшим expires_at. Stripe v1 держал ключи 24 часа; v2 расширил до 30 дней.

Redis с TTL (высокий throughput): SETNX key value EX ttl_seconds — атомарный set-if-not-exists. Redis быстрее, но рискует потерять записи при async-fsync сбое. Платёжные API с юридической ответственностью держат авторитетную запись в Postgres и используют Redis как hot-path read-through cache.