문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
16 KiB
HTTP Client Platform — Configuration Reference
Every outbound call resolves exactly one Named Client Profile. The whole capability lives under
the app.httpclient prefix: profiles under app.httpclient.clients[N], Dynamic Target policies
under app.httpclient.dynamic-targets[N].
Design §30.1 forbids a production profile from inheriting large framework defaults. Anything a
production deployment must decide has either no default or an unusable one, and
HttpClientStartupValidator fails the context rather than guessing.
The master switch
| Property | Type | Default | Environment |
|---|---|---|---|
app.httpclient.enabled |
boolean | true |
APP_HTTPCLIENT_ENABLED |
The module is on when present: a service adds runtimeOnly project(':adapter:outbound:httpclient')
to app-bootstrap/build.gradle, and the module's own config/module-defaults/httpclient.yml (loaded at the lowest
precedence by the support leaf's ModuleDefaultsEnvironmentPostProcessor) supplies enabled: true. Absent from the
build is the ordinary off state. false is the explicit off: HttpClientPlatformAutoConfiguration
is then never processed and neither is anything it imports — no property is bound, and no transport
provider, connection pool, TLS context, credential, thread, gateway or actuator endpoint exists. A
malformed HTTP client setting cannot fail the startup of a deployment that switched it off.
Anything that is not exactly true — yes, 1, blank — turns the platform off. On with no client
declared is a startup failure carrying HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS: a platform with nothing
to call still holds transport providers and gateways no caller can reach.
Declaring clients from the environment
Clients are an indexed list carrying their own name, not a map keyed by name. A map key becomes a
segment of the environment variable and the relaxed binder normalises it, so payment-api and
payment_api would arrive as one entry with nothing said about the one that was lost. Both a
duplicate name and a name that collides once normalised fail startup.
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 is the registry of accepted variable names. It is
derived from the settings record and held to it in both directions, and the platform refuses to
start on an APP_HTTPCLIENT_ variable that is not in it — so
APP_HTTPCLIENT_CLIENTS_0_TIMEUOT_TOTAL_CALL fails startup instead of silently leaving the client
on its default budget. Unknown keys supplied through a configuration file rather than the
environment are refused by strict binding for the same reason.
Only APP_HTTPCLIENT_ENABLED appears in src/.env and docs/registries/env-keys.yaml. It is the
one key with a deployment-independent value; templating an indexed client in application.yml would
materialise a nameless client in every deployment, which the aggregate validation refuses.
app.httpclient.clients[N]
| Property | Type | Default | Notes |
|---|---|---|---|
name |
string | — | Required, unique, and distinct from every other name once normalised for the environment |
mode |
TRUSTED | DYNAMIC |
TRUSTED |
A dynamic profile may not carry a default credential |
base-url |
URI | — | Required for a trusted profile; no userinfo, no query |
allowed-hosts |
list | empty | Required in production |
allowed-ports |
list | empty | Compared against the effective port |
transport |
APACHE | JDK | JETTY | SIMPLE |
APACHE |
SIMPLE is rejected in production; JETTY needs a deployment-registered provider |
protocols |
list | HTTP_1_1 |
The default transport is Apache, whose classic client is HTTP/1.1 only; a profile that wants HTTP/2 declares it together with a transport that can deliver it. HTTP_3 requires the experimental acknowledgement |
experimental-acknowledgement |
string | — | Must equal I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS |
pool
| Property | Default | Meaning |
|---|---|---|
max-total-connections |
50 |
Socket ceiling for the runtime |
max-connections-per-route |
25 |
Per-upstream ceiling |
max-pending-acquires |
100 |
Waiting-request memory ceiling |
pending-acquire-timeout |
200ms |
Pool or stream wait ceiling |
max-idle-time |
30s |
Idle eviction |
max-life-time |
5m |
Picks up DNS, load-balancer, and certificate changes |
validate-after-inactivity |
5s |
Stale and half-open detection |
requires-route-pool |
false |
Set when route-scoped limits are mandatory; the JDK transport then refuses the profile |
requires-bounded-pending-queue |
false |
Same, for a bounded pending queue |
timeout
| Property | Default | Meaning |
|---|---|---|
dns |
300ms |
Hostname resolution |
connect |
500ms |
Socket connect |
tls-handshake |
1s |
TLS and ALPN |
response-header |
2s |
Until final response headers |
read-idle |
3s |
Between response chunks |
total-call |
4s |
The whole logical call, including retry backoff |
total-call must not be shorter than connect or response-header; the validator emits
INVALID_TIMEOUT_BUDGET otherwise. Every timeout above, and pool.pending-acquire-timeout, must be
greater than zero (TIMEOUT_NOT_POSITIVE): both engines read zero as "wait forever".
total-call also bounds the setup of a streaming download — connect, send, and the wait for
response headers. Once the stream is handed over, each gap of the body is bounded by read-idle
instead, so a long download is not cut at an arbitrary total (design §15.3). This holds on both
transports. The JDK transport keeps its exchange-wide timeout off a streamed body and bounds each
read with its own read-idle timer, because the JDK client has no socket read timeout; before
review 2026-11-03 RR-04-03 every JDK download longer than response-header was cut mid-body. A body
failure after hand-over is thrown as HttpResponseTimeoutException (a gap longer than read-idle)
or HttpResponseTruncatedException (the connection ended early), stage RESPONSE_BODY, evidence
PARTIAL_RESPONSE.
Removed settings
Six keys were removed because they were bound and reached no transport (review 2026-11-01 05-15).
Setting one now fails startup with a bind error naming the key (The elements [app.httpclient.clients[0].timeout.request-write-idle] were left unbound.), instead of being
accepted and ignored.
| Removed key | Why |
|---|---|
timeout.request-write-idle |
Neither engine can bound a blocking socket write |
timeout.proxy-connect, proxy.connect-timeout |
The TCP connect to a proxy is governed by timeout.connect |
pool.eviction-interval |
Apache's idle evictor runs at max-idle-time |
pool.shutdown-timeout |
A retired runtime drains for app.httpclient.rotation-drain-timeout |
observability.operation-name-required |
An operation name is mandatory in the API; the switch could only be true |
circuit-breaker
What counts as a failure is fixed: a 5xx, 408 or 429 response — whether the call throws or returns it as a result — and every transport failure. Every other 4xx is a healthy answer. These settings only say how many failures, out of how many calls, open the circuit. Defaults are Resilience4j's own, which every profile ran with before the keys existed.
Two deadlines can end an attempt in flight, and they are counted differently (review 2026-11-03 RR-04-01):
| Ended by | Breaker | Why |
|---|---|---|
The caller's own deadline (HttpOperation.deadline(), when earlier than total-call) |
Not recorded; the permission is given back | The caller ran out of time. Counting it opened the circuit on a healthy upstream whenever callers passed short budgets |
The profile's timeout.total-call |
Recorded as a failure | total-call is the operator's statement of how long a healthy upstream may take; a slow-drip upstream that never trips a per-gap timeout is seen only through it |
| Property | Default | Meaning |
|---|---|---|
failure-rate-threshold |
50 |
Percent of failed calls in the window that opens the circuit, 1–100 |
minimum-number-of-calls |
100 |
Calls recorded before the rate is evaluated; at most sliding-window-size |
sliding-window-size |
100 |
The last N calls the rate is computed over (count-based) |
wait-duration-in-open-state |
60s |
How long an open circuit rejects before trial calls; positive |
permitted-calls-in-half-open-state |
10 |
Trial calls while half-open; at least 1 |
An out-of-range value fails startup with CIRCUIT_BREAKER_SETTING_INVALID. The breaker belongs to
the profile, not to a runtime generation, so a certificate rotation keeps its state.
redirect, request, response
| Property | Default | Meaning |
|---|---|---|
redirect.enabled |
false |
Engine redirect handling is always off; the platform follows hops itself |
redirect.max-hops |
0 |
Enabling redirects with zero hops is a configuration error |
redirect.allow-cross-origin |
false |
When enabled, credentials are stripped on the hop |
request.max-body-bytes |
0 |
Required in production |
request.compression |
false |
|
response.max-wire-bytes |
5242880 |
Bytes on the wire |
response.max-decoded-bytes |
10485760 |
Bytes after decoding; hard maximum is 64 MiB |
response.allowed-content-types |
JSON + problem+json | Empty means "any" |
authentication
| Property | Default | Meaning |
|---|---|---|
type |
NONE |
One of the design §20.1 methods |
registration-id |
— | Required for OAuth2 |
scopes |
empty | Part of the token cache key |
audience |
— | Part of the token cache key |
header-name |
— | Required for API_KEY_HEADER; must be on the allowlist |
secret-reference |
— | Resolved by the deployment's secret loader, never a literal |
retry
| Property | Default | Meaning |
|---|---|---|
policy |
none |
Named policy for reporting |
max-attempts |
1 |
Attempts, not retries; at most 5 (RETRY_MAX_ATTEMPTS_EXCEEDED) |
base-backoff |
50ms |
|
max-backoff |
200ms |
|
jitter |
FULL |
NONE | FULL | DECORRELATED |
retry-after |
HONOR |
HONOR | IGNORE | CAP |
budget |
— | Shared token bucket name. A retrying profile that names none gets its own bucket, with the same pool-derived capacity (max-total-connections / 10, at least 1, refilled each minute) |
tls
| Property | Default | Meaning |
|---|---|---|
profile-id |
— | Required in production; the only TLS identifier the actuator exposes |
protocols |
TLSv1.3, TLSv1.2 |
Anything else is rejected |
hostname-verification |
true |
Setting it false fails startup |
trust-all |
false |
Exists only so the unsafe intent is rejectable; nothing acts on true |
allow-plain-http |
false |
Plaintext fallback fails startup in production |
trust-material-reference |
— | Custom CA, resolved by the secret loader |
key-material-reference |
— | Client certificate for mTLS |
proxy and observability
| Property | Default | Meaning |
|---|---|---|
proxy.enabled |
false |
|
proxy.host / proxy.port / proxy.type |
— / 0 / HTTP |
|
proxy.credential-provider |
— | Proxy authentication is separate from target authentication |
proxy.import-ambient-no-proxy |
false |
Ambient NO_PROXY never widens a validated profile |
observability.full-url-recording |
false |
|
observability.body-logging |
false |
app.httpclient.dynamic-targets[N]
| Property | Default | Meaning |
|---|---|---|
name |
— | Required, unique, and subject to the same normalisation rule as a client name |
allowed-schemes |
https |
|
allowed-ports |
443 |
|
allowed-host-suffixes |
empty | |
allowed-hosts |
empty | Empty means "any host that survives address validation" |
max-redirect-hops |
0 |
Each hop repeats the full validation flow |
trace-propagation |
false |
Off by default for dynamic targets |
blocked-cidrs |
empty | Organisation-defined internal ranges |
Startup violation codes
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.
A key that names no setting is not a violation code: the shared strict binder
(adapter:outbound:support StrictSettingsBinder) refuses it while binding, at any depth. Spring's
own unbound-key check stops at the first level under a list element, so clients[0].timeout.<typo>
used to bind nothing and fail nothing; the binder now refuses a key under clients[N] or
dynamic-targets[N] that bound nothing, for every capability rather than for this platform alone
(review 2026-11-01 05-15). The platform's own guard for it, and its HTTPCLIENT_UNKNOWN_SETTING
code, were removed with that change.
DNS_TIMEOUT_UNSUPPORTED, PROXY_CREDENTIAL_UNSUPPORTED and PROXY_AMBIENT_NO_PROXY_UNSUPPORTED name settings the platform binds but cannot yet honour. Neither the Apache classic
client nor the JDK client exposes a DNS-resolution timeout, and no proxy-credential path exists, so
a non-default value is refused rather than accepted and ignored. Leaving the defaults alone is
unaffected — only a deliberate, unmet request fails.
Three of these are about a guarantee that used to be silently unmet rather than refused:
HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED— declaringprotocols: [HTTP_2]alone states that HTTP/2 is required. No transport can be configured to offer H2 and nothing else; the JDK client treats it as a preference and negotiates HTTP/1.1, and Apache's classic client is HTTP/1.1 only.POOL_ROUTE_EXCEEDS_TOTAL— a per-route ceiling above the total is incoherent.TLS_PROTOCOL_SET_REQUIRED— an emptytls.protocolsused to pass and then let the JVM choose, so emptying the list to "tighten" a profile loosened it.RETRY_POLICY_CONTRADICTS_ATTEMPTS—retry.policywas read by nothing on the execution path, so the actuator could reportnonefor a profile retrying three times. The two settings must now agree:policy: nonerequiresmax-attempts: 1, and any other policy requires more than one.FULL_URL_RECORDING_FORBIDDEN/BODY_LOGGING_FORBIDDEN— both settings were bindable and inert. Recording an expanded URL puts path identifiers and query strings into unbounded metric tags; recording bodies puts someone else's data into logs. Representable so the intent is rejectable, refused under a production profile.
DYNAMIC_TARGET_PROXY_UNSUPPORTED is worth spelling out: a forward proxy resolves the hostname on
its own side, so the addresses this platform validated and pinned are not the addresses the
connection reaches. The SSRF defence would be present, correct, and bypassed — so the combination is
refused rather than served with a guarantee it cannot keep.