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:
@@ -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 호출만 돌린다.
|
||||
|
||||
Reference in New Issue
Block a user