멱등성(Idempotency) Key API 경계

Idempotency Key     = 재시도되는 같은 작업 단위의 식별자
Request Fingerprint = key 오용을 막기 위한 의미 기반 요청 해시 (canonical JSON + SHA-256)
Reserve -> Execute -> Complete | RetryableFail | Unknown
                    = 실행권 선점 후 결과를 replay/retry/reconcile 가능 상태로 확정
Fail(evict)         = '실행되지 않았음이 확실한 실패'에만 예약 해제 (zombie key 방지)
Unknown/Reconcile   = 실행됐을 수도 있는 실패(gateway timeout 등)는 evict 금지, reconcile
Replay              = 같은 key + 같은 fingerprint에 저장된 응답 반환
Boundary Policy     = 도메인 중복과 인프라 실패를 분리

POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
  "customerId": "cus-1",
  "amountCents": 12000,
  "currency": "KRW"
}

처음 보는 key인가            -> 결제 생성 실행
완료된 같은 key + 같은 fp     -> 저장된 응답 replay
같은 key가 아직 실행 중인가   -> 409 Conflict 또는 202 Accepted + Retry-After
같은 key인데 fp가 다른가      -> idempotency key misuse (422)
직전 실행이 side effect 없음이 확실한 실패인가 -> 재실행 허용
직전 실행 결과가 불명확한가                    -> 재실행 금지, reconcile

using System;
using System.Collections.Generic;

public enum IdempotencyStatus { InProgress, Completed }

public enum IdempotencyDecisionKind { Execute, Replay, InProgress, KeyMisuse }

public sealed record ApiResponse(int StatusCode, string Body);

public sealed record IdempotencyDecision(
    IdempotencyDecisionKind Kind,
    ApiResponse? Response);

public sealed class IdempotencyEntry
{
    public IdempotencyEntry(string fingerprint)
    {
        this.Fingerprint = fingerprint;
        this.Status = IdempotencyStatus.InProgress;
    }

    public string Fingerprint { get; }
    public IdempotencyStatus Status { get; private set; }
    public ApiResponse? Response { get; private set; }

    public void Complete(ApiResponse response)
    {
        this.Response = response;
        this.Status = IdempotencyStatus.Completed;
    }
}

public sealed class InMemoryIdempotencyStore
{
    private readonly object gate = new();
    private readonly Dictionary<string, IdempotencyEntry> entries = new();

    public IdempotencyDecision Reserve(string key, string fingerprint)
    {
        lock (this.gate)
        {
            if (!this.entries.TryGetValue(key, out IdempotencyEntry? entry))
            {
                this.entries[key] = new IdempotencyEntry(fingerprint);
                return new IdempotencyDecision(IdempotencyDecisionKind.Execute, null);
            }
            if (entry.Fingerprint != fingerprint)
            {
                return new IdempotencyDecision(IdempotencyDecisionKind.KeyMisuse, null);
            }
            if (entry.Status == IdempotencyStatus.InProgress)
            {
                return new IdempotencyDecision(IdempotencyDecisionKind.InProgress, null);
            }
            return new IdempotencyDecision(IdempotencyDecisionKind.Replay, entry.Response);
        }
    }

    public void Complete(string key, ApiResponse response)
    {
        lock (this.gate)
        {
            this.entries[key].Complete(response);
        }
    }

    // 실행되지 않았음이 확실한 실패에만 예약을 제거해 같은 key 재시도를 허용한다.
    // 실행 여부가 불명확한 실패는 운영 모델에서 unknown/reconcile로 처리한다.
    public void Fail(string key)
    {
        lock (this.gate)
        {
            if (this.entries.TryGetValue(key, out IdempotencyEntry? entry)
                && entry.Status == IdempotencyStatus.InProgress)
            {
                this.entries.Remove(key);
            }
        }
    }
}

type ApiResponse = Readonly<{ statusCode: number; body: unknown }>;

type IdempotencyStatus = "inProgress" | "completed";

type IdempotencyDecision =
  | Readonly<{ kind: "execute" }>
  | Readonly<{ kind: "replay"; response: ApiResponse }>
  | Readonly<{ kind: "inProgress" }>
  | Readonly<{ kind: "keyMisuse" }>;

type IdempotencyEntry = {
  fingerprint: string;
  status: IdempotencyStatus;
  response?: ApiResponse;
};

export class InMemoryIdempotencyStore {
  readonly #entries = new Map<string, IdempotencyEntry>();

