fix: 하네스 제거 및 keycloak 문서 보강
This commit is contained in:
DongHyeonka
@@ -1 +0,0 @@
|
||||
../../vault/20-evidence/official-docs/idempotency-stripe-api-ref.md
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Stripe API Reference — Idempotent requests
|
||||
source_type: official-doc
|
||||
url: https://docs.stripe.com/api/idempotent_requests
|
||||
archive_url:
|
||||
status: raw
|
||||
confidence: high
|
||||
tags: [ca-idempotency, stripe-pair, idempotency-key, api-design, payment-domain]
|
||||
related_projects: [ca-skeleton-operational-contract]
|
||||
related_branches: [feature-rate-limit-idempotency-contract, feature-api-contract-baseline]
|
||||
created: 2026-05-22
|
||||
last_reviewed: 2026-05-27
|
||||
---
|
||||
|
||||
# Stripe API Reference — Idempotent requests
|
||||
|
||||
> Layer: `raw/official-docs/` — Stripe 공식 API reference 의 idempotency 동작 정의. 결제 도메인 idempotency 의 사실상 reference implementation.
|
||||
|
||||
## Parent / 활용 branch (필수)
|
||||
|
||||
> 이 자료가 정당화하는 결정 매핑.
|
||||
|
||||
| Branch | 이 자료가 정당화하는 결정 |
|
||||
|---|---|
|
||||
| [[raw/branch-notes/feature-rate-limit-idempotency-contract]] | Idempotency contract 의 key scope (v1 pair vs v2 triple), TTL (24h vs 30d), response replay (status+body) 정책 비교 근거 |
|
||||
| [[raw/branch-notes/feature-api-contract-baseline]] | `Idempotency-Key` 헤더를 POST endpoint 의 표준 surface 로 노출하는 결정의 vendor 표준 근거 |
|
||||
| [[raw/project-notes/ca-skeleton-operational-contract]] | §13. API Contract Surface (Idempotency-Key) + §18. Control Plane Contract (Rate Limit/Idempotency) 의 글로벌 결제 reference |
|
||||
|
||||
## 컨텍스트
|
||||
|
||||
ca-tmpl 이 채택한 `(authenticatedPrincipal, idempotencyKey, useCaseName)` triple scope 를 평가하려면 업계 표준으로 가장 많이 인용되는 Stripe 의 scope·TTL·response replay 정책과 직접 비교가 필요. Stripe v1 은 사실상 "pair scope (account + key)" 의 reference, v2 는 ca-tmpl 의 triple 과 같은 모양의 (account/sandbox, API, key) triple.
|
||||
|
||||
## 출처 / Source
|
||||
|
||||
- 원본 URL (v1 API ref): https://docs.stripe.com/api/idempotent_requests
|
||||
- 원본 URL (v2 overview): https://docs.stripe.com/api-v2-overview
|
||||
- 관련: Stripe blog "Designing robust and predictable APIs with idempotency" (`stripe.com/blog/idempotency`)
|
||||
- 관련: Brandur Leach "Implementing Stripe-like Idempotency Keys in Postgres" (`brandur.org/idempotency-keys`) — Stripe 엔지니어의 구현 해설
|
||||
- 아카이브 URL: (미수집)
|
||||
- 저자 / 조직: Stripe, Inc. — API Documentation
|
||||
- 발행일: rolling docs (페이지 자체에 명시 없음)
|
||||
- 마지막 확인일: 2026-05-27
|
||||
|
||||
## 핵심 인용 / Key quotes (verbatim)
|
||||
|
||||
> [§Idempotent requests (v1)] "All `POST` requests accept idempotency keys."
|
||||
|
||||
> [§Idempotent requests (v1)] "You can remove keys from the system automatically after they're at least 24 hours old. We generate a new request if a key is reused after the original is pruned."
|
||||
|
||||
> [§Idempotent requests (v1)] "The idempotency layer compares incoming parameters to those of the original request and errors if they're not the same to prevent accidental misuse."
|
||||
|
||||
> [§Idempotent requests (v1)] "Stripe's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including `500` errors."
|
||||
|
||||
> [§API v2 overview — Idempotent replay] "A request is considered an idempotent replay of another request if the following are all true: They use the same idempotency key for the same API; They occur in the scope of the same account or sandbox; They occur within 30 days of each other"
|
||||
|
||||
> [§API v2 overview — Replay behavior] "If the first request succeeded, the API skips making new changes and returns an updated response."
|
||||
|
||||
> [§API v2 overview — Replay behavior] "If the first request failed (or partially failed), the API re-executes the failed requests and returns the new response."
|
||||
|
||||
## Claims Extracted / 추출된 주장
|
||||
|
||||
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
||||
|---|---|---|---|---|---|
|
||||
| STRIPE-IDEMP-C1 | Stripe v1 의 모든 POST endpoint 는 `Idempotency-Key` 헤더를 수용한다 | [§Idempotent requests (v1)] "All `POST` requests accept idempotency keys." | `official-vendor-doc` | Stripe v1 API 의 mutating POST endpoint | GET / DELETE 는 idempotency key 가 무효함은 별도 진술 — 본 인용 범위 밖 |
|
||||
| STRIPE-IDEMP-C2 | v1 의 idempotency key 는 first request 의 24시간 이후부터 시스템에서 자동 제거 가능하며, pruning 이후 같은 키가 재사용되면 새 request 로 처리된다 | [§Idempotent requests (v1)] "You can remove keys from the system automatically after they're at least 24 hours old. We generate a new request if a key is reused after the original is pruned." | `official-vendor-doc` | Stripe v1 idempotency store | 24h 가 정확한 만료 시각이라는 뜻은 아님 — "after they're at least 24 hours old" 는 최소 보유 보장. 24h 가 결제 도메인 일반 표준이라는 뜻도 아님 |
|
||||
| STRIPE-IDEMP-C3 | v1 idempotency layer 는 incoming parameters 를 original request 의 parameters 와 비교하고 다르면 error 를 반환한다 (parameter fingerprint 검사) | [§Idempotent requests (v1)] "The idempotency layer compares incoming parameters to those of the original request and errors if they're not the same to prevent accidental misuse." | `official-vendor-doc` | Stripe v1 의 same-key + different-body 케이스 | 정확한 HTTP status code (예: 400 / 422) 는 본 인용에 없음. ca-tmpl 422 는 IETF draft 기반 (별도 자료) |
|
||||
| STRIPE-IDEMP-C4 | v1 은 first request 의 status code 와 body 를 모두 저장하여 succeed/fail 무관하게 replay 하며, 5xx 도 동일하게 replay 된다 | [§Idempotent requests (v1)] "Stripe's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including `500` errors." | `official-vendor-doc` | Stripe v1 의 모든 replay | 5xx replay 가 클라이언트에게 항상 안전하다는 뜻은 아님 — 비결정 케이스에는 부적합 (해석은 §메모 참조) |
|
||||
| STRIPE-IDEMP-C5 | v2 의 idempotent replay 조건은 (same idempotency key, same API, same account or sandbox, within 30 days) 4가지를 모두 만족할 때 | [§API v2 overview — Idempotent replay] "A request is considered an idempotent replay of another request if the following are all true: They use the same idempotency key for the same API; They occur in the scope of the same account or sandbox; They occur within 30 days of each other" | `official-vendor-doc` | Stripe v2 API | v1 에도 동일하게 적용된다는 뜻은 아님. v2 는 v1 의 pair scope 에 "API" dimension 을 추가한 triple 모델 |
|
||||
| STRIPE-IDEMP-C6 | v2 의 replay 동작은 성공이면 갱신된 응답 반환, 실패/부분실패이면 실패한 부분만 재실행하여 새 응답 반환 (v1 의 "status+body 그대로 replay" 와 다른 동작) | [§API v2 overview — Replay behavior] "If the first request succeeded, the API skips making new changes and returns an updated response." + "If the first request failed (or partially failed), the API re-executes the failed requests and returns the new response." | `official-vendor-doc` | Stripe v2 API | v1 의 "status+body 그대로 replay" 모델과 다른 정책 — v2 는 부분 재실행 모델. 두 동작이 동일하다는 뜻은 아님 |
|
||||
|
||||
## Usage Boundaries / 적용 경계
|
||||
|
||||
- **이 자료가 직접 증명하는 것**:
|
||||
- `STRIPE-IDEMP-C1` ~ `C4`: Stripe v1 의 헤더 수용 범위, 24h TTL 정책, parameter fingerprint 검사, status+body replay 동작
|
||||
- `STRIPE-IDEMP-C5` ~ `C6`: Stripe v2 의 4-조건 replay 정의 + 성공/실패별 다른 replay 동작
|
||||
- **이 자료가 증명하지 않는 것**:
|
||||
- 24h 가 결제 도메인의 표준 TTL 이라는 일반화 (Toss 15일, PayPal 45일, IETF draft 는 시간을 정하지 않음)
|
||||
- v1 fingerprint 검사의 정확한 status code (Stripe blog 또는 SDK 동작으로 별도 확인 필요)
|
||||
- 저장소 backend (Brandur 글이 Postgres 사례를 다루지만 공식 ref 는 명시 없음)
|
||||
- v2 의 "부분 실패만 재실행" 메커니즘의 정확한 unit (transaction / step / operation 단위)
|
||||
- in-flight 동시 요청의 처리 (즉시 409 vs wait) — 본 ref 페이지에 명시 없음
|
||||
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
||||
- ca-tmpl triple `(principal, key, useCaseName)` 과 Stripe v2 triple `(account/sandbox, API, key)` 의 의미론적 mapping (principal == account, useCaseName == API)
|
||||
- ca-tmpl 24h TTL 결정의 위험 (Stripe v1 minimum 24h 와 일치하나 v2 30일보다 짧음 — retry window 손실 vs 저장 비용)
|
||||
- ca-tmpl 422 fingerprint mismatch 가 Stripe v1 의 "errors if they're not the same" 와 정합한지 (Stripe 는 status code 미명시)
|
||||
|
||||
## ca-tmpl 함의 (내 프로젝트 해석)
|
||||
|
||||
> 본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 `wiki/concepts/` 또는 `wiki/projects/` source-summary 로 옮겨야 함.
|
||||
|
||||
- **key scope**: ca-tmpl triple `(principal, key, useCaseName)` ≈ Stripe v2 triple `(account, API, key)`. 개념적으로 거의 동일. Stripe v1 pair 보다는 ca-tmpl 이 한 단계 더 보수적 (endpoint dimension 추가).
|
||||
- **TTL**: ca-tmpl 24h = Stripe v1 최소치 (`STRIPE-IDEMP-C2`). v2 30일보다 보수적이며, 긴 retry window 손실 risk 와 저장소 부하 / 키 추측 공격면 트레이드오프.
|
||||
- **response replay**: ca-tmpl 이 status+body 그대로 replay 하면 Stripe v1 모델 (`C4`), 실패한 부분만 재실행하면 v2 모델 (`C6`). ca-tmpl 의 정확한 선택은 contract 본문 확인 필요.
|
||||
- **fingerprint**: Stripe v1 은 "errors if they're not the same" 만 명시 (`C3`). ca-tmpl 422 는 IETF draft 근거.
|
||||
- **저장소**: 공식 ref 는 미명시. Brandur 글 (Stripe 엔지니어 작성, 비공식) 은 Postgres 테이블 + atomic phase + `locked_at` lock 모델.
|
||||
|
||||
## 메모 / Notes
|
||||
|
||||
> 검증되지 않은 내 해석은 여기에 두지 말 것 — wiki source-summary 단계에서.
|
||||
|
||||
- v1 의 5xx replay 는 "결정적 응답" 제공의 장점이 있으나, 비결정 케이스 (예: 외부 시스템 timeout 후 실제 성공) 에서는 클라이언트가 잘못된 결론에 도달할 수 있음 — 해석은 `wiki/concepts/` 단계에서.
|
||||
- v2 의 "부분 실패만 재실행" 은 ca-tmpl 의 "외부 mutation 부분 복구" 요구사항과 일치할 가능성. 자세한 메커니즘은 v2 별도 페이지 확인 필요.
|
||||
- 추가로 봐야 할 동일 출처: Stripe blog `Designing robust and predictable APIs with idempotency`, Brandur `idempotency-keys`.
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 같은 주제 다른 raw:
|
||||
- [[raw/official-docs/idempotency-paypal-docs]]
|
||||
- [[raw/official-docs/idempotency-ietf-draft]]
|
||||
- [[raw/company-tech-blogs/idempotency-toss-payments-techblog]]
|
||||
- 인용하는 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 요약: (미작성)
|
||||
Reference in New Issue
Block a user