project-auth-server/docs/standards/integration/idempotency.md

Integration Idempotency 기준

1. 목적

이 문서는 외부 API / integration 호출에서 outbound idempotency 를 어떻게 다룰지 정의한다.

이 문서의 목표는 다음과 같다.

• 외부 provider가 제공하는 idempotency 기능을 안전하게 사용한다
• timeout, partial failure, 응답 유실 상황에서 중복 side effect 를 막는다
• 우리 내부 idempotency key와 provider idempotency key의 관계를 명확히 한다
• 외부 API 재시도 시 어떤 조건에서 같은 key를 재사용해야 하는지 정한다

2. 근거 수준

• Official: IETF HTTPAPI draft, Stripe, PayPal 공식 문서에서 직접 확인되는 내용
• Official + Practice: 공식 규약 위에 일반적인 연동 운영 관행을 결합한 내용
• Project Recommendation: 이 프로젝트 구조와 운영 방식에 맞춘 규칙

3. 기본 원칙

3.1 이 문서는 inbound가 아니라 outbound idempotency를 다룬다

IETF 초안은 Idempotency-Key를 클라이언트가 서버에 보내는 중복 방지 키로 설명한다. 우리 서비스가 provider를 호출할 때는, 우리가 그 provider 입장에서 “클라이언트”가 된다. 따라서 이 문서는 “사용자가 우리 API를 다시 호출하는 상황”이 아니라, “우리가 외부 provider에 같은 요청을 다시 보내는 상황”을 다룬다.

프로젝트 규칙:

• inbound idempotency와 outbound idempotency를 같은 문서로 뒤섞지 않는다
• 이 문서는 provider 호출용 키 생성/재사용/저장/오류 처리 규칙만 정의한다

3.2 outbound idempotency의 핵심 목적은 “같은 외부 side effect를 한 번만 일으키는 것”이다

Stripe는 생성/수정 요청에 idempotency key를 사용하면 연결 오류나 응답 유실이 있어도 같은 요청을 안전하게 반복할 수 있다고 설명한다. PayPal도 POST 호출에서 PayPal-Request-Id를 사용하면 서버가 중복 생성/처리를 피할 수 있다고 설명한다. 즉 outbound idempotency는 “같은 외부 요청 의도”를 다시 보내더라도 provider 쪽에서 한 번만 처리되게 만드는 장치다.

프로젝트 규칙:

• 외부 생성/확정/발급/결제/전송 같은 side effect 호출에는 outbound idempotency를 기본 검토한다
• “응답을 못 받았으니 다시 보내자” 상황에서 중복 side effect가 나지 않아야 한다

3.3 retry와 outbound idempotency는 함께 설계한다

Stripe는 네트워크 오류가 나더라도 같은 idempotency key를 써서 다시 보내면 중복 생성 위험을 줄일 수 있다고 설명한다. 반대로 key 없이 같은 POST를 다시 보내면 중복 호출이 될 수 있다. PayPal도 PayPal-Request-Id를 생략하면 요청이 중복될 수 있다고 설명한다. 따라서 retry는 outbound idempotency와 분리해서 설계할 수 없다.

프로젝트 규칙:

• side effect가 있는 외부 API retry는 outbound idempotency 검토 없이 자동화하지 않는다
• timeout 이후 retry 전략은 반드시 provider idempotency 지원 여부와 함께 본다

4. 언제 필요한가

4.1 기본 검토 대상

프로젝트 규칙:

다음은 outbound idempotency 기본 검토 대상이다.

• 결제 승인/확정/캡처
• 토큰/세션/쿠폰/번호 발급
• 이메일/SMS/웹훅 발송 요청
• 외부 시스템에 리소스를 생성하는 POST
• 외부 상태를 irreversible 하게 바꾸는 요청
• timeout 이후 retry 가능성이 높은 provider 호출

Stripe와 PayPal의 공식 idempotency 문서도 이런 POST 중심 side effect 요청을 주된 대상으로 설명한다.

4.2 기본 검토 대상이 아닌 경우

프로젝트 규칙:

다음은 outbound idempotency header를 기본값으로 요구하지 않는다.

