문제: 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개 모두 문서에 있음).
19 KiB
HTTP Client 플랫폼 — 설정 참조
모든 외부 호출은 Named Client Profile(이름 붙은 client profile) 정확히 하나로 풀린다. capability 전체가
app.httpclient 접두사 아래에 있다. profile은 app.httpclient.clients[N] 아래, Dynamic Target 정책은
app.httpclient.dynamic-targets[N] 아래에 있다.
설계서 §30.1은 운영 profile이 framework의 큰 기본값을 물려받는 것을 금한다. 운영 배포가 정해야 하는 것은
기본값이 없거나 쓸 수 없는 기본값을 가진다. HttpClientStartupValidator는 짐작하지 않고 context를 실패시킨다.
주 스위치
| 속성 | 타입 | 기본값 | 환경 변수 |
|---|---|---|---|
app.httpclient.enabled |
boolean | true |
APP_HTTPCLIENT_ENABLED |
모듈은 있으면 켜진다. 서비스가 app-bootstrap/build.gradle에 runtimeOnly project(':adapter:outbound:httpclient')를
더하면, 모듈 자신의 config/module-defaults/httpclient.yml(support leaf의 ModuleDefaultsEnvironmentPostProcessor가
가장 낮은 우선순위로 읽는다)이 enabled: true를 준다. 빌드에 없는 것이 보통의 꺼진 상태다. false는 명시적으로
끈 것이다. 그러면 HttpClientPlatformAutoConfiguration도, 그것이 import하는 것도 처리되지 않는다. 바인딩되는
속성이 없고, transport provider, connection pool, TLS context, credential, 스레드, gateway, actuator endpoint도
없다. 끈 배포에서는 잘못된 HTTP client 설정이 시작을 실패시키지 않는다.
정확히 true가 아닌 값(yes, 1, 빈 값)은 플랫폼을 끈다. 켰는데 선언한 client가 없으면
HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS로 시작이 실패한다. 부를 대상이 없는 플랫폼도 아무 호출자도 닿을 수 없는
transport provider와 gateway를 쥐고 있기 때문이다.
환경 변수로 client 선언하기
client는 이름을 key로 한 map이 아니라, 자기 name을 가진 index 목록이다. map key는 환경 변수 이름의 한 조각이
되고 relaxed binder가 그것을 정규화한다. 그래서 payment-api와 payment_api가 한 항목으로 도착하고, 사라진
쪽에 대해서는 아무 말도 없다. 이름이 겹치거나 정규화한 뒤 겹치면 둘 다 시작이 실패한다.
APP_HTTPCLIENT_ENABLED=true
APP_HTTPCLIENT_CLIENTS_0_NAME=payment
APP_HTTPCLIENT_CLIENTS_0_BASE_URL=https://payment.example
APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0=payment.example
APP_HTTPCLIENT_CLIENTS_0_ALLOWED_PORTS_0=443
APP_HTTPCLIENT_CLIENTS_0_REQUEST_MAX_BODY_BYTES=1048576
APP_HTTPCLIENT_CLIENTS_0_TLS_PROFILE_ID=payment
APP_HTTPCLIENT_DYNAMIC_TARGETS_0_NAME=webhook
APP_HTTPCLIENT_DYNAMIC_TARGETS_0_ALLOWED_SCHEMES_0=https
docs/httpclient/env-fields.yaml이 받아들이는 변수 이름의 registry다. settings record에서 만들어지고 양쪽
방향으로 그 record와 대조된다. 플랫폼은 여기 없는 APP_HTTPCLIENT_ 변수가 있으면 시작을 거부한다. 그래서
APP_HTTPCLIENT_CLIENTS_0_TIMEUOT_TOTAL_CALL은 client를 조용히 기본 예산으로 두지 않고 시작을 실패시킨다.
환경 변수가 아니라 설정 파일로 준 모르는 key도 같은 이유로 엄격한 바인딩이 거부한다.
src/.env와 docs/registries/env-keys.yaml에는 APP_HTTPCLIENT_ENABLED만 있다. 배포와 상관없는 값을 가진
유일한 key다. index를 단 client를 application.yml에 template로 두면 모든 배포에 이름 없는 client가 생기고,
그것은 묶음 검증이 거부한다.
app.httpclient.clients[N]
| 속성 | 타입 | 기본값 | 비고 |
|---|---|---|---|
name |
string | — | 필수. 유일하고, 환경 변수용으로 정규화한 뒤에도 다른 모든 이름과 달라야 한다 |
mode |
TRUSTED | DYNAMIC |
TRUSTED |
dynamic profile은 기본 credential을 가질 수 없다 |
base-url |
URI | — | trusted profile에 필수. userinfo와 query가 없어야 한다 |
allowed-hosts |
list | 비어 있음 | 운영에서 필수 |
allowed-ports |
list | 비어 있음 | 실제 port와 비교한다 |
transport |
APACHE | JDK | JETTY | SIMPLE |
APACHE |
SIMPLE은 운영에서 거부한다. JETTY는 배포가 등록한 provider가 필요하다 |
protocols |
list | HTTP_1_1 |
기본 transport는 Apache이고, 그 classic client는 HTTP/1.1만 한다. HTTP/2를 원하는 profile은 그것을 줄 수 있는 transport와 함께 선언한다. HTTP_3은 실험 동의가 필요하다 |
experimental-acknowledgement |
string | — | I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS와 같아야 한다 |
pool
| 속성 | 기본값 | 뜻 |
|---|---|---|
max-total-connections |
50 |
런타임의 socket 상한 |
max-connections-per-route |
25 |
upstream 하나의 상한 |
max-pending-acquires |
100 |
기다리는 요청의 메모리 상한 |
pending-acquire-timeout |
200ms |
pool이나 stream을 기다리는 상한 |
max-idle-time |
30s |
놀고 있는 connection 내보내기 |
max-life-time |
5m |
DNS, load balancer, 인증서 변화를 받아들인다 |
validate-after-inactivity |
5s |
낡거나 반쯤 열린 connection 감지 |
requires-route-pool |
false |
route 범위 상한이 필수일 때 켠다. 그러면 JDK transport가 그 profile을 거부한다 |
requires-bounded-pending-queue |
false |
같은 방식으로, 상한 있는 대기 큐가 필수일 때 |
timeout
| 속성 | 기본값 | 뜻 |
|---|---|---|
dns |
300ms |
hostname 풀기 |
connect |
500ms |
socket 연결 |
tls-handshake |
1s |
TLS와 ALPN |
response-header |
2s |
최종 응답 헤더까지 |
read-idle |
3s |
응답 chunk 사이 |
total-call |
4s |
재시도 backoff를 포함한 논리 호출 전체 |
total-call은 connect나 response-header보다 짧으면 안 된다. 짧으면 validator가 INVALID_TIMEOUT_BUDGET을
낸다. 위의 모든 timeout과 pool.pending-acquire-timeout은 0보다 커야 한다(TIMEOUT_NOT_POSITIVE). 두 엔진 모두
0을 「영원히 기다림」으로 읽는다.
total-call은 스트리밍 다운로드의 준비 단계(연결, 보내기, 응답 헤더 기다리기)도 제한한다. stream을 넘긴 뒤에는
본문의 틈마다 read-idle이 제한한다. 그래서 긴 다운로드가 임의의 총 시간에 잘리지 않는다(설계서 §15.3). 두
transport 모두 그렇다.
- JDK transport는 스트리밍 본문에 exchange 전체 timeout을 걸지 않는다. JDK client에는 socket 읽기 timeout이
없으므로 stream마다 watchdog이 읽기 대기를
read-idle로 제한한다. - watchdog은 공용
ForkJoinPool이 아니라 자기 daemon 스레드 하나(httpclient-jdk-read-idle)에서 깬다. 그래서 그 pool을 blocking 작업으로 채운 서비스도 watchdog을 늦추지 않는다(재리뷰 2026-11-04 RR3-03-01). - 그 스레드는 마지막으로 예약한 깨우기 60초 뒤에 끝나고, 다음 stream이 다시 띄운다. 띄운 요청 스레드의 thread-local을 물려받지 않고, 모듈의 class loader를 context loader로 쓴다. 그래서 노는 서비스는 스레드를 붙들지 않고, 다시 배포한 애플리케이션의 loader가 붙잡히지 않는다(RR4-03-04).
- 리뷰 2026-11-03 RR-04-03 전에는
response-header보다 긴 JDK 다운로드가 모두 본문 중간에 잘렸다.
넘긴 뒤의 본문 실패는 read에서 HttpBodyReadException으로 던진다. InputStream이 약속한 대로 IOException
이므로 catch (IOException)도 그것을 잡는다. 그 failure()는 HttpResponseTimeoutException(read-idle보다 긴
기다림)이나 HttpResponseTruncatedException(connection이 일찍 끝남)이고, 단계는 RESPONSE_BODY, 증거는
PARTIAL_RESPONSE다(재리뷰 2026-11-04 RR-03-14). JDK transport에서 read-idle은 skip을 포함해 읽기마다의
기다림을 제한하고, 호출자가 읽기 사이에 쓴 시간은 세지 않는다(RR-03-12).
지운 설정
어느 transport에도 닿지 않으면서 바인딩만 되던 key 여섯을 지웠다(리뷰 2026-11-01 05-15). 이제 그 key를 쓰면
받아들이고 무시하는 대신 그 key를 이름 댄 바인딩 오류(The elements [app.httpclient.clients[0].timeout.request-write-idle] were left unbound.)로 시작이 실패한다.
| 지운 key | 이유 |
|---|---|
timeout.request-write-idle |
어느 엔진도 blocking socket 쓰기를 제한하지 못한다 |
timeout.proxy-connect, proxy.connect-timeout |
proxy로의 TCP 연결은 timeout.connect가 정한다 |
pool.eviction-interval |
Apache의 idle evictor는 max-idle-time마다 돈다 |
pool.shutdown-timeout |
내린 런타임은 app.httpclient.rotation-drain-timeout 동안 비운다 |
observability.operation-name-required |
연산 이름은 API에서 필수다. 이 스위치는 true일 수밖에 없었다 |
circuit-breaker
무엇을 실패로 세는지는 고정이다. 5xx, 408, 429 응답(호출이 던지든 결과로 돌려주든)과 모든 transport 실패다. 그 밖의 4xx는 건강한 답이다. 이 설정은 몇 번 중 몇 번의 실패가 circuit을 여는지만 정한다. 기본값은 Resilience4j 자체의 값이고, key가 생기기 전 모든 profile이 이 값으로 돌았다.
진행 중인 시도를 끝낼 수 있는 기한은 둘이고, 둘을 다르게 센다(리뷰 2026-11-03 RR-04-01).
| 끝낸 것 | Breaker | 이유 |
|---|---|---|
호출자 자신의 기한(HttpOperation.deadline(), total-call보다 이를 때) |
기록하지 않고 허가를 돌려준다 | 호출자의 시간이 다 됐을 뿐이다. 이것을 세면 호출자가 짧은 예산을 줄 때마다 건강한 upstream의 circuit이 열렸다 |
profile의 timeout.total-call |
실패로 기록한다 | total-call은 건강한 upstream이 걸려도 되는 시간에 대한 운영자의 말이다. 틈마다의 timeout에 걸리지 않고 조금씩 흘리는 upstream은 이것으로만 보인다 |
첫 행에는 사각지대가 있다(재리뷰 2026-11-04 RR-03-16). 호출자의 기한이 더 이르고, 시도가 실패했을 때 그 기한이
지났으면 그 시도는 세지 않는다. 코드는 upstream이 그때도 profile 한도 안에서 답하고 있었는지 묻지 않는다.
어떤 profile의 모든 호출자가 connect나 response-header보다 짧은 예산을 주면, 멈춘 upstream(패킷을 버리거나
답하지 않음)은 모든 시도를 호출자의 기한에서 먼저 끝낸다. 그래서 아무 시도도 기록되지 않고 circuit은 열리지
않으며, 모든 호출이 자기 예산을 다 기다린다. 호출자의 기한 전에 오는 실패(거부된 연결)는 여전히 센다. 그런
profile에는 connect와 response-header를 가장 짧은 호출자 예산보다 짧게 둔다.
| 속성 | 기본값 | 뜻 |
|---|---|---|
failure-rate-threshold |
50 |
circuit을 여는, 창 안 실패 호출의 백분율. 1–100 |
minimum-number-of-calls |
100 |
비율을 계산하기 전에 기록할 호출 수. sliding-window-size 이하 |
sliding-window-size |
100 |
비율을 계산하는 최근 N개 호출(개수 기준) |
wait-duration-in-open-state |
60s |
열린 circuit이 시험 호출 전까지 거부하는 시간. 양수 |
permitted-calls-in-half-open-state |
10 |
half-open 동안의 시험 호출. 1 이상 |
범위 밖 값은 CIRCUIT_BREAKER_SETTING_INVALID로 시작이 실패한다. breaker는 런타임 세대가 아니라 profile에
속한다. 그래서 인증서를 교체해도 상태가 남는다.
redirect, request, response
| 속성 | 기본값 | 뜻 |
|---|---|---|
redirect.enabled |
false |
엔진의 redirect 처리는 늘 꺼져 있다. 플랫폼이 hop을 직접 따라간다 |
redirect.max-hops |
0 |
redirect를 켜고 hop을 0으로 두면 설정 오류다 |
redirect.allow-cross-origin |
false |
켜면 hop에서 credential을 지운다 |
request.max-body-bytes |
0 |
운영에서 필수 |
request.compression |
false |
|
response.max-wire-bytes |
5242880 |
wire 위의 바이트 |
response.max-decoded-bytes |
10485760 |
디코딩한 뒤의 바이트. 넘을 수 없는 최대는 64 MiB |
response.allowed-content-types |
JSON + problem+json | 비어 있으면 「아무것이나」 |
authentication
| 속성 | 기본값 | 뜻 |
|---|---|---|
type |
NONE |
설계서 §20.1의 방식 중 하나 |
registration-id |
— | OAuth2에 필수 |
scopes |
비어 있음 | token cache key의 일부 |
audience |
— | token cache key의 일부 |
header-name |
— | API_KEY_HEADER에 필수. 허용 목록에 있어야 한다 |
secret-reference |
— | 배포의 secret loader가 푼다. 값을 그대로 쓰지 않는다 |
retry
| 속성 | 기본값 | 뜻 |
|---|---|---|
policy |
none |
보고용 정책 이름 |
max-attempts |
1 |
재시도 수가 아니라 시도 수. 최대 5(RETRY_MAX_ATTEMPTS_EXCEEDED) |
base-backoff |
50ms |
|
max-backoff |
200ms |
|
jitter |
FULL |
NONE | FULL | DECORRELATED |
retry-after |
HONOR |
HONOR | IGNORE | CAP |
budget |
— | 공유 token bucket 이름. 재시도하는 profile이 이름을 주지 않으면 자기 bucket을 받는다. 용량 계산은 같다(max-total-connections / 10, 최소 1, 1분마다 채움) |
tls
| 속성 | 기본값 | 뜻 |
|---|---|---|
profile-id |
— | 운영에서 필수. actuator가 보여 주는 유일한 TLS 식별자 |
protocols |
TLSv1.3, TLSv1.2 |
그 밖의 값은 거부한다 |
hostname-verification |
true |
false로 두면 시작이 실패한다 |
trust-all |
false |
위험한 의도를 거부할 수 있게 하려고만 있다. true에 반응하는 것은 없다 |
allow-plain-http |
false |
평문으로 물러서기는 운영에서 시작을 실패시킨다 |
trust-material-reference |
— | 사설 CA. secret loader가 푼다 |
key-material-reference |
— | mTLS용 client 인증서 |
proxy와 observability
| 속성 | 기본값 | 뜻 |
|---|---|---|
proxy.enabled |
false |
|
proxy.host / proxy.port / proxy.type |
— / 0 / HTTP |
|
proxy.credential-provider |
— | proxy 인증은 대상 인증과 따로다 |
proxy.import-ambient-no-proxy |
false |
환경의 NO_PROXY는 검증한 profile을 넓히지 않는다 |
observability.full-url-recording |
false |
|
observability.body-logging |
false |
app.httpclient.dynamic-targets[N]
| 속성 | 기본값 | 뜻 |
|---|---|---|
name |
— | 필수, 유일, client 이름과 같은 정규화 규칙 |
allowed-schemes |
https |
|
allowed-ports |
443 |
|
allowed-host-suffixes |
비어 있음 | |
allowed-hosts |
비어 있음 | 비어 있으면 「주소 검증을 통과한 아무 host」 |
max-redirect-hops |
0 |
hop마다 검증 흐름 전체를 다시 돈다 |
trace-propagation |
false |
dynamic target은 기본으로 끈다 |
blocked-cidrs |
비어 있음 | 조직이 정한 내부 범위 |
시작 위반 코드
TRUSTED_BASE_URL_REQUIRED, BASE_URL_USERINFO_FORBIDDEN, BASE_URL_QUERY_FORBIDDEN,
PLAINTEXT_PRODUCTION_TARGET, ALLOWED_HOST_MISMATCH, ALLOWED_PORT_MISMATCH,
REDIRECT_POLICY_INVALID, REDIRECT_CROSS_ORIGIN_CREDENTIAL_POLICY_REQUIRED,
INVALID_TIMEOUT_BUDGET, RESPONSE_HARD_MAXIMUM_EXCEEDED, PRODUCTION_SIMPLE_FACTORY_FORBIDDEN,
JDK_FINE_GRAINED_POOL_UNSUPPORTED, HTTP3_STABLE_FORBIDDEN,
DYNAMIC_TARGET_TRANSPORT_UNSUPPORTED, DYNAMIC_DEFAULT_CREDENTIAL_FORBIDDEN,
OAUTH2_REGISTRATION_REQUIRED, API_KEY_HEADER_NAME_REQUIRED, TRUST_ALL_FORBIDDEN,
HOSTNAME_VERIFICATION_REQUIRED, PLAINTEXT_FALLBACK_FORBIDDEN, TLS_PROTOCOL_FORBIDDEN,
RETRY_BACKOFF_REQUIRED, MISSING_PRODUCTION_SETTING, DUPLICATE_CLIENT_NAME,
HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS, DYNAMIC_BASE_URL_REQUIRED,
DYNAMIC_TARGET_PROXY_UNSUPPORTED,
HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED, POOL_ROUTE_EXCEEDS_TOTAL,
TLS_PROTOCOL_SET_REQUIRED,
RETRY_POLICY_CONTRADICTS_ATTEMPTS, FULL_URL_RECORDING_FORBIDDEN, BODY_LOGGING_FORBIDDEN,
DNS_TIMEOUT_UNSUPPORTED, PROXY_CREDENTIAL_UNSUPPORTED, PROXY_AMBIENT_NO_PROXY_UNSUPPORTED,
TIMEOUT_NOT_POSITIVE, RETRY_MAX_ATTEMPTS_EXCEEDED, CIRCUIT_BREAKER_SETTING_INVALID.
어떤 설정도 가리키지 않는 key는 위반 코드가 아니다. 공용 엄격 binder(adapter:outbound:support
StrictSettingsBinder)가 바인딩하면서 깊이와 상관없이 거부한다. Spring 자체의 바인딩 안 된 key 검사는 list 원소
아래 첫 단계에서 멈춘다. 그래서 clients[0].timeout.<typo>는 아무것도 바인딩하지 않고 아무것도 실패시키지
않았다. 이제 binder는 clients[N]이나 dynamic-targets[N] 아래에서 아무것도 바인딩하지 않은 key를 이
플랫폼만이 아니라 모든 capability에서 거부한다(리뷰 2026-11-01 05-15). 그 변경과 함께 플랫폼 자체의 보호 장치와
그 HTTPCLIENT_UNKNOWN_SETTING 코드는 지웠다.
DNS_TIMEOUT_UNSUPPORTED, PROXY_CREDENTIAL_UNSUPPORTED, PROXY_AMBIENT_NO_PROXY_UNSUPPORTED는 플랫폼이
바인딩은 하지만 아직 지키지 못하는 설정을 가리킨다. Apache classic client도 JDK client도 DNS 풀기 timeout을
내놓지 않고, proxy credential 경로도 없다. 그래서 기본값이 아닌 값은 받아들이고 무시하지 않고 거부한다.
기본값을 그대로 두면 영향이 없다. 의도했지만 지킬 수 없는 요청만 실패한다.
아래 코드들은 예전에 거부하지 않고 조용히 지키지 못하던 보장에 관한 것이다.
HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED—protocols: [HTTP_2]만 선언하면 HTTP/2가 필수라는 뜻이다. H2만 제공하도록 설정할 수 있는 transport는 없다. JDK client는 그것을 선호로 다루고 HTTP/1.1로 협상하고, Apache의 classic client는 HTTP/1.1만 한다.POOL_ROUTE_EXCEEDS_TOTAL— route별 상한이 전체보다 크면 앞뒤가 맞지 않는다.TLS_PROTOCOL_SET_REQUIRED— 빈tls.protocols가 예전에는 통과해서 JVM이 고르게 두었다. 그래서 profile을 「조이려고」 목록을 비우면 오히려 풀렸다.RETRY_POLICY_CONTRADICTS_ATTEMPTS— 실행 경로의 어느 것도retry.policy를 읽지 않았다. 그래서 세 번 재시도하는 profile에 대해 actuator가none을 보고할 수 있었다. 이제 두 설정이 맞아야 한다.policy: none은max-attempts: 1을 요구하고, 다른 정책은 1보다 큰 값을 요구한다.FULL_URL_RECORDING_FORBIDDEN/BODY_LOGGING_FORBIDDEN— 두 설정은 바인딩은 됐지만 아무 효과가 없었다. 펼친 URL을 기록하면 경로 식별자와 query string이 상한 없는 metric tag에 들어가고, 본문을 기록하면 남의 데이터가 로그에 들어간다. 의도를 거부할 수 있게 표현만 해 두고, 운영 profile에서는 거부한다.
DYNAMIC_TARGET_PROXY_UNSUPPORTED는 따로 설명할 만하다. forward proxy는 hostname을 자기 쪽에서 푼다. 그래서
이 플랫폼이 검증하고 고정한 주소가 연결이 실제로 닿는 주소가 아니다. SSRF 방어는 있고 맞지만 우회된다. 그래서
이 조합은 지킬 수 없는 보장을 단 채 내주지 않고 거부한다.