clean-architecture-backend-template/docs/httpclient/configuration-reference.md

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	false	APP_HTTPCLIENT_ENABLED

Off is the shipped state and it is a structural one. HttpClientPlatformAutoConfiguration lives in a package the composition root's component scan excludes, so while the switch is absent or false the class is 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 never wanted outbound HTTP.

Anything that is not exactly true — yes, 1, blank — leaves the platform off. Turning it 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
api	REST_CLIENT | WEB_CLIENT	REST_CLIENT	Decides blocking or reactive runtime
transport	APACHE | JDK | REACTOR_NETTY | JETTY | SIMPLE	APACHE	SIMPLE is rejected in production
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
eviction-interval	15s	Background cleanup
shutdown-timeout	5s	Drain deadline before forced close
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
proxy-connect	500ms	Proxy socket or CONNECT
request-write-idle	1s	No progress writing the request
response-header	2s	Until final response headers
read-idle	3s	Between response chunks
total-call	4s	The whole logical call, including retry backoff
streaming-idle	30s	Silence on a long-lived stream

total-call must not be shorter than connect or response-header; the validator emits INVALID_TIMEOUT_BUDGET otherwise.

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
base-backoff	50ms
max-backoff	200ms
jitter	FULL	NONE | FULL | DECORRELATED
retry-after	HONOR	HONOR | IGNORE | CAP
budget	—	Shared token bucket name

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.connect-timeout	500ms	Recorded as its own metric
proxy.import-ambient-no-proxy	false	Ambient NO_PROXY never widens a validated profile
observability.operation-name-required	true
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, REACTIVE_AUTHENTICATION_UNSUPPORTED, HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED, POOL_ROUTE_EXCEEDS_TOTAL, TLS_PROTOCOL_SET_REQUIRED, REACTIVE_REDIRECT_UNSUPPORTED, RETRY_POLICY_CONTRADICTS_ATTEMPTS, FULL_URL_RECORDING_FORBIDDEN, BODY_LOGGING_FORBIDDEN, DNS_TIMEOUT_UNSUPPORTED, PROXY_CREDENTIAL_UNSUPPORTED, PROXY_AMBIENT_NO_PROXY_UNSUPPORTED.

The last three 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. Only REACTOR_NETTY 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, and on Reactor, where the per-route knob is the only one that exists, it silently becomes the effective limit.
• 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.
• REACTIVE_REDIRECT_UNSUPPORTED — engine redirect following is disabled on every transport and only the blocking stack has a coordinator that follows hops with per-hop re-validation. A WEB_CLIENT profile with redirect.enabled=true did not follow redirects; the caller received the 3xx as an ordinary response. Refused until the reactive coordinator exists.
• 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.