• 단순 GET 조회
• provider가 이미 HTTP 의미상 idempotent한 PUT/DELETE만 제공하는 경우
• 읽기 전용 상태 확인 API
• side effect가 없는 health/ping/check API

Stripe도 GET/DELETE에는 idempotency key를 보내도 의미가 없다고 안내한다.

5. provider key와 내부 key의 관계

5.1 provider가 공식 idempotency key를 지원하면 그 계약을 우선 따른다

Stripe는 Idempotency-Key 헤더를, PayPal은 PayPal-Request-Id 헤더를 공식 지원한다. PayPal은 API call type마다 고유해야 한다고도 설명한다. 따라서 provider가 지원하는 공식 키 규약이 있으면 그 규약을 먼저 따른다.

프로젝트 규칙:

• provider 공식 idempotency header가 있으면 그 이름과 제약을 그대로 따른다
• 우리 내부 표준 헤더 이름을 provider에 억지로 강요하지 않는다
• adapter가 provider별 차이를 캡슐화한다

5.2 내부 idempotency key와 provider idempotency key는 같을 수도, 다를 수도 있다

IETF 초안과 Stripe 문서는 key를 클라이언트가 생성하는 고유 값으로 설명하지만, 실제 운영에서는 우리 내부 command id 와 provider 전송용 key 를 같은 값으로 쓸지 별도 매핑할지 설계 선택이 있다. PayPal은 API call type 단위 고유성을 요구하므로, 단순히 “사용자 요청 ID 하나”를 모든 provider operation에 그대로 쓰는 방식은 맞지 않을 수 있다.

프로젝트 규칙:

• 내부 command id와 provider key를 1:1로 매핑할 수는 있다
• 하지만 provider가 operation scope를 다르게 요구하면 별도 provider key를 만든다
• 내부 키와 provider 키를 무조건 동일시하지 않는다

권장 예:

• 내부 키: outboundCommandId
• provider 키: (provider, operation, outboundCommandId) 기반 생성

5.3 provider key scope는 provider 계약을 따른다

PayPal은 PayPal-Request-Id가 “요청마다 그리고 API call type마다” 고유해야 한다고 설명한다. Stripe도 endpoint와 파라미터가 다르면 idempotency error가 난다고 설명한다. 즉 key scope는 provider마다 다를 수 있다.

프로젝트 규칙:

• 같은 key를 다른 provider operation에 재사용하지 않는다
• 같은 provider라도 다른 endpoint/call type에 key 재사용 여부를 provider 계약 기준으로 판단한다
• scope는 최소한 provider + operation + key 수준으로 본다

6. 키 생성 규칙

6.1 키는 우리가 생성한다

Stripe는 V4 UUID 또는 충분한 entropy를 가진 랜덤 문자열을 권장하고, 민감정보를 key로 쓰지 말라고 말한다. PayPal도 UUID 사용을 권장한다.

프로젝트 규칙:

• provider key는 우리 서비스가 생성한다
• 권장 형식은 UUID v4 또는 이에 준하는 opaque random string
• 이메일, 전화번호, 사용자명, 주문번호 같은 의미 있는 PII를 key에 넣지 않는다

6.2 키는 “같은 외부 요청 의도”에만 재사용한다

Stripe는 동일 key에 대해 원래 요청과 들어온 파라미터를 비교하고, 다르면 에러를 반환한다고 설명한다. 따라서 key는 장기 식별자가 아니라 같은 요청의 재전송용 식별자 여야 한다.

프로젝트 규칙:

• 같은 provider 호출을 다시 보낼 때만 같은 key를 재사용한다
• 요청 의미가 달라지면 새 key를 생성한다
• key를 “사용자별 고정 키”처럼 쓰지 않는다

7. 저장 규칙

7.1 outbound provider 호출에도 내부적으로 key 매핑 기록을 남긴다

