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 is a server-facing intermediary: visitors connect to it, and it forwards eligible requests to an upstream service such as an application server. Unlike a forward proxy configured by a client, this one is deployed in front of services the site operator controls. It can route by hostname or path, manage connections, and optionally terminate TLS. Caddy reverse proxy
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.
In practice
A reverse proxy is useful for isolating application processes from the public network, routing several services under one site and standardizing TLS policy. It also creates an extra dependency to monitor. Pair this mental model with HTTP 502 troubleshooting for upstream failures, HTTP 404 troubleshooting for route mismatches, and CDN for a separate edge-delivery role.
Key takeaways
A reverse proxy is a server-side front door with explicit routing and upstream responsibilities. Determine which rule matched and which upstream was selected before diagnosing a response. Do not assume that adding a proxy automatically enables safe caching, authentication or encrypted upstream transport.
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 .