# Reverse Proxy

> HTTP/1.1 reverse proxy middleware with round-robin load balancing, path filtering, automatic failover, and built-in keep-alive connection pooling.

Source: https://rws8.tech/docs/proxy/reverse-proxy/ · Last updated 2026-11-04

`ReverseProxy` is a [`Middleware`](/building-apps/middleware/) that forwards incoming HTTP/1.1 requests to one or more backends. It lives in `crates/rws-proxy/src/proxy/mod.rs` and requires no feature flags.

## Basic usage

```rust
use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::proxy::ReverseProxy;

// All requests forwarded round-robin across two backends.
let app = App::new()
    .wrap(ReverseProxy::new(["http://backend-1:8080", "http://backend-2:8080"]));
```

## Selective proxying with `path_prefix`

By default every request is proxied. Use `.path_prefix()` to restrict proxying to a specific path prefix; all other requests fall through to the inner application.

```rust
// Only proxy /api/* — other paths are handled locally.
let app = App::new()
    .wrap(ReverseProxy::new(["http://api-service:3000"])
        .path_prefix("/api"));
```

## Load balancing strategy

`ReverseProxy` accepts a `.strategy()` builder for future extensibility. The only active strategy is round-robin.

```rust
use rust_web_server::proxy::{LoadBalancing, ReverseProxy};

let proxy = ReverseProxy::new(["http://a:8080", "http://b:8080"])
    .strategy(LoadBalancing::RoundRobin); // default; explicit for clarity
```

The counter is a lock-free `AtomicUsize` incremented on every request. The backend index is `counter % backend_count`, giving a uniform cyclic distribution with no mutex overhead.

## Timeouts

```rust
let proxy = ReverseProxy::new(["http://backend:8080"])
    .connect_timeout_ms(3_000)   // TCP connect timeout (default: 5 000 ms)
    .read_timeout_ms(60_000);    // Response read timeout (default: 30 000 ms)
```

The write timeout for the forwarded request is always 10 seconds (not configurable via the builder today).

## Automatic failover

When a backend connection fails, `ReverseProxy` tries the next backend in round-robin order. Only after all backends have failed does it return `502 Bad Gateway`.

```
request → backend-1 fails → backend-2 fails → 502 Bad Gateway
request → backend-1 fails → backend-2 OK    → response forwarded
```

## Headers

### Hop-by-hop headers stripped

The following headers are never forwarded to the upstream or back to the client, per RFC 7230:

- `Connection`
- `Keep-Alive`
- `Proxy-Authenticate`
- `Proxy-Authorization`
- `TE`
- `Trailer`
- `Proxy-Connection`
- `Transfer-Encoding`
- `Upgrade`
- any header named in the client's `Connection` header
- `Content-Length` (regenerated from the body that is actually sent)

### Headers added to forwarded requests

| Header | Value |
|--------|-------|
| `X-Forwarded-For` | Client IP from `ConnectionInfo`, appended to an incoming `X-Forwarded-For` (`203.0.113.7, 10.0.0.1`) — like nginx's `$proxy_add_x_forwarded_for`; only trust the entries your own proxies added |
| `Via` | `1.1 rws` |
| `Host` | Backend host (replaces the original `Host` header) |
| `X-Forwarded-Host` | The `Host` the client sent, unless it already carries an `X-Forwarded-Host` (since 18.8.4) |
| `X-Forwarded-Proto` | `https` when the client connected over TLS (HTTPS, HTTP/2 over TLS, HTTP/3), else `http`; an incoming `X-Forwarded-Proto` is kept, so rws behind another TLS terminator passes its answer on (since 18.9.0) |
| `Forwarded` | RFC 7239: `for=<client>;proto=<http|https>;host=<Host>` (IPv6 as `for="[2001:db8::1]"`), appended to an incoming `Forwarded` like `X-Forwarded-For` (since 18.20.0). From a trusted proxy that sent only `X-Forwarded-*`, its hops come first, the client's with the proto and host it reported (`for=198.51.100.7;proto=https;host=app.example, for=10.0.0.2;proto=http;…`, since 18.27.0). `forwarded_header = "off"` (`RWS_CONFIG_FORWARDED_HEADER`) leaves it out and passes the client's through unchanged |

