runtime: bound pg-erd slow-drip response bodies

API_CONFIG_CONTRACT.md

@@ -1,6 +1,6 @@
-# Version 1 Configuration Contracts
+# Versioned Configuration Contracts
 
-## Generic `cwl-pingora-gateway`
+## Generic `cwl-pingora-gateway` version 1
 
 ```yaml
 version: 1
@@ -25,7 +25,7 @@ upstreams:
 
 Unknown fields are rejected. `version` must be `1`. `listener`, `metrics_listener`, and `address` are socket addresses with non-zero ports. Port zero is rejected because production authority must remain operator-declared rather than OS-selected or unusable. Traffic and metrics listeners must not overlap one effective socket authority: equal sockets, same-port same-family wildcard/concrete aliases, exact native/IPv4-mapped aliases, native or mapped IPv4 wildcard aliases, and the platform-dependent same-port IPv6-wildcard/IPv4 combination fail closed. Distinct concrete non-aliased addresses may share a non-zero port. `max_request_body_bytes`, `max_in_flight_requests`, and `upstream_keepalive_pool_size` must all be positive. Generic v1 requires exactly one upstream and a non-empty stable upstream name. Every timeout must be positive.
 
-The timeout fields map directly to the pinned Pingora peer options rather than defining a second gateway timer model. In particular, `read_ms` is a **per-read inactivity budget**: Pingora waits at most that long for each individual upstream `read()` and resets the timer after a successful read. It is not a total-response deadline. A connected upstream that sends no response bytes is therefore bounded by `read_ms`, while a slow-drip response can remain alive across multiple successful reads. Whole-response lifetime remains an explicit open runtime-isolation requirement and must not be inferred from `read_ms`.
+The timeout fields map directly to the pinned Pingora peer options rather than defining a second gateway timer model. In particular, `read_ms` is a **per-read inactivity budget**: Pingora waits at most that long for each individual upstream `read()` and resets the timer after a successful read. It is not a total-response deadline. A connected upstream that sends no response bytes is therefore bounded by `read_ms`, while a slow-drip response can remain alive across multiple successful reads. Generic v1 has no whole-response lifetime and must not infer one from `read_ms`.
 
 `max_in_flight_requests` is a process-local backpressure boundary for non-health downstream requests. When the budget is exhausted, the runtime fails fast with HTTP 503 instead of admitting unbounded work. `/livez` and `/readyz` bypass this application admission budget so saturation does not hide process health. The admission lease is released when the request context ends, including failed requests. `upstream_keepalive_pool_size` is wired directly into Pingora's `ServerConf`; the runtime does not inherit Pingora's framework default of 128 reusable upstream connections.
 
@@ -37,14 +37,15 @@ Generic v1 downstream transport is cleartext TCP. Before proxying, the generic a
 
 ## Bounded `cwl-pingora-pg-erd-migration` candidate
 
-The dedicated pg-erd migration binary consumes a different, migration-specific Admin Config profile. It deliberately reuses the same top-level deployment value names while admitting exactly two fixed transport authorities:
+The dedicated pg-erd migration binary consumes a different, migration-specific Admin Config profile. Version 1 preserves the existing unreleased characterization semantics and rejects `max_upstream_response_body_ms`. Version 2 is the explicit response-lifetime increment and requires a positive `max_upstream_response_body_ms`; the runtime never injects a hidden default.
 
 ```yaml
-version: 1
+version: 2
 listener: 0.0.0.0:6188
 metrics_listener: 127.0.0.1:6192
 max_request_body_bytes: 1048576
 max_in_flight_requests: 128
+max_upstream_response_body_ms: 30000
 upstream_keepalive_pool_size: 32
 upstreams:
   - name: backend
@@ -67,6 +68,12 @@ upstreams:
       idle_ms: 10000
 ```
 
+The numeric response-lifetime value above is illustrative configuration, not a production SLO. A deployment owner must choose the version-2 value from its observed long-response contract before canary or cutover.
+
+`max_upstream_response_body_ms` starts at the first non-informational upstream response header. Runtime Isolation compares elapsed monotonic time only when a non-empty upstream body chunk is observed. Progress at or beyond the configured lifetime raises an upstream-scoped fatal error; empty/end-of-stream bookkeeping callbacks do not manufacture a timeout. If the final response has already been written, `fail_to_proxy` observes Pingora's `Session::response_written()` commitment state and emits no second status. Pre-commit upstream failures retain the existing policy-complete local error response behavior. No route failover is introduced by this contract.
+
+This callback guard is not an exact timer interrupt. `read_ms` remains a per-read inactivity budget that resets after a successful read. A continuously progressing body is stopped at the first non-empty body callback at or beyond `max_upstream_response_body_ms`; a response that becomes quiescent is bounded by `read_ms`. The current callback surface does not wake a pending read exactly at the body-lifetime instant, and slow delivery of an incomplete response header remains a separate transport gap.
+
 This is not a generic multi-route configuration language. Operator input can bind only concrete transport/TLS values for the compiled `backend` and `frontend` identities. Missing, extra, duplicate, renamed, port-zero, or otherwise invalid listener/metrics/upstream transport authorities fail closed before listener activation. Listener and metrics sockets consume the same effective-authority invariant as generic v1, while the migration profile keeps its specific zero-transport-authority error contract. Routes and edge-owned response fields are not configurable: the characterized profile fixes exact `/healthz -> backend`, raw `PathPrefix(`/api`) -> backend` semantics including `/apiary`, fallback `/ -> frontend`, and the four captured response fields `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, and `Permissions-Policy: geolocation=(), microphone=(), camera=()`.
 
 Admin parsing validates only deterministic configuration and authority invariants. It does not read custom trust-bundle bytes. If an admitted TLS upstream supplies `trust_bundle_file`, the canonical Pingora peer adapter reads and parses that material exactly once during `build_proxy`, still before listeners are registered. An unreadable or invalid bundle therefore blocks activation without a validate-then-reload trust-file window.