Files
clean-architecture-backend-…/docs/httpclient/configuration-reference.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

20 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

모듈은 있으면 켜진다. 서비스가 src/bootstrap/app/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도 같은 이유로 엄격한 바인딩이 거부한다.

.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 켜면 transport와 상관없이 Accept-Encoding: gzip, deflate를 보낸다. 받은 본문은 엔진이 아니라 이 플랫폼이 wire 바이트를 센 뒤 푼다(버퍼 본문과 스트리밍 다운로드 모두)
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 지금 transport는 모두 HTTP forward proxy만 한다. type의 값은 HTTP 하나이고, SOCKS는 바인딩이 거부한다
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 방어는 있고 맞지만 우회된다. 그래서 이 조합은 지킬 수 없는 보장을 단 채 내주지 않고 거부한다.