tech-log-backend/docs/httpclient/performance-baseline.md

HTTP Client Platform — Performance Baseline

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.

How to run

# structural bounds only (default; still executes every test)
./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest --console=plain

# full certification, including machine-dependent bounds
./gradlew :adapter:outbound:httpclient:httpClientPerformanceTest \
  -Pperformance.assertions.enabled=true --console=plain

# JMH benchmarks
./gradlew :adapter:outbound:httpclient:jmh --console=plain

Machine-dependent assertions are reported as explicitly skipped when the flag is absent — the lane never silently degrades into a pass.

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
Http2StreamSaturationTest	32 concurrent reactive streams share a 2-connection pool and complete	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

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.

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

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.