Files
clean-architecture-backend-…/src/adapter/outbound/httpclient/README.md
T

5.2 KiB
Raw Blame History

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, or PARTIAL_RESPONSE. NOT_SENT is 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 HttpAmbiguousExecutionException instead 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.yaml SSOT): 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.