Skip to main content

rws_proxy/proxy/
mod.rs

1//! Reverse proxy middleware with round-robin load balancing.
2//!
3//! `ReverseProxy` implements [`Middleware`] — wrap any application with it and
4//! all matching requests are forwarded to one of the configured backends over
5//! plain HTTP/1.1.  Failed backends are skipped and the next one is tried
6//! before returning `502 Bad Gateway`.
7//!
8//! # Example
9//!
10//! ```rust,no_run
11//! # extern crate rws_proxy as rust_web_server;
12//! use rust_web_server::app::App;
13//! use rust_web_server::core::New;
14//! use rust_web_server::proxy::{LoadBalancing, ReverseProxy};
15//!
16//! // Proxy every request across two backends in round-robin order.
17//! let app = App::new()
18//!     .wrap(ReverseProxy::new(["http://backend-1:8080", "http://backend-2:8080"])
19//!         .strategy(LoadBalancing::RoundRobin));
20//!
21//! // Only proxy /api/* requests; everything else is handled locally.
22//! let app2 = App::new()
23//!     .wrap(ReverseProxy::new(["http://api-service:3000"])
24//!         .path_prefix("/api"));
25//! ```
26
27pub mod pool;
28pub mod status;
29#[cfg(feature = "http2")]
30#[doc(hidden)]
31pub mod async_upstream;
32#[cfg(not(target_arch = "wasm32"))]
33pub mod mirror;
34/// Upgraded connections (WebSocket) relayed to a backend (moved from the
35/// Gateway API controller in 18.21.0; config proxy routes use it too).
36#[cfg(not(target_arch = "wasm32"))]
37#[doc(hidden)]
38pub mod upgrade;
39#[cfg(feature = "http2")]
40#[doc(hidden)]
41pub mod h2_upstream;
42#[cfg(feature = "http3")]
43#[doc(hidden)]
44pub mod h3_upstream;
45#[cfg(feature = "http2")]
46pub mod grpc_web;
47#[cfg(feature = "http2")]
48pub use grpc_web::GrpcWebLayer;
49
50#[cfg(test)]
51mod tests;
52
53use std::io::{Read, Write};
54use crate::ext::decimal::Decimal;
55use std::net::{TcpStream, ToSocketAddrs};
56use std::sync::atomic::{AtomicUsize, Ordering};
57use std::sync::Arc;
58use std::time::Duration;
59
60pub use pool::{ConnPool, Pool};
61
62use crate::application::Application;
63use crate::middleware::Middleware;
64use crate::request::Request;
65use crate::response::{Response, STATUS_CODE_REASON_PHRASE};
66use crate::server::ConnectionInfo;
67
68// Hop-by-hop headers that must not be forwarded (RFC 9110 §7.6.1), plus
69// `proxy-connection` (legacy clients). Headers named in `Connection` are
70// dropped too (`connection_listed`).
71const HOP_BY_HOP: &[&str] = &[
72    "connection",
73    "keep-alive",
74    "proxy-authenticate",
75    "proxy-authorization",
76    "proxy-connection",
77    "te",
78    "trailer",
79    "transfer-encoding",
80    "upgrade",
81];
82
83/// Load balancing strategy used by [`ReverseProxy`].
84pub enum LoadBalancing {
85    /// Distribute requests across backends in a cyclic order.
86    RoundRobin,
87}
88
89/// Reverse proxy middleware.
90///
91/// Forwards incoming requests to one of the configured backends over HTTP/1.1.
92/// On connection failure the next backend in the list is tried; when all
93/// backends have failed the middleware returns `502 Bad Gateway`.
94///
95/// Hop-by-hop headers are stripped before forwarding.  `X-Forwarded-For` and
96/// `Via` are added to every forwarded request.
97///
98/// Idle connections are pooled and reused across requests (up to
99/// 64 idle per backend, 60-second timeout).
100/// This eliminates per-request TCP handshake overhead and ephemeral-port
101/// exhaustion.  Use [`ReverseProxy::with_pool`] to share a pool across
102/// multiple proxy instances or to tune pool parameters.
103pub struct ReverseProxy {
104    backends: Vec<Backend>,
105    path_prefix: Option<String>,
106    connect_timeout: Duration,
107    read_timeout: Duration,
108    counter: AtomicUsize,
109    pool: Arc<ConnPool>,
110    breaker: Option<Arc<dyn crate::circuit_breaker::Breaker>>,
111    trust: Option<Arc<UpstreamTls>>,
112    /// What `trust` was built from, so each TLS option adds to the others.
113    tls_ca: Option<String>,
114    tls_client: Option<(String, String)>,
115}
116
117impl ReverseProxy {
118    /// Create a proxy that distributes requests across `backends` in
119    /// round-robin order.  Each entry must be `"http://host:port"` or
120    /// `"host:port"` (port defaults to 80).
121    pub fn new<I, S>(backends: I) -> Self
122    where
123        I: IntoIterator<Item = S>,
124        S: AsRef<str>,
125    {
126        Self {
127            backends: backends
128                .into_iter()
129                .filter_map(|u| Backend::parse(u.as_ref()))
130                .collect(),
131            path_prefix: None,
132            connect_timeout: Duration::from_secs(5),
133            read_timeout: Duration::from_secs(30),
134            counter: AtomicUsize::new(0),
135            pool: Arc::new(ConnPool::new(POOL_MAX_IDLE, pool::IDLE_TIMEOUT)),
136            breaker: None,
137            trust: None,
138            tls_ca: None,
139            tls_client: None,
140        }
141    }
142
143    /// Wire a [`crate::circuit_breaker::CircuitBreaker`] or
144    /// [`crate::circuit_breaker::RedisCircuitBreaker`] into this proxy:
145    /// before dialing a backend, its breaker state is checked (an `Open`
146    /// backend is skipped with no TCP attempt, exactly like a caller
147    /// manually checking `is_available` around each proxied call); after a
148    /// dial, `record_success`/`record_failure` is called automatically.
149    /// No breaker is wired by default — existing `ReverseProxy` callers see
150    /// no behavior change unless they opt in here.
151    ///
152    /// ```rust,no_run
153    /// # extern crate rws_proxy as rust_web_server;
154    /// use std::sync::Arc;
155    /// use rust_web_server::circuit_breaker::global as global_breaker;
156    /// use rust_web_server::proxy::ReverseProxy;
157    ///
158    /// let proxy = ReverseProxy::new(["http://backend-1:8080", "http://backend-2:8080"])
159    ///     .with_circuit_breaker(Arc::new(global_breaker()));
160    /// ```
161    pub fn with_circuit_breaker(mut self, breaker: Arc<dyn crate::circuit_breaker::Breaker>) -> Self {
162        self.breaker = Some(breaker);
163        self
164    }
165
166    /// Only proxy requests whose URI starts with `prefix`.
167    ///
168    /// Other requests are passed through to the next layer in the middleware
169    /// chain (or the inner application).
170    pub fn path_prefix(mut self, prefix: impl Into<String>) -> Self {
171        self.path_prefix = Some(prefix.into());
172        self
173    }
174
175    /// Override the load balancing strategy (currently only `RoundRobin`).
176    pub fn strategy(self, _strategy: LoadBalancing) -> Self {
177        self
178    }
179
180    /// Override the TCP connect timeout (default: 5 000 ms).
181    pub fn connect_timeout_ms(mut self, ms: u64) -> Self {
182        self.connect_timeout = Duration::from_millis(ms);
183        self
184    }
185
186    /// Override the response read timeout (default: 30 000 ms).
187    pub fn read_timeout_ms(mut self, ms: u64) -> Self {
188        self.read_timeout = Duration::from_millis(ms);
189        self
190    }
191
192    /// Attach a shared connection pool.
193    ///
194    /// Useful for sharing one pool across multiple `ReverseProxy` instances
195    /// or for tuning pool parameters (capacity, idle timeout).
196    pub fn with_pool(mut self, pool: Arc<ConnPool>) -> Self {
197        self.pool = pool;
198        self
199    }
200
201    /// Trust the CA certificates in the PEM file `path` for `https://`
202    /// backends, **instead of** the public WebPKI roots — for internal
203    /// services behind a private CA or a self-signed certificate.
204    pub fn tls_ca_file(mut self, path: &str) -> Result<Self, String> {
205        self.tls_ca = Some(path.to_string());
206        self.rebuild_trust()?;
207        Ok(self)
208    }
209
210    /// Present the client certificate in the PEM file `cert` (with its
211    /// private key in `key`) to `https://` backends that require one —
212    /// mutual TLS to the upstream. Since 18.3.0.
213    pub fn tls_client_cert(mut self, cert: &str, key: &str) -> Result<Self, String> {
214        self.tls_client = Some((cert.to_string(), key.to_string()));
215        self.rebuild_trust()?;
216        Ok(self)
217    }
218
219    fn rebuild_trust(&mut self) -> Result<(), String> {
220        let client = self.tls_client.as_ref().map(|(c, k)| (c.as_str(), k.as_str()));
221        self.trust = Some(Arc::new(UpstreamTls::new(self.tls_ca.as_deref(), client)?));
222        Ok(())
223    }
224
225    /// Set the maximum number of idle connections per backend (default: 64).
226    pub fn max_idle_conns(mut self, n: usize) -> Self {
227        self.pool = Arc::new(ConnPool::new(n, pool::IDLE_TIMEOUT));
228        self
229    }
230
231    fn proxy(&self, request: &Request, connection: &ConnectionInfo) -> Result<Response, String> {
232        if self.backends.is_empty() {
233            return Err("no backends configured".to_string());
234        }
235        let n = self.backends.len();
236        let start = self.counter.fetch_add(1, Ordering::Relaxed);
237        let mut last_err = "all backends failed".to_string();
238        for attempt in 0..n {
239            let idx = (start + attempt) % n;
240            let backend = &self.backends[idx];
241            let key = format!("{}:{}", backend.host, backend.port);
242
243            if let Some(breaker) = &self.breaker {
244                if !breaker.is_available(&key) {
245                    last_err = format!("circuit open for {}", key);
246                    continue;
247                }
248            }
249
250            match self.try_backend(request, connection, backend) {
251                Ok(resp) => {
252                    if let Some(breaker) = &self.breaker {
253                        breaker.record_success(&key);
254                    }
255                    return Ok(resp);
256                }
257                Err(e) => {
258                    if let Some(breaker) = &self.breaker {
259                        breaker.record_failure(&key);
260                    }
261                    last_err = e;
262                }
263            }
264        }
265        Err(last_err)
266    }
267
268    fn try_backend(
269        &self,
270        request: &Request,
271        connection: &ConnectionInfo,
272        backend: &Backend,
273    ) -> Result<Response, String> {
274        forward_upstream_trusting(
275            &self.pool,
276            request,
277            crate::proxy::Peer::of(connection),
278            &backend.host,
279            backend.port,
280            backend.tls,
281            self.trust.as_deref(),
282            self.connect_timeout,
283            self.read_timeout,
284        )
285    }
286}
287
288impl Middleware for ReverseProxy {
289    fn handle(
290        &self,
291        request: &Request,
292        connection: &ConnectionInfo,
293        next: &dyn Application,
294    ) -> Result<Response, String> {
295        if let Some(prefix) = &self.path_prefix {
296            if !request.request_uri.starts_with(prefix.as_str()) {
297                return next.execute(request, connection);
298            }
299        }
300        match self.proxy(request, connection) {
301            Ok(mut resp) => {
302                status::received(&mut resp, None);
303                Ok(resp)
304            }
305            Err(e) => {
306                let mut resp = bad_gateway_for(request);
307                status::failed_with(&mut resp, &e, None);
308                Ok(resp)
309            }
310        }
311    }
312}
313
314// ── helpers ───────────────────────────────────────────────────────────────────
315
316/// The client as the forwarders need it: its address for `X-Forwarded-For`
317/// and whether it connected over TLS, for `X-Forwarded-Proto`.
318#[derive(Clone, Copy, Debug)]
319#[doc(hidden)]
320pub struct Peer<'a> {
321    pub ip: &'a str,
322    pub tls: bool,
323}
324
325impl<'a> Peer<'a> {
326    #[doc(hidden)]
327    pub fn of(connection: &'a ConnectionInfo) -> Self {
328        Peer { ip: &connection.client.ip, tls: connection.tls }
329    }
330
331    /// A plain-HTTP client at `ip` (tests and callers without a connection).
332    #[doc(hidden)]
333    pub fn plain(ip: &'a str) -> Self {
334        Peer { ip, tls: false }
335    }
336
337    #[doc(hidden)]
338    pub fn proto(&self) -> &'static str {
339        if self.tls { "https" } else { "http" }
340    }
341}
342
343/// The headers a client sets to describe earlier hops.
344const FORWARDING_HEADERS: [&str; 4] = ["x-forwarded-for", "x-forwarded-proto", "x-forwarded-host", "forwarded"];
345
346/// `request` as the proxy may pass it on: from a peer outside
347/// `trusted_proxies` its `X-Forwarded-For/Proto/Host` and `Forwarded` are
348/// dropped (rws sets its own), so a client can't claim `https` or another
349/// host (18.24.0). Borrowed when nothing needs dropping.
350#[doc(hidden)]
351pub fn from_peer<'a>(request: &'a Request, client: Peer<'_>) -> std::borrow::Cow<'a, Request> {
352    let has = request.headers.iter().any(|h| FORWARDING_HEADERS.iter().any(|n| h.name.eq_ignore_ascii_case(n)));
353    if !has || crate::server_config::ServerConfig::current().trusted_proxies.trusts(client.ip) {
354        return std::borrow::Cow::Borrowed(request);
355    }
356    let mut owned = request.clone();
357    owned.headers.retain(|h| !FORWARDING_HEADERS.iter().any(|n| h.name.eq_ignore_ascii_case(n)));
358    std::borrow::Cow::Owned(owned)
359}
360
361/// The `Forwarded` value for this hop (RFC 7239, 18.20.0): the request's
362/// own `Forwarded` (from proxies before this one) extended with
363/// `for=<client>;proto=<http|https>;host=<Host>`; `None` when
364/// `forwarded_header = "off"`.
365#[doc(hidden)]
366pub fn forwarded_value(request: &Request, client: Peer<'_>) -> Option<String> {
367    if !crate::server_config::ServerConfig::current().forwarded_header {
368        return None;
369    }
370    let mut element = format!("for={};proto={}", forwarded_node(client.ip), client.proto());
371    if let Some(host) = request.header(crate::header::Header::_HOST).map(|h| h.value.as_ref()) {
372        push_forwarded_host(&mut element, host);
373    }
374    let prior = request.headers.iter().filter(|h| h.name.eq_ignore_ascii_case("forwarded")).map(|h| h.value.trim()).filter(|v| !v.is_empty() && !v.bytes().any(|b| b < 0x20)).collect::<Vec<_>>();
375    if prior.is_empty() {
376        // A trusted proxy that sent only X-Forwarded-* (most do): its hops
377        // become Forwarded elements first, the client's with the proto and
378        // host it reported (RFC 7239 §7.4, since 18.27.0), so the chain says
379        // proto=https like X-Forwarded-Proto instead of just this hop's http.
380        if let Some(earlier) = forwarded_from_x_forwarded(request, client) {
381            return Some(format!("{earlier}, {element}"));
382        }
383    }
384    Some(if prior.is_empty() { element } else { format!("{}, {element}", prior.join(", ")) })
385}
386
387/// An RFC 7239 node for an address: IPv4 bare, IPv6 quoted in brackets,
388/// `unknown` for anything else.
389fn forwarded_node(ip: &str) -> String {
390    let ip = ip.trim();
391    let parsed = ip.parse::<std::net::IpAddr>().ok().or_else(|| ip.parse::<std::net::SocketAddr>().ok().map(|a| a.ip()));
392    match parsed {
393        Some(std::net::IpAddr::V4(v4)) => v4.to_string(),
394        Some(std::net::IpAddr::V6(v6)) => match v6.to_ipv4_mapped() {
395            Some(v4) => v4.to_string(),
396            None => format!("\"[{v6}]\""),
397        },
398        None => "unknown".to_string(),
399    }
400}
401
402fn push_forwarded_host(element: &mut String, host: &str) {
403    if host.is_empty() || !host.bytes().all(|b| b.is_ascii_graphic() && b != b'"' && b != b'\\') {
404        return;
405    }
406    if host.bytes().all(|b| b.is_ascii_alphanumeric() || b"!#$%&'*+-.^_`|~".contains(&b)) {
407        element.push_str(&format!(";host={host}"));
408    } else {
409        element.push_str(&format!(";host=\"{host}\""));
410    }
411}
412
413/// `X-Forwarded-For` hops from a trusted peer as `Forwarded` elements, the
414/// first with `X-Forwarded-Proto` and `-Host`; `None` without one.
415fn forwarded_from_x_forwarded(request: &Request, client: Peer<'_>) -> Option<String> {
416    if !crate::server_config::ServerConfig::current().trusted_proxies.trusts(client.ip) {
417        return None;
418    }
419    let hops: Vec<&str> = request.headers.iter()
420        .filter(|h| h.name.eq_ignore_ascii_case("x-forwarded-for"))
421        .flat_map(|h| h.value.split(','))
422        .map(str::trim)
423        .filter(|h| !h.is_empty())
424        .collect();
425    if hops.is_empty() {
426        return None;
427    }
428    let mut elements = Vec::with_capacity(hops.len());
429    for (i, hop) in hops.iter().enumerate() {
430        let mut element = format!("for={}", forwarded_node(hop));
431        if i == 0 {
432            if let Some(proto) = request.header("X-Forwarded-Proto").map(|h| h.value.trim().to_ascii_lowercase()).filter(|p| p == "http" || p == "https") {
433                element.push_str(&format!(";proto={proto}"));
434            }
435            if let Some(host) = request.header("X-Forwarded-Host").map(|h| h.value.trim().to_string()) {
436                push_forwarded_host(&mut element, &host);
437            }
438        }
439        elements.push(element);
440    }
441    Some(elements.join(", "))
442}
443
444#[doc(hidden)]
445pub fn build_request(
446    request: &Request,
447    backend_host: &str,
448    client: Peer<'_>,
449    keep_alive: bool,
450) -> Vec<u8> {
451    let request = &*from_peer(request, client);
452    // One buffer, sized up front and filled with extend_from_slice — no
453    // write!/format machinery, no lower-cased copy of each header name.
454    // `Content-Length` is regenerated from the (possibly de-chunked) body and
455    // `X-Forwarded-For` is extended below, so the client's copies are dropped:
456    // two `Content-Length` lines are a protocol error and a desync risk.
457    let connection = request.header(crate::header::Header::_CONNECTION).map(|h| h.value.as_ref());
458    // Inside a traced request the current span's `traceparent` (and the
459    // request's `baggage`) replace the client's.
460    #[cfg(not(target_arch = "wasm32"))]
461    let trace = crate::otel::propagation_headers();
462    #[cfg(target_arch = "wasm32")]
463    let trace: Option<(String, Option<String>)> = None;
464    let forwarded_header = forwarded_value(request, client);
465    let forwarded = |h: &&crate::header::Header| {
466        // An empty name would be sent as a malformed ": value" line.
467        !h.name.is_empty()
468            && !is_hop_by_hop_or_host(&h.name)
469            && !h.name.eq_ignore_ascii_case(crate::header::Header::_CONTENT_LENGTH)
470            && !h.name.eq_ignore_ascii_case("X-Forwarded-For")
471            && !(forwarded_header.is_some() && h.name.eq_ignore_ascii_case("Forwarded"))
472            && !connection.is_some_and(|c| connection_listed(c, &h.name))
473            && !(trace.is_some() && (h.name.eq_ignore_ascii_case("traceparent") || h.name.eq_ignore_ascii_case("baggage")))
474    };
475    let prior_xff = request.header("X-Forwarded-For").map(|h| h.value.as_ref()).filter(|v| !v.trim().is_empty());
476    // The Host the client asked for, unless an outer proxy already said
477    // (its X-Forwarded-Host passes through like any header).
478    // http or https, as the client connected, unless an outer proxy said.
479    let forwarded_proto = request.header("X-Forwarded-Proto").is_none().then(|| client.proto());
480    let forwarded_host = match request.header("X-Forwarded-Host") {
481        Some(_) => None,
482        None => request.header(crate::header::Header::_HOST).map(|h| h.value.as_ref()).filter(|v| !v.is_empty()),
483    };
484    let body_len = Decimal::new(request.body.len() as u128);
485    let capacity = request.method.len() + request.request_uri.len() + backend_host.len() + 25
486        + request.headers.iter().filter(forwarded).map(|h| h.name.len() + h.value.len() + 4).sum::<usize>()
487        + client.ip.len() + 19 + prior_xff.map_or(0, |v| v.len() + 2)
488        + forwarded_host.map_or(0, |v| v.len() + 20)
489        + forwarded_proto.map_or(0, |v| v.len() + 21)
490        + forwarded_header.as_ref().map_or(0, |v| v.len() + 13)
491        + trace.as_ref().map_or(0, |(t, b)| t.len() + 15 + b.as_ref().map_or(0, |b| b.len() + 11))
492        + 13
493        + 24
494        + if request.body.is_empty() { 0 } else { body_len.as_str().len() + 18 }
495        + 2
496        + request.body.len();
497    let mut out: Vec<u8> = Vec::with_capacity(capacity);
498    for part in [request.method.as_str(), " ", request.request_uri.as_str(), " HTTP/1.1\r\nHost: ", backend_host, "\r\n"] {
499        out.extend_from_slice(part.as_bytes());
500    }
501    for h in request.headers.iter().filter(forwarded) {
502        for part in [h.name.as_ref(), ": ", h.value.as_ref(), "\r\n"] {
503            out.extend_from_slice(part.as_bytes());
504        }
505    }
506    out.extend_from_slice(b"X-Forwarded-For: ");
507    if let Some(prior) = prior_xff {
508        out.extend_from_slice(prior.as_bytes());
509        out.extend_from_slice(b", ");
510    }
511    for part in [client.ip, "\r\n", "Via: 1.1 rws\r\n"] {
512        out.extend_from_slice(part.as_bytes());
513    }
514    if let Some(host) = forwarded_host {
515        for part in ["X-Forwarded-Host: ", host, "\r\n"] {
516            out.extend_from_slice(part.as_bytes());
517        }
518    }
519    if let Some(proto) = forwarded_proto {
520        for part in ["X-Forwarded-Proto: ", proto, "\r\n"] {
521            out.extend_from_slice(part.as_bytes());
522        }
523    }
524    if let Some(value) = &forwarded_header {
525        for part in ["Forwarded: ", value.as_str(), "\r\n"] {
526            out.extend_from_slice(part.as_bytes());
527        }
528    }
529    if let Some((traceparent, baggage)) = &trace {
530        for part in ["traceparent: ", traceparent, "\r\n"] {
531            out.extend_from_slice(part.as_bytes());
532        }
533        if let Some(baggage) = baggage {
534            for part in ["baggage: ", baggage, "\r\n"] {
535                out.extend_from_slice(part.as_bytes());
536            }
537        }
538    }
539    if keep_alive {
540        out.extend_from_slice(b"Connection: keep-alive\r\n");
541    } else {
542        out.extend_from_slice(b"Connection: close\r\n");
543    }
544    if !request.body.is_empty() {
545        out.extend_from_slice(b"Content-Length: ");
546        out.extend_from_slice(body_len.as_str().as_bytes());
547        out.extend_from_slice(b"\r\n");
548    }
549    out.extend_from_slice(b"\r\n");
550    out.extend_from_slice(&request.body);
551    out
552}
553
554/// Whether a request header is dropped on the way upstream: hop-by-hop
555/// headers and `Host` (rws sends its own). Matches `to_lowercase()` against
556/// the lower-case list — Unicode lower-casing, so a non-ASCII name (where
557/// e.g. the Kelvin sign lower-cases to `k`) still takes that path.
558fn is_hop_by_hop_or_host(name: &str) -> bool {
559    if name.is_ascii() {
560        name.eq_ignore_ascii_case("host") || HOP_BY_HOP.iter().any(|h| name.eq_ignore_ascii_case(h))
561    } else {
562        let lower = name.to_lowercase();
563        lower == "host" || HOP_BY_HOP.contains(&lower.as_str())
564    }
565}
566
567/// Whether `name` is one of the comma-separated tokens of a `Connection`
568/// header value — those headers are hop-by-hop for this connection only.
569fn connection_listed(connection: &str, name: &str) -> bool {
570    connection.split(',').any(|token| token.trim().eq_ignore_ascii_case(name))
571}
572
573/// Decode HTTP/1.1 chunked transfer-encoding from `stream`.
574///
575/// `buf[header_end..]` may already contain some body bytes that arrived in
576/// the same read as the headers.  Returns the fully decoded body.
577fn decode_chunked<S: Read>(
578    stream: &mut S,
579    buf: &[u8],
580    header_end: usize,
581    tmp: &mut [u8],
582) -> Result<Vec<u8>, String> {
583    // Seed `raw` with any body bytes already buffered alongside the headers.
584    let mut raw: Vec<u8> = buf[header_end..].to_vec();
585    let mut decoded: Vec<u8> = Vec::new();
586
587    loop {
588        // Wait until we have at least one complete chunk-size line (ends with \r\n).
589        let crlf = loop {
590            if let Some(p) = raw.windows(2).position(|w| w == b"\r\n") {
591                break p;
592            }
593            let n = stream.read(tmp).map_err(|e| e.to_string())?;
594            if n == 0 {
595                return Err("chunked: premature EOF reading chunk size".to_string());
596            }
597            raw.extend_from_slice(&tmp[..n]);
598        };
599
600        // Chunk size is hex, optionally followed by chunk-extensions (";…").
601        let size_line = std::str::from_utf8(&raw[..crlf])
602            .map_err(|_| "chunked: non-UTF-8 chunk size line".to_string())?;
603        let size_str = size_line.split(';').next().unwrap_or("").trim();
604        let chunk_size = usize::from_str_radix(size_str, 16)
605            .map_err(|_| format!("chunked: invalid chunk size '{}'", size_str))?;
606        raw.drain(..crlf + 2); // consume "<size>\r\n"
607
608        if chunk_size == 0 {
609            // Last chunk: skip trailer fields up to the empty line that ends
610            // the message. Leaving any of it unread would corrupt the next
611            // response on a pooled connection.
612            loop {
613                let line_end = loop {
614                    if let Some(p) = raw.windows(2).position(|w| w == b"\r\n") {
615                        break p;
616                    }
617                    let n = stream.read(tmp).map_err(|e| e.to_string())?;
618                    if n == 0 {
619                        return Err("chunked: premature EOF in trailer".to_string());
620                    }
621                    raw.extend_from_slice(&tmp[..n]);
622                };
623                raw.drain(..line_end + 2);
624                if line_end == 0 {
625                    break;
626                }
627            }
628            break;
629        }
630
631        // Read chunk data + trailing CRLF.
632        while raw.len() < chunk_size + 2 {
633            let n = stream.read(tmp).map_err(|e| e.to_string())?;
634            if n == 0 {
635                return Err("chunked: premature EOF reading chunk body".to_string());
636            }
637            raw.extend_from_slice(&tmp[..n]);
638        }
639        decoded.extend_from_slice(&raw[..chunk_size]);
640        raw.drain(..chunk_size + 2); // consume "<data>\r\n"
641    }
642
643    Ok(decoded)
644}
645
646/// Rewrite `buf` in-place: strip `Transfer-Encoding`, add `Content-Length`,
647/// replace the old (undecoded) body with `decoded`.
648fn rewrite_as_content_length(buf: &mut Vec<u8>, header_end: usize, decoded: &[u8]) {
649    let header_str = std::str::from_utf8(&buf[..header_end]).unwrap_or("").to_string();
650    buf.clear();
651    for line in header_str.lines() {
652        if line.to_ascii_lowercase().starts_with("transfer-encoding:") || line.is_empty() {
653            continue;
654        }
655        buf.extend_from_slice(line.as_bytes());
656        buf.extend_from_slice(b"\r\n");
657    }
658    let _ = write!(buf, "Content-Length: {}\r\n\r\n", decoded.len());
659    buf.extend_from_slice(decoded);
660}
661
662// Lives in rws-http (`response`): the disk cache parses stored responses with it too.
663pub(crate) use crate::response::REGENERATED_OR_HOP_BY_HOP;
664
665/// Make a buffered upstream response safe to re-serialize. The body is
666/// already held in `content_range_list`, from which `Response::generate`
667/// (and the HTTP/2 / HTTP/3 writers) emit `Content-Type` and
668/// `Content-Length` themselves, so the upstream's own copies would be
669/// duplicated — and a duplicate `content-length` is a protocol error that
670/// HTTP/2 clients reject outright. The upstream's `Content-Type` is moved
671/// onto the body instead; the status line is re-emitted as HTTP/1.1
672/// regardless of the backend's version.
673#[cfg_attr(not(feature = "http2"), allow(dead_code))]
674#[doc(hidden)]
675pub fn normalize_upstream_response(mut response: Response) -> Response {
676    response.http_version.clear();
677    response.http_version.push_str(crate::http::VERSION.http_1_1);
678    let has_body = !response.content_range_list.is_empty();
679    if let [range] = response.content_range_list.as_mut_slice() {
680        if let Some(h) = response
681            .headers
682            .iter()
683            .find(|h| h.name.eq_ignore_ascii_case(crate::header::Header::_CONTENT_TYPE))
684        {
685            range.content_type.clear();
686            range.content_type.push_str(&h.value);
687        }
688    }
689    // Compared in place (the list is lower-case ASCII), not lower-cased
690    // into a new String per header.
691    response.headers.retain(|h| {
692        if h.name.eq_ignore_ascii_case("content-type") {
693            // Keep it only when there's no body to carry it (e.g. HEAD, 304).
694            return !has_body;
695        }
696        !REGENERATED_OR_HOP_BY_HOP.iter().any(|name| h.name.eq_ignore_ascii_case(name))
697    });
698    response
699}
700
701#[doc(hidden)]
702pub fn bad_gateway() -> Response {
703    crate::error::problem(STATUS_CODE_REASON_PHRASE.n502_bad_gateway, "")
704}
705
706/// [`bad_gateway`] as the HTML error page when `request` is a browser's.
707#[doc(hidden)]
708pub fn bad_gateway_for(request: &Request) -> Response {
709    crate::error::page::negotiated(bad_gateway(), request)
710}
711
712// ── Streaming proxy helpers ───────────────────────────────────────────────────
713
714/// Responses larger than this threshold are streamed instead of buffered.
715const STREAM_THRESHOLD: usize = 1024 * 1024; // 1 MB
716
717/// A `Read` implementation that drains a prefix buffer before reading from the
718/// inner stream. Used to replay body bytes that arrived with the HTTP headers.
719#[doc(hidden)]
720pub struct ConcatReader<R: Read + Send> {
721    prefix: Vec<u8>,
722    prefix_pos: usize,
723    inner: R,
724}
725
726impl<R: Read + Send> ConcatReader<R> {
727    fn new(prefix: Vec<u8>, inner: R) -> Self {
728        ConcatReader { prefix, prefix_pos: 0, inner }
729    }
730}
731
732impl<R: Read + Send> Read for ConcatReader<R> {
733    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
734        if self.prefix_pos < self.prefix.len() {
735            let avail = &self.prefix[self.prefix_pos..];
736            let n = buf.len().min(avail.len());
737            buf[..n].copy_from_slice(&avail[..n]);
738            self.prefix_pos += n;
739            return Ok(n);
740        }
741        self.inner.read(buf)
742    }
743}
744
745/// A streamed upstream body with a `Content-Length`: ends after exactly that
746/// many bytes, and fails if the upstream ends sooner.
747///
748/// Without it the reader went on reading the backend's keep-alive connection
749/// after the last byte and only stopped at the read timeout: HTTP/2 clients
750/// got the whole body and then `RST_STREAM(INTERNAL_ERROR)` 30 s later (Git
751/// LFS downloads behind rws), HTTP/1.1 clients waited 30 s for the end.
752#[doc(hidden)]
753pub struct LengthLimitedReader {
754    inner: Box<dyn Read + Send>,
755    remaining: u64,
756    declared: u64,
757}
758
759impl LengthLimitedReader {
760    #[doc(hidden)]
761    pub fn new(inner: Box<dyn Read + Send>, length: u64) -> Self {
762        LengthLimitedReader { inner, remaining: length, declared: length }
763    }
764}
765
766impl Read for LengthLimitedReader {
767    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
768        if self.remaining == 0 || buf.is_empty() {
769            return Ok(0);
770        }
771        let want = buf.len().min(self.remaining.min(usize::MAX as u64) as usize);
772        let n = self.inner.read(&mut buf[..want])?;
773        if n == 0 {
774            return Err(std::io::Error::new(
775                std::io::ErrorKind::UnexpectedEof,
776                format!("upstream body ended after {} of {} bytes", self.declared - self.remaining, self.declared),
777            ));
778        }
779        self.remaining -= n as u64;
780        Ok(n)
781    }
782}
783
784/// The streamed body reader for an upstream response: bounded by its
785/// `Content-Length` unless it is chunked (the chunked framing ends it).
786#[doc(hidden)]
787pub fn bounded_body(reader: Box<dyn Read + Send>, chunked: bool, content_length: Option<usize>) -> Box<dyn Read + Send> {
788    match content_length {
789        Some(len) if !chunked => Box::new(LengthLimitedReader::new(reader, len as u64)),
790        _ => reader,
791    }
792}
793
794
795/// Idle backend connections kept per `host:port`. 64 matches common nginx
796/// `keepalive` settings and the benchmark's concurrency; fewer meant most
797/// requests at 64-way concurrency still paid a TCP connect.
798#[doc(hidden)]
799pub const POOL_MAX_IDLE: usize = 64;
800
801/// The process-wide backend connection pool used by config-driven proxy
802/// routes (`proxy_config::DynamicProxy`), keyed by `host:port`.
803#[doc(hidden)]
804pub fn shared_pool() -> &'static ConnPool {
805    static POOL: std::sync::OnceLock<ConnPool> = std::sync::OnceLock::new();
806    POOL.get_or_init(|| ConnPool::new(POOL_MAX_IDLE, pool::IDLE_TIMEOUT))
807}
808
809/// A backend connection the pooled forwarder drives: plain TCP, or TLS
810/// over TCP for `https://` backends.
811#[doc(hidden)]
812pub trait UpstreamIo: Read + Write + Send + 'static {
813    fn set_io_timeouts(&self, read: Duration, write: Duration) -> std::io::Result<()>;
814
815    /// An idle pooled connection the backend has closed (or sent anything
816    /// on, which an idle HTTP/1.1 backend only does to close it): not to be
817    /// reused. Checked without blocking or consuming data.
818    fn peer_closed(&self) -> bool {
819        false
820    }
821}
822
823impl UpstreamIo for TcpStream {
824    fn set_io_timeouts(&self, read: Duration, write: Duration) -> std::io::Result<()> {
825        self.set_read_timeout(Some(read))?;
826        self.set_write_timeout(Some(write))
827    }
828
829    fn peer_closed(&self) -> bool {
830        socket_closed(self)
831    }
832}
833
834/// Whether a blocking idle socket is unusable: EOF, unexpected bytes or an
835/// error on a non-blocking peek (only "would block" means still open).
836fn socket_closed(stream: &TcpStream) -> bool {
837    if stream.set_nonblocking(true).is_err() {
838        return true;
839    }
840    let peeked = stream.peek(&mut [0u8; 1]);
841    let restored = stream.set_nonblocking(false).is_ok();
842    !restored || !matches!(peeked, Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock)
843}
844
845/// An idle connection from `pool` that is still open, closing the ones the
846/// backend has closed (a POST on one would fail and can't be retried).
847pub(crate) fn acquire_open<S: UpstreamIo>(pool: &Pool<S>, key: &str) -> Option<S> {
848    std::iter::from_fn(|| pool.acquire(key)).find(|s| !s.peer_closed())
849}
850
851#[cfg(any(feature = "http-client", feature = "http2"))]
852#[doc(hidden)]
853pub type TlsStream = rustls::StreamOwned<rustls::ClientConnection, TcpStream>;
854
855#[cfg(any(feature = "http-client", feature = "http2"))]
856impl UpstreamIo for TlsStream {
857    fn set_io_timeouts(&self, read: Duration, write: Duration) -> std::io::Result<()> {
858        self.sock.set_io_timeouts(read, write)
859    }
860
861    fn peer_closed(&self) -> bool {
862        // A close_notify or a FIN both show up on the socket.
863        socket_closed(&self.sock)
864    }
865}
866
867/// Forward `request` to an HTTP or HTTPS backend at `host:port`, over a
868/// pooled keep-alive connection either way: plain backends use `plain_pool`,
869/// TLS backends the process-wide TLS pool (one handshake per connection, not
870/// per request). The single entry point for `ReverseProxy`, config-driven
871/// routes, `canary` and `ingress`.
872#[doc(hidden)]
873pub fn forward_upstream(
874    plain_pool: &ConnPool,
875    request: &Request,
876    client: Peer<'_>,
877    host: &str,
878    port: u16,
879    tls: bool,
880    connect_timeout: Duration,
881    read_timeout: Duration,
882) -> Result<Response, String> {
883    forward_upstream_trusting(plain_pool, request, client, host, port, tls, None, connect_timeout, read_timeout)
884}
885
886/// [`forward_upstream`] with the trust settings of one upstream: `trust`
887/// replaces the WebPKI roots for TLS backends (a private CA).
888#[allow(clippy::too_many_arguments)]
889#[doc(hidden)]
890pub fn forward_upstream_trusting(
891    plain_pool: &ConnPool,
892    request: &Request,
893    client: Peer<'_>,
894    host: &str,
895    port: u16,
896    tls: bool,
897    trust: Option<&UpstreamTls>,
898    connect_timeout: Duration,
899    read_timeout: Duration,
900) -> Result<Response, String> {
901    forward_upstream_as(plain_pool, request, client, host, port, host, tls, trust, connect_timeout, read_timeout)
902}
903
904/// [`forward_upstream_trusting`], sending `host_header` as the `Host` instead
905/// of the backend's address (a config route's `preserve_host` /
906/// `upstream_host`).
907#[allow(clippy::too_many_arguments)]
908#[doc(hidden)]
909pub fn forward_upstream_as(
910    plain_pool: &ConnPool,
911    request: &Request,
912    client: Peer<'_>,
913    host: &str,
914    port: u16,
915    host_header: &str,
916    tls: bool,
917    trust: Option<&UpstreamTls>,
918    connect_timeout: Duration,
919    read_timeout: Duration,
920) -> Result<Response, String> {
921    // Inside a traced request: a client span per forward, current while the
922    // request is built, so the upstream's `traceparent` names it.
923    #[cfg(not(target_arch = "wasm32"))]
924    let span = crate::otel::outbound_span(&request.method);
925    #[cfg(not(target_arch = "wasm32"))]
926    if let Some(span) = &span {
927        let scheme = if tls { "https" } else { "http" };
928        let path = request.request_uri.as_str();
929        for (key, value) in crate::otel::http_client_attributes(&request.method, &format!("{scheme}://{host}:{port}{path}")) {
930            span.set_attribute(key, value);
931        }
932    }
933    let result = forward_upstream_untraced(plain_pool, request, client, host, port, host_header, tls, trust, connect_timeout, read_timeout);
934    #[cfg(not(target_arch = "wasm32"))]
935    if let Some(span) = &span {
936        span.finish_http_client(result.as_ref().map(|r| r.status_code as u16).map_err(String::as_str));
937    }
938    result
939}
940
941#[allow(clippy::too_many_arguments)]
942fn forward_upstream_untraced(
943    plain_pool: &ConnPool,
944    request: &Request,
945    client: Peer<'_>,
946    host: &str,
947    port: u16,
948    host_header: &str,
949    tls: bool,
950    trust: Option<&UpstreamTls>,
951    connect_timeout: Duration,
952    read_timeout: Duration,
953) -> Result<Response, String> {
954    if tls {
955        #[cfg(any(feature = "http-client", feature = "http2"))]
956        {
957            let (pool, config) = match trust {
958                Some(t) => (t.pool, Arc::clone(&t.config)),
959                None => (shared_tls_pool(), tls_client_config()),
960            };
961            return forward_via(pool, request, client, host, port, host_header, read_timeout, || {
962                connect_tls_with(Arc::clone(&config), host, port, connect_timeout)
963            });
964        }
965        #[cfg(not(any(feature = "http-client", feature = "http2")))]
966        {
967            let _ = trust;
968            return Err("HTTPS backends need the http2 or http-client feature, which this build doesn't include".to_string());
969        }
970    }
971    forward_via(plain_pool, request, client, host, port, host_header, read_timeout, || connect_tcp(host, port, connect_timeout))
972}
973
974/// Trust settings for one upstream's TLS backends: the certificates in a CA
975/// file **instead of** the WebPKI roots — for internal services behind a
976/// private CA or a self-signed certificate (nginx's
977/// `proxy_ssl_trusted_certificate`) — and/or a client certificate rws
978/// presents to backends that require one (`proxy_ssl_certificate`, since
979/// 18.3.0). Connections are pooled per setting, so two upstreams at the same
980/// address with different trust never share one.
981pub struct UpstreamTls {
982    #[cfg(any(feature = "http-client", feature = "http2"))]
983    config: Arc<rustls::ClientConfig>,
984    #[cfg(any(feature = "http-client", feature = "http2"))]
985    pool: &'static Pool<TlsStream>,
986    /// Connections for the non-blocking forwarder, made with `config`.
987    #[cfg(feature = "http2")]
988    async_pool: &'static Pool<async_upstream::AsyncTlsStream>,
989    /// `config` offering HTTP/2 by ALPN, for HTTP/2 and gRPC upstreams.
990    #[cfg(feature = "http2")]
991    h2_config: Arc<rustls::ClientConfig>,
992}
993
994impl UpstreamTls {
995    /// Load the PEM certificates in `path` as the only trusted roots.
996    pub fn from_ca_file(path: &str) -> Result<UpstreamTls, String> {
997        UpstreamTls::new(Some(path), None)
998    }
999
1000    /// Trust the PEM certificates in `ca_file` (the WebPKI roots when `None`)
1001    /// and, with `client_cert` = `(certificate chain PEM, private key PEM)`,
1002    /// present that certificate to backends that ask for one.
1003    pub fn new(ca_file: Option<&str>, client_cert: Option<(&str, &str)>) -> Result<UpstreamTls, String> {
1004        #[cfg(any(feature = "http-client", feature = "http2"))]
1005        {
1006            use rustls::pki_types::{pem::PemObject, CertificateDer, PrivateKeyDer};
1007            let roots = match ca_file {
1008                Some(path) => {
1009                    let bytes = std::fs::read(path).map_err(|e| format!("cannot read CA file '{path}': {e}"))?;
1010                    let certs = CertificateDer::pem_slice_iter(&bytes)
1011                        .collect::<Result<Vec<_>, _>>()
1012                        .map_err(|e| format!("cannot parse CA file '{path}': {e}"))?;
1013                    if certs.is_empty() {
1014                        return Err(format!("no certificates in CA file '{path}'"));
1015                    }
1016                    let mut roots = rustls::RootCertStore::empty();
1017                    for cert in certs {
1018                        roots.add(cert).map_err(|e| format!("invalid CA certificate in '{path}': {e}"))?;
1019                    }
1020                    roots
1021                }
1022                None => rustls::RootCertStore::from_iter(webpki_roots::TLS_SERVER_ROOTS.iter().cloned()),
1023            };
1024            let builder = crate::tls_client_builder().with_root_certificates(roots);
1025            let config = match client_cert {
1026                None => builder.with_no_client_auth(),
1027                Some((cert_path, key_path)) => {
1028                    let bytes = std::fs::read(cert_path).map_err(|e| format!("cannot read client certificate '{cert_path}': {e}"))?;
1029                    let chain = CertificateDer::pem_slice_iter(&bytes)
1030                        .collect::<Result<Vec<_>, _>>()
1031                        .map_err(|e| format!("cannot parse client certificate '{cert_path}': {e}"))?;
1032                    if chain.is_empty() {
1033                        return Err(format!("no certificate in '{cert_path}'"));
1034                    }
1035                    let bytes = std::fs::read(key_path).map_err(|e| format!("cannot read client key '{key_path}': {e}"))?;
1036                    let key = PrivateKeyDer::from_pem_slice(&bytes).map_err(|e| format!("cannot parse client key '{key_path}': {e}"))?;
1037                    builder.with_client_auth_cert(chain, key).map_err(|e| format!("client certificate '{cert_path}': {e}"))?
1038                }
1039            };
1040            let label = format!("{}|{}", ca_file.unwrap_or("webpki"), client_cert.map_or("", |(cert, _)| cert));
1041            Ok(UpstreamTls::with_config(config, &label))
1042        }
1043        #[cfg(not(any(feature = "http-client", feature = "http2")))]
1044        {
1045            let _ = client_cert;
1046            Err(format!("tls_ca_file '{}': HTTPS backends need the http2 or http-client feature", ca_file.unwrap_or("")))
1047        }
1048    }
1049
1050    #[cfg(any(feature = "http-client", feature = "http2"))]
1051    fn with_config(config: rustls::ClientConfig, label: &str) -> UpstreamTls {
1052        #[cfg(feature = "http2")]
1053        let h2_config = Arc::new(h2_upstream::with_h2_alpn(config.clone()));
1054        UpstreamTls {
1055            config: Arc::new(config),
1056            pool: tls_pool_for_ca(label),
1057            #[cfg(feature = "http2")]
1058            async_pool: async_tls_pool_for_ca(label),
1059            #[cfg(feature = "http2")]
1060            h2_config,
1061        }
1062    }
1063
1064    /// The client configuration for HTTP/2 upstreams (ALPN `h2`).
1065    #[cfg(feature = "http2")]
1066    #[doc(hidden)]
1067    pub fn h2_config(&self) -> &Arc<rustls::ClientConfig> {
1068        &self.h2_config
1069    }
1070
1071    /// Trust nothing: every TLS handshake fails, so the upstream answers 502.
1072    /// Used when a configured CA file can't be loaded — failing closed rather
1073    /// than falling back to the public roots.
1074    #[doc(hidden)]
1075    pub fn reject_all(label: &str) -> UpstreamTls {
1076        #[cfg(any(feature = "http-client", feature = "http2"))]
1077        {
1078            let config = crate::tls_client_builder().with_root_certificates(rustls::RootCertStore::empty()).with_no_client_auth();
1079            UpstreamTls::with_config(config, &format!("reject-all:{label}"))
1080        }
1081        #[cfg(not(any(feature = "http-client", feature = "http2")))]
1082        {
1083            let _ = label;
1084            UpstreamTls {}
1085        }
1086    }
1087
1088    /// How the non-blocking forwarder reaches these backends.
1089    #[cfg(feature = "http2")]
1090    #[doc(hidden)]
1091    pub fn async_tls(&self) -> async_upstream::AsyncTls {
1092        async_upstream::AsyncTls { config: Arc::clone(&self.config), pool: self.async_pool }
1093    }
1094
1095    /// The client configuration (for health checks).
1096    #[cfg(any(feature = "http-client", feature = "http2"))]
1097    #[doc(hidden)]
1098    pub fn client_config(&self) -> Arc<rustls::ClientConfig> {
1099        Arc::clone(&self.config)
1100    }
1101}
1102
1103/// One non-blocking connection pool per CA file, for the life of the process
1104/// (a reload that keeps the same file keeps its warm connections).
1105#[cfg(feature = "http2")]
1106fn async_tls_pool_for_ca(path: &str) -> &'static Pool<async_upstream::AsyncTlsStream> {
1107    static POOLS: std::sync::OnceLock<
1108        std::sync::Mutex<std::collections::HashMap<String, &'static Pool<async_upstream::AsyncTlsStream>>>,
1109    > = std::sync::OnceLock::new();
1110    let mut pools = POOLS.get_or_init(Default::default).lock().unwrap_or_else(|e| e.into_inner());
1111    pools
1112        .entry(path.to_string())
1113        .or_insert_with(|| Box::leak(Box::new(Pool::new(POOL_MAX_IDLE, pool::IDLE_TIMEOUT))))
1114}
1115
1116/// One pool per CA file, for the life of the process.
1117#[cfg(any(feature = "http-client", feature = "http2"))]
1118fn tls_pool_for_ca(path: &str) -> &'static Pool<TlsStream> {
1119    static POOLS: std::sync::OnceLock<std::sync::Mutex<std::collections::HashMap<String, &'static Pool<TlsStream>>>> =
1120        std::sync::OnceLock::new();
1121    let mut pools = POOLS.get_or_init(Default::default).lock().unwrap_or_else(|e| e.into_inner());
1122    pools
1123        .entry(path.to_string())
1124        .or_insert_with(|| Box::leak(Box::new(Pool::new(POOL_MAX_IDLE, pool::IDLE_TIMEOUT))))
1125}
1126
1127/// Forward `request` to `host:port` over plain HTTP/1.1, reusing an idle
1128/// connection from `pool` when there is one and returning the connection to
1129/// `pool` after a complete, reusable response.
1130#[doc(hidden)]
1131pub fn forward_pooled(
1132    pool: &ConnPool,
1133    request: &Request,
1134    client: Peer<'_>,
1135    host: &str,
1136    port: u16,
1137    connect_timeout: Duration,
1138    read_timeout: Duration,
1139) -> Result<Response, String> {
1140    forward_via(pool, request, client, host, port, host, read_timeout, || connect_tcp(host, port, connect_timeout))
1141}
1142
1143/// [`forward_pooled`], sending `host_header` as the `Host` (the client's, for
1144/// a gateway that must preserve it) instead of the backend's address.
1145#[cfg(feature = "gateway-api")]
1146#[allow(clippy::too_many_arguments)]
1147#[doc(hidden)]
1148pub fn forward_pooled_with_host(
1149    pool: &ConnPool,
1150    request: &Request,
1151    client: Peer<'_>,
1152    host: &str,
1153    port: u16,
1154    host_header: &str,
1155    connect_timeout: Duration,
1156    read_timeout: Duration,
1157) -> Result<Response, String> {
1158    forward_via(pool, request, client, host, port, host_header, read_timeout, || connect_tcp(host, port, connect_timeout))
1159}
1160
1161/// The pooled request/response cycle, for any connection type.
1162///
1163/// A backend may close an idle keep-alive connection at any moment, so a
1164/// pooled connection that fails before *any* response byte arrives is
1165/// retried once on a fresh connection — but only for idempotent methods
1166/// (RFC 9110 §9.2.2): the request may already have reached the backend.
1167#[allow(clippy::too_many_arguments)]
1168fn forward_via<S: UpstreamIo>(
1169    pool: &Pool<S>,
1170    request: &Request,
1171    client: Peer<'_>,
1172    host: &str,
1173    port: u16,
1174    host_header: &str,
1175    read_timeout: Duration,
1176    connect: impl Fn() -> Result<S, String>,
1177) -> Result<Response, String> {
1178    let key = format!("{}:{}", host, port);
1179    if let Some(stream) = acquire_open(pool, &key) {
1180        match exchange(pool, &key, stream, request, host_header, client, read_timeout) {
1181            Exchange::Done(response) => return Ok(response),
1182            Exchange::NoResponse(_) if is_idempotent(&request.method) => {} // stale: retry fresh
1183            Exchange::NoResponse(e) | Exchange::Failed(e) => return Err(e),
1184        }
1185    }
1186    let stream = connect()?;
1187    match exchange(pool, &key, stream, request, host_header, client, read_timeout) {
1188        Exchange::Done(response) => Ok(response),
1189        Exchange::NoResponse(e) | Exchange::Failed(e) => Err(e),
1190    }
1191}
1192
1193/// Connect to the first address of `host:port` that accepts. `localhost`
1194/// resolves to `::1` before `127.0.0.1` on many systems; a backend listening
1195/// on IPv4 only must still be reachable by name.
1196fn connect_tcp(host: &str, port: u16, connect_timeout: Duration) -> Result<TcpStream, String> {
1197    let key = format!("{}:{}", host, port);
1198    let addrs: Vec<_> = key
1199        .to_socket_addrs()
1200        .map_err(|e| format!("DNS lookup for {} failed: {}", key, e))?
1201        .collect();
1202    let mut last_error = format!("no address resolved for {}", key);
1203    for addr in addrs {
1204        match TcpStream::connect_timeout(&addr, connect_timeout) {
1205            Ok(stream) => {
1206                let _ = stream.set_nodelay(true);
1207                return Ok(stream);
1208            }
1209            Err(e) => last_error = format!("connect to {} ({}) failed: {}", key, addr, e),
1210        }
1211    }
1212    Err(last_error)
1213}
1214
1215/// The process-wide pool of TLS connections to `https://` backends.
1216#[cfg(any(feature = "http-client", feature = "http2"))]
1217fn shared_tls_pool() -> &'static Pool<TlsStream> {
1218    static POOL: std::sync::OnceLock<Pool<TlsStream>> = std::sync::OnceLock::new();
1219    POOL.get_or_init(|| Pool::new(POOL_MAX_IDLE, pool::IDLE_TIMEOUT))
1220}
1221
1222/// TLS client settings for backends: the Mozilla root store, no client
1223/// certificate. Built once — parsing the root store per request was a large
1224/// part of the per-request cost of HTTPS upstreams.
1225#[cfg(any(feature = "http-client", feature = "http2"))]
1226#[doc(hidden)]
1227pub fn tls_client_config() -> Arc<rustls::ClientConfig> {
1228    static CONFIG: std::sync::OnceLock<Arc<rustls::ClientConfig>> = std::sync::OnceLock::new();
1229    Arc::clone(CONFIG.get_or_init(|| {
1230        let roots = rustls::RootCertStore::from_iter(webpki_roots::TLS_SERVER_ROOTS.iter().cloned());
1231        Arc::new(crate::tls_client_builder().with_root_certificates(roots).with_no_client_auth())
1232    }))
1233}
1234
1235#[cfg(any(feature = "http-client", feature = "http2"))]
1236fn connect_tls_with(config: Arc<rustls::ClientConfig>, host: &str, port: u16, connect_timeout: Duration) -> Result<TlsStream, String> {
1237    let tcp = connect_tcp(host, port, connect_timeout)?;
1238    let server_name = rustls::pki_types::ServerName::try_from(host.to_string())
1239        .map_err(|e| format!("invalid upstream hostname '{}': {}", host, e))?;
1240    let conn = rustls::ClientConnection::new(config, server_name).map_err(|e| e.to_string())?;
1241    Ok(rustls::StreamOwned::new(conn, tcp))
1242}
1243
1244fn is_idempotent(method: &str) -> bool {
1245    matches!(method, "GET" | "HEAD" | "OPTIONS" | "TRACE" | "PUT" | "DELETE")
1246}
1247
1248enum Exchange {
1249    Done(Response),
1250    /// Failed before any response byte (write error, or closed/errored on the first read).
1251    NoResponse(String),
1252    Failed(String),
1253}
1254
1255/// One request/response on `stream`. A fully read, keep-alive response puts
1256/// the connection back in `pool`; a streamed response keeps it until done.
1257fn exchange<S: UpstreamIo>(
1258    pool: &Pool<S>,
1259    key: &str,
1260    mut stream: S,
1261    request: &Request,
1262    host: &str,
1263    client: Peer<'_>,
1264    read_timeout: Duration,
1265) -> Exchange {
1266    if let Err(e) = stream.set_io_timeouts(read_timeout, Duration::from_secs(10)) {
1267        return Exchange::Failed(e.to_string());
1268    }
1269    // keep_alive = true: ask the backend to hold the connection open.
1270    let req_bytes = build_request(request, host, client, true);
1271    if let Err(e) = stream.write_all(&req_bytes) {
1272        return Exchange::NoResponse(format!("write to backend failed: {}", e));
1273    }
1274
1275    let mut tmp = [0u8; 4096];
1276    let (header_bytes, body_prefix) = match read_final_response_head(&mut stream, &mut tmp) {
1277        Ok(head) => head,
1278        Err(HeadError::NothingReceived(e)) => return Exchange::NoResponse(e),
1279        Err(HeadError::Partial(e)) => return Exchange::Failed(e),
1280    };
1281    let header_lower = std::str::from_utf8(&header_bytes).unwrap_or("").to_ascii_lowercase();
1282
1283    if response_has_no_body(&request.method, &header_lower) {
1284        if !header_lower.lines().any(|l| l.starts_with("connection:") && l.contains("close")) {
1285            pool.release(key, stream);
1286        }
1287        return match Response::parse_upstream(&header_bytes, REGENERATED_OR_HOP_BY_HOP) {
1288            Ok(response) => Exchange::Done(response),
1289            Err(e) => Exchange::Failed(e),
1290        };
1291    }
1292
1293    if should_stream_response(&header_lower) {
1294        // Streaming path — pipe bytes straight to the client; the connection
1295        // can't be reused while the body is in flight.
1296        return match parse_status_and_headers(&header_bytes) {
1297            Ok(mut response) => {
1298                let facts = HeadFacts::scan(&header_bytes);
1299                let body: Box<dyn Read + Send> = Box::new(ConcatReader::new(body_prefix, stream));
1300                response.stream_pipe = Some(bounded_body(body, facts.chunked, facts.content_length));
1301                Exchange::Done(response)
1302            }
1303            Err(e) => Exchange::Failed(e),
1304        };
1305    }
1306    // Buffered path — read the full body, then return the connection to the pool.
1307    match read_response_from_partial(&mut stream, header_bytes, body_prefix, &mut tmp) {
1308        Ok((resp_bytes, reusable)) => {
1309            if reusable {
1310                pool.release(key, stream);
1311            }
1312            match Response::parse_upstream(&resp_bytes, REGENERATED_OR_HOP_BY_HOP) {
1313                Ok(response) => Exchange::Done(response),
1314                Err(e) => Exchange::Failed(e),
1315            }
1316        }
1317        Err(e) => Exchange::Failed(e),
1318    }
1319}
1320
1321/// Read exactly the HTTP response headers (up to and including `\r\n\r\n`).
1322///
1323/// Returns `(header_bytes, body_prefix)` where `body_prefix` contains any
1324/// body bytes that arrived in the same TCP segment as the headers.
1325#[cfg(test)]
1326fn read_headers_only(stream: &mut TcpStream, tmp: &mut [u8]) -> Result<(Vec<u8>, Vec<u8>), String> {
1327    read_response_head(stream, tmp).map_err(|e| match e {
1328        HeadError::NothingReceived(msg) | HeadError::Partial(msg) => msg,
1329    })
1330}
1331
1332/// Why reading a response head failed: before any byte arrived (the request
1333/// may never have been processed — e.g. a pooled connection the backend had
1334/// already closed) or part-way through.
1335enum HeadError {
1336    NothingReceived(String),
1337    Partial(String),
1338}
1339
1340fn read_response_head<S: Read>(stream: &mut S, tmp: &mut [u8]) -> Result<(Vec<u8>, Vec<u8>), HeadError> {
1341    read_response_head_from(stream, tmp, Vec::with_capacity(4096), false)
1342}
1343
1344/// The final response head: interim `1xx` heads (`100 Continue`,
1345/// `103 Early Hints`, …) are read past (RFC 9110 §15.2); a `103`'s `Link`
1346/// values are passed on to the client (`early_hints::forward_upstream`). Returning one as
1347/// the response left the real response in the connection, and once pooled
1348/// the next request — possibly another client's — received it.
1349fn read_final_response_head<S: Read>(stream: &mut S, tmp: &mut [u8]) -> Result<(Vec<u8>, Vec<u8>), HeadError> {
1350    let (mut head, mut rest) = read_response_head(stream, tmp)?;
1351    let mut interim = 0;
1352    while is_interim_response(&head) {
1353        crate::early_hints::forward_upstream(&head);
1354        interim += 1;
1355        if interim > MAX_INTERIM_RESPONSES {
1356            return Err(HeadError::Partial("too many interim (1xx) responses from the backend".to_string()));
1357        }
1358        (head, rest) = read_response_head_from(stream, tmp, rest, true)?;
1359    }
1360    Ok((head, rest))
1361}
1362
1363/// Read until a complete head is in `buf` (which may already hold bytes
1364/// that followed a previous head). `received` — bytes already came from this
1365/// response, so a failure is never "nothing received".
1366fn read_response_head_from<S: Read>(
1367    stream: &mut S,
1368    tmp: &mut [u8],
1369    mut buf: Vec<u8>,
1370    received: bool,
1371) -> Result<(Vec<u8>, Vec<u8>), HeadError> {
1372    loop {
1373        if let Some(pos) = buf.windows(4).position(|w| w == b"\r\n\r\n") {
1374            let body_prefix = buf[pos + 4..].to_vec();
1375            buf.truncate(pos + 4);
1376            return Ok((buf, body_prefix));
1377        }
1378        let nothing = buf.is_empty() && !received;
1379        let n = match stream.read(tmp) {
1380            Ok(n) => n,
1381            Err(e) if nothing => return Err(HeadError::NothingReceived(e.to_string())),
1382            Err(e) => return Err(HeadError::Partial(e.to_string())),
1383        };
1384        if n == 0 {
1385            let msg = "backend closed connection before headers were complete".to_string();
1386            return Err(if nothing { HeadError::NothingReceived(msg) } else { HeadError::Partial(msg) });
1387        }
1388        buf.extend_from_slice(&tmp[..n]);
1389    }
1390}
1391
1392/// Interim responses tolerated before the final one.
1393#[doc(hidden)]
1394pub const MAX_INTERIM_RESPONSES: usize = 16;
1395
1396/// An interim (1xx) response head other than `101 Switching Protocols`
1397/// (which ends the HTTP exchange): the final response follows it.
1398#[doc(hidden)]
1399pub fn is_interim_response(head: &[u8]) -> bool {
1400    let line_end = head.iter().position(|b| *b == b'\r' || *b == b'\n').unwrap_or(head.len());
1401    let status = head[..line_end].split(|b| *b == b' ').nth(1).unwrap_or(&[]);
1402    status.len() == 3 && status.iter().all(u8::is_ascii_digit) && status[0] == b'1' && status != b"101"
1403}
1404
1405/// RFC 9112 §6.3: a response to HEAD, and any 1xx, 204 or 304 response, ends
1406/// with its head — whatever `Content-Length` says (for HEAD it describes the
1407/// GET body). Waiting for that body hung until the read timeout (a 502).
1408#[doc(hidden)]
1409pub fn response_has_no_body(method: &str, header_lower: &str) -> bool {
1410    let status = header_lower.split_whitespace().nth(1).unwrap_or("");
1411    method.eq_ignore_ascii_case("HEAD") || status.starts_with('1') || status == "204" || status == "304"
1412}
1413
1414/// Returns `true` when the response should be streamed rather than buffered.
1415///
1416/// Streams when any of the following hold:
1417/// - `Content-Type: text/event-stream` — SSE
1418/// - `Transfer-Encoding: chunked` — AI token streams, etc.
1419/// - `Content-Length` exceeds 1 MB — large file downloads
1420#[doc(hidden)]
1421pub fn should_stream_response(header_lower: &str) -> bool {
1422    let is_sse = header_lower.lines().any(|l| {
1423        l.starts_with("content-type:") && l.contains("text/event-stream")
1424    });
1425    let is_chunked = header_lower.lines().any(|l| {
1426        l.starts_with("transfer-encoding:") && l.contains("chunked")
1427    });
1428    let content_length: Option<usize> = header_lower.lines().find_map(|l| {
1429        l.strip_prefix("content-length:")?.trim().parse().ok()
1430    });
1431    let is_large = content_length.map_or(false, |n| n > STREAM_THRESHOLD);
1432    is_sse || is_chunked || is_large
1433}
1434
1435/// What the forwarders need from an upstream response head, found in one
1436/// case-insensitive pass over the raw bytes — the same answers as
1437/// [`response_has_no_body`], [`should_stream_response`] and the
1438/// `connection:` / `content-length:` scans over a lower-cased copy, without
1439/// making that copy.
1440#[cfg_attr(not(feature = "http2"), allow(dead_code))]
1441#[doc(hidden)]
1442pub struct HeadFacts {
1443    /// The second whitespace-separated token of the head (the status code).
1444    #[doc(hidden)]
1445    pub status_no_body: bool,
1446    #[doc(hidden)]
1447    pub sse: bool,
1448    #[doc(hidden)]
1449    pub chunked: bool,
1450    /// The first `content-length:` value that parses.
1451    #[doc(hidden)]
1452    pub content_length: Option<usize>,
1453    #[doc(hidden)]
1454    pub connection_close: bool,
1455}
1456
1457#[cfg_attr(not(feature = "http2"), allow(dead_code))]
1458impl HeadFacts {
1459    #[doc(hidden)]
1460    pub fn scan(head: &[u8]) -> HeadFacts {
1461        let text = std::str::from_utf8(head).unwrap_or("");
1462        let status = text.split_whitespace().nth(1).unwrap_or("");
1463        let mut facts = HeadFacts {
1464            status_no_body: status.starts_with('1') || status == "204" || status == "304",
1465            sse: false,
1466            chunked: false,
1467            content_length: None,
1468            connection_close: false,
1469        };
1470        for line in text.lines() {
1471            if let Some(value) = strip_prefix_ignore_ascii_case(line, "content-type:") {
1472                facts.sse |= contains_ignore_ascii_case(value, "text/event-stream");
1473            } else if let Some(value) = strip_prefix_ignore_ascii_case(line, "transfer-encoding:") {
1474                facts.chunked |= contains_ignore_ascii_case(value, "chunked");
1475            } else if let Some(value) = strip_prefix_ignore_ascii_case(line, "content-length:") {
1476                if facts.content_length.is_none() {
1477                    facts.content_length = value.trim().parse().ok();
1478                }
1479            } else if let Some(value) = strip_prefix_ignore_ascii_case(line, "connection:") {
1480                facts.connection_close |= contains_ignore_ascii_case(value, "close");
1481            }
1482        }
1483        facts
1484    }
1485
1486    /// [`response_has_no_body`].
1487    #[doc(hidden)]
1488    pub fn no_body(&self, method: &str) -> bool {
1489        method.eq_ignore_ascii_case("HEAD") || self.status_no_body
1490    }
1491
1492    /// [`should_stream_response`].
1493    #[doc(hidden)]
1494    pub fn should_stream(&self) -> bool {
1495        self.sse || self.chunked || self.content_length.is_some_and(|n| n > STREAM_THRESHOLD)
1496    }
1497}
1498
1499fn strip_prefix_ignore_ascii_case<'a>(line: &'a str, prefix: &str) -> Option<&'a str> {
1500    let bytes = line.as_bytes();
1501    // `prefix` is ASCII, so a byte match ends on a char boundary.
1502    (bytes.len() >= prefix.len() && bytes[..prefix.len()].eq_ignore_ascii_case(prefix.as_bytes()))
1503        .then(|| &line[prefix.len()..])
1504}
1505
1506fn contains_ignore_ascii_case(haystack: &str, needle: &str) -> bool {
1507    haystack.as_bytes().windows(needle.len()).any(|w| w.eq_ignore_ascii_case(needle.as_bytes()))
1508}
1509
1510/// Parse the status line and headers from raw header bytes (ending at `\r\n\r\n`).
1511fn parse_status_and_headers(header_bytes: &[u8]) -> Result<Response, String> {
1512    let s = std::str::from_utf8(header_bytes)
1513        .map_err(|e| format!("non-UTF-8 response headers: {}", e))?;
1514    let mut lines = s.lines();
1515    let status_line = lines.next().ok_or("empty backend response")?;
1516    let mut parts = status_line.splitn(3, ' ');
1517    let http_version = parts.next().unwrap_or("HTTP/1.1").to_string();
1518    let status_code: i16 = parts
1519        .next()
1520        .unwrap_or("502")
1521        .parse()
1522        .map_err(|_| format!("invalid status code in '{}'", status_line))?;
1523    let reason_phrase = parts.next().unwrap_or("").trim_end_matches('\r').to_string();
1524    let mut headers = Vec::new();
1525    for line in lines {
1526        let line = line.trim_end_matches('\r');
1527        if line.is_empty() { break; }
1528        if let Some(colon) = line.find(':') {
1529            headers.push(crate::header::Header {
1530                name: line[..colon].trim().to_string().into(),
1531                value: (line[colon + 1..].trim().to_string()).into(),
1532            });
1533        }
1534    }
1535    Ok(Response {
1536        http_version,
1537        status_code,
1538        reason_phrase,
1539        headers,
1540        content_range_list: vec![],
1541        stream_file: None,
1542        stream_pipe: None,
1543        trailers: None,
1544    })
1545}
1546
1547/// Read the remaining body after headers have already been read.
1548///
1549/// `header_bytes` ends with `\r\n\r\n`; `body_prefix` holds any body bytes
1550/// that arrived in the same TCP read.  Handles all three body mechanisms
1551/// (chunked, content-length, read-to-EOF).  Returns `(full_response_bytes, can_reuse)`.
1552fn read_response_from_partial<S: Read>(
1553    stream: &mut S,
1554    header_bytes: Vec<u8>,
1555    body_prefix: Vec<u8>,
1556    tmp: &mut [u8],
1557) -> Result<(Vec<u8>, bool), String> {
1558    let header_end = header_bytes.len();
1559    let mut buf = header_bytes;
1560    buf.extend_from_slice(&body_prefix);
1561
1562    let header_lower =
1563        std::str::from_utf8(&buf[..header_end]).unwrap_or("").to_ascii_lowercase();
1564    let connection_close =
1565        header_lower.lines().any(|l| l.starts_with("connection:") && l.contains("close"));
1566    let is_chunked = header_lower
1567        .lines()
1568        .any(|l| l.starts_with("transfer-encoding:") && l.contains("chunked"));
1569    let content_length: Option<usize> = header_lower.lines().find_map(|l| {
1570        l.strip_prefix("content-length:")?.trim().parse().ok()
1571    });
1572
1573    if is_chunked {
1574        let decoded = decode_chunked(stream, &buf, header_end, tmp)?;
1575        rewrite_as_content_length(&mut buf, header_end, &decoded);
1576        Ok((buf, !connection_close))
1577    } else if let Some(len) = content_length {
1578        while buf.len() < header_end + len {
1579            let n = stream.read(tmp).map_err(|e| e.to_string())?;
1580            if n == 0 { break; }
1581            buf.extend_from_slice(&tmp[..n]);
1582        }
1583        Ok((buf, !connection_close))
1584    } else {
1585        loop {
1586            let n = stream.read(tmp).map_err(|e| e.to_string())?;
1587            if n == 0 { break; }
1588            buf.extend_from_slice(&tmp[..n]);
1589        }
1590        Ok((buf, false))
1591    }
1592}
1593
1594// ── Backend URL parsing ───────────────────────────────────────────────────────
1595
1596struct Backend {
1597    host: String,
1598    port: u16,
1599    /// Whether the upstream connection should use TLS.
1600    /// Set when the URL scheme is `https://`, `h2s://`, or `grpcs://`.
1601    tls: bool,
1602}
1603
1604impl Backend {
1605    fn parse(url: &str) -> Option<Self> {
1606        let (rest, tls, default_port) = if let Some(r) = url.strip_prefix("https://") {
1607            (r, true, 443u16)
1608        } else if let Some(r) = url.strip_prefix("h2s://") {
1609            (r, true, 443u16)
1610        } else if let Some(r) = url.strip_prefix("grpcs://") {
1611            (r, true, 443u16)
1612        } else if let Some(r) = url.strip_prefix("http://") {
1613            (r, false, 80u16)
1614        } else if let Some(r) = url.strip_prefix("h2://") {
1615            (r, false, 80u16)
1616        } else if let Some(r) = url.strip_prefix("grpc://") {
1617            (r, false, 80u16)
1618        } else {
1619            (url, false, 80u16)
1620        };
1621        // Drop any path component.
1622        let host_port = rest.split('/').next().unwrap_or(rest);
1623        let (host, port) = if let Some(colon) = host_port.rfind(':') {
1624            let port_str = &host_port[colon + 1..];
1625            if let Ok(p) = port_str.parse::<u16>() {
1626                (host_port[..colon].to_string(), p)
1627            } else {
1628                (host_port.to_string(), default_port)
1629            }
1630        } else {
1631            (host_port.to_string(), default_port)
1632        };
1633        if host.is_empty() {
1634            return None;
1635        }
1636        Some(Backend { host, port, tls })
1637    }
1638}
1639
1640// ── HTTP/2 reverse proxy ──────────────────────────────────────────────────────
1641
1642/// Reverse proxy that forwards requests to HTTP/2 backends.
1643///
1644/// Wraps [`ReverseProxy`] and forces HTTP/2 (`h2`) for all upstream connections.
1645/// Requires the `http2` Cargo feature.
1646///
1647/// This proxy also transparently handles gRPC traffic
1648/// (`Content-Type: application/grpc*`) — gRPC DATA frames are forwarded
1649/// as-is because gRPC is layered directly on HTTP/2.
1650#[cfg(feature = "http2")]
1651pub struct H2ReverseProxy {
1652    inner: ReverseProxy,
1653}
1654
1655#[cfg(feature = "http2")]
1656impl H2ReverseProxy {
1657    /// Create a proxy distributing requests across `backends` in round-robin order.
1658    ///
1659    /// Each backend entry can be:
1660    /// - `"host:port"` — plain TCP (HTTP/2 cleartext)
1661    /// - `"h2://host:port"` — plain TCP (explicit scheme)
1662    /// - `"h2s://host:port"` — TLS (HTTP/2 over HTTPS; port defaults to 443)
1663    /// - `"https://host:port"` — TLS (same as `h2s://`)
1664    ///
1665    /// TLS backends require the `http2` Cargo feature (includes `rustls` +
1666    /// `webpki-roots`).  Certificate verification uses the WebPKI trust store.
1667    pub fn new<I, S>(backends: I) -> Self
1668    where
1669        I: IntoIterator<Item = S>,
1670        S: AsRef<str>,
1671    {
1672        H2ReverseProxy {
1673            inner: ReverseProxy::new(backends),
1674        }
1675    }
1676
1677    /// Only proxy requests whose URI starts with `prefix`; pass others through.
1678    pub fn path_prefix(mut self, prefix: impl Into<String>) -> Self {
1679        self.inner = self.inner.path_prefix(prefix);
1680        self
1681    }
1682
1683    /// Override the TCP connect timeout (default: 5 s).
1684    pub fn connect_timeout_ms(mut self, ms: u64) -> Self {
1685        self.inner = self.inner.connect_timeout_ms(ms);
1686        self
1687    }
1688
1689    /// Override the read timeout (default: 30 s). It bounds each wait for
1690    /// the upstream — the handshake, the response head, every body frame — so
1691    /// a streaming response (a gRPC server stream) ends only when it goes
1692    /// quiet for that long.
1693    pub fn read_timeout_ms(mut self, ms: u64) -> Self {
1694        self.inner = self.inner.read_timeout_ms(ms);
1695        self
1696    }
1697
1698    /// Trust the CA certificates in the PEM file `path` for `h2s://` /
1699    /// `https://` backends instead of the WebPKI roots. Since 18.3.0.
1700    pub fn tls_ca_file(mut self, path: &str) -> Result<Self, String> {
1701        self.inner = self.inner.tls_ca_file(path)?;
1702        Ok(self)
1703    }
1704
1705    /// Present a client certificate to TLS backends that require one (mutual
1706    /// TLS). Since 18.3.0.
1707    pub fn tls_client_cert(mut self, cert: &str, key: &str) -> Result<Self, String> {
1708        self.inner = self.inner.tls_client_cert(cert, key)?;
1709        Ok(self)
1710    }
1711
1712    fn matches(&self, request: &Request) -> bool {
1713        self.inner.path_prefix.as_ref().is_none_or(|prefix| request.request_uri.starts_with(prefix.as_str()))
1714    }
1715}
1716
1717#[cfg(feature = "http2")]
1718impl crate::middleware::Middleware for H2ReverseProxy {
1719    fn handle(
1720        &self,
1721        request: &crate::request::Request,
1722        connection: &crate::server::ConnectionInfo,
1723        next: &dyn crate::application::Application,
1724    ) -> Result<crate::response::Response, String> {
1725        if !self.matches(request) {
1726            return next.execute(request, connection);
1727        }
1728        if self.inner.backends.is_empty() {
1729            let mut response = bad_gateway_for(request);
1730            status::failed(&mut response, status::ProxyError::DestinationUnavailable, None, None);
1731            return Ok(response);
1732        }
1733        // A streamed request body can be sent once: no second backend then.
1734        let attempts = if matches!(request.body, crate::request::Body::Stream(_)) { 1 } else { self.inner.backends.len() };
1735        let n = self.inner.backends.len();
1736        let start = self.inner.counter.fetch_add(1, Ordering::Relaxed);
1737        let mut last_error = String::new();
1738        for attempt in 0..attempts {
1739            let backend = &self.inner.backends[(start + attempt) % n];
1740            let tls = backend.tls.then(|| match &self.inner.trust {
1741                Some(trust) => trust.h2_config(),
1742                None => h2_upstream::default_tls(),
1743            });
1744            let target = h2_upstream::Target {
1745                backend,
1746                tls,
1747                connect_timeout: self.inner.connect_timeout,
1748                read_timeout: self.inner.read_timeout,
1749                authority: None,
1750                server_name: None,
1751            };
1752            match h2_upstream::forward(request, Peer::of(connection), &target) {
1753                Ok(mut response) => {
1754                    status::received(&mut response, None);
1755                    return Ok(response);
1756                }
1757                Err(e) => last_error = e,
1758            }
1759        }
1760        let mut response = bad_gateway_for(request);
1761        status::failed_with(&mut response, &last_error, None);
1762        Ok(response)
1763    }
1764
1765    /// Headers only: a request this proxy doesn't forward passes through
1766    /// untouched.
1767    fn accepts_streamed_body(&self, _request: &Request, _connection: &crate::server::ConnectionInfo) -> bool {
1768        true
1769    }
1770
1771    /// Requests this proxy forwards are sent as their body arrives (gRPC
1772    /// client streaming and bidirectional calls).
1773    fn answers_streamed_body(&self, request: &Request, _connection: &crate::server::ConnectionInfo) -> bool {
1774        self.matches(request)
1775    }
1776}
1777
1778// ── HTTP/3 reverse proxy ──────────────────────────────────────────────────────
1779
1780/// Reverse proxy that forwards requests to `https://` backends over HTTP/3
1781/// (QUIC). Since 18.13.0; requires the `http3` feature (default).
1782///
1783/// A backend QUIC can't reach (UDP blocked, no handshake within the connect
1784/// timeout, a TLS failure) is sent the request over HTTPS on TCP instead,
1785/// and stays on TCP for five minutes; `rws_upstream_h3_fallbacks_total`
1786/// counts it under the proxy's [`name`](Self::name).
1787///
1788/// ```rust,no_run
1789/// # extern crate rws_proxy as rust_web_server;
1790/// use rust_web_server::app::App;
1791/// use rust_web_server::core::New;
1792/// use rust_web_server::proxy::H3ReverseProxy;
1793///
1794/// let proxy = H3ReverseProxy::new(["https://edge1.internal:443", "https://edge2.internal:443"])
1795///     .path_prefix("/api")
1796///     .tls_ca_file("/etc/rws/internal-ca.pem")
1797///     .unwrap();
1798/// let app = App::new().wrap(proxy);
1799/// ```
1800#[cfg(feature = "http3")]
1801pub struct H3ReverseProxy {
1802    inner: ReverseProxy,
1803    name: String,
1804    /// Backends on TCP until the time kept here.
1805    tcp_until: std::sync::Mutex<std::collections::HashMap<String, std::time::Instant>>,
1806}
1807
1808#[cfg(feature = "http3")]
1809impl H3ReverseProxy {
1810    /// A proxy distributing requests across `backends` (`https://host:port`,
1811    /// port 443 by default) in round-robin order. Certificates are checked
1812    /// against the WebPKI roots unless [`tls_ca_file`](Self::tls_ca_file)
1813    /// says otherwise. A backend that isn't `https://` is reached over
1814    /// HTTP/1.1 on TCP.
1815    pub fn new<I, S>(backends: I) -> Self
1816    where
1817        I: IntoIterator<Item = S>,
1818        S: AsRef<str>,
1819    {
1820        H3ReverseProxy { inner: ReverseProxy::new(backends), name: "h3-reverse-proxy".to_string(), tcp_until: std::sync::Mutex::default() }
1821    }
1822
1823    /// The `upstream` label of this proxy's fallback metric.
1824    pub fn name(mut self, name: impl Into<String>) -> Self {
1825        self.name = name.into();
1826        self
1827    }
1828
1829    /// Only proxy requests whose URI starts with `prefix`; pass others through.
1830    pub fn path_prefix(mut self, prefix: impl Into<String>) -> Self {
1831        self.inner = self.inner.path_prefix(prefix);
1832        self
1833    }
1834
1835    /// QUIC handshake (and TCP connect) timeout (default: 5 s).
1836    pub fn connect_timeout_ms(mut self, ms: u64) -> Self {
1837        self.inner = self.inner.connect_timeout_ms(ms);
1838        self
1839    }
1840
1841    /// Longest wait for the backend — the response head and each body
1842    /// chunk (default: 30 s).
1843    pub fn read_timeout_ms(mut self, ms: u64) -> Self {
1844        self.inner = self.inner.read_timeout_ms(ms);
1845        self
1846    }
1847
1848    /// Trust the CA certificates in the PEM file `path` instead of the
1849    /// WebPKI roots.
1850    pub fn tls_ca_file(mut self, path: &str) -> Result<Self, String> {
1851        self.inner = self.inner.tls_ca_file(path)?;
1852        Ok(self)
1853    }
1854
1855    /// Present a client certificate to backends that require one.
1856    pub fn tls_client_cert(mut self, cert: &str, key: &str) -> Result<Self, String> {
1857        self.inner = self.inner.tls_client_cert(cert, key)?;
1858        Ok(self)
1859    }
1860
1861    fn matches(&self, request: &Request) -> bool {
1862        self.inner.path_prefix.as_ref().is_none_or(|prefix| request.request_uri.starts_with(prefix.as_str()))
1863    }
1864
1865    fn on_tcp(&self, key: &str) -> bool {
1866        let mut tcp_until = self.tcp_until.lock().unwrap_or_else(|e| e.into_inner());
1867        match tcp_until.get(key) {
1868            Some(until) if std::time::Instant::now() < *until => true,
1869            Some(_) => {
1870                tcp_until.remove(key);
1871                false
1872            }
1873            None => false,
1874        }
1875    }
1876
1877    /// One attempt at `backend`: HTTP/3 unless it's on TCP, TCP when QUIC
1878    /// can't connect.
1879    fn attempt(&self, backend: &Backend, request: &Request, connection: &crate::server::ConnectionInfo) -> Result<Response, String> {
1880        let key = format!("{}:{}", backend.host, backend.port);
1881        if backend.tls && !self.on_tcp(&key) {
1882            let config = match &self.inner.trust {
1883                Some(trust) => trust.client_config(),
1884                None => tls_client_config(),
1885            };
1886            let target = h3_upstream::Target {
1887                host: &backend.host,
1888                port: backend.port,
1889                authority: None,
1890                tls: &config,
1891                connect_timeout: self.inner.connect_timeout,
1892                read_timeout: self.inner.read_timeout,
1893            };
1894            match h3_upstream::forward(request, Peer::of(connection), &target) {
1895                Err(h3_upstream::H3Error::Connect(e)) => {
1896                    self.tcp_until.lock().unwrap_or_else(|e| e.into_inner()).insert(key.clone(), std::time::Instant::now() + crate::proxy_config::H3_FALLBACK);
1897                    crate::proxy_config::upstream::observe_h3_fallback(&self.name);
1898                    eprintln!("{}: HTTP/3 to {key} failed ({e}); using TCP for {} s", self.name, crate::proxy_config::H3_FALLBACK.as_secs());
1899                }
1900                result => return result.map_err(|e| e.to_string()),
1901            }
1902        }
1903        forward_upstream_trusting(
1904            &self.inner.pool,
1905            request,
1906            Peer::of(connection),
1907            &backend.host,
1908            backend.port,
1909            backend.tls,
1910            self.inner.trust.as_deref(),
1911            self.inner.connect_timeout,
1912            self.inner.read_timeout,
1913        )
1914    }
1915}
1916
1917#[cfg(feature = "http3")]
1918impl crate::middleware::Middleware for H3ReverseProxy {
1919    fn handle(
1920        &self,
1921        request: &crate::request::Request,
1922        connection: &crate::server::ConnectionInfo,
1923        next: &dyn crate::application::Application,
1924    ) -> Result<crate::response::Response, String> {
1925        if !self.matches(request) {
1926            return next.execute(request, connection);
1927        }
1928        if self.inner.backends.is_empty() {
1929            let mut response = bad_gateway_for(request);
1930            status::failed(&mut response, status::ProxyError::DestinationUnavailable, None, None);
1931            return Ok(response);
1932        }
1933        // A streamed request body can be sent once: no second backend then.
1934        let attempts = if matches!(request.body, crate::request::Body::Stream(_)) { 1 } else { self.inner.backends.len() };
1935        let n = self.inner.backends.len();
1936        let start = self.inner.counter.fetch_add(1, Ordering::Relaxed);
1937        let mut last_error = String::new();
1938        for attempt in 0..attempts {
1939            match self.attempt(&self.inner.backends[(start + attempt) % n], request, connection) {
1940                Ok(mut response) => {
1941                    status::received(&mut response, None);
1942                    return Ok(response);
1943                }
1944                Err(e) => last_error = e,
1945            }
1946        }
1947        let mut response = bad_gateway_for(request);
1948        status::failed_with(&mut response, &last_error, None);
1949        Ok(response)
1950    }
1951
1952    fn accepts_streamed_body(&self, _request: &Request, _connection: &crate::server::ConnectionInfo) -> bool {
1953        true
1954    }
1955
1956    /// Requests this proxy forwards are sent as their body arrives.
1957    fn answers_streamed_body(&self, request: &Request, _connection: &crate::server::ConnectionInfo) -> bool {
1958        self.matches(request)
1959    }
1960}
1961
1962/// Forward `request` over HTTP/2 to `url` (`h2://`, `grpc://`, `h2s://`,
1963/// `grpcs://`, `https://` or `host:port`) — the config file's `grpc` action.
1964/// `tls` forces TLS for a bare `host:port` (`[[upstream]] tls = true`).
1965#[cfg(feature = "http2")]
1966#[doc(hidden)]
1967pub fn forward_h2(
1968    request: &Request,
1969    client: Peer<'_>,
1970    url: &str,
1971    tls: bool,
1972    trust: Option<&UpstreamTls>,
1973    connect_timeout: Duration,
1974    read_timeout: Duration,
1975) -> Result<Response, String> {
1976    let mut backend = Backend::parse(url).ok_or_else(|| format!("invalid upstream address '{url}'"))?;
1977    backend.tls |= tls;
1978    let tls = backend.tls.then(|| match trust {
1979        Some(t) => t.h2_config(),
1980        None => h2_upstream::default_tls(),
1981    });
1982    h2_upstream::forward(request, client, &h2_upstream::Target { backend: &backend, tls, connect_timeout, read_timeout, authority: None, server_name: None })
1983}
1984
1985/// Forward over TLS to `ip:port` with `config`, `server_name` as SNI (and
1986/// the name `config`'s verifier checks), `host_header` as the `Host` — the
1987/// Gateway API router's BackendTLSPolicy backends. Connections are pooled
1988/// per `label` (one per distinct policy content).
1989#[cfg(feature = "gateway-api")]
1990#[allow(clippy::too_many_arguments)]
1991#[doc(hidden)]
1992pub fn forward_tls_with_host(
1993    config: &Arc<rustls::ClientConfig>,
1994    label: &str,
1995    request: &Request,
1996    client: Peer<'_>,
1997    ip: &str,
1998    port: u16,
1999    server_name: &str,
2000    host_header: &str,
2001    connect_timeout: Duration,
2002    read_timeout: Duration,
2003) -> Result<Response, String> {
2004    let pool = tls_pool_for_ca(label);
2005    forward_via(pool, request, client, ip, port, host_header, read_timeout, || {
2006        let tcp = connect_tcp(ip, port, connect_timeout)?;
2007        let name = rustls::pki_types::ServerName::try_from(server_name.to_string()).map_err(|e| format!("invalid TLS server name '{server_name}': {e}"))?;
2008        let conn = rustls::ClientConnection::new(Arc::clone(config), name).map_err(|e| e.to_string())?;
2009        Ok(rustls::StreamOwned::new(conn, tcp))
2010    })
2011}
2012
2013/// Forward over cleartext HTTP/2 with prior knowledge (h2c) to `host:port`,
2014/// sending `authority` as `:authority` — the Gateway API router's
2015/// `kubernetes.io/h2c` backends.
2016#[cfg(feature = "gateway-api")]
2017#[doc(hidden)]
2018pub fn forward_h2c_with_host(
2019    request: &Request,
2020    client: Peer<'_>,
2021    host: &str,
2022    port: u16,
2023    authority: &str,
2024    connect_timeout: Duration,
2025    read_timeout: Duration,
2026) -> Result<Response, String> {
2027    let backend = Backend { host: host.to_string(), port, tls: false };
2028    h2_upstream::forward(request, client, &h2_upstream::Target { backend: &backend, tls: None, connect_timeout, read_timeout, authority: Some(authority), server_name: None })
2029}
2030
2031/// Forward over HTTP/2 on TLS to `ip:port` with `config` (offering `h2` by
2032/// ALPN), `server_name` as SNI, sending `authority` as `:authority` — the
2033/// Gateway API router's gRPC and h2c backends a BackendTLSPolicy covers.
2034#[cfg(feature = "gateway-api")]
2035#[allow(clippy::too_many_arguments)]
2036#[doc(hidden)]
2037pub fn forward_h2_tls_with_host(
2038    config: &Arc<rustls::ClientConfig>,
2039    request: &Request,
2040    client: Peer<'_>,
2041    ip: &str,
2042    port: u16,
2043    server_name: &str,
2044    authority: &str,
2045    connect_timeout: Duration,
2046    read_timeout: Duration,
2047) -> Result<Response, String> {
2048    let backend = Backend { host: ip.to_string(), port, tls: true };
2049    let target = h2_upstream::Target { backend: &backend, tls: Some(config), connect_timeout, read_timeout, authority: Some(authority), server_name: Some(server_name) };
2050    h2_upstream::forward(request, client, &target)
2051}
2052
2053// ── gRPC proxy ────────────────────────────────────────────────────────────────
2054
2055/// gRPC reverse proxy middleware.
2056///
2057/// Recognises requests with `Content-Type: application/grpc*` and forwards them
2058/// to a backend over HTTP/2, leaving all other requests to the next layer.
2059///
2060/// Requires the `http2` Cargo feature.
2061///
2062/// # Example
2063///
2064/// ```rust,no_run
2065/// # extern crate rws_proxy as rust_web_server;
2066/// use rust_web_server::app::App;
2067/// use rust_web_server::core::New;
2068/// use rust_web_server::proxy::GrpcProxy;
2069///
2070/// let app = App::new()
2071///     .wrap(GrpcProxy::new(["grpc-service:50051"]));
2072/// ```
2073#[cfg(feature = "http2")]
2074pub struct GrpcProxy {
2075    inner: H2ReverseProxy,
2076}
2077
2078#[cfg(feature = "http2")]
2079impl GrpcProxy {
2080    /// Create a proxy distributing gRPC connections across `backends` in round-robin order.
2081    ///
2082    /// Each backend entry can be:
2083    /// - `"host:port"` — plain TCP (gRPC cleartext)
2084    /// - `"grpc://host:port"` — plain TCP (explicit scheme)
2085    /// - `"grpcs://host:port"` — TLS (gRPC over TLS; port defaults to 443)
2086    /// - `"https://host:port"` — TLS (same as `grpcs://`)
2087    ///
2088    /// TLS backends require the `http2` Cargo feature.
2089    pub fn new<I, S>(backends: I) -> Self
2090    where
2091        I: IntoIterator<Item = S>,
2092        S: AsRef<str>,
2093    {
2094        GrpcProxy { inner: H2ReverseProxy::new(backends) }
2095    }
2096
2097    /// Only proxy requests whose URI starts with `prefix`; pass others through.
2098    pub fn path_prefix(mut self, prefix: impl Into<String>) -> Self {
2099        self.inner = self.inner.path_prefix(prefix);
2100        self
2101    }
2102
2103    /// See [`H2ReverseProxy::connect_timeout_ms`].
2104    pub fn connect_timeout_ms(mut self, ms: u64) -> Self {
2105        self.inner = self.inner.connect_timeout_ms(ms);
2106        self
2107    }
2108
2109    /// See [`H2ReverseProxy::read_timeout_ms`]: a stream quiet for longer ends.
2110    pub fn read_timeout_ms(mut self, ms: u64) -> Self {
2111        self.inner = self.inner.read_timeout_ms(ms);
2112        self
2113    }
2114
2115    /// Trust this CA for `grpcs://` backends. Since 18.3.0.
2116    pub fn tls_ca_file(mut self, path: &str) -> Result<Self, String> {
2117        self.inner = self.inner.tls_ca_file(path)?;
2118        Ok(self)
2119    }
2120
2121    /// Present a client certificate to `grpcs://` backends (mutual TLS).
2122    /// Since 18.3.0.
2123    pub fn tls_client_cert(mut self, cert: &str, key: &str) -> Result<Self, String> {
2124        self.inner = self.inner.tls_client_cert(cert, key)?;
2125        Ok(self)
2126    }
2127}
2128
2129#[cfg(feature = "http2")]
2130impl crate::middleware::Middleware for GrpcProxy {
2131    fn handle(
2132        &self,
2133        request: &crate::request::Request,
2134        connection: &crate::server::ConnectionInfo,
2135        next: &dyn crate::application::Application,
2136    ) -> Result<crate::response::Response, String> {
2137        if is_grpc(request) {
2138            self.inner.handle(request, connection, next)
2139        } else {
2140            next.execute(request, connection)
2141        }
2142    }
2143
2144    fn accepts_streamed_body(&self, _request: &Request, _connection: &crate::server::ConnectionInfo) -> bool {
2145        true
2146    }
2147
2148    fn answers_streamed_body(&self, request: &Request, _connection: &crate::server::ConnectionInfo) -> bool {
2149        is_grpc(request) && self.inner.matches(request)
2150    }
2151}
2152
2153#[cfg(feature = "http2")]
2154fn is_grpc(request: &Request) -> bool {
2155    request.header(crate::header::Header::_CONTENT_TYPE).is_some_and(|h| h.value.starts_with("application/grpc"))
2156}
2157
2158// ── Backend::parse unit tests ─────────────────────────────────────────────────
2159
2160#[cfg(test)]
2161mod backend_parse_tests {
2162    use super::Backend;
2163
2164    fn parse(url: &str) -> Option<(String, u16, bool)> {
2165        Backend::parse(url).map(|b| (b.host, b.port, b.tls))
2166    }
2167
2168    #[test]
2169    fn bare_host_port() {
2170        assert_eq!(Some(("api.example.com".into(), 8080, false)), parse("api.example.com:8080"));
2171    }
2172
2173    #[test]
2174    fn http_scheme() {
2175        assert_eq!(Some(("backend".into(), 3000, false)), parse("http://backend:3000"));
2176    }
2177
2178    #[test]
2179    fn h2_scheme_plain() {
2180        assert_eq!(Some(("svc".into(), 50051, false)), parse("h2://svc:50051"));
2181    }
2182
2183    #[test]
2184    fn grpc_scheme_plain() {
2185        assert_eq!(Some(("svc".into(), 50051, false)), parse("grpc://svc:50051"));
2186    }
2187
2188    #[test]
2189    fn https_scheme_sets_tls_and_default_port() {
2190        assert_eq!(Some(("api.example.com".into(), 443, true)), parse("https://api.example.com"));
2191    }
2192
2193    #[test]
2194    fn https_scheme_explicit_port() {
2195        assert_eq!(Some(("api.example.com".into(), 8443, true)), parse("https://api.example.com:8443"));
2196    }
2197
2198    #[test]
2199    fn h2s_scheme_sets_tls() {
2200        assert_eq!(Some(("svc".into(), 443, true)), parse("h2s://svc"));
2201    }
2202
2203    #[test]
2204    fn h2s_scheme_explicit_port() {
2205        assert_eq!(Some(("svc".into(), 8443, true)), parse("h2s://svc:8443"));
2206    }
2207
2208    #[test]
2209    fn grpcs_scheme_sets_tls() {
2210        assert_eq!(Some(("grpc-svc".into(), 443, true)), parse("grpcs://grpc-svc"));
2211    }
2212
2213    #[test]
2214    fn grpcs_scheme_explicit_port() {
2215        assert_eq!(Some(("grpc-svc".into(), 50052, true)), parse("grpcs://grpc-svc:50052"));
2216    }
2217
2218    #[test]
2219    fn empty_host_returns_none() {
2220        assert_eq!(None, parse("https://"));
2221    }
2222
2223    #[test]
2224    fn bare_host_no_port_defaults_to_80() {
2225        assert_eq!(Some(("myhost".into(), 80, false)), parse("myhost"));
2226    }
2227}