  public reserve(key: string, fingerprint: string): IdempotencyDecision {
    const entry = this.#entries.get(key);
    if (entry === undefined) {
      this.#entries.set(key, { fingerprint, status: "inProgress" });
      return { kind: "execute" };
    }
    if (entry.fingerprint !== fingerprint) {
      return { kind: "keyMisuse" };
    }
    if (entry.status === "inProgress") {
      return { kind: "inProgress" };
    }
    return { kind: "replay", response: entry.response! };
  }

  public complete(key: string, response: ApiResponse): void {
    const entry = this.#entries.get(key);
    if (entry === undefined) {
      throw new RangeError("예약되지 않은 idempotency key입니다.");
    }
    entry.status = "completed";
    entry.response = response;
  }

  public fail(key: string): void {
    const entry = this.#entries.get(key);
    if (entry !== undefined && entry.status === "inProgress") {
      this.#entries.delete(key);
    }
  }
}

import threading
from dataclasses import dataclass
from enum import Enum


@dataclass(frozen=True)
class ApiResponse:
    status_code: int
    body: object


class IdempotencyStatus(Enum):
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"


class IdempotencyDecisionKind(Enum):
    EXECUTE = "execute"
    REPLAY = "replay"
    IN_PROGRESS = "in_progress"
    KEY_MISUSE = "key_misuse"


@dataclass
class IdempotencyEntry:
    fingerprint: str
    status: IdempotencyStatus
    response: ApiResponse | None = None


@dataclass(frozen=True)
class IdempotencyDecision:
    kind: IdempotencyDecisionKind
    response: ApiResponse | None = None


class InMemoryIdempotencyStore:
    def __init__(self) -> None:
        self._entries: dict[str, IdempotencyEntry] = {}
        # GIL은 단일 바이트코드 원자성만 보장한다. get -> if -> set 같은
        # check-then-act 복합 연산은 원자적이지 않으므로 Lock으로 임계구역을 보호한다.
        self._lock = threading.Lock()

    def reserve(self, key: str, fingerprint: str) -> IdempotencyDecision:
        with self._lock:
            entry = self._entries.get(key)
            if entry is None:
                self._entries[key] = IdempotencyEntry(
                    fingerprint=fingerprint,
                    status=IdempotencyStatus.IN_PROGRESS,
                )
                return IdempotencyDecision(kind=IdempotencyDecisionKind.EXECUTE)
            if entry.fingerprint != fingerprint:
                return IdempotencyDecision(kind=IdempotencyDecisionKind.KEY_MISUSE)
            if entry.status == IdempotencyStatus.IN_PROGRESS:
                return IdempotencyDecision(kind=IdempotencyDecisionKind.IN_PROGRESS)
            return IdempotencyDecision(
                kind=IdempotencyDecisionKind.REPLAY,
                response=entry.response,
            )

    def complete(self, key: str, response: ApiResponse) -> None:
        with self._lock:
            entry = self._entries[key]
            entry.status = IdempotencyStatus.COMPLETED
            entry.response = response

    def fail(self, key: str) -> None:
        with self._lock:
            entry = self._entries.get(key)
            if entry is not None and entry.status == IdempotencyStatus.IN_PROGRESS:
                del self._entries[key]