**Which incoming values are believed** (since 18.24.0): an incoming
`X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host` or `Forwarded` is
kept only when the connection comes from a `trusted_proxies` address —
loopback and the private ranges (`10.0.0.0/8`, `172.16.0.0/12`,
`192.168.0.0/16`, `100.64.0.0/10`, `fc00::/7`) by default, where load
balancers usually sit. From anyone else they're dropped and rws sends its own,
so a client on the internet can't tell your app it arrived over `https` or for
another host. Behind a public CDN, list its ranges; `"*"` trusts everyone (the
behaviour before 18.24), `"none"` no one:

```toml
trusted_proxies = ["10.0.0.0/8", "173.245.48.0/20", "2400:cb00::/32"]   # RWS_CONFIG_TRUSTED_PROXIES
```

### The client address

Behind a load balancer every connection comes from the balancer. Since
18.27.0, when the peer is a `trusted_proxies` address, rws takes the client
from its `X-Forwarded-For` the way nginx's `real_ip_recursive` does: it walks
the list from the right, skips addresses that are themselves trusted, and
uses the first one that isn't (a client can prepend anything, so the left end
is never believed). With no `X-Forwarded-For` it reads `Forwarded: for=`.
From an untrusted peer both are ignored and the peer is the client.

That address is what the rate limit, `allow_ips` / `deny_ips`, the
blocklist, WAF IP rules, `ip_hash` load balancing, the access and request
logs, FastCGI `REMOTE_ADDR`, admin audit lines and Wasm plugins see. The
`X-Forwarded-For` rws sends upstream still appends the peer, so the chain
stays intact. To key everything on the TCP peer again:

```toml
client_ip = "peer"   # RWS_CONFIG_CLIENT_IP: "forwarded" (default) or "peer"
```

The same trusted peer's `X-Forwarded-Proto` (else `Forwarded: proto=`)
says whether the client used HTTPS, for the URLs rws hands back to it: the
A2A agent card's interface, the OIDC client's redirect URI (when none is
configured), its cookies' `Secure` flag, and the `X-Forwarded-Proto` and
`X-Forwarded-For` forward-auth sends. Before 18.28.0 a TLS-terminating load
balancer made them all `http`. In code: `ip_filter::request_scheme(request,
peer, tls)`.
| `Connection` | `keep-alive` (pooled path) or `close` (non-pooled callers) |
| `Content-Length` | Length of the forwarded body (exactly one) |

## Connection pooling

`ReverseProxy` ships with a built-in `ConnPool` that reuses idle TCP connections to backends (`https://` backends share a process-wide pool of TLS connections). When a backend responds with `Connection: keep-alive` and a fixed-size body (`Content-Length`), the stream is returned to the pool and reused for the next request to the same backend.

