Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

11 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

IETF draft — The Idempotency-Key HTTP Header Field

Layer: raw/official-docs/ — IETF httpapi 워킹그룹의 Idempotency-Key HTTP 헤더 표준화 초안. ca-tmpl 의 422/409 status code 선택의 표준 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-rate-limit-idempotency-contract	ca-tmpl 의 422 (fingerprint mismatch) / 409 (in-flight) status code 의 표준 근거 + scope 정의 자유 ("resource owner defines")
raw/branch-notes/feature-api-contract-baseline	`Idempotency-Key` 헤더명 채택의 표준 초안 근거 (vendor-specific 헤더명 회피)
raw/project-notes/ca-skeleton-operational-contract	§13. API Contract Surface (Idempotency-Key) + §18. Control Plane Contract — 표준 reference

컨텍스트

ca-tmpl 이 사용하는 422 (fingerprint mismatch) / 409 (in-flight) 상태 코드의 근거를 표준 문서 차원에서 확인. 또한 "scope 는 resource owner 가 정의한다" 는 점이 ca-tmpl triple scope 선택의 정당성 근거가 됨. 정식 RFC 가 아니라 draft 단계이지만 Stripe / PayPal / Square / Adyen 등이 공통 참조하는 사실상의 헤더 표준 초안.

출처 / Source

원본 URL: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
보조: latest draft (draft-07, 2025-10) 의 HTML 렌더링
아카이브 URL: (미수집)
저자 / 조직: IETF httpapi Working Group (Editors: Sanyam Mehra, et al.)
발행일: draft-ietf-httpapi-idempotency-key-header-07 (2025-10)
마지막 확인일: 2026-05-27 (WebFetch 재검증 완료 against draft-07 — 5개 quote 중 4개 verbatim MATCH, 1개 (C1) 는 라이브 본문이 "resource server" 가 아닌 "resource", 2026-05-27 verified 본 추가)

핵심 인용 / Key quotes (verbatim)

[§Introduction, 2026-05-22 capture — "resource server" 표현, 라이브 본문은 "resource"] "An idempotency key is a unique value generated by the client which the resource server uses to recognize subsequent retries of the same request. The Idempotency-Key HTTP request header field carries this key."

[§2, draft-07, 2026-05-27 verified verbatim] "An idempotency key is a unique value generated by the client which the resource uses to recognize subsequent retries of the same request."

[§2.2, draft-07, 2026-05-27 verified — full form] "Uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients of the resource."

[§2.7, draft-07, 2026-05-27 verified MATCH] "If there is an attempt to reuse an idempotency key with a different request payload, the resource SHOULD reply with a HTTP 422 status code..."

[§2.6, draft-07, 2026-05-27 verified MATCH] "The request was retried before the original request completed. The resource SHOULD respond with a resource conflict error."

[§2.3, draft-07, 2026-05-27 verified — full sentence] "The resource MAY require time based idempotency keys to be able to purge or delete a key upon its expiry. The resource SHOULD define such expiration policy and publish it in the documentation."

