5.2 KiB
adapter:outbound:httpclient
The outbound HTTP Client Platform: a single contract for how this service talks to anything over
HTTP. It is not a wrapper around RestClient — it owns the target, the connection resources, the
time budget, the evidence of what actually executed, retry safety, authentication, TLS, SSRF
defence, and observability.
Design: httpclient-superpowers-package/docs/superpowers/specs/2026-08-08-httpclient-platform-design.md
Adaptation to this repository: docs/httpclient/repository-adaptation.md
Choosing a surface
| Surface | Use it when | What it fixes for you |
|---|---|---|
H1 typed client (HttpServiceRegistry) |
almost always | URL, timeout, auth, retry, limits, metrics |
H2 generic exchange (GenericHttpGateway, BlockingStreamingGateway) |
method, path, or body must vary at runtime | scheme, host, port, TLS, credentials, hard limits |
H3 dynamic target (DynamicTargetGateway) |
the URL comes from a user | full SSRF validation; inherits no credential |
| H4 native engine | never, from application code | — |
@HttpClientProfile("users")
@HttpExchange("/users")
public interface UsersClient {
@GetExchange("/{id}")
@HttpOperationPolicy(name = "get-user", idempotency = OperationIdempotency.STANDARD_IDEMPOTENT)
UserResponse get(@PathVariable long id);
}
The interface fails startup unless it names a profile, gives every method a stable operation name, declares idempotency explicitly, and supplies a key parameter when the operation requires one.
Every call is blocking and runs on the caller's thread — a virtual thread in this template. There is
no reactive (WebClient/Reactor Netty) surface; it was removed on 2026-09-25 (decision 9).
What the platform decides for you
- Time. One effective deadline covers pool acquire, DNS, connect, TLS, write, read, and every retry backoff. Streaming splits setup, idle, and total lifetime.
- Evidence. Each attempt reports
NOT_SENT,SENT_NO_RESPONSE,RESPONSE_RECEIVED, orPARTIAL_RESPONSE.NOT_SENTis only claimed when a stage failure proves it. - Retry. Never from the HTTP method alone. Idempotency, body replayability, evidence, deadline,
and a per-upstream token budget all have to agree. A sent, non-idempotent request with no response
raises
HttpAmbiguousExecutionExceptioninstead of being retried or reported as a plain failure. - Order. Every physical attempt passes Circuit Breaker → Rate Limiter → Bulkhead, and holds no permit while a backoff waits.
- Resources. Connections and buffers are reclaimed after success, error, decode failure, size rejection, and cancellation alike.
- Secrets. No URL, query value, path variable, token, cookie, or idempotency key reaches a log, a metric label, or an exception message.
제공하는 것 · 추가할 한 줄 · env 키
-
제공: 위 H1–H3 surface(
HttpServiceRegistry,GenericHttpGateway,DynamicTargetGateway등), transport·TLS·credential·resilience·관측, actuator endpoint. OAuth2 client credential 지원 (spring-security-oauth2-client)도 이 모듈이 가진다. 설정 기본값config/module-defaults/httpclient.yml은 support의ModuleDefaultsEnvironmentPostProcessor가 읽는다(우선순위 가장 낮음). -
추가할 한 줄(기본 조립에는 없다):
// app-bootstrap/build.gradle runtimeOnly project(':adapter:outbound:httpclient') // 외부 HTTP 호출이 줄을 지우면 platform bean, 설정 기본값, OAuth2 client 의존성이 모두 함께 빠진다.
-
켜기와 끄기: 모듈이 있으면 켜진다.
APP_HTTPCLIENT_ENABLED=false로만 끈다. -
필요한 env 키(
docs/registries/env-keys.yamlSSOT): client 하나 이상 —APP_HTTPCLIENT_CLIENTS_0_NAME,APP_HTTPCLIENT_CLIENTS_0_BASE_URL,APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0,APP_HTTPCLIENT_CLIENTS_0_ALLOWED_PORTS_0,APP_HTTPCLIENT_CLIENTS_0_REQUEST_MAX_BODY_BYTES,APP_HTTPCLIENT_CLIENTS_0_TLS_PROFILE_ID(필드 전체는docs/httpclient/env-fields.yaml). client가 없으면HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS로 기동이 실패한다.
Configuration
Profiles live under app.httpclient.clients[N]; Dynamic Target policies under
app.httpclient.dynamic-targets[N]. Every startup guard, property, and violation code is listed in
docs/httpclient/configuration-reference.md.
Verification
cd src
./gradlew :adapter:outbound:httpclient:test --console=plain
./gradlew :adapter:outbound:httpclient:httpClientStableContractTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientSecurityTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain
./gradlew :adapter:outbound:httpclient:httpClientFailureInjectionTest --console=plain # needs Docker
No lane skips silently. The fault lane fails without Docker, the contract lane fails on an empty or unknown transport selection, and the performance lane reports which machine-dependent bounds it did not assert.
Further reading
docs/httpclient/ holds the support matrix, configuration reference, retry and ambiguity guide,
security guide, streaming guide, operations runbook, performance baseline, and
release checklist.