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
+171 -183
View File
@@ -1,37 +1,34 @@
# HTTP Client Platform — Configuration Reference
# HTTP Client 플랫폼 — 설정 참조
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]`.
모든 외부 호출은 **Named Client Profile**(이름 붙은 client profile) 정확히 하나로 풀린다. capability 전체가
`app.httpclient` 접두사 아래에 있다. profile은 `app.httpclient.clients[N]` 아래, Dynamic Target 정책은
`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.
설계서 §30.1은 운영 profile이 framework의 큰 기본값을 물려받는 것을 금한다. 운영 배포가 정해야 하는 것은
기본값이 없거나 쓸 수 없는 기본값을 가진다. `HttpClientStartupValidator`는 짐작하지 않고 context를 실패시킨다.
## 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.
모듈은 있으면 켜진다. 서비스가 `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 설정이 시작을 실패시키지 않는다.
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.
정확히 `true`가 아닌 값(`yes`, `1`, 빈 값)은 플랫폼을 끈다. 켰는데 선언한 client가 없으면
`HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`로 시작이 실패한다. 부를 대상이 없는 플랫폼도 아무 호출자도 닿을 수 없는
transport provider와 gateway를 쥐고 있기 때문이다.
## Declaring clients from the environment
## 환경 변수로 client 선언하기
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.
client는 이름을 key로 한 map이 아니라, 자기 `name`을 가진 index 목록이다. map key는 환경 변수 이름의 한 조각이
되고 relaxed binder가 그것을 정규화한다. 그래서 `payment-api`와 `payment_api`가 한 항목으로 도착하고, 사라진
쪽에 대해서는 아무 말도 없다. 이름이 겹치거나 정규화한 뒤 겹치면 둘 다 시작이 실패한다.
```dotenv
APP_HTTPCLIENT_ENABLED=true
@@ -47,200 +44,194 @@ 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.
`docs/httpclient/env-fields.yaml`이 받아들이는 변수 이름의 registry다. settings record에서 만들어지고 양쪽
방향으로 그 record와 대조된다. 플랫폼은 여기 없는 `APP_HTTPCLIENT_` 변수가 있으면 시작을 거부한다. 그래서
`APP_HTTPCLIENT_CLIENTS_0_TIMEUOT_TOTAL_CALL`은 client를 조용히 기본 예산으로 두지 않고 시작을 실패시킨다.
환경 변수가 아니라 설정 파일로 준 모르는 key도 같은 이유로 엄격한 바인딩이 거부한다.
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.
`src/.env`와 `docs/registries/env-keys.yaml`에는 `APP_HTTPCLIENT_ENABLED`만 있다. 배포와 상관없는 값을 가진
유일한 key다. index를 단 client를 `application.yml`에 template로 두면 모든 배포에 이름 없는 client가 생기고,
그것은 묶음 검증이 거부한다.
## `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` |
| `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`
| 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 |
| `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`
| 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 |
| `dns` | `300ms` | hostname 풀기 |
| `connect` | `500ms` | socket 연결 |
| `tls-handshake` | `1s` | TLS와 ALPN |
| `response-header` | `2s` | 최종 응답 헤더까지 |
| `read-idle` | `3s` | 응답 chunk 사이 |
| `total-call` | `4s` | 재시도 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`은 `connect`나 `response-header`보다 짧으면 안 된다. 짧으면 validator가 `INVALID_TIMEOUT_BUDGET`을
낸다. 위의 모든 timeout과 `pool.pending-acquire-timeout`은 0보다 커야 한다(`TIMEOUT_NOT_POSITIVE`). 두 엔진 모두
0을 「영원히 기다림」으로 읽는다.
`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 a per-stream
watchdog bounds each read's wait by `read-idle`, because the JDK client has no socket read timeout.
The watchdog wakes on one daemon thread of its own (`httpclient-jdk-read-idle`), not on the common
`ForkJoinPool`, so a service that fills that pool with blocking work does not delay it (re-review
2026-11-04 RR3-03-01). That thread ends 60 s after the last wake it had queued and the next stream
starts it again; it inherits no thread-locals from the request thread that starts it and uses the
module's class loader as its context loader, so an idle service keeps no thread and a redeployed
application's loader is not pinned (RR4-03-04). 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 from `read` as `HttpBodyReadException` — an `IOException`, as
`InputStream` promises, so `catch (IOException)` still sees it — whose `failure()` is
`HttpResponseTimeoutException` (a wait longer than `read-idle`) or `HttpResponseTruncatedException`
(the connection ended early), stage `RESPONSE_BODY`, evidence `PARTIAL_RESPONSE` (re-review
2026-11-04 RR-03-14). On the JDK transport `read-idle` bounds each read's wait, `skip` included, and
time the caller spends between reads does not count (RR-03-12).
`total-call`은 스트리밍 다운로드의 준비 단계(연결, 보내기, 응답 헤더 기다리기)도 제한한다. stream을 넘긴 뒤에는
본문의 틈마다 `read-idle`이 제한한다. 그래서 긴 다운로드가 임의의 총 시간에 잘리지 않는다(설계서 §15.3). 두
transport 모두 그렇다.
### Removed settings
- 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 다운로드가 모두 본문 중간에 잘렸다.
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.
넘긴 뒤의 본문 실패는 `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).
| Removed key | Why |
### 지운 설정
어느 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` | 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 |
| `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`
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.
무엇을 실패로 세는지는 고정이다. 5xx, 408, 429 응답(호출이 던지든 결과로 돌려주든)과 모든 transport 실패다.
그 밖의 4xx는 건강한 답이다. 이 설정은 몇 번 중 몇 번의 실패가 circuit을 여는지만 정한다. 기본값은
Resilience4j 자체의 값이고, key가 생기기 전 모든 profile이 이 값으로 돌았다.
Two deadlines can end an attempt in flight, and they are counted differently (review 2026-11-03
RR-04-01):
진행 중인 시도를 끝낼 수 있는 기한은 둘이고, 둘을 다르게 센다(리뷰 2026-11-03 RR-04-01).
| Ended by | Breaker | Why |
| 끝낸 것 | Breaker | 이유 |
|---|---|---|
| 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 |
| 호출자 자신의 기한(`HttpOperation.deadline()`, `total-call`보다 이를 때) | 기록하지 않고 허가를 돌려준다 | 호출자의 시간이 다 됐을 뿐이다. 이것을 세면 호출자가 짧은 예산을 줄 때마다 건강한 upstream의 circuit이 열렸다 |
| profile의 `timeout.total-call` | 실패로 기록한다 | `total-call`은 건강한 upstream이 걸려도 되는 시간에 대한 운영자의 말이다. 틈마다의 timeout에 걸리지 않고 조금씩 흘리는 upstream은 이것으로만 보인다 |
The first row has a blind spot (re-review 2026-11-04 RR-03-16). The attempt is let off whenever the
caller's deadline was the earlier one and had passed when the attempt failed — the code does not ask
whether the upstream was still answering within the profile's limits. If every caller of a profile
passes a budget shorter than `connect` or `response-header`, an upstream that hangs (drops packets,
never answers) ends every attempt at the caller's deadline first, so no attempt is recorded and the
circuit never opens; every call waits out its own budget. A failure that comes before the caller's
deadline — a refused connection — is still counted. For such a profile, set `connect` and
`response-header` shorter than the shortest caller budget.
첫 행에는 사각지대가 있다(재리뷰 2026-11-04 RR-03-16). 호출자의 기한이 더 이르고, 시도가 실패했을 때 그 기한이
지났으면 그 시도는 세지 않는다. 코드는 upstream이 그때도 profile 한도 안에서 답하고 있었는지 묻지 않는다.
어떤 profile의 모든 호출자가 `connect`나 `response-header`보다 짧은 예산을 주면, 멈춘 upstream(패킷을 버리거나
답하지 않음)은 모든 시도를 호출자의 기한에서 먼저 끝낸다. 그래서 아무 시도도 기록되지 않고 circuit은 열리지
않으며, 모든 호출이 자기 예산을 다 기다린다. 호출자의 기한 전에 오는 실패(거부된 연결)는 여전히 센다. 그런
profile에는 `connect`와 `response-header`를 가장 짧은 호출자 예산보다 짧게 둔다.
| 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 |
| `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 이상 |
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.
범위 밖 값은 `CIRCUIT_BREAKER_SETTING_INVALID`로 시작이 실패한다. breaker는 런타임 세대가 아니라 profile에
속한다. 그래서 인증서를 교체해도 상태가 남는다.
### `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 |
| `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` | 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" |
| `response.max-wire-bytes` | `5242880` | wire 위의 바이트 |
| `response.max-decoded-bytes` | `10485760` | 디코딩한 뒤의 바이트. 넘을 수 없는 최대는 64 MiB |
| `response.allowed-content-types` | JSON + problem+json | 비어 있으면 「아무것이나」 |
### `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 |
| `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`
| Property | Default | Meaning |
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `policy` | `none` | Named policy for reporting |
| `max-attempts` | `1` | Attempts, not retries; at most 5 (`RETRY_MAX_ATTEMPTS_EXCEEDED`) |
| `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` | — | 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) |
| `budget` | — | 공유 token bucket 이름. 재시도하는 profile이 이름을 주지 않으면 자기 bucket을 받는다. 용량 계산은 같다(`max-total-connections / 10`, 최소 1, 1분마다 채움) |
### `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 |
| `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` and `observability`
### `proxy`와 `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 |
| `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]`
| Property | Default | Meaning |
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `name` | — | Required, unique, and subject to the same normalisation rule as a client name |
| `name` | — | 필수, 유일, client 이름과 같은 정규화 규칙 |
| `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 |
| `allowed-host-suffixes` | 비어 있음 | |
| `allowed-hosts` | 비어 있음 | 비어 있으면 「주소 검증을 통과한 아무 host」 |
| `max-redirect-hops` | `0` | hop마다 검증 흐름 전체를 다시 돈다 |
| `trace-propagation` | `false` | dynamic target은 기본으로 끈다 |
| `blocked-cidrs` | 비어 있음 | 조직이 정한 내부 범위 |
## Startup violation codes
## 시작 위반 코드
`TRUSTED_BASE_URL_REQUIRED`, `BASE_URL_USERINFO_FORBIDDEN`, `BASE_URL_QUERY_FORBIDDEN`,
`PLAINTEXT_PRODUCTION_TARGET`, `ALLOWED_HOST_MISMATCH`, `ALLOWED_PORT_MISMATCH`,
@@ -259,36 +250,33 @@ the profile, not to a runtime generation, so a certificate rotation keeps its st
`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.
어떤 설정도 가리키지 않는 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` 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.
`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`는 플랫폼이
바인딩은 하지만 아직 지키지 못하는 설정을 가리킨다. Apache classic client도 JDK client도 DNS 풀기 timeout을
내놓지 않고, proxy credential 경로도 없다. 그래서 기본값이 아닌 값은 받아들이고 무시하지 않고 거부한다.
기본값을 그대로 두면 영향이 없다. 의도했지만 지킬 수 없는 요청만 실패한다.
Three of these are about a guarantee that used to be silently unmet rather than refused:
아래 코드들은 예전에 거부하지 않고 조용히 지키지 못하던 보장에 관한 것이다.
- `HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED` — declaring `protocols: [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 empty `tls.protocols` used to pass and then let the JVM choose,
so emptying the list to "tighten" a profile loosened it.
- `RETRY_POLICY_CONTRADICTS_ATTEMPTS` — `retry.policy` was read by nothing on the execution path, so
the actuator could report `none` for a profile retrying three times. The two settings must now
agree: `policy: none` requires `max-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.
- `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` 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.
`DYNAMIC_TARGET_PROXY_UNSUPPORTED`는 따로 설명할 만하다. forward proxy는 hostname을 자기 쪽에서 푼다. 그래서
이 플랫폼이 검증하고 고정한 주소가 연결이 실제로 닿는 주소가 아니다. SSRF 방어는 있고 맞지만 우회된다. 그래서
이 조합은 지킬 수 없는 보장을 단 채 내주지 않고 거부한다.