A web server does more than simply receive an HTTP request and return a response. Modern applications often require several processing steps, including authentication, redirects, header manipulation, compression, caching, and reverse proxying. Caddy handles these operations through a powerful request-processing architecture known as the HTTP handler chain.
Understanding how Caddy’s handler chain works is particularly useful when configuring reverse proxies or troubleshooting unexpected request behavior. Instead of treating each configuration directive as an isolated instruction, administrators can understand Caddy as a sequence of handlers that process a request in a defined order.
This article explains the fundamentals of Caddy’s HTTP handler chain, how handlers interact, and how the chain affects real-world web traffic.
What Is a Caddy HTTP Handler?
In Caddy, an HTTP handler is a component responsible for performing a specific operation on an incoming request.
Depending on the configuration, a handler may:
- Serve static files
- Redirect requests
- Rewrite URLs
- Add or modify headers
- Authenticate clients
- Compress responses
- Proxy requests to an upstream application
- Return a specific HTTP response
Handlers are generally organized into a chain. A request enters the chain and passes through handlers until one of them produces a response or delegates processing to the next handler.
A simplified representation looks like this:
Client Request
|
v
Handler 1
|
v
Handler 2
|
v
Handler 3
|
v
Application
|
v
HTTP Response
This architecture gives Caddy considerable flexibility when processing requests.
How the Handler Chain Processes Requests
When Caddy receives an HTTP request, it first determines which site configuration and routing rules apply. The relevant handlers are then executed according to the resulting route structure.
Consider a simple configuration:
example.com {
reverse_proxy localhost:8080
}
Here, Caddy receives the request and eventually passes it to the reverse proxy handler. The reverse proxy forwards the request to the application listening on port 8080.
A more complex configuration might perform several operations first:
Client
|
v
Authentication
|
v
Request Rewrite
|
v
Header Processing
|
v
Reverse Proxy
|
v
Application
Each stage can influence what happens to the request before it reaches the backend.
Directive Order and Handler Order
One important concept is that the order in which directives appear in a Caddyfile does not always directly determine their execution order.
Caddy uses a defined directive ordering system when adapting the Caddyfile into its underlying JSON configuration. This means administrators should understand Caddy’s routing and handler ordering rather than assuming that configuration lines are always executed strictly from top to bottom.
For example, a configuration containing authentication, rewriting, and reverse proxying may be adapted into a handler chain where those operations execute according to Caddy’s routing rules.
When precise control is required, explicit routes can make the intended processing sequence clearer.
Matchers Determine Which Requests Are Processed
Handlers can be combined with request matchers to apply processing only to specific requests.
For example:
example.com {
@api path /api/*
reverse_proxy @api localhost:8080
}
The @api matcher identifies requests beginning with /api/.
A request such as:
matches the rule and is forwarded to the backend.
A request for:
does not match that particular rule and can be handled by another configured handler.
Matchers therefore act as decision points within the request-processing architecture.
Routes and Nested Handler Chains
Caddy supports routes that allow administrators to group handlers together.
For example:
example.com {
route {
header {
X-Example “enabled”
}
reverse_proxy localhost:8080
}
}
The route block establishes an explicit processing sequence.
This is useful when multiple operations must occur in a particular order. Instead of relying entirely on global directive ordering, administrators can define a route containing the handlers that should execute together.
Conceptually:
Request
|
v
Route
|
+–> Header Handler
|
+–> Reverse Proxy Handler
|
v
Backend
Middleware and Terminal Handlers
Many Caddy HTTP handlers behave like middleware. Middleware can perform an operation and then continue processing the request through the remaining chain.
For example, a handler might inspect a request, add a header, and then pass control to the next handler.
Other handlers can be effectively terminal. A static file handler that successfully serves a requested resource may generate the response without passing the request to a backend.
This distinction is important when troubleshooting because a handler that terminates processing can prevent subsequent handlers from executing.
Reverse Proxy as a Handler
The reverse proxy handler is one of the most common components in Caddy deployments.
Consider:
example.com {
reverse_proxy localhost:3000
}
The request flow becomes:
Browser
|
v
Caddy
|
v
Reverse Proxy Handler
|
v
Application :3000
The application receives the forwarded request and generates a response. Caddy then returns that response to the client.
Because reverse proxying occurs within the handler architecture, additional processing can be performed before or around the proxy operation.
Why Handler Ordering Matters
Incorrect handler ordering can produce unexpected results.
For example, suppose an administrator wants authentication to happen before a request reaches the application. If the authentication logic does not execute before the proxy handler, unauthorized requests might reach the backend.
Similarly, a rewrite performed at the wrong stage can cause the backend to receive an unexpected URL.
Common symptoms of handler-order problems include:
- Unexpected redirects
- Authentication being bypassed
- Incorrect URL paths
- Headers not being applied
- Static files being served instead of proxied
- Requests reaching the wrong backend
- Unexpected 404 or 403 responses
Understanding the actual handler chain helps identify these problems much faster.
Troubleshooting the Handler Chain
When a Caddy configuration behaves unexpectedly, start by determining which request should match the configuration.
Check the:
- Hostname being requested
- Request path
- HTTP method
- Request matcher
- Route structure
- Handler ordering
- Upstream configuration
Caddy’s JSON configuration representation can also be useful for understanding how a Caddyfile has been adapted into the actual server configuration.
Logging is another valuable troubleshooting tool. Access logs can reveal whether a request reached Caddy, which status code was returned, and whether the issue appears to originate from Caddy or the upstream application.
Testing the backend independently can further isolate the problem. For example:
curl http://127.0.0.1:8080
If the backend responds correctly but the public request fails, attention should shift toward Caddy’s routing, handlers, TLS, or network configuration.
Best Practices for Designing Handler Chains
A well-organized Caddy configuration should be easy to understand and troubleshoot.
Use explicit matchers when different applications or paths require different behavior. Group related operations into routes when processing order matters. Keep authentication and security controls close to the request-processing logic they protect.
Avoid unnecessary complexity. A short configuration with clearly defined routes is generally easier to maintain than a large collection of overlapping matchers.
Administrators should also test configuration changes before deploying them to production and maintain useful access logs for troubleshooting.
Conclusion
Caddy’s HTTP handler chain is the foundation of its request-processing architecture. Rather than treating Caddy as a simple web server, it is useful to view it as a collection of handlers that process requests through routing, matching, middleware, and terminal operations.
Understanding this architecture makes it easier to design reverse proxies, authentication systems, URL rewrites, and application routing. More importantly, it provides a practical framework for troubleshooting unexpected behavior.
When a request does not produce the expected result, examining the matchers, routes, handler order, and upstream service can reveal exactly where the request flow differs from the intended design. This makes Caddy’s handler chain an essential concept for anyone managing Caddy in production environments.
Facing issues?
Our technical support
engineers can solve it.