Stripe와 PayPal은 provider 측 idempotency를 제공하지만, 우리 서비스가 timeout/partial failure를 겪었을 때 “이 key로 이미 보냈는가, 응답을 받았는가, 재전송해야 하는가”를 판단하려면 내부 기록이 필요하다. 공식 문서들도 provider가 이전 요청의 결과나 최신 상태를 반환한다고 설명하므로, 우리 쪽에서도 그 연관관계를 추적해야 운영이 가능하다.

프로젝트 규칙:

내부적으로 다음을 기록할 수 있어야 한다

• provider
• operation
• provider idempotency key
• 내부 command id
• request fingerprint
• provider request status(시도 중/완료/최종 실패)
• provider response reference
• provider가 idempotency를 제공해도 우리 내부 기록을 완전히 생략하지 않는다

7.2 request fingerprint를 함께 저장한다

Stripe는 같은 key 재사용 시 들어온 파라미터를 원래 요청과 비교해 다르면 에러를 낸다고 설명한다. 우리도 내부적으로 같은 key가 다른 요청 의미로 재사용되지 않았는지 확인할 수 있어야 한다.

프로젝트 규칙:

• 내부 저장소에는 key뿐 아니라 request fingerprint도 함께 둔다
• fingerprint는 provider operation 의미를 기준으로 계산한다
• 같은 key + 다른 fingerprint는 버그 또는 오용으로 본다

8. 재전송 규칙

8.1 timeout/응답 유실 시에는 같은 key로 재전송한다

Stripe는 네트워크 연결 오류로 응답을 못 받아도 같은 key로 재시도하면 안전하다고 설명한다. PayPal도 동일한 PayPal-Request-Id를 다시 보내면 이전 요청의 최신 상태를 반환한다고 설명한다.

프로젝트 규칙:

• provider에 요청을 보냈지만 응답을 못 받았으면 같은 key 재전송을 기본 검토한다
• 새 key로 다시 보내는 것을 기본값으로 두지 않는다
• 이 판단은 retry/timeout 정책과 함께 묶어서 설계한다

8.2 provider가 “실행이 시작되지 않았다”고 말한 경우는 새 시도로 볼 수 있다

Stripe는 validation 실패나 concurrent conflict처럼 endpoint 실행이 시작되지 않은 경우에는 결과를 저장하지 않으며, 이런 경우는 다시 시도할 수 있다고 설명한다.

프로젝트 규칙:

• provider가 execution not started에 해당하는 오류를 명시하면 같은 key 재시도 가능성을 검토한다
• validation 자체가 잘못된 요청이라면 재시도보다 요청 수정이 우선이다
• “실행이 시작되지 않았음”과 “응답만 못 받음”을 구분한다

8.3 동시 중복 송신을 피한다

PayPal은 같은 PayPal-Request-Id로 동시에 두 요청을 보내면 첫 번째를 처리하고 두 번째는 실패할 수 있다고 설명한다.

프로젝트 규칙:

• 같은 provider key를 가진 outbound 호출은 동시에 두 개 이상 송신하지 않는다
• 내부적으로 키 단위 동시성 제어를 검토한다
• 같은 command를 여러 worker가 동시에 처리하는 구조라면 key-level dedup/lock을 둔다

9. provider 응답 해석 규칙

9.1 replay 응답은 새 성공과 같은 의미로 취급하되, 출처는 구분 가능해야 한다

Stripe는 같은 key에 대해 첫 결과의 status와 body를 재사용한다고 설명하고, PayPal은 이전 요청의 최신 상태를 반환한다고 설명한다. 즉, provider가 반환한 응답이 “새로 실행된 결과”인지 “기존 실행의 재생/현재 상태”인지 내부적으로는 구분할 수 있는 편이 좋다.

프로젝트 규칙:

• provider replay 응답도 비즈니스적으로는 성공/실패 결과로 받아들인다
• 다만 내부 observability에는
• new execution
• replayed result
• latest known status
• 를 구분할 수 있게 한다
• 외부 API 응답 body를 우리 내부 의미로 무조건 “새로 생성됨”으로 번역하지 않는다

9.2 provider의 “latest status”와 “original result” 차이를 이해한다