Streaming responses (SSE, chunked, large downloads) are forwarded directly to the client without buffering — see [Streaming responses](#streaming-responses).

**Defaults:** 64 idle connections per backend, 60-second idle timeout. No configuration needed.

### Tuning the built-in pool

```rust
use rust_web_server::proxy::ReverseProxy;

let proxy = ReverseProxy::new(["http://backend:8080"])
    .max_idle_conns(32);   // up to 32 idle connections per backend
```

### Sharing a pool across proxy instances

Useful when two `ReverseProxy` instances route to overlapping backends (e.g., an API proxy and an auth proxy both reach the same service).

```rust
use std::sync::Arc;
use std::time::Duration;
use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::proxy::{ConnPool, ReverseProxy};

let pool = Arc::new(ConnPool::new(32, Duration::from_secs(120)));

let api  = App::new().wrap(
    ReverseProxy::new(["http://api:3000"]).with_pool(Arc::clone(&pool)));
let auth = App::new().wrap(
    ReverseProxy::new(["http://auth:4000"]).with_pool(Arc::clone(&pool)));
```

### How pooling works

| Backend response | Pool action |
|-----------------|-------------|
| `Connection: keep-alive` + `Content-Length` ≤ 1 MB | Stream returned to pool after body is read |
| `Transfer-Encoding: chunked` | Streamed to client (re-framed); connection not pooled |
| `Content-Type: text/event-stream` | Streamed to client (chunked re-encoding); connection not pooled |
| `Content-Length` > 1 MB | Streamed to client with the same `Content-Length`; connection not pooled |
| `Connection: close` or EOF | Stream dropped; TCP connection closed |
| Idle stream older than `idle_timeout` | Evicted on next `acquire()` |
| Pool at `max_idle` for this backend | Extra stream dropped (TCP closed) |

:::tip
Connection pooling is most impactful when backends and the proxy share a network (low-latency link). On high-throughput routes, pooling eliminates per-request TCP handshake latency entirely.
:::

## Backend URL format

Backend strings accept any of these forms:

```
https://host:port     # TLS, verified against the WebPKI roots; port defaults to 443
http://host:port      # scheme stripped, plain TCP
h2://host:port        # treated as plain TCP
host:port             # bare host:port
host                  # port defaults to 80
```

:::note[TLS to upstream]
`https://` backends are reached over TLS (rustls), with the certificate
verified against the WebPKI root store — the CA bundle browsers use. TLS
connections are pooled like plain ones, so the handshake is paid once per
connection, not per request. For a backend with a private-CA or
self-signed certificate, trust that CA instead of the public roots:

```rust
let proxy = ReverseProxy::new(["https://billing.internal:8443"])
    .tls_ca_file("/etc/rws/internal-ca.pem")?;   // PEM; replaces the WebPKI roots
```

A backend that requires a client certificate (mutual TLS) gets the one you
give it (since 18.3.0):

```rust
let proxy = ReverseProxy::new(["https://billing.internal:8443"])
    .tls_client_cert("/etc/rws/client.pem", "/etc/rws/client.key")?;  // PEM chain + private key
```
:::

## Streaming responses

`ReverseProxy` detects streaming backend responses and forwards bytes to the client as they arrive, without buffering the full body in memory. A response is streamed when any of these conditions are true:

| Condition | Use case |
|-----------|----------|
| `Content-Type: text/event-stream` | SSE / Server-Sent Events |
| `Transfer-Encoding: chunked` | AI token streams (OpenAI, Anthropic, etc.) |
| `Content-Length` > 1 MB | Large file downloads |

### How it works

1. The proxy reads only the response headers from the backend.
2. It creates a `Response` with the parsed headers and sets `Response::stream_pipe` to a reader backed by the live backend TCP connection.
3. The server detects `stream_pipe` and calls `Server::pipe_stream()`:
   - **Chunked backend**: the frames are decoded and framed again, so the body ends at the backend's last chunk (upstream trailers are not forwarded over HTTP/1.1).
   - **`Content-Length` body** (a large download): the length is kept and exactly that many bytes are copied, unframed, so the client can tell a complete body from a cut one.
   - **SSE / body of unknown length**: bytes are re-encoded as `Transfer-Encoding: chunked` so the client receives each fragment immediately.

   A streamed body ends at its `Content-Length` or last chunk, never by waiting on the backend's kept-alive connection. Reads and writes are up to 64 KiB. If the backend fails or closes early, the body is not ended (no final chunk, fewer bytes than the `Content-Length`) and the connection is closed, so the client sees a failed transfer rather than a short body that looks complete.

Streamed connections are never returned to the `ConnPool` — the backend socket is consumed by the pipe.

### SSE through the proxy

```rust
use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::proxy::ReverseProxy;

// All SSE responses from the backend are forwarded without buffering.
let app = App::new()
    .wrap(ReverseProxy::new(["http://event-service:9000"])
        .path_prefix("/events"));
```

The client connects with `Accept: text/event-stream` as usual. The proxy transparently forwards each SSE event as a chunked frame the moment it arrives from the backend.

### AI token stream through the proxy

```rust
use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::proxy::ReverseProxy;

// OpenAI / Anthropic APIs send Transfer-Encoding: chunked.
// The proxy forwards each token chunk without waiting for the full response.
let app = App::new()
    .wrap(ReverseProxy::new(["https://api.openai.com"])
        .path_prefix("/v1"));
```

### Custom stream_pipe (application code)

Any application handler can use `stream_pipe` to stream arbitrary `Read` sources:

```rust
use rust_web_server::response::{Response, STATUS_CODE_REASON_PHRASE};

fn my_handler(_req: &_, _params: &_, _conn: &_, _state: &_) -> Response {
    let mut r = Response::new();
    r.status_code = *STATUS_CODE_REASON_PHRASE.n200_ok.status_code;
    r.reason_phrase = STATUS_CODE_REASON_PHRASE.n200_ok.reason_phrase.to_string();
    // Any std::io::Read + Send value works: files, cursors, sockets, generators …
    r.stream_pipe = Some(Box::new(std::io::Cursor::new(b"data: hello\n\n".to_vec())));
    r
}
```

## HTTP/3 backends

`H3ReverseProxy` forwards to `https://` backends over HTTP/3 (QUIC), with the
same builder methods as `ReverseProxy` (since 18.13.0, `http3` feature —
the default):

```rust
use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::proxy::H3ReverseProxy;

let proxy = H3ReverseProxy::new(["https://edge1.internal:443", "https://edge2.internal:443"])
    .path_prefix("/api")
    .tls_ca_file("/etc/rws/internal-ca.pem")?  // or the WebPKI roots by default
    .name("edge");                            // the fallback metric's upstream label
let app = App::new().wrap(proxy);
```

One multiplexed QUIC connection per backend is reused across requests;
bodies stream both ways and trailers are kept. A backend QUIC can't reach is
sent the request over HTTPS on TCP and stays on TCP for 5 minutes,
counted by `rws_upstream_h3_fallbacks_total{upstream="edge"}`. In the config
file the same is `[[upstream]] protocol = "h3"` — see
[HTTP/3 upstreams](/proxy/config-driven/#http3-upstreams).

## When a backend fails: `Proxy-Status`

When every attempt fails the client gets `502 Bad Gateway` (or `503`
when every backend is out of rotation), as
[problem details](/reference/errors/). Every proxied response, the
successful ones too, carries a `Proxy-Status` header
([RFC 9209](https://www.rfc-editor.org/rfc/rfc9209), since 18.17.0) saying
what this hop saw:

```http
Proxy-Status: rws; received-status=200
Proxy-Status: rws; error=connection_refused
Proxy-Status: rws; error=http_response_timeout
```

| `error=` | When |
|---|---|
| `dns_error` | The backend's name didn't resolve |
| `connection_refused` | Nothing listens on the backend's port |
| `connection_timeout` | The connection (or TLS handshake) took longer than the connect timeout |
| `destination_ip_unroutable` | No route to the backend's address |
| `destination_unavailable` | No backend in rotation (health checks, circuit breaker, drained) |
| `tls_certificate_error` / `tls_protocol_error` | The backend's certificate wasn't trusted / the TLS handshake failed |
| `http_response_timeout` | No response head within the read timeout |
| `connection_terminated` | The backend closed or reset the connection before answering |
| `http_response_incomplete` | The body ended early |
| `http_protocol_error` | The response wasn't valid HTTP |
| `proxy_configuration_error` | A backend address or TLS setting rws can't use |

A `Proxy-Status` from the backend (another proxy behind this one) is kept,
and rws's member is added after it, nearest the client last. Settings (all
top-level in the config file):

```toml
proxy_status          = "always"  # RWS_CONFIG_PROXY_STATUS: "errors" = failures only, "off" = never
proxy_name            = "edge-1"  # RWS_CONFIG_PROXY_NAME: this hop's name (default "rws")
proxy_status_next_hop = false     # RWS_CONFIG_PROXY_STATUS_NEXT_HOP: add next-hop (backend address) and details (the error text)
```

`next-hop` and `details` name internal addresses, so they're off unless you
turn them on; turn them on inside your own network, where they make a
failed request explain itself.

## Combining with other middleware

Because `ReverseProxy` implements `Middleware`, you can stack it with rate limiting, auth, rewriting, and any other middleware via `.wrap()`.

```rust
use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::proxy::ReverseProxy;
use rust_web_server::rate_limit::RateLimitLayer;

let app = App::new()
    .wrap(RateLimitLayer::new(100, 60))   // 100 req/min per IP
    .wrap(ReverseProxy::new(["http://backend:3000"])
        .path_prefix("/api"));
```

Middleware is applied outermost-first, so `RateLimitLayer` runs before `ReverseProxy`.
