diff --git a/docs/httpclient/configuration-reference.md b/docs/httpclient/configuration-reference.md index d23ff7c0..25691bed 100644 --- a/docs/httpclient/configuration-reference.md +++ b/docs/httpclient/configuration-reference.md @@ -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.` -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.`는 아무것도 바인딩하지 않고 아무것도 실패시키지 +않았다. 이제 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 방어는 있고 맞지만 우회된다. 그래서 +이 조합은 지킬 수 없는 보장을 단 채 내주지 않고 거부한다. diff --git a/docs/httpclient/env-fields.yaml b/docs/httpclient/env-fields.yaml index b8ecbf59..f10d483e 100644 --- a/docs/httpclient/env-fields.yaml +++ b/docs/httpclient/env-fields.yaml @@ -1,29 +1,27 @@ -# HTTP Client platform — Java field path to environment variable template. +# HTTP Client 플랫폼 — Java 필드 경로에서 환경 변수 template로의 대응. # -# The SSOT is HttpClientPlatformSettings. HttpClientPlatformEnvManifestTest derives this list from -# the record tree and fails when the two disagree in either direction, and the shared strict binder -# refuses to start on an APP_HTTPCLIENT_ variable that names no field. So a -# field added with no entry, an entry whose field was renamed, and a misspelled variable in a -# deployment are all failures rather than silence. +# 정본은 HttpClientPlatformSettings다. HttpClientPlatformEnvManifestTest가 record 트리에서 이 목록을 만들어 +# 양쪽 방향으로 어긋나면 실패하고, 공용 엄격 binder는 어떤 필드도 가리키지 않는 APP_HTTPCLIENT_ 변수가 +# 있으면 시작을 거부한다. 그래서 항목 없이 더한 필드, 필드 이름이 바뀐 항목, 배포의 오타 변수가 모두 +# 조용히 넘어가지 않고 실패한다. # -# `N` and `M` are list indices, not literals: `N` for the outermost list, `M` for a list inside it. -# `app.httpclient.clients[N].base-url` is set as APP_HTTPCLIENT_CLIENTS_0_BASE_URL for the first -# client, and `clients[N].allowed-hosts[M]` as APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0. +# `N`과 `M`은 글자 그대로가 아니라 list index다. `N`은 바깥 list, `M`은 그 안의 list다. +# 첫 client의 `app.httpclient.clients[N].base-url`은 APP_HTTPCLIENT_CLIENTS_0_BASE_URL로, +# `clients[N].allowed-hosts[M]`은 APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0으로 준다. # -# Only APP_HTTPCLIENT_ENABLED is registered in docs/registries/env-keys.yaml and shipped in -# src/.env: it is the only key with a deployment-independent value, and it is the only one the -# three-way :app-bootstrap:verifyEnvKeys gate can express. Everything below is per deployment and is set directly -# in the environment — templating an indexed client in application.yml would materialise a nameless -# client in every deployment, which the settings' aggregate validation refuses. +# docs/registries/env-keys.yaml에 등록하고 src/.env에 담는 것은 APP_HTTPCLIENT_ENABLED뿐이다. 배포와 +# 상관없는 값을 가진 유일한 key이고, 세 방향을 대조하는 :app-bootstrap:verifyEnvKeys 게이트가 표현할 수 +# 있는 유일한 key다. 아래 나머지는 모두 배포마다 다르고 환경에 직접 준다. index를 단 client를 +# application.yml에 template로 두면 모든 배포에 이름 없는 client가 생기고, settings의 묶음 검증이 그것을 +# 거부한다. # -# This file lives beside the HTTP Client documentation rather than in docs/registries, which is a -# fail-closed catalog of exactly eight contract registries with a fixed row schema -# (owner_branch/compatibility_impact/required_test per row). A field-to-variable mapping does not -# have that shape, and admitting it would have meant loosening a gate rather than satisfying one. +# 이 파일은 docs/registries가 아니라 HTTP Client 문서 옆에 있다. docs/registries는 행 schema +# (행마다 owner_branch/compatibility_impact/required_test)가 고정된 계약 registry만 받는, 닫힌 쪽으로 +# 실패하는 목록이다. 필드-변수 대응은 그 모양이 아니고, 받아들이려면 게이트를 맞추는 대신 풀어야 했다. # -# Secrets are referenced, never carried: authentication.secret-reference, tls.*-material-reference -# and proxy.credential-provider name material that a secret backend resolves. Putting the material -# itself in one of these variables defeats the indirection they exist for. +# secret은 값이 아니라 참조로 준다. authentication.secret-reference, tls.*-material-reference, +# proxy.credential-provider는 secret backend가 푸는 재료의 이름이다. 재료 자체를 이 변수에 넣으면 +# 이 변수들이 있는 이유인 간접화가 무너진다. fields: - field: enabled env: APP_HTTPCLIENT_ENABLED diff --git a/docs/httpclient/operations.md b/docs/httpclient/operations.md index bf95cfae..f19f8754 100644 --- a/docs/httpclient/operations.md +++ b/docs/httpclient/operations.md @@ -1,129 +1,123 @@ -# HTTP Client Platform — Operations Runbook +# HTTP Client 플랫폼 — 운영 runbook -## Metrics +## Metric -| Metric | Meaning | +| Metric | 뜻 | |---|---| -| `http.client.requests` | Physical attempt timer (Spring standard name, kept deliberately) | -| `http.client.logical.calls` | User-visible logical call timer | -| `http.client.attempts` | Attempt counter | -| `http.client.retry.count` | Retries by reason | -| `http.client.retry.exhausted` | Retry budget exhausted | -| `http.client.ambiguous` | Ambiguous outcomes | -| `http.client.timeout` | Timeouts by stage | -| `http.client.request.bytes` | Request wire bytes | -| `http.client.response.bytes` | Response bytes | -| `http.client.active` | In-flight attempts | -| `http.client.pool.connections` | Leased and available connections | -| `http.client.pool.pending` | Pool waiters | -| `http.client.pool.acquire.duration` | Pool wait time | -| `http.client.dns.duration` | DNS time | -| `http.client.connect.duration` | Connect time | -| `http.client.tls.duration` | TLS time | -| `http.client.circuit.state` | Circuit state | -| `http.client.bulkhead.rejected` | Bulkhead rejections | -| `http.client.rate_limit.rejected` | Local rate-limit rejections | -| `http.client.oauth.refresh` | Token refresh outcomes | -| `http.client.ssrf.rejected` | Dynamic target rejections | +| `http.client.requests` | 물리 시도 timer(Spring 표준 이름. 일부러 그대로 둔다) | +| `http.client.logical.calls` | 사용자에게 보이는 논리 호출 timer | +| `http.client.attempts` | 시도 counter | +| `http.client.retry.count` | 이유별 재시도 | +| `http.client.retry.exhausted` | 재시도 예산 소진 | +| `http.client.ambiguous` | 결과를 모르는 경우 | +| `http.client.timeout` | 단계별 시간 초과 | +| `http.client.request.bytes` | 요청 wire 바이트 | +| `http.client.response.bytes` | 응답 바이트 | +| `http.client.active` | 진행 중인 시도 | +| `http.client.pool.connections` | 빌려 간 connection과 남은 connection | +| `http.client.pool.pending` | pool 대기자 | +| `http.client.pool.acquire.duration` | pool 대기 시간 | +| `http.client.dns.duration` | DNS 시간 | +| `http.client.connect.duration` | 연결 시간 | +| `http.client.tls.duration` | TLS 시간 | +| `http.client.circuit.state` | circuit 상태 | +| `http.client.bulkhead.rejected` | bulkhead 거부 | +| `http.client.rate_limit.rejected` | 로컬 속도 제한 거부 | +| `http.client.oauth.refresh` | token 갱신 결과 | +| `http.client.ssrf.rejected` | dynamic target 거부 | -`http.client.requests` counts attempts and `http.client.logical.calls` counts user calls. When they -diverge, retries are absorbing failures — which is the first thing to look at during an incident. +`http.client.requests`는 시도를 세고 `http.client.logical.calls`는 사용자 호출을 센다. 둘이 벌어지면 재시도가 +실패를 흡수하고 있다는 뜻이다. 장애 때 가장 먼저 볼 곳이다. -## Reading an incident +## 장애 읽기 -| Symptom | Likely cause | Where to look | +| 증상 | 그럴듯한 원인 | 볼 곳 | |---|---|---| -| logical calls fine, attempts spiking | upstream degraded, retries absorbing it | `http.client.retry.count` by reason | -| `http.client.ambiguous` non-zero | non-idempotent writes reaching `SENT_NO_RESPONSE` | reconcile with the upstream; consider an idempotency key | -| pool pending climbing | pool too small or upstream slow | `http.client.pool.acquire.duration`, `pool.connections` | -| circuit open | sustained upstream failure: transport errors, 5xx, 408, 429 | `http.client.circuit.state`; local rejections and other 4xx do not open it | -| `http.client.ssrf.rejected` non-zero | a caller is submitting internal URLs | Dynamic Target policy and audit trail | +| 논리 호출은 괜찮은데 시도가 치솟는다 | upstream이 나빠졌고 재시도가 흡수하고 있다 | 이유별 `http.client.retry.count` | +| `http.client.ambiguous`가 0이 아니다 | 멱등이 아닌 쓰기가 `SENT_NO_RESPONSE`에 닿는다 | upstream과 맞춰 본다. 멱등 key를 검토한다 | +| pool 대기가 오른다 | pool이 작거나 upstream이 느리다 | `http.client.pool.acquire.duration`, `pool.connections` | +| circuit이 열렸다 | 계속된 upstream 실패: transport 오류, 5xx, 408, 429 | `http.client.circuit.state`. 로컬 거부와 그 밖의 4xx는 circuit을 열지 않는다 | +| `http.client.ssrf.rejected`가 0이 아니다 | 호출자가 내부 URL을 넣고 있다 | Dynamic Target 정책과 감사 기록 | ## Actuator -`GET /actuator/httpclients` reports profile name, runtime generation, state, transport, API, -protocols, active leases, pool ceiling, credential type, TLS profile id, redirect flag, retry policy, -and capability warnings. Base URL, credentials, trust store paths, and resolved IPs are deliberately -absent: an actuator endpoint is reachable by more people than a secret store is. +`GET /actuator/httpclients`는 profile 이름, 런타임 세대, 상태, transport, API, protocol, 진행 중인 lease, pool +상한, credential 유형, TLS profile id, redirect flag, 재시도 정책, capability 경고를 보고한다. Base URL, credential, +trust store 경로, 푼 IP는 일부러 뺐다. actuator endpoint에는 secret 저장소보다 많은 사람이 닿는다. -## Rotation +## 교체 -Certificates and secrets rotate by building a new runtime generation and swapping the registry -pointer, never by mutating a live client. A connection pool holds sockets established under the -previous identity, so replacing material without replacing the pool leaves live connections -authenticated by a certificate that is meant to be gone. +인증서와 secret은 살아 있는 client를 바꾸지 않고, 새 런타임 세대를 만들어 registry pointer를 바꿔 끼우는 식으로 +교체한다. connection pool은 앞 신원으로 맺은 socket을 쥐고 있다. 그래서 pool은 그대로 두고 재료만 바꾸면, 없어져야 +할 인증서로 인증한 connection이 살아 있다. ```text -build new generation → validate → atomic swap → new calls use it -old generation → DRAINING → in-flight calls finish → no new retries → forced close at the drain deadline +새 세대 만들기 → 검증 → 원자적 교체 → 새 호출이 그것을 쓴다 +옛 세대 → DRAINING → 진행 중인 호출이 끝난다 → 새 재시도 없음 → drain 기한에 강제로 닫는다 ``` -## Shutdown +## 종료 ```text RUNNING → DRAINING -new logical calls refused or routed to the new generation -in-flight attempts complete -new retries refused -shutdown timeout -remaining calls cancelled -pool closed +새 논리 호출을 거부하거나 새 세대로 보낸다 +진행 중인 시도가 끝난다 +새 재시도를 거부한다 +종료 시간 초과 +남은 호출을 취소한다 +pool을 닫는다 ``` -## Retry ownership +## 재시도 소유 -Exactly one of the application client, an external SDK, or the service mesh may own retries. -Two owners multiply traffic during an incident. Record the owner per upstream and check it whenever -a mesh retry policy changes. +애플리케이션 client, 외부 SDK, service mesh 중 정확히 하나만 재시도를 가진다. 소유자가 둘이면 장애 중에 트래픽이 +곱절로 는다. upstream마다 소유자를 적고, mesh 재시도 정책이 바뀔 때마다 확인한다. -## Error model +## 오류 모델 -Every outbound failure is one of these stable types. The type is derived from the classified failure -category, not from whatever the engine happened to throw, so it means the same thing on Apache and -JDK. Each carries `HttpFailureMetadata`: client, operation, method, URI **template**, -evidence, replayability, stage, retryability, attempt, elapsed, remaining deadline, status, trace id -— and nothing else. +모든 외부 호출 실패는 아래 안정된 타입 중 하나다. 타입은 엔진이 마침 던진 것이 아니라 분류한 실패 범주에서 +정한다. 그래서 Apache와 JDK에서 같은 뜻이다. 모두 `HttpFailureMetadata`를 가진다: client, 연산, method, URI +**template**, 증거, 재전송 가능성, 단계, 재시도 가능 여부, 시도 번호, 흐른 시간, 남은 기한, 상태, trace id. +그 밖의 것은 없다. -| Exception | Raised when | Retryable | +| 예외 | 던지는 때 | 재시도 | |---|---|---| -| `HttpConfigurationException` | profile, operation, or capability configuration is invalid | never | -| `HttpTargetRejectedException` | target URI, host, port, header, or address policy refused the request | never | -| `HttpDnsException` | hostname resolution failed or timed out | yes, inside budget | -| `HttpPoolAcquireTimeoutException` | no connection or stream within the pending-acquire budget | yes, inside budget | -| `HttpConnectException` | socket connect failed | yes, inside budget | -| `HttpProxyException` | proxy connect, CONNECT tunnel, or proxy auth failed | yes, inside budget | -| `HttpTlsException` | TLS handshake failed | only a transient handshake timeout | -| `HttpRequestWriteException` | request headers or body could not be fully written | only when safely idempotent | -| `HttpResponseTimeoutException` | final headers or a body chunk did not arrive in time | only when safely idempotent | -| `HttpResponseTruncatedException` | the response ended before the body was complete | only when safely idempotent and undelivered | -| `HttpRemoteErrorException` | non-success status without a problem document | per the status rules | -| `HttpProblemDetailException` | non-success status with a bounded RFC 9457 document | per the status rules | -| `HttpRedirectRejectedException` | a hop violated hop count, origin, method, or replay policy | never | -| `HttpAuthenticationException` | credential materialization or refresh failed | never | -| `HttpSerializationException` | request encoding or response decoding failed | never | -| `HttpResponseTooLargeException` | wire or decoded bytes exceeded the profile limit | never | -| `HttpDeadlineExceededException` | the effective deadline was reached | never | -| `HttpCircuitOpenException` | the upstream circuit is open | never | -| `HttpBulkheadRejectedException` | no attempt or logical admission permit was available | never | -| `HttpRateLimitRejectedException` | the local attempt rate limiter rejected the attempt | never | -| `HttpRetryBudgetExhaustedException` | the per-upstream retry budget refused a further attempt | never | -| `HttpRuntimeDrainingException` | the profile's runtime was retired (certificate rotation) before a granted retry started | never — a new call runs on the replacement | -| `HttpUnknownTransportException` | the engine failed in a way no category above describes; the metadata evidence, not the type, says whether it was sent | never | -| `HttpAmbiguousExecutionException` | a non-idempotent request was sent and the outcome is unknown | never — reconcile instead | +| `HttpConfigurationException` | profile, 연산, capability 설정이 잘못됐다 | 안 함 | +| `HttpTargetRejectedException` | 대상 URI, host, port, 헤더, 주소 정책이 요청을 거부했다 | 안 함 | +| `HttpDnsException` | hostname 풀기가 실패하거나 시간이 넘었다 | 예산 안에서 함 | +| `HttpPoolAcquireTimeoutException` | 대기 예산 안에 connection이나 stream을 얻지 못했다 | 예산 안에서 함 | +| `HttpConnectException` | socket 연결이 실패했다 | 예산 안에서 함 | +| `HttpProxyException` | proxy 연결, CONNECT tunnel, proxy 인증이 실패했다 | 예산 안에서 함 | +| `HttpTlsException` | TLS handshake가 실패했다 | 일시적인 handshake 시간 초과만 | +| `HttpRequestWriteException` | 요청 헤더나 본문을 다 쓰지 못했다 | 안전하게 멱등일 때만 | +| `HttpResponseTimeoutException` | 최종 헤더나 본문 chunk가 제때 오지 않았다 | 안전하게 멱등일 때만 | +| `HttpResponseTruncatedException` | 본문이 끝나기 전에 응답이 끝났다 | 안전하게 멱등이고 아직 넘기지 않았을 때만 | +| `HttpRemoteErrorException` | problem document 없는 실패 상태 | 상태 규칙대로 | +| `HttpProblemDetailException` | 크기가 제한된 RFC 9457 document가 있는 실패 상태 | 상태 규칙대로 | +| `HttpRedirectRejectedException` | hop이 hop 수, origin, method, 재전송 정책을 어겼다 | 안 함 | +| `HttpAuthenticationException` | credential 만들기나 갱신이 실패했다 | 안 함 | +| `HttpSerializationException` | 요청 인코딩이나 응답 디코딩이 실패했다 | 안 함 | +| `HttpResponseTooLargeException` | wire나 디코딩한 바이트가 profile 한도를 넘었다 | 안 함 | +| `HttpDeadlineExceededException` | 실제 기한에 닿았다 | 안 함 | +| `HttpCircuitOpenException` | upstream circuit이 열렸다 | 안 함 | +| `HttpBulkheadRejectedException` | 시도나 논리 허가를 얻지 못했다 | 안 함 | +| `HttpRateLimitRejectedException` | 로컬 시도 속도 제한이 시도를 거부했다 | 안 함 | +| `HttpRetryBudgetExhaustedException` | upstream별 재시도 예산이 다음 시도를 거부했다 | 안 함 | +| `HttpRuntimeDrainingException` | 허락한 재시도가 시작되기 전에 profile 런타임이 내려갔다(인증서 교체) | 안 함 — 새 호출은 바뀐 런타임에서 돈다 | +| `HttpUnknownTransportException` | 위 범주 어느 것도 설명하지 못하는 방식으로 엔진이 실패했다. 보냈는지는 타입이 아니라 metadata의 증거가 말한다 | 안 함 | +| `HttpAmbiguousExecutionException` | 멱등이 아닌 요청을 보냈고 결과를 모른다 | 안 함 — 대신 맞춰 본다 | -A streamed body that fails after hand-over is the one place these arrive wrapped: `read` throws -`HttpBodyReadException`, an `IOException` as `InputStream` promises, and its `failure()` is the -`HttpResponseTimeoutException` or `HttpResponseTruncatedException` above (re-review 2026-11-04 -RR-03-14). +이 예외들이 감싸져서 오는 곳은 하나다. 넘긴 뒤 실패한 스트리밍 본문이다. `read`가 `HttpBodyReadException`을 +던진다. `InputStream`이 약속한 대로 `IOException`이고, 그 `failure()`가 위의 `HttpResponseTimeoutException`이나 +`HttpResponseTruncatedException`이다(재리뷰 2026-11-04 RR-03-14). -## Traces +## Trace ```text -http.client.operation logical internal span -└─ http.client.request attempt 1 CLIENT span -└─ http.client.request attempt 2 CLIENT span +http.client.operation 논리 호출의 내부 span +└─ http.client.request 시도 1의 CLIENT span +└─ http.client.request 시도 2의 CLIENT span ``` -W3C Trace Context is propagated with a Baggage allowlist. Dynamic Targets do not propagate trace -context by default. Retry reason and evidence are recorded as span events; credentials and remote -error bodies are never recorded as attributes. +W3C Trace Context를 Baggage 허용 목록과 함께 전파한다. Dynamic Target은 기본으로 trace context를 전파하지 +않는다. 재시도 이유와 증거는 span event로 기록한다. credential과 원격 오류 본문은 절대 속성으로 기록하지 않는다. diff --git a/docs/httpclient/performance-baseline.md b/docs/httpclient/performance-baseline.md index 0a1ee87e..ea6a387b 100644 --- a/docs/httpclient/performance-baseline.md +++ b/docs/httpclient/performance-baseline.md @@ -1,55 +1,51 @@ -# HTTP Client Platform — Performance Baseline +# HTTP Client 플랫폼 — 성능 기준선 -The certification lane asserts **resource bounds**, not throughput targets. Its purpose is to prove -that a failing upstream, a large body, or a rotation cannot consume unbounded memory, connections, -threads, or upstream traffic. Nothing here becomes a runtime adaptive default: every bound comes -from an explicit profile setting. +인증 lane은 처리량 목표가 아니라 **자원 상한**을 단언한다. 실패하는 upstream, 큰 본문, 교체가 메모리, connection, +스레드, upstream 트래픽을 끝없이 먹지 못함을 증명하려는 것이다. 여기 있는 어떤 것도 실행 중 적응형 기본값이 되지 +않는다. 모든 상한은 profile에 명시한 설정에서 온다. -## How to run +## 돌리는 법 ```bash -# every bound, structural and machine-dependent +# 모든 상한: 구조적 상한과 기계에 따른 상한 ./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain -# JMH benchmarks: numbers only, never a gate +# JMH benchmark: 숫자만 낸다. 게이트가 아니다 ./gradlew :adapter:outbound:httpclient:jmh --console=plain ``` -The lane asserts every bound in every run. There is no switch that turns the machine-dependent one -off: the strict-lane convention fails a performance lane before it runs when the build sets -`performance.assertions.enabled` to anything but `true`, and fails it when one of its tests is -skipped. The same command is what `integration-main.yml` (`:performanceCheck`) and `release.yml` -run. Every run prints the measured heap increase (`[httpclient-performance] streaming download heap -increase … bytes, bound … bytes`) to the test output and report, and a bound that fails repeats the -value in its assertion message; for numbers without a verdict, use JMH. +lane은 매번 모든 상한을 단언한다. 기계에 따라 다른 상한을 끄는 스위치는 없다. 빌드가 +`performance.assertions.enabled`에 `true` 아닌 값을 넣으면 strict lane convention이 성능 lane을 돌기 전에 실패시키고, +테스트 하나라도 건너뛰면 실패시킨다. `integration-main.yml`(`:performanceCheck`)과 `release.yml`이 도는 것도 같은 +명령이다. 매번 잰 heap 증가량(`[httpclient-performance] streaming download heap increase … bytes, bound … bytes`)을 +테스트 출력과 보고서에 찍고, 실패한 상한은 단언 메시지에 그 값을 다시 적는다. 판정 없는 숫자가 필요하면 JMH를 쓴다. -## Certified bounds +## 인증한 상한 -| Test | Bound | Kind | +| 테스트 | 상한 | 종류 | |---|---|---| -| `RetryStormBudgetTest` | 10 000 logical calls against a failing upstream produce at most 11 000 physical attempts at a 10 % budget | structural | -| `LargeBodyResourceTest` | a 32 MiB streaming download consumes every byte without buffering the payload on the heap | structural + machine-dependent heap bound | -| `PoolSaturationPerformanceTest` | 24 concurrent calls against a 4-connection pool all reach a terminal outcome; none hang | structural | -| `OAuthRefreshContentionTest` | 100 genuinely concurrent callers produce exactly one token request | structural | -| `RuntimeRotationDrainTest` | 50 rotations close all 50 retired generations and leave no drain thread | structural | +| `RetryStormBudgetTest` | 실패하는 upstream에 대한 논리 호출 10 000개가 10 % 예산에서 물리 시도를 최대 11 000개 만든다 | 구조적 | +| `LargeBodyResourceTest` | 32 MiB 스트리밍 다운로드가 payload를 heap에 버퍼링하지 않고 모든 바이트를 읽는다 | 구조적 + 기계에 따른 heap 상한 | +| `PoolSaturationPerformanceTest` | connection 4개짜리 pool에 대한 동시 호출 24개가 모두 끝 상태에 닿는다. 멈춘 것이 없다 | 구조적 | +| `OAuthRefreshContentionTest` | 정말 동시에 부르는 호출자 100개가 token 요청을 정확히 하나 만든다 | 구조적 | +| `RuntimeRotationDrainTest` | 교체 50번이 내린 세대 50개를 모두 닫고 drain 스레드를 남기지 않는다 | 구조적 | -## Recording a baseline +## 기준선 기록하기 -When certifying a deployment, record alongside the numbers: the exact command, the commit, hardware, -JVM flags, the profile YAML under test, p50/p95/p99/max, peak heap, peak direct memory, thread count, -connection count, physical attempt count, and error count. A latency figure without its profile and -hardware is not a baseline; it is an anecdote. +배포를 인증할 때는 숫자와 함께 이것을 적는다: 정확한 명령, commit, 하드웨어, JVM flag, 시험한 profile YAML, +p50/p95/p99/max, 최대 heap, 최대 direct memory, 스레드 수, connection 수, 물리 시도 수, 오류 수. profile과 +하드웨어 없는 지연 숫자는 기준선이 아니라 일화다. -| Field | Value | +| 항목 | 값 | |---|---| -| Command | _fill in at certification time_ | -| Commit | _fill in_ | -| Hardware / JVM | _fill in_ | -| Profile under test | _fill in_ | -| p50 / p95 / p99 / max | _fill in_ | -| Peak heap / direct memory | _fill in_ | -| Threads / connections | _fill in_ | -| Physical attempts / errors | _fill in_ | +| 명령 | _인증할 때 채운다_ | +| Commit | _채운다_ | +| 하드웨어 / JVM | _채운다_ | +| 시험한 profile | _채운다_ | +| p50 / p95 / p99 / max | _채운다_ | +| 최대 heap / direct memory | _채운다_ | +| 스레드 / connection | _채운다_ | +| 물리 시도 / 오류 | _채운다_ | -The table is intentionally left unfilled in the repository: publishing numbers measured on a build -agent as if they were a certified baseline would be worse than having none. +이 표는 저장소에서 일부러 비워 둔다. 빌드 agent에서 잰 숫자를 인증한 기준선처럼 내놓는 것은 기준선이 없는 +것보다 나쁘다. diff --git a/docs/httpclient/release-checklist.md b/docs/httpclient/release-checklist.md index a11e0f7f..f4de1284 100644 --- a/docs/httpclient/release-checklist.md +++ b/docs/httpclient/release-checklist.md @@ -1,8 +1,8 @@ -# HTTP Client Platform — Release Checklist +# HTTP Client 플랫폼 — 릴리스 점검표 -A release is complete when each item below is demonstrated by a command, not by review. +아래 항목마다 검토가 아니라 명령으로 보여 줬을 때 릴리스가 끝난다. -## Gates +## 게이트 ```bash cd src @@ -11,34 +11,33 @@ cd src ./gradlew :adapter:outbound:httpclient:httpClientSecurityTest --console=plain ./gradlew :adapter:outbound:httpclient:spring62ApiSurfaceScan --console=plain ./gradlew :adapter:outbound:httpclient:spring70CompatibilityTest --console=plain -./gradlew :adapter:outbound:httpclient:httpClientFailureInjectionTest --console=plain # needs Docker -./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain # every bound asserted +./gradlew :adapter:outbound:httpclient:httpClientFailureInjectionTest --console=plain # Docker 필요 +./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain # 모든 상한을 단언 ./gradlew verifyCleanArchitectureDependencies --console=plain ./gradlew :app-bootstrap:architectureTest --console=plain python3 ../scripts/verify-httpclient-docs.py ``` -## Completion criteria (design §33) +## 완료 기준 (설계서 §33) -- [ ] Typed clients are the default entry point; H2 and H3 are separately authorised. -- [ ] H1–H4 cannot bypass timeout, host, TLS, auth, size, or observation policy. -- [ ] Apache and JDK produce identical result and exception metadata. -- [ ] Pool, DNS, connect, TLS, and retry backoff all fit inside the effective deadline. -- [ ] Every extra attempt is explained by idempotency, replayability, evidence, deadline, and budget. -- [ ] Non-idempotent `SENT_NO_RESPONSE` surfaces as `HttpAmbiguousExecutionException`. -- [ ] Pool and buffers are reclaimed after unread bodies, decode errors, cancels, and size rejections. -- [ ] OAuth2 refresh is single-flight and 401 replay happens at most once. -- [ ] Trust-all and hostname-verification bypass fail at startup. -- [ ] Canonicalisation, DNS/IP validation, redirect revalidation, and egress control all pass. -- [ ] No transparent retry occurs after the first delivered byte. -- [ ] The negotiated wire protocol matches what the support matrix claims per transport. -- [ ] Logical calls and attempts are separate metrics with no forbidden label. -- [ ] DNS, pool, TLS, reset, partial response, and HTTP/2 GOAWAY are reproducible. -- [ ] Thread, heap, direct memory, pool, and retry budget bounds hold. -- [ ] The support matrix, configuration reference, security guide and runbook match the code. +- [ ] 타입 있는 client가 기본 진입점이다. H2와 H3은 따로 허가한다. +- [ ] H1–H4는 timeout, host, TLS, 인증, 크기, 관측 정책을 우회할 수 없다. +- [ ] Apache와 JDK가 같은 결과와 예외 metadata를 낸다. +- [ ] pool, DNS, 연결, TLS, 재시도 backoff가 모두 실제 기한 안에 들어간다. +- [ ] 추가 시도마다 멱등성, 재전송 가능성, 증거, 기한, 예산으로 설명된다. +- [ ] 멱등이 아닌 `SENT_NO_RESPONSE`는 `HttpAmbiguousExecutionException`으로 드러난다. +- [ ] 읽지 않은 본문, 디코딩 오류, 취소, 크기 거부 뒤에 pool과 buffer를 되찾는다. +- [ ] OAuth2 갱신은 한 번만 날아가고, 401 재전송은 많아야 한 번이다. +- [ ] trust-all과 hostname 검증 우회는 시작 때 실패한다. +- [ ] 정규화, DNS/IP 검증, redirect 재검증, egress 통제가 모두 통과한다. +- [ ] 첫 바이트를 넘긴 뒤에는 투명한 재시도가 일어나지 않는다. +- [ ] 협상한 wire protocol이 support matrix가 transport마다 주장하는 것과 맞는다. +- [ ] 논리 호출과 시도는 따로 된 metric이고 금지 label이 없다. +- [ ] DNS, pool, TLS, reset, 부분 응답, HTTP/2 GOAWAY를 재현할 수 있다. +- [ ] 스레드, heap, direct memory, pool, 재시도 예산 상한이 지켜진다. +- [ ] support matrix, 설정 참조, 보안 안내, runbook이 코드와 맞는다. ## Experimental -Jetty HTTP/3 stays Experimental until `Http3CapabilityReport` reports QUIC and TLS 1.3 and the -contract subset it declares passes in a dedicated environment. It is never auto-configured by the -Stable starter. +Jetty HTTP/3은 `Http3CapabilityReport`가 QUIC와 TLS 1.3을 보고하고, 그것이 선언한 계약 부분집합이 전용 환경에서 +통과할 때까지 Experimental로 남는다. Stable starter가 자동 구성하는 일은 없다. diff --git a/docs/httpclient/repository-adaptation.md b/docs/httpclient/repository-adaptation.md index 4b7c9476..fbd7d5b9 100644 --- a/docs/httpclient/repository-adaptation.md +++ b/docs/httpclient/repository-adaptation.md @@ -1,44 +1,43 @@ -# HTTP Client Platform — Repository Adaptation Contract +# HTTP Client 플랫폼 — 저장소 적응 계약 -**Design source:** `docs/design/2026-08-08-httpclient-platform-design.md` -**Plan source:** `docs/history/plans/2026-08-08-httpclient-platform-implementation-plan.md` +**설계서:** `docs/design/2026-08-08-httpclient-platform-design.md` +**계획서:** `docs/history/plans/2026-08-08-httpclient-platform-implementation-plan.md` -The design package states its own adaptation rule: +설계 패키지는 자기 적응 규칙을 스스로 밝힌다. > 실제 Backend Skeleton 저장소가 제공되지 않았으므로 package 경로와 Gradle 구조는 설계서의 명시적 > 구현 가정이다. 구현 전 저장소의 기존 convention과 root package에 맞춰 경로만 조정하고 공개 계약과 > 정책 의미론은 유지한다. -This file is the single record of *how* the design's assumed layout was mapped onto this repository. -Only paths, build DSL, and composition-root ownership changed. Public contracts, policy order, and -error semantics are implemented exactly as specified. +이 파일은 설계가 가정한 배치를 이 저장소에 *어떻게* 옮겼는지 적은 유일한 기록이다. 바뀐 것은 경로, 빌드 DSL, +조립 루트의 소유뿐이다. 공개 계약, 정책 순서, 오류 의미는 명세대로 구현했다. -## 1. Why the module layout differs +## 1. 모듈 배치가 다른 이유 -The design assumes a greenfield library with 19 Gradle projects under `modules/httpclient/`. -This repository is a Clean Architecture template whose **fail-closed registry** -(`src/config/architecture/modules.json`, enforced by `src/settings.gradle` and -`verifyCleanArchitectureDependencies`) declares **exactly 19 leaf identities**. Creating 19 more -Gradle projects would violate HARD-STOP #5 in `AGENTS.md`. +설계는 `modules/httpclient/` 아래에 Gradle 프로젝트 19개를 둔 새 라이브러리를 가정한다. 이 저장소는 Clean +Architecture 템플릿이고, **닫힌 쪽으로 실패하는 registry**(`src/config/architecture/modules.json`)가 Gradle 프로젝트 +목록을 정한다. `src/settings.gradle`이 registry에 있는 프로젝트만 포함하고, `verifyCleanArchitectureDependencies`가 +허용하지 않은 의존을 막는다. leaf 목록은 registry가 정본이다. 설계의 모듈마다 Gradle 프로젝트를 만들면 +`AGENTS.md`의 HARD-STOP 5번(registry·Gradle 의존성 검증 위반)에 걸린다. -Therefore the design's 19 library modules become **package boundaries inside the registered leaf** -`:adapter:outbound:httpclient`, with two exceptions driven by this repository's own rules: +그래서 설계의 라이브러리 모듈은 등록된 leaf `:adapter:outbound:httpclient` **안의 package 경계**가 된다. 이 저장소 +자신의 규칙 때문에 예외가 둘 있다. -| Design module | Repository home | Reason | +| 설계 모듈 | 저장소 위치 | 이유 | |---|---|---| -| `httpclient-spring-boot-starter` | `:adapter:outbound:httpclient` (`dev.caskeleton.adapter.outbound.httpclient.autoconfigure`) | Capability-specific Spring composition is owned with the reusable HTTP client platform; `app-bootstrap` only selects/includes the capability and runtime activation remains `app.httpclient.enabled`. | -| `httpclient-testkit` | `:adapter:outbound:httpclient` `src/testFixtures/java/**/testkit` | The design forbids production modules depending on the testkit. Gradle `testFixtures` publishes the reusable test support only to test consumers; ordinary tests, integration/performance lanes, and JMH opt into that surface explicitly without exposing it to production. `PlatformClasses` excludes test-fixture output so the boundary rules keep meaning production classes. | +| `httpclient-spring-boot-starter` | `:adapter:outbound:httpclient`(`dev.caskeleton.adapter.outbound.httpclient.autoconfigure`) | capability 전용 Spring 조립은 재사용하는 HTTP client 플랫폼과 함께 둔다. `app-bootstrap`은 capability를 고르고 포함할 뿐이고, 런타임 활성화는 `app.httpclient.enabled`로 남는다. | +| `httpclient-testkit` | `:adapter:outbound:httpclient` `src/testFixtures/java/**/testkit` | 설계는 production 모듈이 testkit에 의존하는 것을 금한다. Gradle `testFixtures`는 재사용 테스트 지원을 테스트 소비자에게만 내놓는다. 보통 테스트, integration/performance lane, JMH는 그 면을 명시적으로 골라 쓰고 production에는 드러나지 않는다. `PlatformClasses`는 test-fixture 출력을 빼서 경계 규칙이 계속 production 클래스만 뜻하게 한다. | -The package boundary is enforced by ArchUnit rules (`PublicApiArchitectureTest`, -`HttpClientModuleBoundaryTest`) that reproduce the design's module dependency table. +package 경계는 설계의 모듈 의존 표를 재현한 ArchUnit 규칙(`PublicApiArchitectureTest`, +`HttpClientModuleBoundaryTest`)이 강제한다. -## 2. Package mapping +## 2. Package 대응 Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbound.httpclient`. -| Design module | Design package | Repository package | +| 설계 모듈 | 설계 package | 저장소 package | |---|---|---| -| `httpclient-core-api` | `…httpclient.api` (+ `.body`, `.error`, `.operation`, `.result`) | `dev.caskeleton.adapter.outbound.httpclient.api` (+ same subpackages) | +| `httpclient-core-api` | `…httpclient.api` (+ `.body`, `.error`, `.operation`, `.result`) | `dev.caskeleton.adapter.outbound.httpclient.api` (+ 같은 하위 package) | | `httpclient-profile` | `…httpclient.profile` | `…outbound.httpclient.profile` | | `httpclient-transport-spi` | `…httpclient.transport` | `…outbound.httpclient.transport` | | `httpclient-transport-apache` | `…httpclient.apache` | `…outbound.httpclient.apache` | @@ -48,38 +47,38 @@ Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbo | `httpclient-auth` | `…httpclient.auth` | `…outbound.httpclient.auth` | | `httpclient-security` | `…httpclient.security` | `…outbound.httpclient.security` | | `httpclient-observability` | `…httpclient.observation` | `…outbound.httpclient.observation` | -| `httpclient-transport-reactor-netty` | `…httpclient.reactor` | removed (decision 9, 2026-09-25: blocking only) | -| `httpclient-webclient` | `…httpclient.webclient` | removed (decision 9, 2026-09-25: blocking only) | +| `httpclient-transport-reactor-netty` | `…httpclient.reactor` | 지움(결정 9, 2026-09-25: blocking만) | +| `httpclient-webclient` | `…httpclient.webclient` | 지움(결정 9, 2026-09-25: blocking만) | | `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` | | `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` | | `httpclient-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` | | `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.adapter.outbound.httpclient.autoconfigure` | -| `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (`testkit` source set) | +| `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (`testFixtures` source set) | -## 3. Other deliberate substitutions +## 3. 그 밖에 일부러 바꾼 것 -| Design assumption | Repository reality | Adaptation | +| 설계 가정 | 저장소 현실 | 적응 | |---|---|---| -| Gradle Kotlin DSL, `build-logic` convention plugin | Groovy DSL, root `build.gradle` conventions, `LockMode.STRICT` dependency locking | Dependencies declared in `src/adapter/outbound/httpclient/build.gradle`; `gradle.lockfile` regenerated. | -| Spring Framework 6.2 baseline with 7.0 compatibility | Spring Boot 4.0.8 / Spring Framework 7.0 is the repository baseline | Common code targets the Spring 6.2 **API surface** (no 6.2-only or 7.0-only classes in common packages). The Spring 7 HTTP Service Group integration and the `RestTemplate` migration package were removed. | -| `settings.gradle.kts` module registration | Fail-closed registry | No registry change; leaf identity, gradle path, allowed dependencies unchanged. | -| Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable | Spring's blocking factory drives Apache's **classic** client, which is HTTP/1.1 only; HTTP/2 lives in Apache's async client | `ApacheBlockingTransportProvider` declares HTTP/1.1 and rejects an HTTP/2 profile at startup. Blocking HTTP/2 is served by the JDK transport, measured by `NegotiatedProtocolContractTest`. | -| Design §28.1 names WireMock for stateful fixtures | WireMock's Jetty modules bind a different Jetty 12 ABI than the Boot-managed one this module already needs for HTTP/3, and fail at server start | `StatefulUpstream` provides path-keyed stateful responses on the existing fixture server; the WireMock dependency was removed rather than worked around with a shaded jar | -| Per-task `git commit` | `AGENTS.md`: commit policy is `human-only` | Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here. | -| `docs/httpclient/**`, `.github/workflows/httpclient-*.yml`, `scripts/verify-httpclient-docs.py` | Repository already owns `docs/` and `.github/workflows/` | Created at the same repository-relative paths. | +| Gradle Kotlin DSL, `build-logic` convention plugin | Groovy DSL, root `build.gradle` convention, `LockMode.STRICT` 의존성 잠금 | 의존성은 `src/adapter/outbound/httpclient/build.gradle`에 선언하고 `gradle.lockfile`을 다시 만들었다. | +| Spring Framework 6.2 기준, 7.0 호환 | 저장소 기준은 Spring Boot 4.0 계열 / Spring Framework 7.0이다. 정확한 버전은 `src/gradle/libs.versions.toml`의 `springBoot`다 | 공통 코드는 Spring 6.2 **API 면**을 대상으로 한다(공통 package에 6.2 전용이나 7.0 전용 클래스가 없다). Spring 7 HTTP Service Group 통합과 `RestTemplate` 이전 package는 지웠다. | +| `settings.gradle.kts` 모듈 등록 | 닫힌 쪽으로 실패하는 registry | registry는 바꾸지 않았다. leaf 식별자, gradle path, 허용 의존은 그대로다. | +| 설계 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다 | Spring의 blocking factory는 Apache의 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. HTTP/2는 Apache의 async client에 있다 | `ApacheBlockingTransportProvider`는 HTTP/1.1을 선언하고 HTTP/2 profile을 시작 때 거부한다. blocking HTTP/2는 JDK transport가 맡고, `NegotiatedProtocolContractTest`가 잰다. | +| 설계 §28.1은 상태 있는 fixture로 WireMock을 든다 | WireMock의 Jetty 모듈은 이 모듈이 HTTP/3 때문에 이미 쓰는 Boot 관리 Jetty 12와 ABI가 달라 서버 시작에서 실패한다 | `StatefulUpstream`이 기존 fixture 서버 위에서 경로별 상태 있는 응답을 준다. shaded jar로 돌아가지 않고 WireMock 의존성을 지웠다 | +| 작업마다 `git commit` | `AGENTS.md`: 커밋 정책은 `human-only` | 구현은 stage하지 않은 채 넘겼고, 커밋은 사람이 했다. 계획 중 일부러 실행하지 않은 단계는 이것 하나이고, 여기 적어 둔다. | +| `docs/httpclient/**`, `.github/workflows/httpclient-*.yml`, `scripts/verify-httpclient-docs.py` | 저장소가 이미 `docs/`와 `.github/workflows/`를 가진다 | 같은 저장소 상대 경로에 만들었다. | -## 4. What is unchanged from the design +## 4. 설계에서 바뀌지 않은 것 -- H1 / H2 / H3 / H4 exposure rules and the forbidden native-engine signatures. +- H1 / H2 / H3 / H4 노출 규칙과 금지한 native 엔진 시그니처. - `ExecutionEvidence`, `BodyReplayability`, `OperationIdempotency`, `AttemptStage`, `FailureCategory`. - `HttpOperation`, `HttpCallResult`, `BodySource`, `ResponseType`, `BlockingStreamingResponse`. -- The complete stable exception hierarchy and `HttpFailureMetadata` redaction rules. -- Named Client Profile schema, startup validation codes, and operation override direction. -- Effective deadline formula, attempt budget, and streaming setup/idle split. -- Retry eligibility inputs, the ordered decision table, retry budget, and backoff rules. -- Circuit → Rate Limiter → Bulkhead attempt order and logical admission placement. -- OAuth2 cache key, single-flight refresh, and the 401 replay-at-most-once rule. -- TLS allow/forbid lists and permanent-failure classification. -- Dynamic Target canonicalization → all-answer DNS validation → pinning → redirect revalidation. -- Low-cardinality tag allowlist, forbidden labels, trace and logging rules. -- Runtime generation swap and drain semantics. +- 안정된 예외 계층 전체와 `HttpFailureMetadata` 가리기 규칙. +- Named Client Profile schema, 시작 검증 코드, 연산 덮어쓰기 방향. +- 실제 기한 공식, 시도 예산, 스트리밍의 준비/idle 분리. +- 재시도 자격 입력, 순서 있는 판정 표, 재시도 예산, backoff 규칙. +- Circuit → Rate Limiter → Bulkhead 시도 순서와 논리 허가 위치. +- OAuth2 cache key, 한 번만 날아가는 갱신, 401 재전송은 많아야 한 번이라는 규칙. +- TLS 허용/금지 목록과 영구 실패 분류. +- Dynamic Target 정규화 → 모든 DNS 답 검증 → 고정 → redirect 재검증. +- 가짓수가 적은 tag 허용 목록, 금지 label, trace와 로그 규칙. +- 런타임 세대 교체와 drain 의미. diff --git a/docs/httpclient/retry-and-ambiguity.md b/docs/httpclient/retry-and-ambiguity.md index 0f7e5b4c..8aa43fe1 100644 --- a/docs/httpclient/retry-and-ambiguity.md +++ b/docs/httpclient/retry-and-ambiguity.md @@ -1,87 +1,80 @@ -# Retry and Ambiguity +# 재시도와 결과 모름 -The platform never decides a retry from the HTTP method alone (design D-09). A second attempt -happens only when idempotency, body replayability, execution evidence, deadline, and retry budget -all permit it. +플랫폼은 HTTP method만 보고 재시도를 정하지 않는다(설계 D-09). 두 번째 시도는 멱등성, 본문 재전송 가능성, 실행 +증거, 기한, 재시도 예산이 모두 허락할 때만 일어난다. -## Execution evidence +## 실행 증거 -| Evidence | Meaning | Typical cause | +| 증거 | 뜻 | 흔한 원인 | |---|---|---| -| `NOT_SENT` | Proven that the server never received the request | profile rejection, pool timeout, DNS failure, connect failure, pre-request TLS failure, HTTP/2 `REFUSED_STREAM` | -| `SENT_NO_RESPONSE` | Some or all of the request was written, no final header arrived | partial write, response-header timeout, connection reset | -| `RESPONSE_RECEIVED` | Final headers arrived, whatever the status | 2xx, 4xx, 5xx, redirect | -| `PARTIAL_RESPONSE` | Headers and part of the body arrived | reset during decode, interrupted stream | +| `NOT_SENT` | 서버가 요청을 받지 않았음이 증명됐다 | profile 거부, pool 시간 초과, DNS 실패, 연결 실패, 요청 전 TLS 실패, HTTP/2 `REFUSED_STREAM` | +| `SENT_NO_RESPONSE` | 요청 일부나 전부를 썼고, 최종 헤더가 오지 않았다 | 부분 쓰기, 응답 헤더 시간 초과, connection reset | +| `RESPONSE_RECEIVED` | 상태와 상관없이 최종 헤더가 왔다 | 2xx, 4xx, 5xx, redirect | +| `PARTIAL_RESPONSE` | 헤더와 본문 일부가 왔다 | 디코딩 중 reset, 끊긴 stream | -`NOT_SENT` is only produced by a stage failure that proves it. A generic engine I/O error is never -upgraded to `NOT_SENT`, because that is exactly how a timeout becomes a duplicate payment. +`NOT_SENT`는 그것을 증명하는 단계 실패만 만든다. 일반 엔진 I/O 오류는 절대 `NOT_SENT`로 올리지 않는다. 시간 +초과가 이중 결제가 되는 길이 바로 그것이기 때문이다. -## Body replayability +## 본문 재전송 가능성 -| Body | Replayability | +| 본문 | 재전송 가능성 | |---|---| -| immutable `byte[]` | `REPLAYABLE` | -| DTO plus a deterministic codec | `REPLAYABLE` | -| reopenable file or resource supplier | `REOPENABLE` | -| a single `InputStream` instance | `ONE_SHOT` | -| publisher factory | as declared | -| publisher instance | `ONE_SHOT` | -| multipart | the weakest part | +| 바뀌지 않는 `byte[]` | `REPLAYABLE` | +| DTO와 결정적 codec | `REPLAYABLE` | +| 다시 열 수 있는 파일이나 resource supplier | `REOPENABLE` | +| `InputStream` 인스턴스 하나 | `ONE_SHOT` | +| publisher factory | 선언한 대로 | +| publisher 인스턴스 | `ONE_SHOT` | +| multipart | 가장 약한 part를 따른다 | -## Decision order +## 판정 순서 -`DefaultRetryEligibilityEngine` evaluates in this order, and a later rule can never re-enable -something an earlier one forbade: +`DefaultRetryEligibilityEngine`은 이 순서로 판정한다. 뒤 규칙은 앞 규칙이 금지한 것을 절대 다시 허락하지 못한다. -1. `SENT_NO_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure` -2. attempts exhausted → `RetryDenied.maxAttempts()` -3. retry budget empty → `RetryDenied.budgetExhausted()` -4. body not replayable → `RetryDenied.bodyNotReplayable()` -5. first byte already delivered → `RetryDenied.responseAlreadyDelivered()` -6. runtime draining → `RetryDenied.runtimeDraining()` -7. remaining deadline below the minimum attempt budget → `RetryDenied.deadline()` -8. permanent failure category → `RetryDenied.permanentFailure(...)` -9. `PARTIAL_RESPONSE` on an operation that is not safely idempotent → `AmbiguousFailure` -10. status- and failure-specific rules +1. 안전하게 멱등이 아닌 연산의 `SENT_NO_RESPONSE` → `AmbiguousFailure` +2. 시도를 다 썼다 → `RetryDenied.maxAttempts()` +3. 재시도 예산이 비었다 → `RetryDenied.budgetExhausted()` +4. 본문을 재전송할 수 없다 → `RetryDenied.bodyNotReplayable()` +5. 첫 바이트를 이미 넘겼다 → `RetryDenied.responseAlreadyDelivered()` +6. 런타임이 비우는 중이다 → `RetryDenied.runtimeDraining()` +7. 남은 기한이 최소 시도 예산보다 작다 → `RetryDenied.deadline()` +8. 영구 실패 범주 → `RetryDenied.permanentFailure(...)` +9. 안전하게 멱등이 아닌 연산의 `PARTIAL_RESPONSE` → `AmbiguousFailure` +10. 상태별·실패별 규칙 -Ambiguity comes first because it describes the outcome, not whether another attempt is allowed. It -used to sit below the attempt check, so with the default `max-attempts: 1` a POST that timed out -after it was sent reached the caller as an ordinary timeout (review 2026-11-01 05-14). +결과 모름이 맨 앞인 것은 그것이 다른 시도가 허락되는지가 아니라 결과를 설명하기 때문이다. 예전에는 시도 검사 +아래에 있었다. 그래서 기본값 `max-attempts: 1`에서는 보낸 뒤 시간이 넘은 POST가 호출자에게 보통의 시간 초과로 +도착했다(리뷰 2026-11-01 05-14). -## Status rules +## 상태 규칙 -| Status | Decision | +| 상태 | 판정 | |---|---| -| 408 | retry inside deadline and budget | -| 425 | at most one retry, first attempt only | -| 429 | retry inside `Retry-After`, deadline, and budget | -| 401 | one refresh-and-replay, safe replayable operations only. The credential is refreshed only once the retry is granted; a 401 that will not be replayed (one attempt, no budget, no deadline) leaves the token cache alone | -| 500 | denied unless the upstream registered it as transient **and** the operation is safely idempotent | -| 502, 503, 504 | retry for safely idempotent operations; ambiguous otherwise | -| other 4xx | denied | +| 408 | 기한과 예산 안에서 재시도 | +| 425 | 첫 시도에서만, 많아야 한 번 재시도 | +| 429 | `Retry-After`, 기한, 예산 안에서 재시도 | +| 401 | 안전하고 재전송 가능한 연산에서만 갱신 후 재전송 한 번. credential은 재시도를 허락받은 뒤에만 갱신한다. 재전송하지 않을 401(시도 한 번, 예산 없음, 기한 없음)은 token cache를 건드리지 않는다 | +| 500 | upstream이 일시적이라고 등록했고 **그리고** 연산이 안전하게 멱등일 때만 허락. 아니면 거부 | +| 502, 503, 504 | 안전하게 멱등인 연산은 재시도. 아니면 결과 모름 | +| 그 밖의 4xx | 거부 | -## Ambiguity +## 결과 모름 -A non-idempotent request that reached `SENT_NO_RESPONSE` raises -`HttpAmbiguousExecutionException`. It is a third answer on purpose: retrying may duplicate a side -effect, and reporting a plain failure would tell the caller the request did not happen, which may -be false. The caller reconciles, usually by querying the upstream or replaying with an idempotency -key. +멱등이 아닌 요청이 `SENT_NO_RESPONSE`에 닿으면 `HttpAmbiguousExecutionException`을 던진다. 일부러 만든 세 번째 +답이다. 재시도하면 부수 효과가 두 번 날 수 있고, 보통의 실패로 알리면 요청이 일어나지 않았다고 호출자에게 말하는 +셈인데 그것이 거짓일 수 있다. 호출자는 맞춰 본다. 보통 upstream에 조회하거나 멱등 key로 다시 보낸다. -### Where the evidence comes from +### 증거는 어디서 오나 -Whether a failed request was sent is read from the stage the attempt reached and the engine's -exception type. Apache reports the moment it starts writing the request onto an established -connection (`RequestWriteSignal`), so a failure while leasing, resolving, connecting or completing -the TLS handshake is `NOT_SENT` even when the engine throws a generic exception. Transports that -cannot report that moment (JDK, Jetty) are treated as writing from the moment the engine is called, -because guessing "not sent" is what turns a timeout into a duplicate payment. An HTTP/2 -`REFUSED_STREAM` frame is proof the peer processed nothing and is kept as `NOT_SENT` through -exception mapping. +실패한 요청을 보냈는지는 시도가 닿은 단계와 엔진의 예외 타입에서 읽는다. Apache는 맺은 connection에 요청을 쓰기 +시작하는 순간을 알려 준다(`RequestWriteSignal`). 그래서 빌리기, 풀기, 연결, TLS handshake 중의 실패는 엔진이 일반 +예외를 던져도 `NOT_SENT`다. 그 순간을 알려 주지 못하는 transport(JDK, Jetty)는 엔진을 부른 순간부터 쓰는 중으로 +본다. 「안 보냈다」고 짐작하는 것이 시간 초과를 이중 결제로 바꾸기 때문이다. HTTP/2 `REFUSED_STREAM` frame은 +상대가 아무것도 처리하지 않았다는 증거이고, 예외 변환을 거쳐도 `NOT_SENT`로 남는다. -## Budget and backoff +## 예산과 backoff -Retry tokens come from a per-upstream token bucket sized as a fraction of real traffic, so a failing -upstream cannot be flooded by retries from a healthy fleet. Backoff is exponential with full or -decorrelated jitter, bounded by `max-backoff`, by `Retry-After`, and by the remaining deadline. No -connection and no bulkhead permit is held while a backoff is waiting. +재시도 token은 실제 트래픽의 일정 비율로 크기를 정한 upstream별 token bucket에서 나온다. 그래서 건강한 인스턴스 +무리가 실패하는 upstream을 재시도로 덮치지 못한다. backoff는 full이나 decorrelated jitter를 쓰는 지수 backoff이고, +`max-backoff`, `Retry-After`, 남은 기한으로 제한한다. backoff를 기다리는 동안에는 connection도 bulkhead 허가도 +잡지 않는다. diff --git a/docs/httpclient/security.md b/docs/httpclient/security.md index e15f28c4..15d716fc 100644 --- a/docs/httpclient/security.md +++ b/docs/httpclient/security.md @@ -1,75 +1,68 @@ -# HTTP Client Platform — Security Guide +# HTTP Client 플랫폼 — 보안 안내 -## What the platform owns +## 플랫폼이 소유하는 것 -`Authorization`, `Proxy-Authorization`, `Host`, `Content-Length`, `Transfer-Encoding`, -`Traceparent`, `Tracestate`, `Baggage`, and (unless a profile opts in) `Cookie` are platform-owned. -A caller cannot set them. `Idempotency-Key` is accepted only when the operation declares it. Any -header name or value containing CR or LF is rejected before the request is built. +`Authorization`, `Proxy-Authorization`, `Host`, `Content-Length`, `Transfer-Encoding`, `Traceparent`, +`Tracestate`, `Baggage`, 그리고 (profile이 고르지 않는 한) `Cookie`는 플랫폼이 소유한다. 호출자는 이것들을 정할 수 +없다. `Idempotency-Key`는 연산이 선언했을 때만 받는다. 이름이나 값에 CR이나 LF가 있는 헤더는 요청을 만들기 전에 +거부한다. -## Target policy +## 대상 정책 -A trusted profile accepts only a profile-relative URI template. An absolute URI is rejected rather -than sanitised: varying the destination is what H3 is for, and H3 has its own policy, credentials, -and address validation. Template variables are encoded per component, so a value containing `/`, -`?`, or `#` cannot change the shape of the request. +trusted profile은 profile 기준 상대 URI template만 받는다. 절대 URI는 정리하지 않고 거부한다. 목적지를 바꾸는 것은 +H3가 하는 일이고, H3에는 자기 정책, credential, 주소 검증이 있다. template 변수는 구성 요소마다 인코딩한다. 그래서 +`/`, `?`, `#`이 든 값도 요청의 모양을 바꾸지 못한다. ## TLS -Allowed: TLS 1.2 and 1.3, hostname verification, the JVM trust store, a per-profile custom CA, a -per-profile client certificate, mTLS, SNI and ALPN, and certificate rotation through a new runtime -generation. +허락: TLS 1.2와 1.3, hostname 검증, JVM trust store, profile별 사설 CA, profile별 client 인증서, mTLS, SNI와 +ALPN, 새 런타임 세대를 통한 인증서 교체. -Forbidden and unrepresentable: a trust-all trust manager, disabled hostname verification, ignoring -certificate errors, automatically trusting a production self-signed certificate, falling back to -plaintext after an HTTPS failure, and writing key material into configuration or logs. +금지하고 표현할 수도 없음: 모두 믿는 trust manager, hostname 검증 끄기, 인증서 오류 무시, 운영의 자체 서명 인증서를 +자동으로 믿기, HTTPS 실패 뒤 평문으로 물러서기, key 재료를 설정이나 로그에 쓰기. -Unknown CA, hostname mismatch, expired certificate, revoked certificate, protocol mismatch, and a -missing client certificate are permanent. Only a transient handshake timeout may be retried, inside -the deadline. +모르는 CA, hostname 불일치, 만료한 인증서, 폐기된 인증서, protocol 불일치, 빠진 client 인증서는 영구 실패다. +일시적인 handshake 시간 초과만 기한 안에서 재시도할 수 있다. ## Dynamic Target (SSRF) -Every hop — the first one included — runs the whole flow: +첫 hop을 포함해 모든 hop이 흐름 전체를 돈다. -1. strict URI parse -2. scheme allowlist -3. reject userinfo and invalid ports -4. IDNA-canonicalise the host -5. host allowlist or suffix policy -6. resolve **every** A and AAAA answer -7. normalise each address, including IPv4-mapped IPv6 -8. reject loopback, link-local, RFC1918, ULA, carrier-grade NAT, unspecified, multicast, cloud - metadata, and organisation-defined ranges -9. pin the connection to the approved addresses through the same validated resolver -10. apply response size and content policy -11. repeat for each redirect +1. 엄격한 URI 파싱 +2. scheme 허용 목록 +3. userinfo와 잘못된 port 거부 +4. host를 IDNA로 정규화 +5. host 허용 목록이나 접미사 정책 +6. A와 AAAA 답을 **모두** 푼다 +7. IPv4-mapped IPv6를 포함해 주소마다 정규화 +8. loopback, link-local, RFC1918, ULA, carrier-grade NAT, 미지정, multicast, cloud metadata, 조직이 정한 범위를 + 거부 +9. 같은 검증 resolver로 connection을 승인한 주소에 고정 +10. 응답 크기와 content 정책 적용 +11. redirect마다 반복 -Any forbidden address in the answer set rejects the whole target. Validating only the first answer -would let a host that resolves to one public and one private address through. +답 묶음에 금지 주소가 하나라도 있으면 대상 전체를 거부한다. 첫 답만 검증하면 공개 주소 하나와 사설 주소 하나로 +풀리는 host가 통과한다. -Dynamic profiles inherit no API key, OAuth token, Cookie, or default header, and no Cookie jar is -created. A specific host may be granted a credential only through an explicitly registered -`DynamicCredentialBinding`. +dynamic profile은 API key, OAuth token, Cookie, 기본 헤더를 물려받지 않고, Cookie jar도 만들지 않는다. 특정 host에 +credential을 주려면 명시적으로 등록한 `DynamicCredentialBinding`을 거쳐야만 한다. -Application-level validation is not sufficient on its own. A network control — Kubernetes -NetworkPolicy, service-mesh egress policy, firewall, or proxy ACL — is an operational completion -requirement. +애플리케이션 수준 검증만으로는 충분하지 않다. 네트워크 통제(Kubernetes NetworkPolicy, service mesh egress 정책, +방화벽, proxy ACL)가 운영 완료 요건이다. -## Redirects +## Redirect -Disabled by default. Engine redirect handling is off in every transport so the platform can -re-validate each hop. 307 and 308 preserve method and body and are therefore allowed only for a -replayable body. Cross-origin hops are refused unless the profile opts in, and when they are -allowed `Authorization`, `Proxy-Authorization`, `Cookie`, and API-key headers are stripped. +기본으로 꺼져 있다. 플랫폼이 hop마다 다시 검증할 수 있게 모든 transport에서 엔진의 redirect 처리를 끈다. 307과 +308은 method와 본문을 유지하므로 재전송 가능한 본문일 때만 허락한다. origin을 넘는 hop은 profile이 고르지 않으면 +거부하고, 허락하면 `Authorization`, `Proxy-Authorization`, `Cookie`, API key 헤더를 지운다. -## Observability +## 관측 -Allowed tags: `clientName`, `operationName`, `method`, `uriTemplate`, `status`, `outcome`, -`transport`, `protocol`, `timeoutType`, `retryReason`, `evidence`, `circuitState`. +허락한 tag: `clientName`, `operationName`, `method`, `uriTemplate`, `status`, `outcome`, `transport`, +`protocol`, `timeoutType`, `retryReason`, `evidence`, `circuitState`. -Rejected outright: full URL, query parameters, path variable values, user ID, raw tenant ID, -resolved IP, API key, token, Cookie, idempotency key, request or response body, exception message. +바로 거부: 전체 URL, query parameter, 경로 변수 값, user ID, 날것의 tenant ID, 푼 IP, API key, token, Cookie, 멱등 +key, 요청이나 응답 본문, 예외 메시지. -Failures are logged once, structured, at the end of a logical call. Retry attempts are DEBUG or span -events. URLs appear only as templates. +실패는 논리 호출 끝에 구조화해서 한 번 로그를 남긴다. 재시도 시도는 DEBUG이거나 span event다. URL은 template로만 +나온다. diff --git a/docs/httpclient/streaming.md b/docs/httpclient/streaming.md index a68136d2..fd5e0686 100644 --- a/docs/httpclient/streaming.md +++ b/docs/httpclient/streaming.md @@ -1,36 +1,34 @@ -# Streaming and Large Bodies +# 스트리밍과 큰 본문 -## Response lifecycle +## 응답 수명 -A streaming download returns `BlockingStreamingResponse`, never a bare `InputStream`. Closing is -idempotent and always releases the connection — after a full read, a partial read, a decode failure, -or a size rejection. The status is validated before any body byte is delivered, so a failed download -never becomes a half-consumed stream the caller has to reason about. +스트리밍 다운로드는 맨 `InputStream`이 아니라 `BlockingStreamingResponse`를 돌려준다. 닫기는 멱등이고, 다 읽은 +뒤든, 일부만 읽은 뒤든, 디코딩 실패나 크기 거부 뒤든 늘 connection을 돌려준다. 상태는 본문 바이트를 넘기기 전에 +검증한다. 그래서 실패한 다운로드가 호출자가 따져야 하는 반쯤 읽힌 stream이 되지 않는다. -Wire bytes and decoded bytes are bounded independently, because a compressed payload passes a wire -check and then expands. Limits are enforced while reading, not after buffering. +wire 바이트와 디코딩한 바이트는 따로 제한한다. 압축한 payload는 wire 검사를 통과한 뒤 늘어나기 때문이다. 한도는 +버퍼링한 뒤가 아니라 읽는 동안 강제한다. -## The first-byte boundary +## 첫 바이트 경계 ```text -response headers received - → nothing delivered yet - → a read-only operation may still be retried - → the response is handed to the caller - → transparent retry is no longer possible +응답 헤더를 받았다 + → 아직 아무것도 넘기지 않았다 + → 읽기 전용 연산은 아직 재시도할 수 있다 + → 응답을 호출자에게 넘겼다 + → 투명한 재시도는 더는 할 수 없다 ``` -Retrying after delivery would replay a stream the caller has already partly consumed, producing -duplicated or reordered data that no downstream code can detect. The streaming gateway hands out -the response only after the attempt has finished, so there is no retry left to run once the caller -reads. +넘긴 뒤에 재시도하면 호출자가 이미 일부 읽은 stream을 다시 보내게 된다. 그러면 아래쪽 어느 코드도 알아챌 수 없는 +중복되거나 순서가 바뀐 데이터가 생긴다. 스트리밍 gateway는 시도가 끝난 뒤에만 응답을 넘긴다. 그래서 호출자가 +읽기 시작하면 돌릴 재시도가 남아 있지 않다. -## Request bodies +## 요청 본문 -A reopenable body is opened once per attempt, which is what makes it replayable; reusing the -previous stream would silently send an empty body on the retry. A one-shot stream is never retried. +다시 열 수 있는 본문은 시도마다 한 번 연다. 그래서 재전송할 수 있다. 앞 stream을 다시 쓰면 재시도에서 빈 본문을 +조용히 보낸다. 한 번만 쓰는 stream은 절대 재시도하지 않는다. ## Server-sent events -The platform has no server-sent-event client. It was part of the reactive stack, which was removed -(decision 9, 2026-09-25): the platform runs blocking calls on the caller's thread only. +플랫폼에는 server-sent event client가 없다. 그것은 지운 reactive stack의 일부였다(결정 9, 2026-09-25). 플랫폼은 +호출자의 스레드에서 blocking 호출만 돌린다. diff --git a/docs/httpclient/support-matrix.md b/docs/httpclient/support-matrix.md index a253cfd9..24bc5509 100644 --- a/docs/httpclient/support-matrix.md +++ b/docs/httpclient/support-matrix.md @@ -1,87 +1,82 @@ -# HTTP Client Platform — Support Matrix +# HTTP Client 플랫폼 — 지원 매트릭스 -Grades follow design §6 and §29. A row is **Stable** only when the cross-transport contract suite -proves it; anything the suite cannot prove is **Experimental** and says so. +등급은 설계서 §6과 §29를 따른다. 행이 **Stable**이려면 transport를 넘는 계약 suite가 그것을 증명해야 한다. suite가 +증명하지 못하는 것은 **Experimental**이고 그렇다고 밝힌다. 등급 이름(Stable, Default, Restricted, Internal, +Experimental)은 원문 그대로 쓴다. ## Spring API -| API | Grade | Role | Constraint | +| API | 등급 | 역할 | 제약 | |---|---|---|---| -| `RestClient` | Stable | Blocking execution (the only execution model) | Bounded concurrency and an effective deadline are mandatory | -| HTTP Service Client (`@HttpExchange`) | Default | Declarative typed client | Operation metadata is mandatory | -| Generic Exchange (H2) | Restricted | Dynamic method, path, body | Base URL and policy are immutable | -| Dynamic Target (H3) | Restricted | User-supplied URL | Separate SSRF policy; inherits no credential | -| Native engine | Internal | Engine-specific configuration | Never an application-facing API | +| `RestClient` | Stable | blocking 실행(유일한 실행 모델) | 동시성 상한과 실제 기한이 필수다 | +| HTTP Service Client(`@HttpExchange`) | Default | 선언형 타입 있는 client | 연산 metadata가 필수다 | +| Generic Exchange (H2) | Restricted | 동적 method, 경로, 본문 | Base URL과 정책은 바꿀 수 없다 | +| Dynamic Target (H3) | Restricted | 사용자가 준 URL | 따로 된 SSRF 정책. credential을 물려받지 않는다 | +| Native 엔진 | Internal | 엔진별 설정 | 애플리케이션이 쓰는 API가 절대 아니다 | -## Transports +## Transport -The platform is blocking only (decision 9, 2026-09-25): every call runs on the caller's thread — -a virtual thread in this template — through `RestClient`. There is no reactive execution path, no -`WebClient`, and no Reactor Netty transport. +플랫폼은 blocking만 한다(결정 9, 2026-09-25). 모든 호출은 호출자의 스레드(이 템플릿에서는 virtual thread)에서 +`RestClient`를 거쳐 돈다. reactive 실행 경로도, `WebClient`도, Reactor Netty transport도 없다. -| Transport | HTTP/1.1 | HTTP/2 | HTTP/3 | Grade | Verified by | +| Transport | HTTP/1.1 | HTTP/2 | HTTP/3 | 등급 | 확인하는 것 | |---|---:|---:|---:|---|---| -| Apache HttpClient 5 (classic) | yes | **no** | no | Stable (default) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` | -| JDK HttpClient | yes | yes (TLS/ALPN) | no | Stable (lightweight, HTTP/2) | `NegotiatedProtocolContractTest` | -| Jetty | yes | yes | yes | **Experimental** | `Http3OptInTest` only | -| Simple request factory | limited | no | no | Local test only | rejected in production by `ClientProfileValidator` | +| Apache HttpClient 5 (classic) | 된다 | **안 된다** | 안 된다 | Stable(기본) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` | +| JDK HttpClient | 된다 | 된다(TLS/ALPN) | 안 된다 | Stable(가벼움, HTTP/2) | `NegotiatedProtocolContractTest` | +| Jetty | 된다 | 된다 | 된다 | **Experimental** | `Http3OptInTest`뿐 | +| Simple request factory | 제한적 | 안 된다 | 안 된다 | 로컬 테스트 전용 | 운영에서는 `ClientProfileValidator`가 거부한다 | -### Apache is HTTP/1.1 here, and why +### 여기서 Apache가 HTTP/1.1인 이유 -Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable, and the library is — in its **async** -client. Spring's `HttpComponentsClientHttpRequestFactory` drives the **classic** client, which -speaks HTTP/1.1 only. `NegotiatedProtocolContractTest` measures this rather than assuming it: the -classic client fails outright against a prior-knowledge h2c server. +설계서 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다. 라이브러리는 그렇다. 다만 **async** client에서다. +Spring의 `HttpComponentsClientHttpRequestFactory`는 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. +`NegotiatedProtocolContractTest`는 이것을 가정하지 않고 잰다. classic client는 prior-knowledge h2c 서버에 대해 +바로 실패한다. -So `ApacheBlockingTransportProvider.capabilities()` declares HTTP/1.1, and a profile that pairs -Apache with `HTTP_2` is rejected at startup instead of quietly running HTTP/1.1 while this table -claims otherwise. **HTTP/2 is served by the JDK transport**, measured from the client after a real -TLS handshake, not read from configuration. No transport can be restricted to HTTP/2 alone, so a -profile that declares only `HTTP_2` is refused (`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`). +그래서 `ApacheBlockingTransportProvider.capabilities()`는 HTTP/1.1을 선언한다. Apache와 `HTTP_2`를 짝지은 +profile은 이 표가 다르게 주장하는 동안 조용히 HTTP/1.1로 도는 대신 시작 때 거부된다. **HTTP/2는 JDK transport가 +맡는다.** 설정에서 읽지 않고, 실제 TLS handshake 뒤 client 쪽에서 잰다. HTTP/2만으로 제한할 수 있는 transport는 +없으므로 `HTTP_2`만 선언한 profile은 거부한다(`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`). -The JDK transport declares `routeScopedPool=false`, `boundedPendingAcquireQueue=false`, and -`dynamicTargetStable=false`. A profile that needs any of those is rejected at startup rather than -served with weaker guarantees. Choosing between Apache and JDK is therefore a real trade: Apache -gives route-scoped pooling and Dynamic Target pinning, JDK gives HTTP/2. +JDK transport는 `routeScopedPool=false`, `boundedPendingAcquireQueue=false`, `dynamicTargetStable=false`를 +선언한다. 그중 하나라도 필요한 profile은 약한 보장으로 돌지 않고 시작 때 거부된다. 그래서 Apache와 JDK 사이의 +선택은 진짜 맞바꿈이다. Apache는 route 범위 pool과 Dynamic Target 고정을 주고, JDK는 HTTP/2를 준다. -## Capability gates +## Capability 관문 -| Capability | Gate | +| Capability | 관문 | |---|---| -| Dynamic Target (H3) | Apache only; JDK and Jetty are rejected | -| HTTP/3 | `experimentalAcknowledgement` must equal `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS` | -| Cross-origin redirect | opt-in per profile; credentials are stripped on the hop | -| Retry | evidence-based; never enabled by HTTP method alone | +| Dynamic Target (H3) | Apache만. JDK와 Jetty는 거부한다 | +| HTTP/3 | `experimentalAcknowledgement`가 `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS`와 같아야 한다 | +| origin을 넘는 redirect | profile마다 골라 켠다. hop에서 credential을 지운다 | +| 재시도 | 증거 기반. HTTP method만으로 켜지지 않는다 | -## CI matrix +## CI 매트릭스 -| Profile | Frequency | Release gate | Task | +| Profile | 빈도 | 릴리스 게이트 | Task | |---|---|---|---| -| Spring Framework 7.0 (repository baseline) | PR touching this leaf, main push, release | required | `spring70CompatibilityTest` | -| Spring Framework 6.2 API surface | every PR (`check`), release | required | `spring62ApiSurfaceScan` | -| Apache HC5 + RestClient | PR touching this leaf (both transports together on every PR through `check`), release | required | `httpClientStableContractTest -Phttpclient.contract.transports=apache` | -| JDK HttpClient + RestClient | PR touching this leaf (both transports together on every PR through `check`), release | required | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` | -| SSRF / cardinality suite | every PR (`check`), release | required | `httpClientSecurityTest` | -| Toxiproxy fault suite | main push, nightly (`integrationCheck`), release | required | `httpClientFailureInjectionTest` | -| Performance certification | main push, nightly (`performanceCheck`), release | required | `httpClientPerformanceTest` (every bound asserted; no switch turns them off) | -| Jetty HTTP/3 | main push, nightly | Experimental, non-blocking | `test -Phttp3.tests.enabled=true` | +| Spring Framework 7.0(저장소 기준) | 이 leaf를 건드린 PR, main push, 릴리스 | 필수 | `spring70CompatibilityTest` | +| Spring Framework 6.2 API 면 | 모든 PR(`check`), 릴리스 | 필수 | `spring62ApiSurfaceScan` | +| Apache HC5 + RestClient | 이 leaf를 건드린 PR(두 transport는 `check`로 모든 PR에서 함께 돈다), 릴리스 | 필수 | `httpClientStableContractTest -Phttpclient.contract.transports=apache` | +| JDK HttpClient + RestClient | 이 leaf를 건드린 PR(두 transport는 `check`로 모든 PR에서 함께 돈다), 릴리스 | 필수 | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` | +| SSRF / 가짓수 suite | 모든 PR(`check`), 릴리스 | 필수 | `httpClientSecurityTest` | +| Toxiproxy 장애 suite | main push, nightly(`integrationCheck`), 릴리스 | 필수 | `httpClientFailureInjectionTest` | +| 성능 인증 | main push, nightly(`performanceCheck`), 릴리스 | 필수 | `httpClientPerformanceTest`(모든 상한을 단언. 끄는 스위치가 없다) | +| Jetty HTTP/3 | main push, nightly | Experimental, 막지 않음 | `test -Phttp3.tests.enabled=true` | -### Known limitation of the Spring 6.2 lane +### Spring 6.2 lane의 알려진 한계 -This repository's Spring Boot 4.0 baseline pins Spring Framework 7, so a real 6.2 runtime cannot be -resolved here. `spring62ApiSurfaceScan` therefore verifies the **API surface**: the common -packages must not reference any Spring 7-only type, and no class uses -`org.springframework.web.service.registry`. Executing the suite against an actual 6.2 distribution -requires a host project on that line. This limitation is stated rather than hidden behind a passing -check. +이 저장소의 Spring Boot 4.0 기준은 Spring Framework 7을 고정한다. 그래서 여기서는 실제 6.2 런타임을 풀 수 없다. +`spring62ApiSurfaceScan`은 대신 **API 면**을 확인한다. 공통 package가 Spring 7 전용 타입을 참조하지 않아야 하고, +어떤 클래스도 `org.springframework.web.service.registry`를 쓰지 않아야 한다. 실제 6.2 배포판에 대해 suite를 +돌리려면 그 계열의 host 프로젝트가 필요하다. 이 한계는 통과하는 검사 뒤에 숨기지 않고 밝혀 둔다. +## Suite가 증명하지 않는 것 -## What the suites do not prove +매트릭스를 바람이 아니라 측정으로 읽게 하려고 적는다. -Stated so the matrix is read as a measurement rather than an aspiration. - -| Gap | Why | What is proven instead | +| 빈곳 | 이유 | 대신 증명하는 것 | |---|---|---| -| HTTP/2 frame injection (`REFUSED_STREAM`, arbitrary `GOAWAY`) | The fixture server exposes no frame-level control, and a purpose-built h2 server is a larger dependency than the guarantee is worth here | `Http2EvidenceMapperTest` proves the frame → evidence mapping, and `NegotiatedProtocolContractTest` proves h2 is really negotiated | -| Spring 6.2 runtime | This repository's Boot 4.0 baseline pins Spring 7 | `spring62ApiSurfaceScan` confines the common packages to the 6.2 API surface | -| Performance latency baseline | Numbers measured on a build agent are not a certification | `httpClientPerformanceTest` asserts its structural bounds and the streaming heap bound in every run; it asserts no latency figure | +| HTTP/2 frame 주입(`REFUSED_STREAM`, 임의 `GOAWAY`) | fixture 서버에 frame 수준 제어가 없고, 전용 h2 서버는 여기서 얻는 보장보다 큰 의존성이다 | `Http2EvidenceMapperTest`가 frame → 증거 대응을, `NegotiatedProtocolContractTest`가 h2가 정말 협상되는지를 증명한다 | +| Spring 6.2 런타임 | 이 저장소의 Boot 4.0 기준이 Spring 7을 고정한다 | `spring62ApiSurfaceScan`이 공통 package를 6.2 API 면 안에 가둔다 | +| 성능 지연 기준선 | 빌드 agent에서 잰 숫자는 인증이 아니다 | `httpClientPerformanceTest`가 매번 구조적 상한과 스트리밍 heap 상한을 단언한다. 지연 숫자는 단언하지 않는다 | diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 550fc337..5b33de9d 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -37,15 +37,6 @@ language docs/adr/ADR-WS-002-resume-and-cluster.md language docs/adr/ADR-WS-003-stomp-and-broker-relay.md language docs/compatibility/grpc-advanced-support-matrix.md language docs/compatibility/grpc-support-matrix.md -language docs/httpclient/configuration-reference.md -language docs/httpclient/operations.md -language docs/httpclient/performance-baseline.md -language docs/httpclient/release-checklist.md -language docs/httpclient/repository-adaptation.md -language docs/httpclient/retry-and-ambiguity.md -language docs/httpclient/security.md -language docs/httpclient/streaming.md -language docs/httpclient/support-matrix.md language docs/jpa/batch-write-guide.md language docs/jpa/entity-mapping-guide.md language docs/jpa/experimental-promotion-checklist.md @@ -167,8 +158,6 @@ reference src/README.md .github/scripts/verify-gate-matrix.sh # 숫자: 정본(src/gradle/libs.versions.toml, registry)이 정하는 값을 복사한 곳. 정본을 가리키게 고치면 지운다. number docs/compatibility/grpc-support-matrix.md Spring Boot 4.0.8 -number docs/httpclient/repository-adaptation.md 19 leaf -number docs/httpclient/repository-adaptation.md Spring Boot 4.0.8 number docs/jpa/repository-adaptation.md 19 leaf number docs/jpa/repository-adaptation.md Spring Boot 4.0.8 number docs/manual/01-generator.md 5 leaf