Files
clean-architecture-backend-…/docs/httpclient/retry-and-ambiguity.md
T
DongHyeonka e38c949c2f docs(httpclient): HTTP client 문서를 한국어로 옮기고 숫자 복사를 없앤다
문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외).
repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring
Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit`
source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다.

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는
원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다.
leaf 수는 registry(src/config/architecture/modules.json)를, 버전은
src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default,
Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만
옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만).
configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다.

버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라
날짜와 함께 그대로 둔다.

위험·한계: 내용 감사는 하지 않았다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0).
python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
2026-11-07 17:29:57 +09:00

81 lines
5.0 KiB
Markdown

# 재시도와 결과 모름
플랫폼은 HTTP method만 보고 재시도를 정하지 않는다(설계 D-09). 두 번째 시도는 멱등성, 본문 재전송 가능성, 실행
증거, 기한, 재시도 예산이 모두 허락할 때만 일어난다.
## 실행 증거
| 증거 | 뜻 | 흔한 원인 |
|---|---|---|
| `NOT_SENT` | 서버가 요청을 받지 않았음이 증명됐다 | profile 거부, pool 시간 초과, DNS 실패, 연결 실패, 요청 전 TLS 실패, HTTP/2 `REFUSED_STREAM` |
| `SENT_NO_RESPONSE` | 요청 일부나 전부를 썼고, 최종 헤더가 오지 않았다 | 부분 쓰기, 응답 헤더 시간 초과, connection reset |
| `RESPONSE_RECEIVED` | 상태와 상관없이 최종 헤더가 왔다 | 2xx, 4xx, 5xx, redirect |
| `PARTIAL_RESPONSE` | 헤더와 본문 일부가 왔다 | 디코딩 중 reset, 끊긴 stream |
`NOT_SENT`는 그것을 증명하는 단계 실패만 만든다. 일반 엔진 I/O 오류는 절대 `NOT_SENT`로 올리지 않는다. 시간
초과가 이중 결제가 되는 길이 바로 그것이기 때문이다.
## 본문 재전송 가능성
| 본문 | 재전송 가능성 |
|---|---|
| 바뀌지 않는 `byte[]` | `REPLAYABLE` |
| DTO와 결정적 codec | `REPLAYABLE` |
| 다시 열 수 있는 파일이나 resource supplier | `REOPENABLE` |
| `InputStream` 인스턴스 하나 | `ONE_SHOT` |
| publisher factory | 선언한 대로 |
| publisher 인스턴스 | `ONE_SHOT` |
| multipart | 가장 약한 part를 따른다 |
## 판정 순서
`DefaultRetryEligibilityEngine`은 이 순서로 판정한다. 뒤 규칙은 앞 규칙이 금지한 것을 절대 다시 허락하지 못한다.
1. 안전하게 멱등이 아닌 연산의 `SENT_NO_RESPONSE` → `AmbiguousFailure`
2. 시도를 다 썼다 → `RetryDenied.maxAttempts()`
3. 재시도 예산이 비었다 → `RetryDenied.budgetExhausted()`
4. 본문을 재전송할 수 없다 → `RetryDenied.bodyNotReplayable()`
5. 첫 바이트를 이미 넘겼다 → `RetryDenied.responseAlreadyDelivered()`
6. 런타임이 비우는 중이다 → `RetryDenied.runtimeDraining()`
7. 남은 기한이 최소 시도 예산보다 작다 → `RetryDenied.deadline()`
8. 영구 실패 범주 → `RetryDenied.permanentFailure(...)`
9. 안전하게 멱등이 아닌 연산의 `PARTIAL_RESPONSE` → `AmbiguousFailure`
10. 상태별·실패별 규칙
결과 모름이 맨 앞인 것은 그것이 다른 시도가 허락되는지가 아니라 결과를 설명하기 때문이다. 예전에는 시도 검사
아래에 있었다. 그래서 기본값 `max-attempts: 1`에서는 보낸 뒤 시간이 넘은 POST가 호출자에게 보통의 시간 초과로
도착했다(리뷰 2026-11-01 05-14).
## 상태 규칙
| 상태 | 판정 |
|---|---|
| 408 | 기한과 예산 안에서 재시도 |
| 425 | 첫 시도에서만, 많아야 한 번 재시도 |
| 429 | `Retry-After`, 기한, 예산 안에서 재시도 |
| 401 | 안전하고 재전송 가능한 연산에서만 갱신 후 재전송 한 번. credential은 재시도를 허락받은 뒤에만 갱신한다. 재전송하지 않을 401(시도 한 번, 예산 없음, 기한 없음)은 token cache를 건드리지 않는다 |
| 500 | upstream이 일시적이라고 등록했고 **그리고** 연산이 안전하게 멱등일 때만 허락. 아니면 거부 |
| 502, 503, 504 | 안전하게 멱등인 연산은 재시도. 아니면 결과 모름 |
| 그 밖의 4xx | 거부 |
## 결과 모름
멱등이 아닌 요청이 `SENT_NO_RESPONSE`에 닿으면 `HttpAmbiguousExecutionException`을 던진다. 일부러 만든 세 번째
답이다. 재시도하면 부수 효과가 두 번 날 수 있고, 보통의 실패로 알리면 요청이 일어나지 않았다고 호출자에게 말하는
셈인데 그것이 거짓일 수 있다. 호출자는 맞춰 본다. 보통 upstream에 조회하거나 멱등 key로 다시 보낸다.
### 증거는 어디서 오나
실패한 요청을 보냈는지는 시도가 닿은 단계와 엔진의 예외 타입에서 읽는다. Apache는 맺은 connection에 요청을 쓰기
시작하는 순간을 알려 준다(`RequestWriteSignal`). 그래서 빌리기, 풀기, 연결, TLS handshake 중의 실패는 엔진이 일반
예외를 던져도 `NOT_SENT`다. 그 순간을 알려 주지 못하는 transport(JDK, Jetty)는 엔진을 부른 순간부터 쓰는 중으로
본다. 「안 보냈다」고 짐작하는 것이 시간 초과를 이중 결제로 바꾸기 때문이다. HTTP/2 `REFUSED_STREAM` frame은
상대가 아무것도 처리하지 않았다는 증거이고, 예외 변환을 거쳐도 `NOT_SENT`로 남는다.
## 예산과 backoff
재시도 token은 실제 트래픽의 일정 비율로 크기를 정한 upstream별 token bucket에서 나온다. 그래서 건강한 인스턴스
무리가 실패하는 upstream을 재시도로 덮치지 못한다. backoff는 full이나 decorrelated jitter를 쓰는 지수 backoff이고,
`max-backoff`, `Retry-After`, 남은 기한으로 제한한다. backoff를 기다리는 동안에는 connection도 bulkhead 허가도
잡지 않는다.