draft status caveat (2026-05-27): 본 quote 들은 draft-ietf-httpapi-idempotency-key-header-07 (2025-10) 기준 verbatim. IETF draft 는 revision 마다 본문 변경 가능 (draft-08+ 출시 시 재확인 필수). RFC 정식 승급 전 까지는 strength = official-reference (정식 standard 아닌 work-in-progress IETF document).

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
IETF-IDEMP-C1	idempotency key 는 client 가 생성한 unique value 로 resource 가 subsequent retry 를 인식하는 데 사용되며, `Idempotency-Key` HTTP request header field 가 이 key 를 운반	[§2, draft-07, 2026-05-27 verified] "An idempotency key is a unique value generated by the client which the resource uses to recognize subsequent retries of the same request."	`official-reference`	HTTP API 의 idempotent request 헤더 명명	RFC 가 아닌 IETF draft — 정식 표준 지위 아님. revision 마다 본문 변경 가능. 2026-05-22 capture 의 "resource server" 는 draft-07 의 "resource" 와 다름 (의미 비등가하지만 draft 진화 과정에서 단순화된 표현)
IETF-IDEMP-C2	key 의 uniqueness 정의는 resource owner (= server) 가 책임지며 (`MUST`), client 는 이를 구현해야 함 (`MUST`)	[§2.2, draft-07, 2026-05-27 verified] "Uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients of the resource."	`official-reference`	scope 정의 (어떤 dimension 으로 unique 한지)	scope 를 반드시 어떤 형태 (pair/triple/body-hash) 로 정의해야 한다는 뜻은 아님 — 자유. draft 상태이므로 정식 RFC 미달
IETF-IDEMP-C3	같은 idempotency key 로 다른 request payload 를 재사용하면 resource 는 HTTP `422` 를 반환해야 함 (`SHOULD`)	[§2.7, draft-07, 2026-05-27 verified] "If there is an attempt to reuse an idempotency key with a different request payload, the resource SHOULD reply with a HTTP `422` status code..."	`official-reference`	server 측 fingerprint mismatch 처리	`MUST` 가 아닌 `SHOULD` — 다른 status code (예: 400) 사용도 draft 위반은 아님. body 동일성 비교 메커니즘 (hash / 전체 비교) 은 본 인용 범위 밖
IETF-IDEMP-C4	original request 가 완료되기 전 재시도된 request 에 대해 resource 는 conflict error (HTTP `409`) 로 응답해야 함 (`SHOULD`)	[§2.6, draft-07, 2026-05-27 verified] "The request was retried before the original request completed. The resource SHOULD respond with a resource conflict error."	`official-reference`	in-flight 동시 요청 처리	`SHOULD` — wait/poll 동작도 draft 위반은 아님 (ca-tmpl 의 200ms wait 는 다른 선택). client backoff 정책은 인용 범위 밖
IETF-IDEMP-C5	resource 는 time-based key expiration 정책을 요구할 수 있고 (`MAY`), 그러한 expiration 정책을 정의하여 문서에 공표해야 함 (`SHOULD`). 표준이 정확한 시간을 정하지는 않음	[§2.3, draft-07, 2026-05-27 verified] "The resource MAY require time based idempotency keys to be able to purge or delete a key upon its expiry. The resource SHOULD define such expiration policy and publish it in the documentation."	`official-reference`	TTL 정책 (24h / 30일 / 45일 등 vendor 별 자유)	표준이 권장 TTL 을 정한다는 뜻은 아님. expiration 없이 영구 보존하는 것이 draft 위반이라는 뜻도 아님

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것 (단, IETF draft = work-in-progress 상태):
- IETF-IDEMP-C1: Idempotency-Key 헤더명 표준화 시도
- IETF-IDEMP-C2: scope 정의 자유는 server 책임
- IETF-IDEMP-C3 ~ C4: 422 (fingerprint mismatch) / 409 (in-flight) status code 권장
- IETF-IDEMP-C5: expiration 정책은 server 가 정의하여 문서화
이 자료가 증명하지 않는 것:
- 정식 RFC 지위 (draft 상태 — published RFC 가 아님)
- 모든 vendor 가 이 권장을 따른다는 보장 (Stripe v1 은 status code 미명시, PayPal 은 "might fail" 모호 표현)
- response replay 의 정확한 메커니즘 (status+body cache vs 부분 재실행)
- 저장소 backend / lock 정책 (운영 핵심을 표준이 안 다룸)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 2026-05-27 시점 latest draft (draft-08+ 가 있다면) 재확인 — draft 본문은 revision 마다 변할 수 있음
- ca-tmpl 200ms wait 동작이 IETF-IDEMP-C4 의 409 권장과 정합한지 (즉시 409 vs 짧은 wait 후 hit/409)
- 정식 RFC 승급 시 본 draft 의 어떤 부분이 변경되는지 monitoring

ca-tmpl 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.

scope 자유: ca-tmpl triple (principal, key, useCaseName) 은 draft 가 허용하는 "resource owner defines" (IETF-IDEMP-C2) 범위 안. Stripe v1 pair, ca-tmpl triple, body-hash 모두 표준 안에서 가능 — 표준 위반 아님.
422 fingerprint: ca-tmpl 422 → draft 422 (IETF-IDEMP-C3) 와 일치.
409 in-flight: ca-tmpl 200ms wait 는 draft 409 권장 (IETF-IDEMP-C4) 과 다른 선택. ca-tmpl 이 더 친절하지만 표준 동작은 아님. 면접 / 외부 인용 시 "표준 따름" 표현 금지, "표준 기반 + 운영 친화적 변형" 으로.
TTL 자유: draft 가 시간을 정하지 않음 (IETF-IDEMP-C5) — ca-tmpl 24h, Stripe v1 24h, Stripe v2 30일, Toss 15일, PayPal 45일 모두 표준 안에서 가능.

메모 / Notes

draft status: 정식 RFC 가 아니라 IETF httpapi WG 의 작업 중 초안 (draft-07, 2025-10, 2026-05-27 시점 status=expired). revision 마다 본문 변경 가능. 외부 인용 시 "IETF draft (work-in-progress)" 명시 필요. 절대 "IETF 표준" 으로 표현 금지. strength 를 official-reference 로 라벨 (정식 standard 가 아닌 IETF reference document).
2026-05-27 재검증: WebFetch 완료. draft-07 본문 직접 fetch 하여 5개 quote 모두 verbatim 위치 확인. C1 의 "resource server" → "resource" 변화 발견 (2026-05-22 capture 의 표현은 더 이른 draft 본문이었거나 user 의 paraphrase 였을 가능성). 다른 4개는 verbatim 또는 더 긴 full sentence 형태로 MATCH.
단점 (해석): 표준이 너무 느슨해 구현체별 동작이 제각각 (Stripe·PayPal·Square 각각 다름). TTL / 저장 layer / lock 정책 등 운영 핵심을 표준이 안 다룸.

같은 주제 다른 raw:
인용하는 branch:
- raw/branch-notes/feature-rate-limit-idempotency-contract
- raw/branch-notes/feature-api-contract-baseline
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (§13, §18)
인용한 wiki 요약: (미작성)

11 KiB Raw Permalink Blame History