feat(httpclient): close the platform review's P0/P1/P2 findings

The review found one defect shape repeated across the platform: surfaces that were declared, bound, and documented, but that nothing read. An operator configuring fullUrlRecording, bodyLogging, retry.policy, validatedDnsPinning, timeout.dns, or any of ten declared metric names got a guarantee the code never delivered. Every such surface is now in exactly one of three states -- wired for real, rejected at startup, or registered in a test-enforced gap list with its reason. No silent no-ops remain. P0: - Activate the platform from bootstrap behind app.httpclient.enabled, with a single auto-configuration importing the nine child configurations. - Give the platform a strict, repository-level ENV contract: 74 leaf fields derived from the settings record tree, unknown APP_HTTPCLIENT_* rejected. - Route typed HTTP service clients through the call kernel via KernelHttpExchangeAdapter, so they stop bypassing platform policy. - Pin dynamic-target DNS resolution to the socket for the life of a call, closing the resolve-then-connect TOCTOU / rebinding window. - Actually transmit the idempotency key, and make retry eligibility depend on transmission rather than on merely holding one. - Reject reactive authentication and reactive redirect at startup instead of declaring support that does not function. - Fix the Reactor-only Stable contract row so the lane stops failing. - Stop advertising HTTP/3 on a transport that negotiates HTTP/1. P1 covers execution and retry accounting, redirect security (per-hop target guarding, sensitive-header stripping, 303 body handling), runtime rotation and transport resource ownership keyed by generation, dynamic-target hardening (subdomain matching, global-unicast classification, strict CIDR parsing), protocol intent, pool and timeout wiring, streaming and body limits, observability parity, and OAuth single-flight refresh on a bounded pool with a bounded wait. P2 covers configuration and documentation drift, the Gradle check wiring for the four hermetic lanes, and the CI gate matrix. Two test-quality defects surfaced while closing these: the HTTP/2 stream saturation test ran against cleartext HTTP/1.1 while asserting nothing about the protocol, and an OAuth contention test slept on a latch that could fire before the callers it meant to observe. Both now assert what their names claim. Verification run: :adapter:outbound:httpclient:check and :app-bootstrap:check (checkstyle, spotless, spotbugs, and the four hermetic lanes), verifyCleanArchitectureDependencies, verifyEnvKeys, verifyOneTypePerFile, verifyDependencyLocks, the documentation and gate-matrix verifiers, and the performance lane against a real TLS+ALPN HTTP/2 server. Not executed, and tracked rather than claimed: Docker/Toxiproxy fault injection, JMH, a real QUIC/HTTP3 server, a real Spring Framework 6.2 distribution (now a delegated-pending gate), live OAuth/TLS/proxy/DNS integration, and a whole-repository check. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-11 16:49:31 +09:00
parent 5f10b791d3
commit 0cd959a494
148 changed files with 26812 additions and 2368 deletions
@@ -0,0 +1,228 @@
+# HTTP Client Platform — Configuration Reference
+
+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]`.
+
+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.
+
+## The master switch
+
+| Property | Type | Default | Environment |
+|---|---|---|---|
+| `app.httpclient.enabled` | boolean | `false` | `APP_HTTPCLIENT_ENABLED` |
+
+Off is the shipped state and it is a structural one. `HttpClientPlatformAutoConfiguration` lives in
+a package the composition root's component scan excludes, so while the switch is absent or false the
+class is 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 never wanted outbound
+HTTP.
+
+Anything that is not exactly `true` — `yes`, `1`, blank — leaves the platform off. Turning it 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.
+
+## Declaring clients from the environment
+
+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.
+
+```dotenv
+APP_HTTPCLIENT_ENABLED=true
+
+APP_HTTPCLIENT_CLIENTS_0_NAME=payment
+APP_HTTPCLIENT_CLIENTS_0_BASE_URL=https://payment.example
+APP_HTTPCLIENT_CLIENTS_0_ALLOWED_HOSTS_0=payment.example
+APP_HTTPCLIENT_CLIENTS_0_ALLOWED_PORTS_0=443
+APP_HTTPCLIENT_CLIENTS_0_REQUEST_MAX_BODY_BYTES=1048576
+APP_HTTPCLIENT_CLIENTS_0_TLS_PROFILE_ID=payment
+
+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.
+
+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.
+
+## `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 |
+| `api` | `REST_CLIENT` \| `WEB_CLIENT` | `REST_CLIENT` | Decides blocking or reactive runtime |
+| `transport` | `APACHE` \| `JDK` \| `REACTOR_NETTY` \| `JETTY` \| `SIMPLE` | `APACHE` | `SIMPLE` is rejected in production |
+| `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` |
+
+### `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 |
+| `eviction-interval` | `15s` | Background cleanup |
+| `shutdown-timeout` | `5s` | Drain deadline before forced close |
+| `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 |
+
+### `timeout`
+
+| Property | Default | Meaning |
+|---|---|---|
+| `dns` | `300ms` | Hostname resolution |
+| `connect` | `500ms` | Socket connect |
+| `tls-handshake` | `1s` | TLS and ALPN |
+| `proxy-connect` | `500ms` | Proxy socket or CONNECT |
+| `request-write-idle` | `1s` | No progress writing the request |
+| `response-header` | `2s` | Until final response headers |
+| `read-idle` | `3s` | Between response chunks |
+| `total-call` | `4s` | The whole logical call, including retry backoff |
+| `streaming-idle` | `30s` | Silence on a long-lived stream |
+
+`total-call` must not be shorter than `connect` or `response-header`; the validator emits
+`INVALID_TIMEOUT_BUDGET` otherwise.
+
+### `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 |
+| `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" |
+
+### `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 |
+
+### `retry`
+
+| Property | Default | Meaning |
+|---|---|---|
+| `policy` | `none` | Named policy for reporting |
+| `max-attempts` | `1` | Attempts, not retries |
+| `base-backoff` | `50ms` | |
+| `max-backoff` | `200ms` | |
+| `jitter` | `FULL` | `NONE` \| `FULL` \| `DECORRELATED` |
+| `retry-after` | `HONOR` | `HONOR` \| `IGNORE` \| `CAP` |
+| `budget` | — | Shared token bucket name |
+
+### `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 |
+
+### `proxy` and `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.connect-timeout` | `500ms` | Recorded as its own metric |
+| `proxy.import-ambient-no-proxy` | `false` | Ambient `NO_PROXY` never widens a validated profile |
+| `observability.operation-name-required` | `true` | |
+| `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 |
+| `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 |
+
+## Startup violation codes
+
+`TRUSTED_BASE_URL_REQUIRED`, `BASE_URL_USERINFO_FORBIDDEN`, `BASE_URL_QUERY_FORBIDDEN`,
+`PLAINTEXT_PRODUCTION_TARGET`, `ALLOWED_HOST_MISMATCH`, `ALLOWED_PORT_MISMATCH`,
+`REDIRECT_POLICY_INVALID`, `REDIRECT_CROSS_ORIGIN_CREDENTIAL_POLICY_REQUIRED`,
+`INVALID_TIMEOUT_BUDGET`, `RESPONSE_HARD_MAXIMUM_EXCEEDED`, `PRODUCTION_SIMPLE_FACTORY_FORBIDDEN`,
+`JDK_FINE_GRAINED_POOL_UNSUPPORTED`, `HTTP3_STABLE_FORBIDDEN`,
+`DYNAMIC_TARGET_TRANSPORT_UNSUPPORTED`, `DYNAMIC_DEFAULT_CREDENTIAL_FORBIDDEN`,
+`OAUTH2_REGISTRATION_REQUIRED`, `API_KEY_HEADER_NAME_REQUIRED`, `TRUST_ALL_FORBIDDEN`,
+`HOSTNAME_VERIFICATION_REQUIRED`, `PLAINTEXT_FALLBACK_FORBIDDEN`, `TLS_PROTOCOL_FORBIDDEN`,
+`RETRY_BACKOFF_REQUIRED`, `MISSING_PRODUCTION_SETTING`, `DUPLICATE_CLIENT_NAME`,
+`HTTPCLIENT_ACTIVE_WITHOUT_CLIENTS`, `DYNAMIC_BASE_URL_REQUIRED`,
+`DYNAMIC_TARGET_PROXY_UNSUPPORTED`, `REACTIVE_AUTHENTICATION_UNSUPPORTED`,
+`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`, `POOL_ROUTE_EXCEEDS_TOTAL`,
+`TLS_PROTOCOL_SET_REQUIRED`, `REACTIVE_REDIRECT_UNSUPPORTED`,
+`RETRY_POLICY_CONTRADICTS_ATTEMPTS`, `FULL_URL_RECORDING_FORBIDDEN`, `BODY_LOGGING_FORBIDDEN`,
+`DNS_TIMEOUT_UNSUPPORTED`, `PROXY_CREDENTIAL_UNSUPPORTED`, `PROXY_AMBIENT_NO_PROXY_UNSUPPORTED`.
+
+The last three 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.
+
+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. Only `REACTOR_NETTY` 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, and on Reactor,
+  where the per-route knob is the only one that exists, it silently becomes the effective limit.
+- `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.
+- `REACTIVE_REDIRECT_UNSUPPORTED` — engine redirect following is disabled on every transport and
+  only the blocking stack has a coordinator that follows hops with per-hop re-validation. A
+  `WEB_CLIENT` profile with `redirect.enabled=true` did not follow redirects; the caller received the
+  3xx as an ordinary response. Refused until the reactive coordinator exists.
+- `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.
+
+`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.
@@ -0,0 +1,179 @@
+# HTTP Client platform — Java field path to environment variable template.
+#
+# The SSOT is HttpClientPlatformSettings. HttpClientEnvironmentKeys derives this list from the
+# record tree at runtime, HttpClientPlatformEnvManifestTest fails when the two disagree in either
+# direction, and the platform refuses to start on an APP_HTTPCLIENT_ variable that is not here. 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.
+#
+# `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.
+#
+# 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 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.
+#
+# 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.
+#
+# 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.
+fields:
+  - field: enabled
+    env: APP_HTTPCLIENT_ENABLED
+  - field: clients[N].name
+    env: APP_HTTPCLIENT_CLIENTS_N_NAME
+  - field: clients[N].mode
+    env: APP_HTTPCLIENT_CLIENTS_N_MODE
+  - field: clients[N].base-url
+    env: APP_HTTPCLIENT_CLIENTS_N_BASE_URL
+  - field: clients[N].allowed-hosts[M]
+    env: APP_HTTPCLIENT_CLIENTS_N_ALLOWED_HOSTS_M
+  - field: clients[N].allowed-ports[M]
+    env: APP_HTTPCLIENT_CLIENTS_N_ALLOWED_PORTS_M
+  - field: clients[N].api
+    env: APP_HTTPCLIENT_CLIENTS_N_API
+  - field: clients[N].transport
+    env: APP_HTTPCLIENT_CLIENTS_N_TRANSPORT
+  - field: clients[N].protocols[M]
+    env: APP_HTTPCLIENT_CLIENTS_N_PROTOCOLS_M
+  - field: clients[N].pool.max-total-connections
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_TOTAL_CONNECTIONS
+  - field: clients[N].pool.max-connections-per-route
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_CONNECTIONS_PER_ROUTE
+  - field: clients[N].pool.max-pending-acquires
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_PENDING_ACQUIRES
+  - field: clients[N].pool.pending-acquire-timeout
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_PENDING_ACQUIRE_TIMEOUT
+  - field: clients[N].pool.max-idle-time
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_IDLE_TIME
+  - field: clients[N].pool.max-life-time
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_MAX_LIFE_TIME
+  - field: clients[N].pool.validate-after-inactivity
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_VALIDATE_AFTER_INACTIVITY
+  - field: clients[N].pool.eviction-interval
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_EVICTION_INTERVAL
+  - field: clients[N].pool.shutdown-timeout
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_SHUTDOWN_TIMEOUT
+  - field: clients[N].pool.requires-route-pool
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_REQUIRES_ROUTE_POOL
+  - field: clients[N].pool.requires-bounded-pending-queue
+    env: APP_HTTPCLIENT_CLIENTS_N_POOL_REQUIRES_BOUNDED_PENDING_QUEUE
+  - field: clients[N].timeout.dns
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_DNS
+  - field: clients[N].timeout.connect
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_CONNECT
+  - field: clients[N].timeout.tls-handshake
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_TLS_HANDSHAKE
+  - field: clients[N].timeout.proxy-connect
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_PROXY_CONNECT
+  - field: clients[N].timeout.request-write-idle
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_REQUEST_WRITE_IDLE
+  - field: clients[N].timeout.response-header
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_RESPONSE_HEADER
+  - field: clients[N].timeout.read-idle
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_READ_IDLE
+  - field: clients[N].timeout.total-call
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_TOTAL_CALL
+  - field: clients[N].timeout.streaming-idle
+    env: APP_HTTPCLIENT_CLIENTS_N_TIMEOUT_STREAMING_IDLE
+  - field: clients[N].redirect.enabled
+    env: APP_HTTPCLIENT_CLIENTS_N_REDIRECT_ENABLED
+  - field: clients[N].redirect.max-hops
+    env: APP_HTTPCLIENT_CLIENTS_N_REDIRECT_MAX_HOPS
+  - field: clients[N].redirect.allow-cross-origin
+    env: APP_HTTPCLIENT_CLIENTS_N_REDIRECT_ALLOW_CROSS_ORIGIN
+  - field: clients[N].request.max-body-bytes
+    env: APP_HTTPCLIENT_CLIENTS_N_REQUEST_MAX_BODY_BYTES
+  - field: clients[N].request.compression
+    env: APP_HTTPCLIENT_CLIENTS_N_REQUEST_COMPRESSION
+  - field: clients[N].response.max-wire-bytes
+    env: APP_HTTPCLIENT_CLIENTS_N_RESPONSE_MAX_WIRE_BYTES
+  - field: clients[N].response.max-decoded-bytes
+    env: APP_HTTPCLIENT_CLIENTS_N_RESPONSE_MAX_DECODED_BYTES
+  - field: clients[N].response.allowed-content-types[M]
+    env: APP_HTTPCLIENT_CLIENTS_N_RESPONSE_ALLOWED_CONTENT_TYPES_M
+  - field: clients[N].authentication.type
+    env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_TYPE
+  - field: clients[N].authentication.registration-id
+    env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_REGISTRATION_ID
+  - field: clients[N].authentication.scopes[M]
+    env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_SCOPES_M
+  - field: clients[N].authentication.audience
+    env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_AUDIENCE
+  - field: clients[N].authentication.header-name
+    env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_HEADER_NAME
+  - field: clients[N].authentication.secret-reference
+    env: APP_HTTPCLIENT_CLIENTS_N_AUTHENTICATION_SECRET_REFERENCE
+  - field: clients[N].retry.policy
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_POLICY
+  - field: clients[N].retry.max-attempts
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_MAX_ATTEMPTS
+  - field: clients[N].retry.base-backoff
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_BASE_BACKOFF
+  - field: clients[N].retry.max-backoff
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_MAX_BACKOFF
+  - field: clients[N].retry.jitter
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_JITTER
+  - field: clients[N].retry.retry-after
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_RETRY_AFTER
+  - field: clients[N].retry.budget
+    env: APP_HTTPCLIENT_CLIENTS_N_RETRY_BUDGET
+  - field: clients[N].observability.operation-name-required
+    env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_OPERATION_NAME_REQUIRED
+  - field: clients[N].observability.full-url-recording
+    env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_FULL_URL_RECORDING
+  - field: clients[N].observability.body-logging
+    env: APP_HTTPCLIENT_CLIENTS_N_OBSERVABILITY_BODY_LOGGING
+  - field: clients[N].tls.profile-id
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_PROFILE_ID
+  - field: clients[N].tls.protocols[M]
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_PROTOCOLS_M
+  - field: clients[N].tls.hostname-verification
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_HOSTNAME_VERIFICATION
+  - field: clients[N].tls.trust-all
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_TRUST_ALL
+  - field: clients[N].tls.allow-plain-http
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_ALLOW_PLAIN_HTTP
+  - field: clients[N].tls.trust-material-reference
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_TRUST_MATERIAL_REFERENCE
+  - field: clients[N].tls.key-material-reference
+    env: APP_HTTPCLIENT_CLIENTS_N_TLS_KEY_MATERIAL_REFERENCE
+  - field: clients[N].proxy.enabled
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_ENABLED
+  - field: clients[N].proxy.host
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_HOST
+  - field: clients[N].proxy.port
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_PORT
+  - field: clients[N].proxy.type
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_TYPE
+  - field: clients[N].proxy.credential-provider
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_CREDENTIAL_PROVIDER
+  - field: clients[N].proxy.connect-timeout
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_CONNECT_TIMEOUT
+  - field: clients[N].proxy.import-ambient-no-proxy
+    env: APP_HTTPCLIENT_CLIENTS_N_PROXY_IMPORT_AMBIENT_NO_PROXY
+  - field: clients[N].experimental-acknowledgement
+    env: APP_HTTPCLIENT_CLIENTS_N_EXPERIMENTAL_ACKNOWLEDGEMENT
+  - field: dynamic-targets[N].name
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_NAME
+  - field: dynamic-targets[N].allowed-schemes[M]
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_SCHEMES_M
+  - field: dynamic-targets[N].allowed-ports[M]
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_PORTS_M
+  - field: dynamic-targets[N].allowed-host-suffixes[M]
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_HOST_SUFFIXES_M
+  - field: dynamic-targets[N].allowed-hosts[M]
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_ALLOWED_HOSTS_M
+  - field: dynamic-targets[N].max-redirect-hops
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_MAX_REDIRECT_HOPS
+  - field: dynamic-targets[N].trace-propagation
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_TRACE_PROPAGATION
+  - field: dynamic-targets[N].blocked-cidrs[M]
+    env: APP_HTTPCLIENT_DYNAMIC_TARGETS_N_BLOCKED_CIDRS_M
@@ -0,0 +1,64 @@
+# Migrating from `RestTemplate`
+
+`RestTemplate` is permitted only inside `…httpclient.migration`; `RestTemplateBoundaryTest` enforces
+that. New retry, Dynamic Target, and HTTP/3 capabilities are deliberately unreachable from the
+migration path — a caller that wants them moves to a Named Client Profile.
+
+## 1. Audit before changing anything
+
+```java
+RestTemplateInventory inventory = new RestTemplateInventoryScanner().scan(existingTemplate);
+```
+
+The inventory reports the request factory, message converters, interceptors, error handler, and URI
+template handler, plus findings:
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `SIMPLE_REQUEST_FACTORY` | blocking | no connection pool; unsupported in production |
+| `NO_MESSAGE_CONVERTERS` | blocking | the template cannot encode or decode a body |
+| `NO_INTERCEPTORS` | warning | confirm where correlation and timeouts are applied |
+| `TIMEOUTS_NOT_INTROSPECTABLE` | informational | declare timeouts explicitly on the target profile |
+
+## 2. Bridge without changing behaviour
+
+```java
+RestClient client = new RestTemplateToRestClientAdapter().adaptChecked(existingTemplate);
+```
+
+`adaptChecked` refuses to migrate a template with a blocking finding. The bridge carries the
+existing converters, interceptors, error handler, and URI handler across, so this step changes the
+API and nothing else.
+
+## 3. Move to a Named Client Profile
+
+Turn the platform on with `APP_HTTPCLIENT_ENABLED=true` — it ships off, and while it is off none of
+the settings below are bound — then declare the upstream as `app.httpclient.clients[N]` with its
+`name` and an explicit base URL, transport, timeouts, pool, body limits, authentication, retry
+policy, redirect policy, and TLS profile. Startup validation will tell you exactly which of those is
+missing. See `docs/httpclient/configuration-reference.md` for the environment form.
+
+## 4. Move to a typed client
+
+```java
+@HttpClientProfile("payment")
+@HttpExchange("/payments")
+public interface PaymentClient {
+
+  @PostExchange
+  @HttpOperationPolicy(
+      name = "create-payment",
+      idempotency = OperationIdempotency.IDEMPOTENCY_KEY_REQUIRED,
+      retryPolicy = "payment-write")
+  PaymentResponse create(
+      @RequestHeader("Idempotency-Key") String idempotencyKey, @RequestBody PaymentRequest request);
+}
+```
+
+The interface fails startup validation unless it declares a profile, gives every method a stable
+operation name and an explicit idempotency, supplies a key parameter when the operation requires
+one, keeps a single execution model, and does not enable retry on a non-idempotent write.
+
+## 5. Retire the template
+
+Once no production package references `RestTemplate`, `RestTemplateBoundaryTest` keeps it that way.
@@ -0,0 +1,87 @@
+# HTTP Client Platform — Repository Adaptation Contract
+
+**Design source:** `httpclient-superpowers-package/docs/superpowers/specs/2026-08-08-httpclient-platform-design.md`
+**Plan source:** `httpclient-superpowers-package/docs/superpowers/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.
+
+## 1. Why the module layout differs
+
+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`.
+
+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:
+
+| Design module | Repository home | Reason |
+|---|---|---|
+| `httpclient-spring-boot-starter` | `:app-bootstrap` (`dev.caskeleton.bootstrap.autoconfigure.httpclient`) | This repository's composition root owns wiring and canonical activation; an adapter leaf must not auto-configure itself. |
+| `httpclient-testkit` | `:adapter:outbound:httpclient` `src/test/java/**/testkit` | The design forbids production modules depending on the testkit; a test source set gives the same guarantee without a new Gradle project. |
+
+The package boundary is enforced by ArchUnit rules (`PublicApiArchitectureTest`,
+`HttpClientModuleBoundaryTest`) that reproduce the design's module dependency table.
+
+## 2. Package mapping
+
+Root package: `io.backend.skeleton.httpclient` → `dev.caskeleton.adapter.outbound.httpclient`.
+
+| Design module | Design package | Repository package |
+|---|---|---|
+| `httpclient-core-api` | `…httpclient.api` (+ `.body`, `.error`, `.operation`, `.result`) | `dev.caskeleton.adapter.outbound.httpclient.api` (+ same subpackages) |
+| `httpclient-profile` | `…httpclient.profile` | `…outbound.httpclient.profile` |
+| `httpclient-transport-spi` | `…httpclient.transport` | `…outbound.httpclient.transport` |
+| `httpclient-transport-apache` | `…httpclient.apache` | `…outbound.httpclient.apache` |
+| `httpclient-transport-jdk` | `…httpclient.jdk` | `…outbound.httpclient.jdk` |
+| `httpclient-restclient` | `…httpclient.restclient` | `…outbound.httpclient.restclient` |
+| `httpclient-resilience` | `…httpclient.resilience` | `…outbound.httpclient.resilience` |
+| `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` | `…outbound.httpclient.reactor` |
+| `httpclient-webclient` | `…httpclient.webclient` | `…outbound.httpclient.webclient` |
+| `httpclient-service-client` | `…httpclient.service` | `…outbound.httpclient.service` |
+| `httpclient-dynamic-target` | `…httpclient.dynamic` | `…outbound.httpclient.dynamic` |
+| `httpclient-resttemplate-migration` | `…httpclient.migration` | `…outbound.httpclient.migration` |
+| `httpclient-spring7-service-groups` | `…httpclient.spring7` | `…outbound.httpclient.spring7` |
+| `httpclient-jetty-http3-experimental` | `…httpclient.http3` | `…outbound.httpclient.http3` |
+| `httpclient-spring-boot-starter` | `…httpclient.autoconfigure` | `dev.caskeleton.bootstrap.autoconfigure.httpclient` |
+| `httpclient-testkit` | `…httpclient.testkit` | `…outbound.httpclient.testkit` (test source set) |
+
+## 3. Other deliberate substitutions
+
+| 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.0 / 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 stays isolated in `…httpclient.spring7`, exactly as the design requires. |
+| `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. |
+
+## 4. What is unchanged from the design
+
+- H1 / H2 / H3 / H4 exposure rules and the forbidden native-engine signatures.
+- `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.