concept HTTP, TLS & web servers
Reverse proxy
See how a reverse proxy receives public requests and forwards them to one or more upstream applications.
What it means
A reverse proxy receives requests on behalf of one or more upstream services and forwards or handles them according to configured routes. It can terminate client TLS, balance traffic or supply headers, but a successful proxy response does not prove that an upstream application responded correctly. The exact forwarded scheme, host and client identity are trust-boundary decisions. Caddy reverse_proxy HTTP semantics
The proxy is not the application. It can serve as a stable public entrance while an app listens privately, but the result depends on actual configuration and upstream health. Adding a single reverse proxy is not, by itself, high availability.
Try it
Simulation — route a request through a declared front door. Change the synthetic hostname or path and run a request. The selected upstream, matching rule and returned status are shown separately. Only fixed local upstream names are available; the scene cannot forward traffic.
Route through a reverse proxy
Follow a host/path rule to a fixed upstream and separate route selection from upstream health.
The selected fixed upstream returns a valid 200 response.
- Client: www.example.test/api/items
- 1. /api/ prefix
- Gateway → api.internal.test:8000
- Gateway → client: 200
| Item | State / result | Why it matters |
|---|---|---|
| Matched rule | 1. /api/ prefix | Host scope is checked before path rules. |
| Forwarded path | /api/items | No prefix rewrite is modeled. |
| Upstream | api.internal.test:8000 | Only two allowlisted synthetic destinations exist. |
| Front-door response | 200 | No route and selected-but-unavailable upstream are different outcomes. |
Two invented upstreams and explicit rule order; not a Caddy or Nginx configuration emulator.
About this model
The specific /api/ prefix is evaluated before the catch-all. Disabling it sends /api/ paths to the web upstream. Status mappings are declared fixture behavior, not a universal response to every gateway failure. Paths never select arbitrary destinations.
Read the article’s primary sources for protocol rules and implementation-specific limits. This scene has no network access.
The default policy checks the /api/ prefix before its site catch-all. /api/items goes to the API fixture, while /guide goes to the site fixture. Change the policy to catch-all only and compare the same API path: it now reaches the site fixture. A rule's order and matching boundary matter, not just the existence of two upstreams.
| Request or condition | Selected fixture | Declared outcome |
|---|---|---|
/api/items under the default policy | API on internal port 8000 | The API response |
/guide under the default policy | Site on internal port 8080 | The site response |
Bare /api without the trailing slash | Site catch-all | The exact prefix rule does not match |
| Unknown hostname | No configured route | 404 from this front door |
| Matched but unavailable upstream | The selected upstream still matters | 502 under this fixture's error policy |
An upstream failure is not the same observation as an unmatched public route. Real proxies can map transport failures and timeouts differently; the statuses here are explicit teaching rules, not an assertion about all Caddy configurations. External URLs, traversal and unsupported path syntax are rejected rather than becoming open-proxy targets.
Reset restores the default host, /api/items, specific-before-catch-all policy and both available upstreams. TLS verification, load balancing, cache eligibility, retries and authentication are separate features not implemented by this scene. Proxy configuration capabilities Gateway and status semantics
What the proxy can and cannot do
| Capability | Important condition |
|---|---|
| Route hostnames or paths | The matching and rewriting rules must reflect app expectations |
| Terminate public HTTPS | TLS is authenticated at the public endpoint; upstream security is separate |
| Balance requests | Multiple healthy upstreams and an appropriate policy must actually exist |
| Add forwarded information | Only correctly trusted proxy chains should supply client identity |
| Cache or compress | An additional configured behavior, not automatic for every proxy |
Caddy documents upstream selection, transports, header controls and health checks as configurable features, not automatic guarantees. Forwarded headers such as X-Forwarded-For can be spoofed if an application trusts arbitrary clients; define which proxy hops are trusted. Header handling
How to reason about a failure
- Is the public hostname resolving and the public TLS handshake valid? If not, investigate before application routing.
- Does the proxy route this exact hostname and path? A missing rule may return
404even while the upstream is healthy. - Is the intended upstream reachable from the proxy, listening on the selected socket and producing valid HTTP responses? A failing connection can surface as a proxy error.
- Do logs on the proxy and application agree on a sanitized request ID, time window and status? Remove tokens and personal data from any shared traces.
- If TLS is terminated twice, verify the upstream certificate independently. Do not turn off certificate verification as an expedient fix.
The public request and the upstream request differ
A visitor requests https://example.test/app. The proxy may send an HTTP request to an internal upstream while keeping the client connection under TLS. The browser does not learn the private upstream address merely because the proxy used it. A different route might point to a down or misconfigured service and produce a gateway error even though the proxy itself is reachable. Forwarded headers can be useful for application logging but should not be accepted as trusted identity when supplied by arbitrary external clients. The scene models request routing, not live proxy configuration. Proxy behavior
In practice
In authorized read-only checks, follow one request from public route through proxy rule to upstream, recording method, host, response status and relevant logs on both sides. Before a config change, save the exact previous route and confirm that upstream health and TLS expectations are correct. If upstream attribution is uncertain, stop instead of broadening access or bypassing identity checks.
Key takeaways
A reverse proxy adds an explicit routing and trust layer. Diagnose client-to-proxy and proxy-to-upstream separately, and assign ownership for TLS, headers and upstream availability before publishing changes.
Frequently asked questions
Editorial questions, answered from the sources listed for this article.
Can a reverse proxy serve multiple domains?
Yes. Host-based routing can direct requests for different names to different upstreams if the configuration and certificates support those names.
Does an upstream always see the visitor IP as its TCP peer?
No. It commonly sees the proxy peer. Forwarded information depends on trusted proxy configuration and should not be blindly treated as an authenticated client identity.
Can a proxy use TLS on both sides?
Yes. Client-to-proxy and proxy-to-upstream connections can each have their own TLS configuration and identity verification.
Does a reverse proxy automatically cache every response?
No. Routing and caching are separate capabilities and policies; the HTTP response and intermediary configuration determine cache behavior.
Sources & model boundaries
Primary references used for this explanation. The interactive example is an educational model, not a live check.
- Caddy Documentation — reverse_proxy
Upstreams, load balancing, headers, transport and health checks. Reverse proxy upstream selection, forwarded headers, optional TLS transport and health checks.
Checked .
- RFC 9110 — HTTP Semantics
Sections 6, 8, 9 and 15. HTTP messages, methods, representations and status codes.
Checked .
- RFC 9846 — The Transport Layer Security (TLS) Protocol Version 1.3
TLS 1.3 security properties and connection boundaries; verified erratum 9040 reviewed, version negotiation not modeled. TLS 1.3 confidentiality, integrity and authentication boundaries. Obsoletes RFC 8446; the scene is not a handshake or version-negotiation implementation.
Checked .