use std::collections::HashMap;
use std::sync::Mutex;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ApiResponse {
    pub status_code: u16,
    pub body: String,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum IdempotencyStatus { InProgress, Completed }

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum IdempotencyDecision {
    Execute,
    Replay { response: ApiResponse },
    InProgress,
    KeyMisuse,
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct IdempotencyEntry {
    fingerprint: String,
    status: IdempotencyStatus,
    response: Option<ApiResponse>,
}

#[derive(Debug, Default)]
pub struct InMemoryIdempotencyStore {
    entries: Mutex<HashMap<String, IdempotencyEntry>>,
}

impl InMemoryIdempotencyStore {
    // 학습용 예제라 lock/unwrap을 단순화했다. 운영 코드에서는 요청 경로에서
    // panic(expect)하지 말고, 락 poison과 누락 응답을 Result로 처리해야 한다.
    pub fn reserve(&self, key: &str, fingerprint: &str) -> IdempotencyDecision {
        let mut entries = self.entries.lock().expect("mutex poisoned");
        match entries.get(key) {
            None => {
                entries.insert(
                    key.to_owned(),
                    IdempotencyEntry {
                        fingerprint: fingerprint.to_owned(),
                        status: IdempotencyStatus::InProgress,
                        response: None,
                    },
                );
                IdempotencyDecision::Execute
            }
            Some(entry) if entry.fingerprint != fingerprint => IdempotencyDecision::KeyMisuse,
            Some(entry) if entry.status == IdempotencyStatus::InProgress => {
                IdempotencyDecision::InProgress
            }
            Some(entry) => IdempotencyDecision::Replay {
                response: entry.response.clone().expect("completed response"),
            },
        }
    }

    pub fn complete(&self, key: &str, response: ApiResponse) {
        let mut entries = self.entries.lock().expect("mutex poisoned");
        let entry = entries.get_mut(key).expect("reserved key");
        entry.status = IdempotencyStatus::Completed;
        entry.response = Some(response);
    }

    pub fn fail(&self, key: &str) {
        let mut entries = self.entries.lock().expect("mutex poisoned");
        // get(불변 borrow) 직후 remove(가변 borrow)를 겹치지 않도록 판단을 먼저 끝낸다.
        let should_remove = entries
            .get(key)
            .is_some_and(|entry| entry.status == IdempotencyStatus::InProgress);
        if should_remove {
            entries.remove(key);
        }
    }
}

import { createHash } from "node:crypto";

type CreatePaymentRequest = Readonly<{
  idempotencyKey: string;
  customerId: string;
  amountCents: number;
  currency: "KRW" | "USD";
}>;

type PaymentGateway = Readonly<{
  createPaymentAsync: (request: CreatePaymentRequest) => Promise<Readonly<{ paymentId: string }>>;
}>;

// 최소 canonical 직렬화: top-level 키만 정렬한다. flat request DTO 전용 최소 예제다.
// 주의: nested 객체의 키 순서가 흔들리면 같은 의미의 재시도가 fingerprint 불일치로
// 422(key misuse)로 오탐될 수 있다. nested object, array 내부 object, number
// normalization, Unicode escaping, I-JSON 제약까지 필요하면 재귀 정렬하는 RFC 8785
// (JCS) 구현체를 쓰거나, payload를 flat DTO로 설계해 직렬화 복잡도를 물리적으로 차단한다.
function canonicalJson(value: Record<string, unknown>): string {
  const sorted = Object.keys(value)
    .sort()
    .reduce<Record<string, unknown>>((acc, k) => {
      acc[k] = value[k];
      return acc;
    }, {});
  return JSON.stringify(sorted);
}

function createPaymentFingerprint(request: CreatePaymentRequest): string {
  const canonical = canonicalJson({
    customerId: request.customerId,
    amountCents: request.amountCents,
    currency: request.currency,
  });
  return createHash("sha256").update(canonical, "utf8").digest("hex");
}

function validateCreatePaymentRequest(request: CreatePaymentRequest): void {
  // 길이는 entropy 검증이 아니라 "명백히 나쁜 key"를 거르는 휴리스틱일 뿐이다.
  if (request.idempotencyKey.trim().length < 16) {
    throw new RangeError("idempotencyKey가 너무 짧습니다.");
  }
  if (request.customerId.trim().length === 0) {
    throw new RangeError("customerId는 비어 있을 수 없습니다.");
  }
  if (!Number.isInteger(request.amountCents) || request.amountCents <= 0) {
    throw new RangeError("amountCents는 1 이상 정수여야 합니다.");
  }
}

// NOTE: 이 함수는 예제용 policy hook이며 기본값은 false다(비관적 정책).
// 네트워크 에러는 기본적으로 모두 'Unknown(실행 여부 불명)'으로 간주한다.
// 실제 구현에서는 HTTP client/error type, 전송 단계, gateway 계약을 근거로
// "요청이 하류에 도달하지 않았음"이 증명되는 경우(예: 외부 호출 전 로컬 예외)에만
// true를 반환해야 한다. 외부로 패킷이 나갔다면 무조건 reconcile 대상이다.
function isDefinitelyNotExecuted(error: unknown): boolean {
  void error;
  return false;
}

export async function createPaymentApiAsync(
  request: CreatePaymentRequest,
  store: InMemoryIdempotencyStore,
  gateway: PaymentGateway,
): Promise<ApiResponse> {
  validateCreatePaymentRequest(request);
  const fingerprint = createPaymentFingerprint(request);

  let decision: IdempotencyDecision;
  try {
    decision = store.reserve(request.idempotencyKey, fingerprint);
  } catch {
    // store 장애 시, 결제처럼 중복 비용이 큰 도메인은 fail-closed(요청 거절)한다.
    return { statusCode: 503, body: { code: "idempotency_store_unavailable" } };
  }

  if (decision.kind === "replay") {
    return decision.response;
  }
  if (decision.kind === "inProgress") {
    return { statusCode: 409, body: { code: "idempotency_key_in_progress" } };
  }
  if (decision.kind === "keyMisuse") {
    return { statusCode: 422, body: { code: "idempotency_key_reused_with_different_payload" } };
  }

  try {
    const payment = await gateway.createPaymentAsync(request);
    const response: ApiResponse = {
      statusCode: 201,
      body: { paymentId: payment.paymentId, status: "created" },
    };
    store.complete(request.idempotencyKey, response);
    return response;
  } catch (gatewayError) {
    // 실패 정책은 "실행됐는지"에 따라 갈린다.
    //  - 실행되지 않았음이 확실한 실패(gateway 호출 전 실패 등) -> store.fail로 예약
    //    해제(재실행 허용). zombie key 방지.
    //  - 실행됐을 수도 있는 실패(gateway timeout, 연결 끊김 등) -> evict 금지. 예약을
    //    in-progress로 남겨 reconcile 대상이 되게 하거나, 하류 PG에도 같은 idempotency
    //    key를 전달해 중복 결제를 막는다.
    if (isDefinitelyNotExecuted(gatewayError)) {
      store.fail(request.idempotencyKey);
    }
    throw gatewayError; // 상위에서 5xx로 매핑
  }
}

validateCreatePaymentRequest  = 외부 입력 검증
createPaymentFingerprint      = canonical JSON + SHA-256로 의미 기반 fingerprint 생성
IdempotencyStore.reserve      = key 선점 / replay / misuse / in-progress 판단
PaymentGateway                = 실제 결제 생성 I/O
IdempotencyStore.complete/fail= 실행 결과 저장 / 실패 시 예약 해제
createPaymentApiAsync         = API 응답 정책 조립

Idempotency-Key가 있는가
-> key가 충분히 예측 불가능한가 (클라이언트가 UUID 등으로 생성)
-> payload fingerprint가 안정적으로 계산되는가 (canonical + hash)
-> 처음 보는 key인가
-> 같은 key인데 fingerprint가 다른가
-> 이미 완료된 key인가
-> 아직 실행 중인 key인가
-> 직전 실행이 side effect 없음이 확실한 실패인가 (unknown이면 재실행 금지)
-> 실제 I/O는 한 번만 수행되는가
-> 실패 시 예약이 해제되는가
-> 결과가 replay 가능한 형태로 저장되는가

- key만 비교하고 payload fingerprint를 비교하지 않음
- fingerprint를 단순 join으로 만들어 구분자 삽입/충돌에 취약함
- idempotency key에 이메일, 전화번호, 주민번호 같은 민감정보를 넣음
- tenant/account scope 없이 전역 key로 저장함
- reserve와 domain write가 원자적으로 묶이지 않아 중복 실행됨
- 실행 실패 시 예약을 해제하지 않아 zombie key가 영원히 in-progress로 남음
- 반대로, 결과가 불명한 실패(gateway timeout 등)를 무조건 evict해 중복 결제를 유발함
- response replay에 필요한 status/body/schema version을 저장하지 않음
- 같은 key 재시도에서 201 대신 200을 돌려도 되는지 API 계약이 없음
- idempotency store 장애를 무시하고 결제 생성으로 바로 진행함 (fail-closed 위반)

const processedKeys = new Set<string>();

async function createPaymentBadAsync(
  request: CreatePaymentRequest,
  gateway: PaymentGateway,
): Promise<ApiResponse> {
  if (processedKeys.has(request.idempotencyKey)) {
    return { statusCode: 200, body: { status: "already_processed" } };
  }
  const payment = await gateway.createPaymentAsync(request);
  processedKeys.add(request.idempotencyKey);
  return { statusCode: 201, body: { paymentId: payment.paymentId } };
}

- 결제 생성 후 key를 기록하므로, gateway 성공 직후 프로세스가 죽으면 재시도 때 중복 결제가 가능하다.
- payload fingerprint를 비교하지 않아 같은 key로 다른 결제 요청을 보내도 막지 못한다.
- 저장된 원래 응답을 replay하지 않고 가짜 already_processed 응답을 만든다.
- tenant/account scope가 없다.
- in-progress 상태를 표현하지 못해 동시 요청 두 개가 모두 gateway로 들어갈 수 있다.
- 프로세스 메모리에만 저장하므로 서버 재시작, scale-out, multi-instance 환경에서 깨진다.

CREATE TABLE api_idempotency_keys (
    scope_id             TEXT NOT NULL,
    idempotency_key      TEXT NOT NULL,
    request_fingerprint  TEXT NOT NULL,
    status               TEXT NOT NULL CHECK (status IN
                           ('in_progress','completed','failed_retryable','unknown','expired')),
    response_status_code INTEGER NULL,
    response_body        JSONB NULL,
    response_schema_version INTEGER NULL,
    last_error_code      TEXT NULL,
    locked_until         TIMESTAMPTZ NULL,   -- in-progress zombie 회수용 실행권 임대 만료
    reconcile_after      TIMESTAMPTZ NULL,   -- unknown 상태 대사(reconcile) 예약 시각
    created_at           TIMESTAMPTZ NOT NULL,
    completed_at         TIMESTAMPTZ NULL,
    expires_at           TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (scope_id, idempotency_key)
);

-- 실행권 획득 시도. ON CONFLICT DO NOTHING은 에러를 던지지 않으므로 트랜잭션이 abort되지 않는다.
INSERT INTO api_idempotency_keys
  (scope_id, idempotency_key, request_fingerprint, status, locked_until, created_at, expires_at)
VALUES ($1, $2, $3, 'in_progress', now() + interval '5 minutes', now(), now() + interval '48 hours')
ON CONFLICT (scope_id, idempotency_key) DO NOTHING
RETURNING scope_id;
-- RETURNING이 row를 주면 -> 이 요청이 실행권을 얻음
-- 0 rows(충돌) -> 이미 존재. 이어서 별도 SELECT로 상태/fingerprint/응답 조회

1. transaction 시작
2. INSERT ... ON CONFLICT DO NOTHING RETURNING 실행
3. RETURNING row 있음 -> 실행권 획득
4. 0 rows -> 별도 SELECT로 기존 row 조회 (트랜잭션 abort 없음)
5. fingerprint 다름     -> 422 misuse
6. status=in_progress AND locked_until >  now() -> 409 Conflict 또는 202 + Retry-After
   status=in_progress AND locked_until <= now() -> unknown으로 원자적 전환 후 reconcile
7. status=completed        -> 저장된 response replay
8. status=failed_retryable -> 재실행 허용 (side effect 없음이 확실한 실패)
   status=unknown          -> 재실행 금지, reconcile (side effect 여부 불명)
9. 실행권을 얻은 요청만 domain write 수행
10. domain write와 idempotency row completion을 같은 transaction에서 commit

UPDATE api_idempotency_keys
SET status = 'in_progress',
    locked_until = now() + interval '5 minutes',
    last_error_code = NULL
WHERE scope_id = $1
  AND idempotency_key = $2
  AND request_fingerprint = $3
  AND status = 'failed_retryable'
RETURNING scope_id;
-- RETURNING row 있음 -> 이 요청이 재실행권 획득
-- 0 rows -> 그 사이 다른 요청이 이미 가져갔거나 상태가 바뀜

status=in_progress AND locked_until >  now()  -> 409 Conflict 또는 202 + Retry-After
status=in_progress AND locked_until <= now()  -> 재실행 금지, unknown으로 전환 후 reconcile

UPDATE api_idempotency_keys
SET status = 'unknown',
    reconcile_after = now(),
    last_error_code = 'in_progress_lock_expired'
WHERE scope_id = $1
  AND idempotency_key = $2
  AND request_fingerprint = $3
  AND status = 'in_progress'
  AND locked_until <= now()
RETURNING scope_id;

UPDATE api_idempotency_keys
SET status = 'unknown',
    reconcile_after = now(),
    last_error_code = 'in_progress_lock_expired'
WHERE status = 'in_progress'
  AND locked_until <= now()
RETURNING scope_id, idempotency_key;

- failed_retryable    : 원자적 UPDATE로 in_progress로 전환한 요청만 실행권을 갖는다.
- unknown             : 어떤 클라이언트 재시도도 실행권을 못 얻고, reconcile 파이프라인만
                        completed/failed_retryable로 전이시킨다.
- expired in_progress : 자동 재실행하지 말고 unknown으로 전환해 대사한다.

A. hard delete : expires_at이 지난 row를 pruning job이 물리 삭제한다.
B. soft expire : 감사/분석을 위해 status='expired'로 바꾸고 replay 대상에서 제외한다.

api.idempotency.reserve.created.count
api.idempotency.reserve.replay.count
api.idempotency.reserve.in_progress.count
api.idempotency.reserve.key_misuse.count
api.idempotency.reserve.failed_retry.count
api.idempotency.reserve.unknown.count
api.idempotency.store.error.count
api.idempotency.zombie_key.count
api.idempotency.ttl_pruned.count
api.idempotency.reconcile.scheduled.count
api.idempotency.reconcile.resolved.count
api.idempotency.reconcile.failed.count

POST를 안전하게 재시도하려면 key, fingerprint, durable replay, 실패 해제를 함께 설계하라.