PayPal은 이전 요청의 “원래 응답”이 아니라 “현재 시점의 최신 상태”를 반환한다고 설명한다. Stripe는 첫 실행 결과를 재사용하는 쪽에 더 가깝다. provider마다 의미가 다르므로, outbound adapter는 이 차이를 내부로 올바르게 번역해야 한다.

프로젝트 규칙:

• provider replay semantics를 문서화한다
• “같은 key면 항상 동일 body 재생”이라고 일반화하지 않는다
• provider별로
• original response replay
• latest status lookup
• concurrent duplicate failure
• 를 구분한다

10. TTL 규칙

10.1 provider TTL을 존중한다

Stripe는 키를 최소 24시간 이후 정리할 수 있다고 설명한다. PayPal은 일부 API에서 PayPal-Request-Id 보관 기간이 정해져 있고, 그동안 재시도 가능하다고 설명한다.

프로젝트 규칙:

• provider key TTL은 provider 공식 문서 기준을 따른다
• TTL 내 재전송은 같은 key 사용
• TTL 이후는 새 요청으로 처리될 수 있음을 전제로 한다

10.2 내부 기록 TTL은 provider TTL보다 짧게 두지 않는다

프로젝트 규칙:

• 내부 key 매핑 기록 TTL은 provider TTL 이상을 기본 검토한다
• provider는 아직 기억하는데 우리는 잊어버리는 상태를 만들지 않는다
• 최소한 “왜 같은 key가 다시 쓰였는지” 추적 가능한 기간을 확보한다

11. observability 규칙

11.1 outbound idempotency key는 로그에 원문 전체를 남기지 않는다

Stripe는 key에 민감정보를 넣지 말라고 하지만, 그렇다고 로그에 원문 전체를 항상 남겨도 된다는 뜻은 아니다. 외부 키도 운영 식별자일 뿐 민감도 없는 공개값으로 취급하지 않는다.

프로젝트 규칙:

• provider key 원문 전체 로그를 기본 금지
• 필요하면 prefix 또는 내부 correlation id만 남긴다
• 로그에는
• provider
• operation
• outboundCommandId
• providerRequestId
• 정도의 내부 식별자를 우선 사용한다

11.2 replay / duplicate / key mismatch는 관측 가능해야 한다

프로젝트 규칙:

outbound idempotency 관련 운영 이벤트는 최소한 다음을 구분 가능해야 한다

• 새 호출
• 같은 key 재전송
• provider replay 응답
• 같은 key 다른 fingerprint 충돌
• 동시 중복 송신 차단
• retry와 idempotency를 함께 분석할 수 있어야 한다

12. 다른 문서와의 경계

이 문서는 outbound idempotency만 다룬다. 아래 주제의 source of truth는 별도 문서다.

• retry
• timeout
• fallback
• serialization/deserialization
• exception translation

이 문서는 위 주제들을 다시 반복하지 않고, 외부 provider idempotency를 어떻게 써야 하는지만 정의한다.

13. 금지 규칙

다음은 기본 금지다.

• provider 공식 idempotency key 지원이 있는데 무시하고 새 요청처럼 재전송
• 같은 key를 다른 provider operation에 재사용
• 같은 key를 다른 fingerprint 요청에 재사용
• timeout 후 새 key로 같은 side effect 요청 재전송
• provider key와 내부 command 추적 관계를 저장하지 않음
• 같은 key의 동시 중복 송신 허용
• key에 이메일/전화번호/주문자명 같은 의미 있는 PII 사용
• replay semantics가 다른 provider를 같은 규칙으로 단순화

14. 체크리스트

다음 질문에 “예”로 답할 수 있어야 한다.

• 이 outbound 호출은 side effect가 있어 idempotency가 필요한가?
• provider가 공식 idempotency key/header를 지원하는가?
• 내부 key와 provider key의 scope가 명확한가?
• timeout/응답 유실 시 같은 key 재전송 전략이 정의되어 있는가?
• 같은 key의 fingerprint 충돌을 감지할 수 있는가?
• provider TTL과 내부 저장 TTL이 정렬되어 있는가?
• replay/new/latest-status semantics를 provider별로 구분하고 있는가?
• retry와 idempotency가 함께 관측 가능한가?