docs(httpclient): HTTP client 문서를 한국어로 옮기고 숫자 복사를 없앤다
문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외). repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit` source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다. 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는 원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다. leaf 수는 registry(src/config/architecture/modules.json)를, 버전은 src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default, Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만 옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만). configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다. 버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라 날짜와 함께 그대로 둔다. 위험·한계: 내용 감사는 하지 않았다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
This commit is contained in:
@@ -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.<typo>`
|
||||
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.<typo>`는 아무것도 바인딩하지 않고 아무것도 실패시키지
|
||||
않았다. 이제 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 방어는 있고 맞지만 우회된다. 그래서
|
||||
이 조합은 지킬 수 없는 보장을 단 채 내주지 않고 거부한다.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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과 원격 오류 본문은 절대 속성으로 기록하지 않는다.
|
||||
|
||||
@@ -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에서 잰 숫자를 인증한 기준선처럼 내놓는 것은 기준선이 없는
|
||||
것보다 나쁘다.
|
||||
|
||||
@@ -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가 자동 구성하는 일은 없다.
|
||||
|
||||
@@ -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 의미.
|
||||
|
||||
@@ -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 허가도
|
||||
잡지 않는다.
|
||||
|
||||
+46
-53
@@ -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로만
|
||||
나온다.
|
||||
|
||||
@@ -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 호출만 돌린다.
|
||||
|
||||
@@ -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 상한을 단언한다. 지연 숫자는 단언하지 않는다 |
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user