Files
clean-architecture-backend-…/docs/httpclient/retry-and-ambiguity.md
T
DongHyeonka 931178760a
pr / done (pull_request) Canceled after 0s
fix(outbound)!: S3 조건부 쓰기·MongoDB 예산과 lease·HTTP 압축을 맞춘다
S3 control 저장소는 SDK가 응답을 잃고 다시 보낸 조건부 PUT의 412를
충돌로 본다. MongoDB 집계는 결과 바이트 예산을 보지 않고 전부 메모리에
올린다. tenant client registry는 쓰는 중인 client를 내보내고, 내보내다
닫기에 실패하면 다른 tenant의 acquire가 실패한다. migration lease를 잃은
runner가 그 뒤에도 checkpoint를 쓴다. HTTP client는 SOCKS proxy를 HTTP로
붙이고, 압축을 켜면 Apache는 스스로 풀어 max-wire-bytes가 푼 크기를
세며, JDK transport는 그 설정을 읽지 않는다.

고른 방법: S3는 412에서 다시 읽어 이 호출이 쓴 record 그대로면 성공으로
본다. 집계는 $limit(maxResults + 1)과 maxResultBytes를 집행한다. registry
acquire는 Lease를 돌려주고 쓰는 중에는 내보내지 않으며 idle은 마지막
close부터 잰다. 상한·lease 수·내보내기는 registry 밖에서 잡을 수 없는 전용
lock 하나로 묶는다. 닫기 실패는 evictionCloseFailures가 센다. migration
ledger는 lock 문서의 현재 fence로 쓴다. ProxyType은 HTTP만 남긴다.
압축은 RestClient 기본 헤더로 보내고 ContentDecoding이 버퍼·스트리밍
본문을 모두 푼다(겹친 coding과 그 밖의 coding은 거부, 빈 본문은 빈
본문). Jetty HTTP/3는 기동 뒤 decoder를 비운다. 버린 대안: SOCKS 지원
(transport 셋 중 하나만 된다), transport마다 자동 풀기(크기 상한이
transport마다 달라진다), 집계를 RawBsonDocument로 재기(converter를 거치지
않으면 반환 타입 mapping이 갈라진다).

위험·한계: MongoTenantClientRegistry.acquire 반환형과 ProxyType이 바뀐다.
S3에서 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다
(Javadoc과 안내 3절). 집계 결과는 converter로만 바뀌어 entity callback이
돌지 않는다. evictionCloseFailures 지표는 지표 묶음에 넘긴다.

검증: desktop RED(pr2-red2). GREEN은 PR 본문의 verify.sh pr 결과.

Refs: RR9-01-08, RR9-01-11, RR9-01-19, RR9-01-20, RR9-01-27, RR9-01-28, RR9-01-30, RR9-01-31
BREAKING CHANGE: MongoTenantClientRegistry.acquire가 Lease를 돌려주고, migration lease를 잃은 refresh가 MongoOperationRejectedException을 던진다. HTTP client ProxyType.SOCKS가 없어져 그 설정은 바인딩이 실패한다. request.compression이 모든 transport에서 같은 coding만 받는다. docs/upgrade/2026-11-round9-outbound.md
2026-11-13 16:21:16 +09:00

81 lines
5.3 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 | 안전하게 멱등인 연산만 기한과 예산 안에서 재시도. 아니면 결과 모름(upstream이 받은 뒤 답한 것일 수 있다) |
| 425 | 안전하게 멱등인 연산만, 첫 시도에서만, 많아야 한 번 재시도. 아니면 결과 모름 |
| 429 | 안전하게 멱등인 연산만 `Retry-After`, 기한, 예산 안에서 재시도. 아니면 거부(`notRetryableStatus`). 429는 일정 신호이지 "아무 일도 없었다"는 말이 아니다 |
| 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 허가도
잡지 않는다.