문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
261 lines
15 KiB
Markdown
261 lines
15 KiB
Markdown
# 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.
|
||
|
||
```dotenv
|
||
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).
|
||
|
||
### 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 `HTTPCLIENT_UNKNOWN_SETTING` naming the key, 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.
|
||
|
||
| 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`,
|
||
`HTTPCLIENT_UNKNOWN_SETTING`.
|
||
|
||
`HTTPCLIENT_UNKNOWN_SETTING` covers a gap in the shared strict binder: Spring's 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 platform now checks every key under `clients[N]` and `dynamic-targets[N]`
|
||
against the settings records.
|
||
|
||
`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` — 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.
|
||
|
||
`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.
|