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개 모두 문서에 있음).
This commit is contained in:
DongHyeonka
2026-11-07 17:29:57 +09:00
parent 6583cc2e02
commit e38c949c2f
11 changed files with 568 additions and 626 deletions
+21 -23
View File
@@ -1,36 +1,34 @@
# Streaming and Large Bodies
# 스트리밍과 큰 본문
## Response lifecycle
## 응답 수명
A streaming download returns `BlockingStreamingResponse`, never a bare `InputStream`. Closing is
idempotent and always releases the connection — after a full read, a partial read, a decode failure,
or a size rejection. The status is validated before any body byte is delivered, so a failed download
never becomes a half-consumed stream the caller has to reason about.
스트리밍 다운로드는 맨 `InputStream`이 아니라 `BlockingStreamingResponse`를 돌려준다. 닫기는 멱등이고, 다 읽은
뒤든, 일부만 읽은 뒤든, 디코딩 실패나 크기 거부 뒤든 늘 connection을 돌려준다. 상태는 본문 바이트를 넘기기 전에
검증한다. 그래서 실패한 다운로드가 호출자가 따져야 하는 반쯤 읽힌 stream이 되지 않는다.
Wire bytes and decoded bytes are bounded independently, because a compressed payload passes a wire
check and then expands. Limits are enforced while reading, not after buffering.
wire 바이트와 디코딩한 바이트는 따로 제한한다. 압축한 payload는 wire 검사를 통과한 뒤 늘어나기 때문이다. 한도는
버퍼링한 뒤가 아니라 읽는 동안 강제한다.
## The first-byte boundary
## 첫 바이트 경계
```text
response headers received
→ nothing delivered yet
→ a read-only operation may still be retried
→ the response is handed to the caller
→ transparent retry is no longer possible
응답 헤더를 받았다
→ 아직 아무것도 넘기지 않았다
→ 읽기 전용 연산은 아직 재시도할 수 있다
→ 응답을 호출자에게 넘겼다
→ 투명한 재시도는 더는 할 수 없다
```
Retrying after delivery would replay a stream the caller has already partly consumed, producing
duplicated or reordered data that no downstream code can detect. The streaming gateway hands out
the response only after the attempt has finished, so there is no retry left to run once the caller
reads.
넘긴 뒤에 재시도하면 호출자가 이미 일부 읽은 stream을 다시 보내게 된다. 그러면 아래쪽 어느 코드도 알아챌 수 없는
중복되거나 순서가 바뀐 데이터가 생긴다. 스트리밍 gateway는 시도가 끝난 뒤에만 응답을 넘긴다. 그래서 호출자가
읽기 시작하면 돌릴 재시도가 남아 있지 않다.
## Request bodies
## 요청 본문
A reopenable body is opened once per attempt, which is what makes it replayable; reusing the
previous stream would silently send an empty body on the retry. A one-shot stream is never retried.
다시 열 수 있는 본문은 시도마다 한 번 연다. 그래서 재전송할 수 있다. 앞 stream을 다시 쓰면 재시도에서 빈 본문을
조용히 보낸다. 한 번만 쓰는 stream은 절대 재시도하지 않는다.
## Server-sent events
The platform has no server-sent-event client. It was part of the reactive stack, which was removed
(decision 9, 2026-09-25): the platform runs blocking calls on the caller's thread only.
플랫폼에는 server-sent event client가 없다. 그것은 지운 reactive stack의 일부였다(결정 9, 2026-09-25). 플랫폼은
호출자의 스레드에서 blocking 호출만 돌린다.