안전성과 멱등성 — 어떤 요청을 다시 보내도 되는가

# Demonstrate: PUT 은 retry 안전; POST 는 아님.

# PUT — idempotent. 5번 돌려 봐; user 항상 동일 상태.
for i in {1..5}; do
  curl -X PUT https://api.example.com/users/42 \
    -H 'Content-Type: application/json' \
    -d '{"name":"Pippa","role":"daughter"}'
done
# 최종 state: user 42 가 정확히 그 한 user. 중복 없음, 추가 row 없음.

# POST — not idempotent. 5번 돌리면 user 5개 다른 거 나옴.
for i in {1..5}; do
  curl -X POST https://api.example.com/users \
    -H 'Content-Type: application/json' \
    -d '{"name":"Pippa"}'
done
# 최종 state: 별개 user row 5개, 각각 다른 생성 id.

# Idempotency 존중하는 retry decorator
import time
import httpx

IDEMPOTENT_METHODS = {'GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'}

def safe_retry(request: httpx.Request, max_retries: int = 3):
    """Idempotent request retry; not-idempotent 은 절대 retry 안 함."""
    method = request.method.upper()
    if method not in IDEMPOTENT_METHODS:
        # POST/PATCH — idempotency key 없으면 단일 시도만
        with httpx.Client() as client:
            return client.send(request)

    last_exc = None
    for attempt in range(max_retries):
        try:
            with httpx.Client() as client:
                resp = client.send(request)
                if resp.status_code < 500:
                    return resp  # 성공 혹은 retry 불가한 client 에러
        except httpx.RequestError as e:
            last_exc = e  # transport 에러 — retry
        time.sleep(2 ** attempt)  # exponential backoff
    raise last_exc or Exception('retry 다 소진')

# Idempotency-Key 패턴 — POST 를 안전하게 retry 가능하게 (Stripe convention)
from fastapi import FastAPI, Header, HTTPException, status
import uuid

app = FastAPI()
_seen_keys: dict[str, dict] = {}  # production 엔 Redis + TTL

@app.post('/payments')
async def create_payment(
    payload: dict,
    idempotency_key: str | None = Header(None, alias='Idempotency-Key'),
):
    if idempotency_key:
        # 본 key 의 반복? Cached response 돌려줌.
        if idempotency_key in _seen_keys:
            return _seen_keys[idempotency_key]

    # 처음 본 key — 실제 작업
    payment_id = str(uuid.uuid4())
    result = {'id': payment_id, 'amount': payload['amount'], 'status': 'charged'}

    if idempotency_key:
        _seen_keys[idempotency_key] = result
    return result

# Client 사용:
# curl -X POST https://api.example.com/payments \
#   -H 'Idempotency-Key: client-generated-uuid-7abc' \
#   -H 'Content-Type: application/json' \
#   -d '{"amount": 1000}'
# 같은 key 로 정확히 이 request 재시도 — 같은 payment_id, 중복 청구 없음.