diff --git a/docs/httpclient/configuration-reference.md b/docs/httpclient/configuration-reference.md
index 5456757e..340573a2 100644
--- a/docs/httpclient/configuration-reference.md
+++ b/docs/httpclient/configuration-reference.md
@@ -167,8 +167,8 @@ profile에는 `connect`와 `response-header`를 가장 짧은 호출자 예산
| `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` | wire 위의 바이트 |
+| `request.compression` | `false` | 켜면 transport와 상관없이 `Accept-Encoding: gzip, deflate`를 보낸다. 받은 본문은 엔진이 아니라 이 플랫폼이 wire 바이트를 센 뒤 푼다(버퍼 본문과 스트리밍 다운로드 모두) |
+| `response.max-wire-bytes` | `5242880` | wire 위의 바이트. 압축을 켜도 압축된 크기로 센다 |
| `response.max-decoded-bytes` | `10485760` | 디코딩한 뒤의 바이트. 넘을 수 없는 최대는 64 MiB |
| `response.allowed-content-types` | JSON + problem+json | 비어 있으면 「아무것이나」 |
@@ -212,7 +212,7 @@ profile에는 `connect`와 `response-header`를 가장 짧은 호출자 예산
| 속성 | 기본값 | 뜻 |
|---|---|---|
| `proxy.enabled` | `false` | |
-| `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | |
+| `proxy.host` / `proxy.port` / `proxy.type` | — / `0` / `HTTP` | 지금 transport는 모두 HTTP forward proxy만 한다. `type`의 값은 `HTTP` 하나이고, `SOCKS`는 바인딩이 거부한다 |
| `proxy.credential-provider` | — | proxy 인증은 대상 인증과 따로다 |
| `proxy.import-ambient-no-proxy` | `false` | 환경의 `NO_PROXY`는 검증한 profile을 넓히지 않는다 |
| `observability.full-url-recording` | `false` | |
diff --git a/docs/httpclient/retry-and-ambiguity.md b/docs/httpclient/retry-and-ambiguity.md
index 8aa43fe1..e2c44497 100644
--- a/docs/httpclient/retry-and-ambiguity.md
+++ b/docs/httpclient/retry-and-ambiguity.md
@@ -50,9 +50,9 @@
| 상태 | 판정 |
|---|---|
-| 408 | 기한과 예산 안에서 재시도 |
-| 425 | 첫 시도에서만, 많아야 한 번 재시도 |
-| 429 | `Retry-After`, 기한, 예산 안에서 재시도 |
+| 408 | 안전하게 멱등인 연산만 기한과 예산 안에서 재시도. 아니면 결과 모름(upstream이 받은 뒤 답한 것일 수 있다) |
+| 425 | 안전하게 멱등인 연산만, 첫 시도에서만, 많아야 한 번 재시도. 아니면 결과 모름 |
+| 429 | 안전하게 멱등인 연산만 `Retry-After`, 기한, 예산 안에서 재시도. 아니면 거부(`notRetryableStatus`). 429는 일정 신호이지 "아무 일도 없었다"는 말이 아니다 |
| 401 | 안전하고 재전송 가능한 연산에서만 갱신 후 재전송 한 번. credential은 재시도를 허락받은 뒤에만 갱신한다. 재전송하지 않을 401(시도 한 번, 예산 없음, 기한 없음)은 token cache를 건드리지 않는다 |
| 500 | upstream이 일시적이라고 등록했고 **그리고** 연산이 안전하게 멱등일 때만 허락. 아니면 거부 |
| 502, 503, 504 | 안전하게 멱등인 연산은 재시도. 아니면 결과 모름 |
diff --git a/docs/httpclient/streaming.md b/docs/httpclient/streaming.md
index fd5e0686..4c9ecaa2 100644
--- a/docs/httpclient/streaming.md
+++ b/docs/httpclient/streaming.md
@@ -7,7 +7,13 @@
검증한다. 그래서 실패한 다운로드가 호출자가 따져야 하는 반쯤 읽힌 stream이 되지 않는다.
wire 바이트와 디코딩한 바이트는 따로 제한한다. 압축한 payload는 wire 검사를 통과한 뒤 늘어나기 때문이다. 한도는
-버퍼링한 뒤가 아니라 읽는 동안 강제한다.
+버퍼링한 뒤가 아니라 읽는 동안 강제한다. 압축(`Content-Encoding: gzip`·`deflate`)은 엔진이 아니라 응답 reader가
+푼다. 도착한 바이트를 wire 한도로 세고, 푼 바이트를 조각마다 디코딩 한도로 센다. 엔진이 먼저 풀면 wire 계수가 푼
+크기를 세게 되어, 잘 압축된 응답이 wire 위에는 없던 크기로 거부됐다(round9 리뷰 2026-11-12, RR9-01-30). 부탁하지 않은
+압축(`br` 등)과 겹친 coding은 거부한다. 스트리밍 다운로드도 같은 곳(`ContentDecoding`)을 거친다. 호출자는 푼 바이트를
+읽고, 응답 헤더에는 `Content-Encoding`·`Content-Length`가 없다. 풀기는 호출자가 읽을 때 시작하므로, 본문이 빈 gzip
+응답(HEAD·204·304)은 빈 본문이다. 어느 transport도 스스로 풀지 않는다. Apache는 압축 처리를 끄고, 실험 transport인
+Jetty HTTP/3은 시작할 때 classpath에서 등록한 decoder를 지운다.
## 첫 바이트 경계
diff --git a/docs/manual/05-idempotency.md b/docs/manual/05-idempotency.md
index fce96ff2..cbdfee67 100644
--- a/docs/manual/05-idempotency.md
+++ b/docs/manual/05-idempotency.md
@@ -57,7 +57,10 @@ executor 조립과 실제 PostgreSQL 저장소 왕복은 `PostgreSqlIdempotencyP
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(정본
`docs/web/http-contract.md` 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
-않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
+않는다. 단, 그 기록이 Redis에 남아 있는 동안만이다. Sentinel·Cluster failover는 비동기 복제라 primary가 받고
+replica에 아직 넘기지 못한 기록을 잃을 수 있고, 그러면 같은 키 요청은 처음 보는 키로 다시 실행된다
+(`docs/runbooks/redis-capability-incident.md` 「Topology and persistence」). 이 창이 업무상 받아들일 수 없는
+작업은 PostgreSQL 저장소를 쓰거나 업무 데이터의 유일 제약으로 따로 막는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다
오래 걸릴 때 보이는 모습도 저장소마다 다르다.
diff --git a/docs/mongodb/advanced/multi-tenancy.md b/docs/mongodb/advanced/multi-tenancy.md
index f05e7ff5..419baf46 100644
--- a/docs/mongodb/advanced/multi-tenancy.md
+++ b/docs/mongodb/advanced/multi-tenancy.md
@@ -41,7 +41,10 @@ email을 모든 tenant에 걸쳐 유일하게 만든다. 그러면 tenant A가
## 2. tenant마다 database (Experimental)
`MongoTenantClientRegistry`는 tenant마다 client를 하나 둔다. 개수 상한이 있고 쓰지 않는 client는
-내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다.
+내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다. `acquire`는 `Lease`를 돌려주고,
+그 client는 lease를 모두 닫을 때까지 쓰는 중이다. 쓰는 중인 client는 얼마나 오래전에 받았든 내보내지 않는다.
+내보낸 client를 닫다가 실패하면 그 tenant 대신 `evictionCloseFailures()`가 센다. 닫기를 부른 다른 tenant의
+`acquire`는 실패하지 않는다(round9 리뷰 2026-11-12, RR9-01-27).
Experimental인 이유가 분명하다. 작을 때는 맞고, 클 때는 한계가 없다. tenant database마다 connection,
file handle, 모니터링 가짓수가 든다. tenant 20개에서는 잘 돌고 2,000개에서는 쓰러진다. 기능 테스트로는
diff --git a/docs/mongodb/query-aggregation-guide.md b/docs/mongodb/query-aggregation-guide.md
index cb3f5805..b6531001 100644
--- a/docs/mongodb/query-aggregation-guide.md
+++ b/docs/mongodb/query-aggregation-guide.md
@@ -39,9 +39,15 @@ regex는 index를 쓰는 척하는 collection 전체 scan이고, 사용자가
| 상한 | 이유 |
|---|---|
| `maxTimeMS` | 아무도 기다리지 않는 query를 서버가 멈춘다. |
-| 결과 개수 상한 | 상한 없는 결과는 단계가 몇 개 더 붙은 OOM이다. |
-| batch 크기 | 왕복 한 번의 메모리를 제한한다. |
-| 검사한 문서 수 상한 | 빠른 날에는 시간 상한만으로 숨겨지는 index 회귀를 잡는다. |
+| 결과 개수 상한(`maxResults`) | 상한 없는 결과는 단계가 몇 개 더 붙은 OOM이다. |
+| 결과 바이트 상한(`maxResultBytes`) | 문서 하나하나가 크면 개수 상한 안에서도 heap이 찬다. |
+| batch 크기(`cursorBatchSize`) | 왕복 한 번의 메모리를 제한한다. |
+
+개수·시간·batch는 서버에 보내는 요청에 실린다(`PolicyAwareMongoQueryBuilder.build`가 만든 `Query`, aggregation의
+`$limit`과 옵션). 바이트는 결과를 읽는 쪽만 셀 수 있다. aggregation은 `PolicyAwareMongoAggregationExecutor`가
+cursor에서 문서를 하나씩 읽으며 encode한 크기를 더하고 넘으면 거부한다(5절). query builder는 `Query`만 돌려주므로
+query의 바이트 상한을 집행하는 템플릿 코드는 없다. 그 `Query`로 결과를 읽는 서비스의 adapter가 `maxResultBytes`를
+직접 센다. 세지 않으면 그 상한은 선언일 뿐이다.
`MongoBudgetPolicyRegistry`가 예산을 연산 이름에 묶는다. `MongoBudgetEnforcer`가 그것을 적용한다. 요청이
예산을 넘으면 실행 전에 `MongoOperationRejectedException`을 던지고, 서버가 상한을 집행하면
@@ -86,6 +92,11 @@ regex는 index를 쓰는 척하는 collection 전체 scan이고, 사용자가
| high | `$lookup`, `$graphLookup`, `$facet`, index 없는 `$sort` | profile의 명시적 승인이 필요하다. |
| forbidden | admin plane 밖의 `$out`·`$merge`, `$function`, `$accumulator` | 거부한다. |
+실행은 예산 둘을 결과가 오는 동안 본다. pipeline 끝에 `$limit(maxResults + 1)`을 붙여 서버가 예산보다 한 개 넘게는
+만들지 않게 하고, 결과를 cursor에서 한 문서씩 읽으며 개수와 encode한 바이트를 더한다. 둘 중 하나라도 넘으면
+`MongoOperationRejectedException`(`aggregation.result`)이다. 예전에는 결과를 전부 메모리에 올린 뒤 개수만 셌고 바이트
+상한은 선언만 있었다(round9 리뷰 2026-11-12, RR9-01-20).
+
`allowDiskUse`는 실행 중 flag가 아니라 plan에 선언하는 속성이다. 디스크가 필요한 pipeline은 모양을 검토해야
하는 pipeline이다.
diff --git a/docs/upgrade/2026-11-round9-outbound.md b/docs/upgrade/2026-11-round9-outbound.md
index c9a769a5..702989cf 100644
--- a/docs/upgrade/2026-11-round9-outbound.md
+++ b/docs/upgrade/2026-11-round9-outbound.md
@@ -1,13 +1,15 @@
# 업그레이드 안내 — 2026-11 outbound 발행·발송·캐시·S3·MongoDB·HTTP client
-- 범위: outbox 발행 대기, SMTP 발송 pool과 시간 상한, Redis 캐시 시간·크기 상한을 고친 변경. 기동 조건이 바뀐 곳이
- 있다. 아래 표가 그 목록이다.
-- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 발행·발송·캐시(B10a) 발견
+- 범위: outbox 발행 대기, SMTP 발송 pool, Redis 캐시 시간·크기 상한, S3 조건부 쓰기, MongoDB 집계 예산·tenant
+ client·migration lease, HTTP client 압축·proxy를 고친 변경. 기동 조건과 공개 타입이 바뀐 곳이 있다. 아래 표가 그
+ 목록이다.
+- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 발행·발송·캐시(B10a)와 S3·Mongo·httpclient
+ (B10b) 발견
## 1. 누가 읽나
-이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 SMTP 알림, Redis 캐시, outbox
-publisher를 직접 구현한 서비스다.
+이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 SMTP 알림, Redis 캐시, MongoDB
+집계·tenant별 database, HTTP client의 압축이나 proxy를 쓰는 서비스다.
## 2. 할 일
@@ -16,7 +18,12 @@ publisher를 직접 구현한 서비스다.
| 1 | SMTP provider profile들의 `max-concurrency` 합이 발송 pool이 담는 수(`app.notification.platform.smtp.dispatch-concurrency`개 thread와 그 네 배의 대기열) 이하인지 확인한다. 모든 SMTP profile이 pool 하나를 같이 쓴다. 기본값(profile 하나, 4와 4)은 맞는다 | 넘으면 넘게 만든 profile의 조립이 기동 때 실패한다. 전에는 넘친 발송이 대기열에서 거절되어 결과 불명으로 남았다 | SMTP 알림을 켠 서비스 |
| 2 | Redis 캐시의 `command-timeout`이 이제 한 캐시 연산 전체(연결 대기와 응답 전부)의 상한이다. 연결 대기가 길던 배포는 값을 다시 본다 | 상한 안에 못 끝난 연산이 캐시 없음(`DEGRADED_UNAVAILABLE`·`Unavailable`)으로 끝나는 일이 늘 수 있다. 전에는 lane 대기 2초가 더해졌다 | Redis 캐시를 켠 서비스 |
| 3 | encode한 값이 1 MiB(`RedisCacheRegionAdapter.DEFAULT_MAXIMUM_VALUE_BYTES`)를 넘는 캐시는 그 값을 기록하지 않는다(`NOT_RECORDED_PROVIDER_POLICY`). 더 큰 값이 필요하면 `app.capabilities.cache.maximum-value-bytes`(`APP_CACHE_REDIS_MAXIMUM_VALUE_BYTES`, 1..16777216)로 상한을 올린다. 2026-08-10에 폐기했던 그 env 키가 다시 묶였다 | 그 값은 매번 source에서 읽힌다 | 큰 값을 캐시하던 서비스 |
-| 4 | SMTP provider profile의 `timeout`(기본이 `10s`에서 `30s`로 바뀌었다)이 발송 한 번을 두 번 묶는다. 발송이 send pool에서 그 시간이 지나도록 시작하지 못하면 relay에 보내지 않고 시작 전 실패(`PROVIDER_UNAVAILABLE`, 재시도)로 기록한다. 시작한 뒤 그 시간이 지나면 결과 불명(`PROVIDER_RESPONSE_LOST`)으로 기록하고 자동으로 다시 보내지 않는다. 값은 `mail.smtp.connectiontimeout`에 `mail.smtp.timeout`·`mail.smtp.writetimeout` 중 긴 것을 더한 값보다 길어야 하고, `dispatch.lease-duration`은 그 두 배보다 길어야 한다. `dispatch.shutdown-grace`가 그 두 배보다 짧으면 종료 중에 끝나지 않은 발송이 결과 불명으로 남는다(`docs/notification/configuration-reference.md` 「SMTP relay」). `SmtpNotificationProviderAdapter`를 직접 만들던 코드는 마지막 인자로 이 timeout을 넘긴다. 직접 만든 `ProviderRuntimeAssembler`는 새 default 메서드 `requireTogether(profiles, deliveryLease)`로 한 family의 켜진 profile 전체에 걸린 검사를 할 수 있다(`NotificationProviderAssembly`가 SERVING일 때 family마다 한 번 부른다). `assemble`을 직접 부르는 코드는 그 전에 `requireTogether`를 부른다 | timeout이 socket timeout 합 이하이거나 lease가 timeout 두 배 이하면 SMTP 조립이 기동 때 실패한다. 상한 안에 끝나지 않는 발송이 결과 불명으로 남는다. 전에는 socket timeout이 명령마다만 묶어, 느린 relay에서 발송이 lease를 넘으면 lease 복구가 아직 도는 발송을 운영자 확인으로 넘겼다. | SMTP 알림을 켠 서비스 |
+| 4 | MongoDB `PolicyAwareMongoAggregationExecutor`는 등록 예산의 `maxResultBytes`를 집행하고, pipeline 끝에 `$limit(maxResults + 1)`을 붙인다. 결과가 큰 집계의 예산을 다시 본다. 집계 결과는 template의 converter로만 바뀌어 `AfterLoadEvent`·`AfterConvertEvent`와 entity callback이 돌지 않는다. 그것에 기대던 listener는 돌려받은 타입에서 직접 한다 | 바이트 예산을 넘는 집계가 `MongoOperationRejectedException`(`aggregation.result`)으로 실패한다. 전에는 결과를 전부 메모리에 올렸다 | MongoDB 집계를 쓰는 서비스 |
+| 5 | experimental `MongoTenantClientRegistry.acquire`가 `Lease`(interface)를 돌려준다. client를 다 쓴 뒤 `lease.close()`(또는 try-with-resources)를 부른다. 쓰는 중인 tenant의 `release`는 거부된다. idle 시간은 마지막 lease를 닫은 때부터 잰다. 열린 lease 수는 `openLeases()`다. 시각을 인자로 받던 `acquire(tenant, Instant)`는 없어졌다. 시계는 생성자의 `Clock` 하나다 | 반환값을 버리는 호출은 컴파일되지만, 닫지 않은 lease의 client는 쓰는 중으로 남아 내보내지지 않고 cap 한 칸을 계속 차지한다. `acquire(tenant, Instant)`를 부른 코드는 컴파일이 실패한다 | tenant별 database를 쓰는 서비스 |
+| 6 | MongoDB migration lease를 잃은 뒤의 `refresh`는 `MongoOperationRejectedException`(`migration.lock`)을 던진다. `IllegalStateException`을 잡던 코드를 바꾼다. collection을 직접 넘겨 `MongoCollectionMigrationLedger`를 만들던 코드는 셋째 인자로 lock collection(`MongoCollectionMigrationLock.DEFAULT_COLLECTION`)을 넘긴다. 옛 runner의 `recordApplied`는 새 runner가 lease를 잡은 뒤면(checkpoint를 쓰기 전이어도) 거부된다 | 그 예외를 잡지 못한다. 두 인자 생성자는 컴파일이 실패한다 | MongoDB migration runner를 직접 쓰는 서비스 |
+| 7 | HTTP client profile의 `proxy.type: SOCKS`를 지우거나 HTTP proxy로 바꾼다. `ProxyType`에는 이제 `HTTP`만 있다 | 설정 바인딩이 실패해 기동하지 않는다. 전에는 SOCKS port에 HTTP proxy로 붙어 첫 요청에서 실패했다 | SOCKS proxy를 설정한 서비스 |
+| 8 | `request.compression: true`인 HTTP client는 transport와 상관없이 `Accept-Encoding: gzip, deflate`를 보내고, 버퍼 본문과 스트리밍 다운로드 모두 이 플랫폼이 푼다(JDK transport는 전에 이 설정을 읽지 않았다). 압축을 켰든 껐든, 그 밖의 `Content-Encoding`(`br` 등)이나 겹친 coding으로 온 응답은 `HttpTargetRejectedException`(`TARGET_REJECTED`, 증거 `RESPONSE_RECEIVED`)으로 거부된다. 본문이 빈 gzip 응답(HEAD·204·304)은 빈 본문이다 | — 동작 변경. `response.max-wire-bytes`가 이제 압축된 크기로 센다. 스트리밍 다운로드도 identity 본문까지 `max-decoded-bytes`로 센다. 실험 transport인 Jetty HTTP/3도 이제 스스로 풀지 않는다 | HTTP client를 쓰는 서비스 |
+| 9 | SMTP provider profile의 `timeout`(기본이 `10s`에서 `30s`로 바뀌었다)이 발송 한 번을 두 번 묶는다. 발송이 send pool에서 그 시간이 지나도록 시작하지 못하면 relay에 보내지 않고 시작 전 실패(`PROVIDER_UNAVAILABLE`, 재시도)로 기록한다. 시작한 뒤 그 시간이 지나면 결과 불명(`PROVIDER_RESPONSE_LOST`)으로 기록하고 자동으로 다시 보내지 않는다. 값은 `mail.smtp.connectiontimeout`에 `mail.smtp.timeout`·`mail.smtp.writetimeout` 중 긴 것을 더한 값보다 길어야 하고, `dispatch.lease-duration`은 그 두 배보다 길어야 한다. `dispatch.shutdown-grace`가 그 두 배보다 짧으면 종료 중에 끝나지 않은 발송이 결과 불명으로 남는다(`docs/notification/configuration-reference.md` 「SMTP relay」). `SmtpNotificationProviderAdapter`를 직접 만들던 코드는 마지막 인자로 이 timeout을 넘긴다. 직접 만든 `ProviderRuntimeAssembler`는 새 default 메서드 `requireTogether(profiles, deliveryLease)`로 한 family의 켜진 profile 전체에 걸린 검사를 할 수 있다(`NotificationProviderAssembly`가 SERVING일 때 family마다 한 번 부른다). `assemble`을 직접 부르는 코드는 그 전에 `requireTogether`를 부른다 | timeout이 socket timeout 합 이하이거나 lease가 timeout 두 배 이하면 SMTP 조립이 기동 때 실패한다. 상한 안에 끝나지 않는 발송이 결과 불명으로 남는다. 전에는 socket timeout이 명령마다만 묶어, 느린 relay에서 발송이 lease를 넘으면 lease 복구가 아직 도는 발송을 운영자 확인으로 넘겼다. | SMTP 알림을 켠 서비스 |
## 3. 바뀐 동작 (따라 할 일 없음)
@@ -27,3 +34,8 @@ publisher를 직접 구현한 서비스다.
relay가 그 행을 backoff 뒤로 미뤘다가 발행한다. 기다리는 중의 interrupt는 전처럼 결과 불명(`PUBLISH_WAIT_INTERRUPTED`)이다.
- SMTP 발송 pool은 첫 발송부터 `dispatch-concurrency`개 thread로 돈다(전에는 대기열이 찰 때까지 thread 하나였다).
pool이 거절한 발송은 relay에 닿지 않은 것(`PROVIDER_UNAVAILABLE`, `CAPACITY_REJECTED`)으로 기록되어 재시도된다.
+- S3 control 저장소의 조건부 `PUT`이 412를 받으면 key를 다시 읽는다. 이 호출이 쓴 record 그대로면 성공이다(SDK가 응답을
+ 잃은 첫 쓰기를 다시 보낸 경우). 다른 내용이나 없음이면 전처럼 충돌이다. 「그대로」는 같은 값이라는 뜻이라, 두 writer가
+ 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다. 그럴 수 있는 호출자는 record에 자기 토큰을 싣는다.
+- MongoDB tenant client를 내보내다 닫기에 실패하면 그 tenant 대신 `evictionCloseFailures()`가 센다. 닫기를 부른 다른
+ tenant의 `acquire`는 실패하지 않는다.
diff --git a/docs/web/http-contract.md b/docs/web/http-contract.md
index 1462840f..c5df1788 100644
--- a/docs/web/http-contract.md
+++ b/docs/web/http-contract.md
@@ -125,7 +125,9 @@ Envelope가 아닌 응답은 두 곳뿐이다. fileserver의 프로토콜 예외
`IDEMPOTENT_IN_FLIGHT`, lease가 지났으면 500 `IDEMPOTENCY_RECOVERY_REQUIRED`다. 이것은 Redis 저장소의
판정이다. PostgreSQL 저장소는 아래처럼 첫 요청이 끝날 때까지 기다린 뒤 판정한다. 새 키로 보내면 서버는
다른 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정
- RR-01-11).
+ RR-01-11). Redis 저장소의 판정은 그 기록이 Redis에 남아 있는 동안만이다. Sentinel·Cluster failover는 비동기
+ 복제라 replica에 아직 넘기지 못한 기록을 잃을 수 있고, 그러면 같은 키 요청은 처음 보는 키로 다시 실행된다
+ (`docs/manual/05-idempotency.md` 「클라이언트에게 무엇을 약속하나」).
- **첫 시도가 lease보다 오래 걸릴 때 — 저장소마다 다르다.** executor는 lease를 늘리지 않으므로 30s를 넘는
정상 요청도 lease가 지난다(재리뷰 2026-11-04 RR5-01-05).
- Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/apache/ApacheClientFactory.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/apache/ApacheClientFactory.java
index 8a12e87a..6478893a 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/apache/ApacheClientFactory.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/apache/ApacheClientFactory.java
@@ -111,15 +111,17 @@ public final class ApacheClientFactory {
.evictIdleConnections(TimeValue.ofMilliseconds(profile.pool().maxIdleTime().toMillis()))
.setDefaultRequestConfig(requestConfig(profile));
- if (!profile.request().compression()) {
- clientBuilder.disableContentCompression();
- }
+ // Apache never decodes the body. With its content compression on, the stream the response
+ // reader counted as "wire" bytes was already decompressed, so a profile's wire limit was a
+ // second decoded limit and a well-compressed response under it was refused for its decoded size
+ // (round9 review 2026-11-12, RR9-01-30). The reader counts the bytes as they arrive and decodes
+ // them itself. Whether to ask for compression is the profile's, sent by the RestClient for
+ // every transport.
+ clientBuilder.disableContentCompression();
if (profile.proxy().enabled()) {
- clientBuilder.setProxy(
- new HttpHost(
- profile.proxy().type().name().toLowerCase(java.util.Locale.ROOT),
- profile.proxy().host(),
- profile.proxy().port()));
+ // An HTTP forward proxy, the only kind ProxyType has: SOCKS used to bind and then become an
+ // HTTP proxy at the SOCKS port.
+ clientBuilder.setProxy(new HttpHost("http", profile.proxy().host(), profile.proxy().port()));
}
return new ApacheRuntime(clientBuilder.build(), pool);
}
@@ -131,7 +133,8 @@ public final class ApacheClientFactory {
.setRedirectsEnabled(false)
.setMaxRedirects(0)
.setCircularRedirectsAllowed(false)
- .setContentCompressionEnabled(profile.request().compression())
+ // Decoding is the response reader's, after it has counted the wire bytes; see create().
+ .setContentCompressionEnabled(false)
// Hard cancellation lets a deadline abort actually abort the socket instead of leaving a
// request in flight after the caller has given up.
.setHardCancellationEnabled(true)
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyHttp3TransportProvider.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyHttp3TransportProvider.java
index 8bf18d5b..3332b1ea 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyHttp3TransportProvider.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyHttp3TransportProvider.java
@@ -22,6 +22,7 @@ import org.eclipse.jetty.http3.client.HTTP3Client;
import org.eclipse.jetty.http3.client.transport.HttpClientTransportOverHTTP3;
import org.eclipse.jetty.io.Transport;
import org.eclipse.jetty.quic.client.ClientQuicConfiguration;
+import org.eclipse.jetty.util.component.LifeCycle;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.JettyClientHttpRequestFactory;
@@ -132,6 +133,18 @@ public final class JettyHttp3TransportProvider implements BlockingTransportProvi
.getRequestListeners()
.addQueuedListener(
request -> AttemptDeadline.abortOnExpiry(() -> abortAtDeadline(request)));
+ // Jetty registers its gzip decoder from the classpath when it starts, then asks for gzip on
+ // every request, decodes the response itself and drops Content-Encoding — so the reader's wire
+ // count saw the decoded size, whatever the profile said (round9 review 2026-11-12,
+ // RR9-01-30). Cleared once started, because an empty list before start is what tells Jetty to
+ // load them; the coded bytes then reach the reader, which counts and decodes them.
+ client.addEventListener(
+ new LifeCycle.Listener() {
+ @Override
+ public void lifeCycleStarted(LifeCycle started) {
+ client.getContentDecoderFactories().clear();
+ }
+ });
return client;
}
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/profile/ProxyType.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/profile/ProxyType.java
index cbdba40b..10b2d93b 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/profile/ProxyType.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/profile/ProxyType.java
@@ -1,7 +1,13 @@
package dev.caskeleton.adapter.outbound.httpclient.profile;
-/** Forward proxy kind (design §24.3). */
+/**
+ * Forward proxy kind (design §24.3).
+ *
+ *
HTTP only. Every shipped transport speaks an HTTP forward proxy and none speaks SOCKS; a
+ * {@code SOCKS} value used to bind and then be wired as an HTTP proxy at the SOCKS port, and a
+ * value whose only possible effect is a failure is not kept as an option ({@code
+ * docs/manual/10-capabilities.md} standard 3). {@code proxy.type: SOCKS} now fails to bind.
+ */
public enum ProxyType {
- HTTP,
- SOCKS
+ HTTP
}
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BlockingStreamingGateway.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BlockingStreamingGateway.java
index 4f21342e..4bcfe560 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BlockingStreamingGateway.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/BlockingStreamingGateway.java
@@ -5,6 +5,7 @@ import dev.caskeleton.adapter.outbound.httpclient.api.HttpStatus;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpDeadlineExceededException;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpFailureMetadata;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpRemoteErrorException;
+import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpTargetRejectedException;
import dev.caskeleton.adapter.outbound.httpclient.api.operation.AttemptStage;
import dev.caskeleton.adapter.outbound.httpclient.api.operation.ExecutionEvidence;
import dev.caskeleton.adapter.outbound.httpclient.api.operation.HttpOperation;
@@ -109,10 +110,38 @@ public final class BlockingStreamingGateway {
// exceptions a buffered call throws, classified by the transport's own
// classifier at the body stage — not as the engine's bare IOException, which
// carried no category, no evidence and nothing to log (RR-04-03).
+ // Decoded here as the buffered reader decodes: the transport hands over the coded
+ // bytes, counted on the wire as they arrive, and what they decode to is counted
+ // against the decoded budget as the caller reads it. A streamed download used to
+ // reach the caller still compressed once the transport stopped decoding.
+ String coding;
+ try {
+ coding = ContentDecoding.codingOf(rawResponse.getHeaders());
+ } catch (ContentDecoding.RefusedCodingException refused) {
+ // A coding this client did not ask for: nothing is handed over, and the
+ // connection is not left open behind the refusal.
+ rawResponse.close();
+ throw new HttpTargetRejectedException(
+ "response content coding is not one this client asked for",
+ metadata
+ .withStatus(new HttpStatus(status))
+ .withEvidence(ExecutionEvidence.RESPONSE_RECEIVED),
+ refused);
+ }
+ InputStream wire =
+ new CountingBoundedInputStream(
+ rawResponse.getBody(), limiter::recordWireBytes);
+ // Counted against the decoded budget whatever the coding, identity included, as
+ // the buffered reader counts it: an identity body is its own decoding.
+ InputStream body =
+ new CountingBoundedInputStream(
+ ContentDecoding.decoding(coding, wire), limiter::recordDecodedBytes);
+ if (!coding.isEmpty()) {
+ ContentDecoding.dropCodingHeaders(responseHeaders);
+ }
InputStream bounded =
new ClassifiedBodyInputStream(
- new CountingBoundedInputStream(
- rawResponse.getBody(), limiter::recordWireBytes),
+ body,
bodyFailure ->
runtime
.support()
@@ -129,11 +158,7 @@ public final class BlockingStreamingGateway {
false);
} catch (RuntimeException failure) {
closeQuietly(admission);
- if (setupDeadline.expired() && !(failure instanceof HttpRemoteErrorException)) {
- throw new HttpDeadlineExceededException(
- "effective deadline reached before the stream was set up", metadata, failure);
- }
- throw failure;
+ throw setupFailure(failure, setupDeadline.expired(), metadata);
}
BlockingStreamingResponse wrapped =
@@ -155,6 +180,29 @@ public final class BlockingStreamingGateway {
}
}
+ /**
+ * What a failure while setting up the stream reaches the caller as.
+ *
+ *
Once the setup budget is spent the failure is the deadline, whatever the transport said. A
+ * response that arrived and was refused, or a remote error, stays what it is: its evidence is
+ * that the server answered.
+ *
+ * @param failure what setting up the stream threw
+ * @param budgetSpent whether the setup deadline had expired when it did
+ * @param metadata the call's failure metadata
+ * @return the exception to throw
+ */
+ static RuntimeException setupFailure(
+ RuntimeException failure, boolean budgetSpent, HttpFailureMetadata metadata) {
+ if (budgetSpent
+ && !(failure instanceof HttpRemoteErrorException)
+ && !(failure instanceof HttpTargetRejectedException)) {
+ return new HttpDeadlineExceededException(
+ "effective deadline reached before the stream was set up", metadata, failure);
+ }
+ return failure;
+ }
+
/** A permit release must not mask the failure that is already propagating. */
private static void closeQuietly(AutoCloseable closeable) {
try {
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ContentDecoding.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ContentDecoding.java
new file mode 100644
index 00000000..2f5b2ba2
--- /dev/null
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ContentDecoding.java
@@ -0,0 +1,162 @@
+package dev.caskeleton.adapter.outbound.httpclient.restclient;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.PushbackInputStream;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+import java.util.zip.GZIPInputStream;
+import java.util.zip.InflaterInputStream;
+import org.springframework.http.HttpHeaders;
+
+/**
+ * Undoes a response's content coding, for the buffered reader and the streaming download alike.
+ *
+ *
The transport does not decode (round9 review 2026-11-12, RR9-01-30): the bytes that arrive are
+ * counted against the wire budget, and what they decode to against the decoded budget. Both read
+ * paths come through here, so a streamed download is decoded the way a buffered body is rather than
+ * handed over compressed.
+ */
+final class ContentDecoding {
+
+ /**
+ * The {@code Accept-Encoding} value a profile with compression on sends: the codings {@link
+ * #decoding} undoes. Kept beside the decoder so the request never asks for a coding the reader
+ * would hand over still compressed.
+ */
+ static final String ACCEPTED = "gzip, deflate";
+
+ /** How much a decoder reads from the wire at a time. */
+ static final int CHUNK = 8 * 1024;
+
+ private ContentDecoding() {}
+
+ /** The codings {@link #decoding} undoes; {@code x-gzip} is the old name of {@code gzip}. */
+ private static final Set DECODABLE = Set.of("gzip", "x-gzip", "deflate");
+
+ /**
+ * A response coded in a way this client did not ask for, refused before its body is read.
+ *
+ *
Its own type so the gateways can report it as what it is — a response that arrived and was
+ * refused — rather than as the bare {@link IOException} a transport classifier reads as a call
+ * that got no response.
+ */
+ static final class RefusedCodingException extends IOException {
+
+ private static final long serialVersionUID = 1L;
+
+ private RefusedCodingException(String message) {
+ super(message);
+ }
+ }
+
+ /**
+ * The response's content coding, lower case; empty for none or {@code identity}.
+ *
+ * @throws RefusedCodingException when the response names more than one coding — stacked codings
+ * are not something this client asks for, and decoding only the first would hand the rest
+ * over as the body — or a coding {@link #decoding} cannot undo
+ */
+ static String codingOf(HttpHeaders headers) throws RefusedCodingException {
+ List codings = new ArrayList<>();
+ for (String value : headers.getOrEmpty(HttpHeaders.CONTENT_ENCODING)) {
+ // Limit -1: every element, an empty trailing one included, which the check below skips.
+ for (String part : value.split(",", -1)) {
+ String coding = part.trim().toLowerCase(Locale.ROOT);
+ if (!coding.isEmpty() && !coding.equals("identity")) {
+ codings.add(coding);
+ }
+ }
+ }
+ if (codings.size() > 1) {
+ throw new RefusedCodingException(
+ "the response stacked content codings this client did not ask for: " + codings);
+ }
+ String coding = codings.isEmpty() ? "" : codings.get(0);
+ if (!coding.isEmpty() && !DECODABLE.contains(coding)) {
+ throw new RefusedCodingException(
+ "the response used a content coding this client did not ask for: " + coding);
+ }
+ return coding;
+ }
+
+ /**
+ * The decoded body, read lazily from {@code wire}.
+ *
+ *
Lazily, because a gzip stream reads its header when it is built: built eagerly, an empty
+ * body under {@code Content-Encoding: gzip} — a {@code HEAD}, a 204 or a 304 — failed the whole
+ * response, and a streamed download read from the network before it was handed over. Here nothing
+ * is read until the caller reads, and a body that turns out empty decodes to nothing.
+ *
+ * @param coding a coding {@link #codingOf} returned
+ * @param wire the counted wire stream
+ */
+ static InputStream decoding(String coding, InputStream wire) {
+ return coding.isEmpty() ? wire : new LazilyDecoded(coding, wire);
+ }
+
+ /** {@code headers} without the two that describe the coded body rather than the decoded one. */
+ static void dropCodingHeaders(Map> headers) {
+ headers
+ .keySet()
+ .removeIf(
+ name ->
+ name.equalsIgnoreCase(HttpHeaders.CONTENT_ENCODING)
+ || name.equalsIgnoreCase(HttpHeaders.CONTENT_LENGTH));
+ }
+
+ private static final class LazilyDecoded extends InputStream {
+
+ private final String coding;
+ private final InputStream wire;
+ private InputStream decoded;
+
+ private LazilyDecoded(String coding, InputStream wire) {
+ this.coding = coding;
+ this.wire = wire;
+ }
+
+ @Override
+ public int read() throws IOException {
+ return open().read();
+ }
+
+ @Override
+ public int read(byte[] buffer, int offset, int length) throws IOException {
+ return open().read(buffer, offset, length);
+ }
+
+ @Override
+ public void close() throws IOException {
+ try {
+ if (decoded != null) {
+ decoded.close();
+ }
+ } finally {
+ wire.close();
+ }
+ }
+
+ private InputStream open() throws IOException {
+ if (decoded == null) {
+ PushbackInputStream peeked = new PushbackInputStream(wire, 1);
+ int first = peeked.read();
+ if (first == -1) {
+ decoded = InputStream.nullInputStream();
+ } else {
+ peeked.unread(first);
+ // deflate is the zlib-wrapped form RFC 9110 names; a server that sends raw deflate under
+ // this name fails to decode, which is a failed response rather than a guessed one.
+ decoded =
+ coding.equals("deflate")
+ ? new InflaterInputStream(peeked)
+ : new GZIPInputStream(peeked, CHUNK);
+ }
+ }
+ return decoded;
+ }
+ }
+}
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ResponseSizeLimiter.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ResponseSizeLimiter.java
index e88961bc..c4f1aa31 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ResponseSizeLimiter.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/ResponseSizeLimiter.java
@@ -36,6 +36,11 @@ public final class ResponseSizeLimiter {
this.metadata = metadata;
}
+ /** What a failure of the response this limiter counts says about the call. */
+ HttpFailureMetadata failureMetadata() {
+ return metadata;
+ }
+
public void recordWireBytes(long additional) {
wireBytes += additional;
if (wireBytes > maxWireBytes) {
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReader.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReader.java
index ef841c2b..37be1c0b 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReader.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReader.java
@@ -1,8 +1,10 @@
package dev.caskeleton.adapter.outbound.httpclient.restclient;
+import dev.caskeleton.adapter.outbound.httpclient.api.HttpStatus;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpFailureMetadata;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpSerializationException;
import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpTargetRejectedException;
+import dev.caskeleton.adapter.outbound.httpclient.api.operation.ExecutionEvidence;
import dev.caskeleton.adapter.outbound.httpclient.api.result.ByteArrayResponseType;
import dev.caskeleton.adapter.outbound.httpclient.api.result.ClassResponseType;
import dev.caskeleton.adapter.outbound.httpclient.api.result.EmptyResponseType;
@@ -10,6 +12,7 @@ import dev.caskeleton.adapter.outbound.httpclient.api.result.GenericResponseType
import dev.caskeleton.adapter.outbound.httpclient.api.result.ResponseType;
import dev.caskeleton.adapter.outbound.httpclient.profile.ResponseLimits;
import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.lang.reflect.Type;
@@ -34,6 +37,11 @@ import org.springframework.http.converter.json.JacksonJsonHttpMessageConverter;
*
The body is bounded while it is read and then decoded from memory by a Spring message
* converter. Doing the bounding first is what makes a decompression bomb or an unexpectedly huge
* payload a rejected request instead of an out-of-memory error.
+ *
+ *
Content coding is undone here, not by the transport: the bytes that arrive are counted against
+ * the wire budget as they arrive, and the bytes they decode to are counted against the decoded
+ * budget as they are produced — a chunk at a time, so a decompression bomb is refused before it is
+ * held in memory (round9 review 2026-11-12, RR9-01-30).
*/
public final class RestClientResponseReader {
@@ -112,16 +120,42 @@ public final class RestClientResponseReader {
java.util.function.LongConsumer responseBytes)
throws IOException {
Objects.requireNonNull(responseBytes, "response byte observer");
+ String coding;
+ try {
+ coding = ContentDecoding.codingOf(headers);
+ } catch (ContentDecoding.RefusedCodingException refused) {
+ // A response arrived and was refused, which the transport classifier would otherwise read
+ // from a bare IOException as a call that got no answer.
+ throw new HttpTargetRejectedException(
+ "response content coding is not one this client asked for",
+ limiter
+ .failureMetadata()
+ .withStatus(new HttpStatus(status))
+ .withEvidence(ExecutionEvidence.RESPONSE_RECEIVED),
+ refused);
+ }
try (InputStream counted =
- new CountingBoundedInputStream(
- body,
- read -> {
- limiter.recordWireBytes(read);
- responseBytes.accept(read);
- })) {
- byte[] bytes = counted.readAllBytes();
- limiter.recordDecodedBytes(bytes.length);
- return new RawResponse(status, toMap(headers), bytes);
+ new CountingBoundedInputStream(
+ body,
+ read -> {
+ limiter.recordWireBytes(read);
+ responseBytes.accept(read);
+ });
+ InputStream decoded = ContentDecoding.decoding(coding, counted)) {
+ ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+ byte[] chunk = new byte[ContentDecoding.CHUNK];
+ int read;
+ while ((read = decoded.read(chunk)) != -1) {
+ limiter.recordDecodedBytes(read);
+ bytes.write(chunk, 0, read);
+ }
+ Map> kept = toMap(headers);
+ if (!coding.isEmpty()) {
+ // The body handed on is the decoded one; keeping these would describe bytes it no longer
+ // is.
+ ContentDecoding.dropCodingHeaders(kept);
+ }
+ return new RawResponse(status, kept, bytes.toByteArray());
}
}
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientRuntimeFactory.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientRuntimeFactory.java
index be59f5ff..14eb9824 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientRuntimeFactory.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientRuntimeFactory.java
@@ -22,6 +22,7 @@ import java.util.Map;
import java.util.Objects;
import java.util.function.Supplier;
import java.util.random.RandomGenerator;
+import org.springframework.http.HttpHeaders;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.web.client.RestClient;
@@ -77,11 +78,15 @@ public final class RestClientRuntimeFactory implements ClientRuntimeFactory {
ClientHttpRequestFactory requestFactory =
provider.create(profile, generation, lifecycleListener);
- RestClient restClient =
- RestClient.builder()
- .requestFactory(requestFactory)
- .baseUrl(profile.baseUrl().toString())
- .build();
+ RestClient.Builder builder =
+ RestClient.builder().requestFactory(requestFactory).baseUrl(profile.baseUrl().toString());
+ if (profile.request().compression()) {
+ // Asked for here, once, for every transport: none of them decodes any more, so the reader
+ // counts the coded bytes on the wire and decodes them itself. The JDK transport used to read
+ // the setting nowhere, and Apache and Jetty each asked on their own.
+ builder.defaultHeader(HttpHeaders.ACCEPT_ENCODING, ContentDecoding.ACCEPTED);
+ }
+ RestClient restClient = builder.build();
AttemptResiliencePipeline pipeline = newResiliencePipeline(profile);
diff --git a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/transport/BlockingTransportCapabilities.java b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/transport/BlockingTransportCapabilities.java
index f813a537..a0e6a053 100644
--- a/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/transport/BlockingTransportCapabilities.java
+++ b/src/adapter/outbound/httpclient/src/main/java/dev/caskeleton/adapter/outbound/httpclient/transport/BlockingTransportCapabilities.java
@@ -8,7 +8,8 @@ import java.util.Set;
* What a blocking transport can actually guarantee (design §13.3).
*
*
A capability that is weaker than the profile requires fails at startup rather than degrading
- * silently at runtime.
+ * silently at runtime. {@code proxySupport} is an HTTP forward proxy, the only kind {@code
+ * ProxyType} has.
*/
public record BlockingTransportCapabilities(
Set protocols,
diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/autoconfigure/HttpClientPlatformSettingsTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/autoconfigure/HttpClientPlatformSettingsTest.java
index afa721b1..04ce86e6 100644
--- a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/autoconfigure/HttpClientPlatformSettingsTest.java
+++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/autoconfigure/HttpClientPlatformSettingsTest.java
@@ -2,13 +2,18 @@ package dev.caskeleton.adapter.outbound.httpclient.autoconfigure;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.assertj.core.api.Assertions.catchThrowable;
import dev.caskeleton.adapter.outbound.httpclient.profile.ClientMode;
import dev.caskeleton.adapter.outbound.httpclient.profile.HttpProtocol;
import dev.caskeleton.adapter.outbound.httpclient.profile.TransportType;
import java.util.List;
+import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
+import org.springframework.boot.context.properties.bind.BindException;
+import org.springframework.boot.context.properties.bind.Binder;
+import org.springframework.boot.context.properties.source.MapConfigurationPropertySource;
/**
* The aggregate rules a single client's own fields cannot express.
@@ -96,6 +101,26 @@ class HttpClientPlatformSettingsTest {
.hasMessageContaining("dynamic-targets");
}
+ @Test
+ void aSocksProxyTypeFailsToBind() {
+ // given
+ Binder binder =
+ new Binder(
+ new MapConfigurationPropertySource(
+ Map.of("proxy.enabled", "true", "proxy.type", "SOCKS")));
+
+ // when
+ Throwable refused =
+ catchThrowable(() -> binder.bind("proxy", HttpClientPlatformSettings.Proxy.class));
+
+ // then
+ assertThat(refused)
+ .as("no shipped transport speaks SOCKS; the value used to bind and then misroute")
+ .isInstanceOf(BindException.class)
+ .rootCause()
+ .hasMessageContaining("SOCKS");
+ }
+
/**
* A client whose only meaningful field here is its name.
*
diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyContentDecodingTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyContentDecodingTest.java
new file mode 100644
index 00000000..43e1cbaf
--- /dev/null
+++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/http3/JettyContentDecodingTest.java
@@ -0,0 +1,38 @@
+package dev.caskeleton.adapter.outbound.httpclient.http3;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles;
+import org.eclipse.jetty.client.HttpClient;
+import org.junit.jupiter.api.Test;
+
+/**
+ * The experimental Jetty client hands the response reader the coded bytes (round9 review
+ * 2026-11-12, RR9-01-30).
+ *
+ *
Jetty loads its gzip decoder from the classpath on start and then decodes every response
+ * itself, which made the reader's wire count the decoded size. Over a plain TCP transport, as the
+ * deadline test does: what is checked is the client's configuration, not the wire.
+ */
+class JettyContentDecodingTest {
+
+ @Test
+ void aStartedClientDecodesNoContentCodingItself() throws Exception {
+ // given
+ HttpClient client =
+ JettyHttp3TransportProvider.configure(
+ new HttpClient(), ClientProfiles.http3Experimental("edge"));
+
+ // when
+ client.start();
+
+ // then
+ try {
+ assertThat(client.getContentDecoderFactories().isEmpty())
+ .as("a decoder left registered decodes the body before the reader can count it")
+ .isTrue();
+ } finally {
+ client.stop();
+ }
+ }
+}
diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReaderEncodingTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReaderEncodingTest.java
new file mode 100644
index 00000000..9706ac6f
--- /dev/null
+++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/RestClientResponseReaderEncodingTest.java
@@ -0,0 +1,156 @@
+package dev.caskeleton.adapter.outbound.httpclient.restclient;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.catchThrowable;
+
+import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpResponseTooLargeException;
+import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpTargetRejectedException;
+import dev.caskeleton.adapter.outbound.httpclient.api.operation.ExecutionEvidence;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.zip.GZIPOutputStream;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.HttpHeaders;
+
+/**
+ * The response reader counts what arrives against the wire budget and what it decodes to against
+ * the decoded budget, a chunk at a time.
+ *
+ *
The transport used to decode before the reader saw the body, so the "wire" count was the
+ * decoded size and a well-compressed response was refused for a size it never had on the wire
+ * (round9 review 2026-11-12, RR9-01-30).
+ */
+class RestClientResponseReaderEncodingTest {
+
+ private final RestClientResponseReader reader = new RestClientResponseReader();
+
+ @Test
+ void aGzipBodyIsCountedCompressedOnTheWireAndDecodedForTheCaller() throws IOException {
+ // given
+ // Six thousand bytes that compress to a few dozen: inside a 1,000-byte wire budget only when
+ // the wire count is the compressed size.
+ byte[] decoded = "a".repeat(6_000).getBytes(StandardCharsets.US_ASCII);
+ byte[] wire = gzip(decoded);
+ ResponseSizeLimiter limiter = new ResponseSizeLimiter(1_000, 10_000);
+
+ // when
+ RestClientResponseReader.RawResponse response =
+ reader.readBounded(200, gzipHeaders(), new ByteArrayInputStream(wire), limiter);
+
+ // then
+ assertThat(
+ List.of(
+ response.body().length,
+ limiter.wireBytes(),
+ limiter.decodedBytes(),
+ response.headers().containsKey(HttpHeaders.CONTENT_ENCODING)))
+ .containsExactly(6_000, (long) wire.length, 6_000L, false);
+ }
+
+ @Test
+ void aBodyThatDecodesPastTheBudgetIsRefusedWhileItIsDecoded() throws IOException {
+ // given
+ // A small wire payload that would expand to a megabyte: refused at the decoded budget, before
+ // the whole expansion is held in memory.
+ byte[] wire = gzip(new byte[1_048_576]);
+ ResponseSizeLimiter limiter = new ResponseSizeLimiter(1_048_576, 64 * 1024);
+
+ // when
+ Throwable refused =
+ catchThrowable(
+ () -> reader.readBounded(200, gzipHeaders(), new ByteArrayInputStream(wire), limiter));
+
+ // then
+ assertThat(
+ List.of(
+ refused instanceof HttpResponseTooLargeException,
+ limiter.decodedBytes() <= 64L * 1024 + 8 * 1024))
+ .as("decoding stopped within one chunk past the budget: %s", refused)
+ .containsExactly(true, true);
+ }
+
+ @Test
+ void anUnaskedForContentCodingIsRefused() {
+ // given
+ HttpHeaders brotli = new HttpHeaders();
+ brotli.add(HttpHeaders.CONTENT_ENCODING, "br");
+ ResponseSizeLimiter limiter = new ResponseSizeLimiter(1_000, 1_000);
+
+ // when
+ Throwable refused =
+ catchThrowable(
+ () ->
+ reader.readBounded(
+ 200, brotli, new ByteArrayInputStream(new byte[] {1, 2, 3}), limiter));
+
+ // then
+ assertThat(refused)
+ .as("a response arrived and was refused; it is not a call that got no answer")
+ .isInstanceOfSatisfying(
+ HttpTargetRejectedException.class,
+ rejected ->
+ assertThat(
+ List.of(
+ rejected.getMessage(),
+ rejected.getCause().getMessage(),
+ rejected.metadata().evidence()))
+ .containsExactly(
+ "response content coding is not one this client asked for",
+ "the response used a content coding this client did not ask for: br",
+ ExecutionEvidence.RESPONSE_RECEIVED));
+ }
+
+ @Test
+ void anEmptyBodyUnderGzipIsAnEmptyBody() throws IOException {
+ // given
+ // What a HEAD, a 204 or a 304 sends with the coding of the representation it describes.
+ ResponseSizeLimiter limiter = new ResponseSizeLimiter(1_000, 1_000);
+
+ // when
+ RestClientResponseReader.RawResponse response =
+ reader.readBounded(204, gzipHeaders(), new ByteArrayInputStream(new byte[0]), limiter);
+
+ // then
+ assertThat(response.body()).isEmpty();
+ }
+
+ @Test
+ void stackedContentCodingsAreRefused() {
+ // given
+ HttpHeaders stacked = new HttpHeaders();
+ stacked.add(HttpHeaders.CONTENT_ENCODING, "gzip");
+ stacked.add(HttpHeaders.CONTENT_ENCODING, "br");
+ ResponseSizeLimiter limiter = new ResponseSizeLimiter(1_000, 1_000);
+
+ // when
+ Throwable refused =
+ catchThrowable(
+ () ->
+ reader.readBounded(
+ 200, stacked, new ByteArrayInputStream(new byte[] {1, 2, 3}), limiter));
+
+ // then
+ assertThat(refused)
+ .isInstanceOf(HttpTargetRejectedException.class)
+ .hasMessage("response content coding is not one this client asked for")
+ .cause()
+ .hasMessageContaining("stacked content codings");
+ }
+
+ private static HttpHeaders gzipHeaders() {
+ HttpHeaders headers = new HttpHeaders();
+ headers.add(HttpHeaders.CONTENT_ENCODING, "gzip");
+ return headers;
+ }
+
+ private static byte[] gzip(byte[] plain) throws IOException {
+ ByteArrayOutputStream compressed = new ByteArrayOutputStream();
+ try (GZIPOutputStream out = new GZIPOutputStream(compressed)) {
+ out.write(plain);
+ }
+ return compressed.toByteArray();
+ }
+}
diff --git a/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StreamingContentCodingTest.java b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StreamingContentCodingTest.java
new file mode 100644
index 00000000..20c31874
--- /dev/null
+++ b/src/adapter/outbound/httpclient/src/test/java/dev/caskeleton/adapter/outbound/httpclient/restclient/StreamingContentCodingTest.java
@@ -0,0 +1,149 @@
+package dev.caskeleton.adapter.outbound.httpclient.restclient;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.catchThrowable;
+
+import dev.caskeleton.adapter.outbound.httpclient.api.OperationName;
+import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpResponseTooLargeException;
+import dev.caskeleton.adapter.outbound.httpclient.api.error.HttpTargetRejectedException;
+import dev.caskeleton.adapter.outbound.httpclient.api.operation.ExecutionEvidence;
+import dev.caskeleton.adapter.outbound.httpclient.api.operation.HttpOperation;
+import dev.caskeleton.adapter.outbound.httpclient.api.result.BlockingStreamingResponse;
+import dev.caskeleton.adapter.outbound.httpclient.profile.ClientProfile;
+import dev.caskeleton.adapter.outbound.httpclient.profile.RequestLimits;
+import dev.caskeleton.adapter.outbound.httpclient.profile.ResponseLimits;
+import dev.caskeleton.adapter.outbound.httpclient.profile.TransportType;
+import dev.caskeleton.adapter.outbound.httpclient.testkit.ClientProfiles;
+import dev.caskeleton.adapter.outbound.httpclient.testkit.MockHttpServer;
+import dev.caskeleton.adapter.outbound.httpclient.testkit.TestGateways;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.zip.GZIPOutputStream;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
+
+/**
+ * A streamed download is decoded the way a buffered body is, on every blocking transport.
+ *
+ *
Once the transports stopped decoding — so the wire budget counts what arrives — the streaming
+ * path still handed the body straight on, and a compressed response reached the caller as gzip
+ * bytes (round9 review 2026-11-12, RR9-01-30). The wire budget here is smaller than the decoded
+ * body and larger than the compressed one: the download passes only when the wire is counted
+ * compressed, which is also what fails if a transport goes back to decoding on its own.
+ */
+class StreamingContentCodingTest {
+
+ private static final byte[] DECODED = "a".repeat(6_000).getBytes(StandardCharsets.US_ASCII);
+
+ @ParameterizedTest(name = "{0}")
+ @EnumSource(
+ value = TransportType.class,
+ names = {"APACHE", "JDK"})
+ void aGzipDownloadReachesTheCallerDecodedAndCountedCompressedOnTheWire(TransportType transport)
+ throws Exception {
+ try (MockHttpServer server = MockHttpServer.start();
+ TestGateways.Harness harness = TestGateways.forProfile(profile(server, transport))) {
+ // given
+ server.enqueueEncodedBody(200, "text/plain", "gzip", gzip(DECODED));
+ BlockingStreamingGateway gateway = new BlockingStreamingGateway(harness.registry());
+
+ // when
+ List