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
+46 -53
View File
@@ -1,75 +1,68 @@
# HTTP Client Platform — Security Guide
# HTTP Client 플랫폼 — 보안 안내
## What the platform owns
## 플랫폼이 소유하는 것
`Authorization`, `Proxy-Authorization`, `Host`, `Content-Length`, `Transfer-Encoding`,
`Traceparent`, `Tracestate`, `Baggage`, and (unless a profile opts in) `Cookie` are platform-owned.
A caller cannot set them. `Idempotency-Key` is accepted only when the operation declares it. Any
header name or value containing CR or LF is rejected before the request is built.
`Authorization`, `Proxy-Authorization`, `Host`, `Content-Length`, `Transfer-Encoding`, `Traceparent`,
`Tracestate`, `Baggage`, 그리고 (profile이 고르지 않는 한) `Cookie`는 플랫폼이 소유한다. 호출자는 이것들을 정할 수
없다. `Idempotency-Key`는 연산이 선언했을 때만 받는다. 이름이나 값에 CR이나 LF가 있는 헤더는 요청을 만들기 전에
거부한다.
## Target policy
## 대상 정책
A trusted profile accepts only a profile-relative URI template. An absolute URI is rejected rather
than sanitised: varying the destination is what H3 is for, and H3 has its own policy, credentials,
and address validation. Template variables are encoded per component, so a value containing `/`,
`?`, or `#` cannot change the shape of the request.
trusted profile은 profile 기준 상대 URI template만 받는다. 절대 URI는 정리하지 않고 거부한다. 목적지를 바꾸는 것은
H3가 하는 일이고, H3에는 자기 정책, credential, 주소 검증이 있다. template 변수는 구성 요소마다 인코딩한다. 그래서
`/`, `?`, `#`이 든 값도 요청의 모양을 바꾸지 못한다.
## TLS
Allowed: TLS 1.2 and 1.3, hostname verification, the JVM trust store, a per-profile custom CA, a
per-profile client certificate, mTLS, SNI and ALPN, and certificate rotation through a new runtime
generation.
허락: TLS 1.2와 1.3, hostname 검증, JVM trust store, profile별 사설 CA, profile별 client 인증서, mTLS, SNI와
ALPN, 새 런타임 세대를 통한 인증서 교체.
Forbidden and unrepresentable: a trust-all trust manager, disabled hostname verification, ignoring
certificate errors, automatically trusting a production self-signed certificate, falling back to
plaintext after an HTTPS failure, and writing key material into configuration or logs.
금지하고 표현할 수도 없음: 모두 믿는 trust manager, hostname 검증 끄기, 인증서 오류 무시, 운영의 자체 서명 인증서를
자동으로 믿기, HTTPS 실패 뒤 평문으로 물러서기, key 재료를 설정이나 로그에 쓰기.
Unknown CA, hostname mismatch, expired certificate, revoked certificate, protocol mismatch, and a
missing client certificate are permanent. Only a transient handshake timeout may be retried, inside
the deadline.
모르는 CA, hostname 불일치, 만료한 인증서, 폐기된 인증서, protocol 불일치, 빠진 client 인증서는 영구 실패다.
일시적인 handshake 시간 초과만 기한 안에서 재시도할 수 있다.
## Dynamic Target (SSRF)
Every hop — the first one included — runs the whole flow:
첫 hop을 포함해 모든 hop이 흐름 전체를 돈다.
1. strict URI parse
2. scheme allowlist
3. reject userinfo and invalid ports
4. IDNA-canonicalise the host
5. host allowlist or suffix policy
6. resolve **every** A and AAAA answer
7. normalise each address, including IPv4-mapped IPv6
8. reject loopback, link-local, RFC1918, ULA, carrier-grade NAT, unspecified, multicast, cloud
metadata, and organisation-defined ranges
9. pin the connection to the approved addresses through the same validated resolver
10. apply response size and content policy
11. repeat for each redirect
1. 엄격한 URI 파싱
2. scheme 허용 목록
3. userinfo와 잘못된 port 거부
4. host를 IDNA로 정규화
5. host 허용 목록이나 접미사 정책
6. A와 AAAA 답을 **모두** 푼다
7. IPv4-mapped IPv6를 포함해 주소마다 정규화
8. loopback, link-local, RFC1918, ULA, carrier-grade NAT, 미지정, multicast, cloud metadata, 조직이 정한 범위를
거부
9. 같은 검증 resolver로 connection을 승인한 주소에 고정
10. 응답 크기와 content 정책 적용
11. redirect마다 반복
Any forbidden address in the answer set rejects the whole target. Validating only the first answer
would let a host that resolves to one public and one private address through.
답 묶음에 금지 주소가 하나라도 있으면 대상 전체를 거부한다. 첫 답만 검증하면 공개 주소 하나와 사설 주소 하나로
풀리는 host가 통과한다.
Dynamic profiles inherit no API key, OAuth token, Cookie, or default header, and no Cookie jar is
created. A specific host may be granted a credential only through an explicitly registered
`DynamicCredentialBinding`.
dynamic profile은 API key, OAuth token, Cookie, 기본 헤더를 물려받지 않고, Cookie jar도 만들지 않는다. 특정 host에
credential을 주려면 명시적으로 등록한 `DynamicCredentialBinding`을 거쳐야만 한다.
Application-level validation is not sufficient on its own. A network control — Kubernetes
NetworkPolicy, service-mesh egress policy, firewall, or proxy ACL — is an operational completion
requirement.
애플리케이션 수준 검증만으로는 충분하지 않다. 네트워크 통제(Kubernetes NetworkPolicy, service mesh egress 정책,
방화벽, proxy ACL)가 운영 완료 요건이다.
## Redirects
## Redirect
Disabled by default. Engine redirect handling is off in every transport so the platform can
re-validate each hop. 307 and 308 preserve method and body and are therefore allowed only for a
replayable body. Cross-origin hops are refused unless the profile opts in, and when they are
allowed `Authorization`, `Proxy-Authorization`, `Cookie`, and API-key headers are stripped.
기본으로 꺼져 있다. 플랫폼이 hop마다 다시 검증할 수 있게 모든 transport에서 엔진의 redirect 처리를 끈다. 307과
308은 method와 본문을 유지하므로 재전송 가능한 본문일 때만 허락한다. origin을 넘는 hop은 profile이 고르지 않으면
거부하고, 허락하면 `Authorization`, `Proxy-Authorization`, `Cookie`, API key 헤더를 지운다.
## Observability
## 관측
Allowed tags: `clientName`, `operationName`, `method`, `uriTemplate`, `status`, `outcome`,
`transport`, `protocol`, `timeoutType`, `retryReason`, `evidence`, `circuitState`.
허락한 tag: `clientName`, `operationName`, `method`, `uriTemplate`, `status`, `outcome`, `transport`,
`protocol`, `timeoutType`, `retryReason`, `evidence`, `circuitState`.
Rejected outright: full URL, query parameters, path variable values, user ID, raw tenant ID,
resolved IP, API key, token, Cookie, idempotency key, request or response body, exception message.
바로 거부: 전체 URL, query parameter, 경로 변수 값, user ID, 날것의 tenant ID, 푼 IP, API key, token, Cookie, 멱등
key, 요청이나 응답 본문, 예외 메시지.
Failures are logged once, structured, at the end of a logical call. Retry attempts are DEBUG or span
events. URLs appear only as templates.
실패는 논리 호출 끝에 구조화해서 한 번 로그를 남긴다. 재시도 시도는 DEBUG이거나 span event다. URL은 template로만
나온다.