HTTP Handlers and Middleware

Relevant source files

• caddyconfig/httpcaddyfile/serveroptions.go
• caddytest/integration/caddyfile_adapt/reverse_proxy_trusted_proxies_unix.caddyfiletest
• modules/caddyhttp/app.go
• modules/caddyhttp/caddyhttp.go
• modules/caddyhttp/matchers.go
• modules/caddyhttp/matchers_test.go
• modules/caddyhttp/routes.go
• modules/caddyhttp/server.go
• modules/caddyhttp/server_test.go

This page documents Caddy's HTTP handler and middleware architecture, including the core handler interfaces, middleware chaining mechanism, route compilation, and request/response flow. For details on specific built-in handlers, see Reverse Proxy, Static File Server, Response Encoding, and Templates. For information about request matching, see Matchers and Routing.

Purpose and Scope

HTTP handlers are modular components that process HTTP requests and generate responses. Handlers can act as middleware (modifying requests/responses and passing control to the next handler) or as responders (originating the response). This document covers:

• Core handler and middleware interfaces
• Handler chaining and compilation mechanisms
• Route structures and matcher integration
• Request/response lifecycle through handler chains
• Error handling patterns
• Overview of built-in handlers

Core Handler Interfaces

Caddy defines two primary handler interfaces that form the foundation of request processing:

Handler Interface

The Handler interface is similar to Go's standard http.Handler but returns an error. Handlers may modify the request, generate a response, invoke other handlers, or return an error to trigger error handling.

Handler Diagram

Sources: modules/caddyhttp/caddyhttp.go59-76 modules/caddyhttp/caddyhttp.go94-112

MiddlewareHandler Interface

The MiddlewareHandler interface takes a third parameter: the next handler in the chain. Middleware handlers typically:

1. Modify the request (e.g., add headers, rewrite path)
2. Call next.ServeHTTP(w, r) to continue the chain
3. Modify the response on the way back
4. Return any errors encountered

Handlers that originate responses (e.g., reverse_proxy, file_server) typically do not invoke the next handler.

Sources: modules/caddyhttp/caddyhttp.go81-92

Middleware Function Type

The Middleware type is a function that wraps a Handler, returning a new Handler. This enables functional composition of handlers into a chain. The wrapMiddleware() and wrapRoute() functions convert MiddlewareHandler and Route types into Middleware functions for chain compilation.

Sources: modules/caddyhttp/caddyhttp.go77-79 modules/caddyhttp/routes.go236-301 modules/caddyhttp/routes.go303-322

Handler Chaining Mechanism

Caddy compiles handlers into a middleware chain where each handler can delegate to the next. The chain is built in reverse order and executes in forward order.

Handler Chain Compilation

Sources: modules/caddyhttp/routes.go220-234

Compilation Process

The RouteList.Compile() method builds the handler chain:

1. Create middleware list: Convert each route to a Middleware function using wrapRoute()
2. Build stack in reverse: Starting with a terminal handler (usually emptyHandler), wrap each middleware around the previous handler
3. Return top of stack: The outermost handler becomes the entry point

Sources: modules/caddyhttp/routes.go220-234

Request and Response Flow

Requests flow down the chain (first handler to last), while responses flow up the chain (last handler to first):

Request/Response Flow Diagram

Sources: modules/caddyhttp/routes.go69-89

Key Insight: Handlers that modify responses must be placed before handlers that originate responses in the handler list, because the response flows back up. For example, encode must come before file_server so that encoding can wrap the response writer before the file is written.

Routes and Request Matching

Routes combine matchers with handler chains to enable conditional request processing.

Route Structure

Sources: modules/caddyhttp/routes.go25-100

Route Evaluation Flow

The wrapRoute() function creates a middleware that:

1. Evaluates matchers: Checks if MatcherSets.AnyMatchWithError() returns true
2. Checks route group: If the route belongs to a group, ensures no other route in the group has matched
3. Handles terminal routes: If Terminal is true, replaces the next handler with emptyHandler or errorEmptyHandler
4. Compiles handler chain: Wraps the route's handlers around the next handler
5. Executes chain: Calls the compiled handler

Route Matching and Execution

Sources: modules/caddyhttp/routes.go236-301

Matcher Sets (AND/OR Logic)

Routes use MatcherSets, which are groups of MatcherSet. Each MatcherSet is a list of matchers that are AND'ed together, while MatcherSets are OR'ed together:

• MatcherSet: All matchers must match (AND)
• MatcherSets: Any matcher set must match (OR)

Sources: modules/caddyhttp/routes.go324-439

Handler Compilation and Provisioning

Handlers undergo a multi-stage lifecycle: unmarshaling, provisioning, validation, and compilation.

Provisioning Stages

Handler Lifecycle

Sources: modules/caddyhttp/routes.go123-170 modules/caddyhttp/routes.go303-322 modules/caddyhttp/app.go366-375

Handler Provisioning

The Route.ProvisionHandlers() method:

1. Loads handler modules from HandlersRaw JSON
2. Appends loaded handlers to route.Handlers
3. Pre-compiles middleware by wrapping each handler with wrapMiddleware()
4. Stores wrapped middleware in route.middleware

Sources: modules/caddyhttp/routes.go149-170

Metrics Instrumentation

When metrics are enabled, wrapMiddleware() wraps handlers with metricsInstrumentedHandler to track handler invocations and durations:

Sources: modules/caddyhttp/routes.go303-322

Request Processing Flow

When a request enters Caddy, it flows through several layers before reaching the handler chain.

Server.ServeHTTP Entry Point

The Server.ServeHTTP() method is the entry point for all HTTP requests. It:

1. Sets the Server header
2. Advertises HTTP/3 via Alt-Svc header if enabled
3. Prepares the request with PrepareRequest() (adds context, replacer, vars)
4. Handles ACME HTTP challenges via tlsApp.HandleHTTPChallenge()
5. Calls s.serveHTTP() to execute the primary handler chain
6. Handles errors via s.errorHandlerChain if an error is returned

Server Request Processing

Sources: modules/caddyhttp/server.go299-459 modules/caddyhttp/server.go920-946

PrepareRequest Context Setup

The PrepareRequest() function enriches the request with context values needed throughout the handler chain:

Context Key	Value	Purpose
caddy.ReplacerCtxKey	*caddy.Replacer	Variable substitution
ServerCtxKey	*Server	Access to server configuration
VarsCtxKey	map[string]any	Handler-specific variables, including TrustedProxyVarKey and ClientIPVarKey
routeGroupCtxKey	map[string]struct{}	Track satisfied route groups
OriginalRequestCtxKey	http.Request	Original request for error handling
ExtraLogFieldsCtxKey	*ExtraLogFields	Additional fields for access logs

Sources: modules/caddyhttp/server.go920-946 modules/caddyhttp/server.go969-1017

Primary Handler Chain Execution

The Server.serveHTTP() method performs validation and executes the primary handler chain:

1. Validates method length: Rejects methods longer than 32 characters
2. Validates Host header: Returns 400 if Host header is empty (RFC 9112)
3. Executes handler chain: Calls s.primaryHandlerChain.ServeHTTP(w, r)
4. Enforcement checks: The primary chain is wrapped by wrapPrimaryRoute(), which runs enforcementHandler() for security checks (e.g., strict SNI-Host matching)

Sources: modules/caddyhttp/server.go461-488 modules/caddyhttp/server.go490-519

Built-in Handlers

Caddy includes several built-in handlers that cover common web server tasks. This section provides an overview; see the linked subsections for detailed information.

Handler Registry

Built-in handlers are registered in the http.handlers namespace:

Handler	Module ID	Purpose	Details
reverse_proxy	http.handlers.reverse_proxy	Proxies requests to upstream servers with load balancing and health checks	Reverse Proxy
file_server	http.handlers.file_server	Serves static files and directory listings	Static File Server
encode	http.handlers.encode	Compresses responses dynamically	Response Encoding
templates	http.handlers.templates	Executes Go templates in responses	Templates
rewrite	http.handlers.rewrite	Rewrites request URI and headers	-
headers	http.handlers.headers	Manipulates request/response headers	-
respond	http.handlers.respond	Writes a static response	-
error	http.handlers.error	Returns an error to trigger error handling	-
subroute	http.handlers.subroute	Executes a nested route list	-
vars	http.handlers.vars	Sets variables in the request context	-

Handler Characteristics

Handlers can be categorized by their behavior:

Middleware Handlers (call next handler):

• encode - Wraps response writer, calls next
• templates - Wraps response writer, calls next
• headers - Modifies headers, calls next
• rewrite - Modifies request, calls next
• vars - Sets variables, calls next

Responder Handlers (terminate chain):

• reverse_proxy - Proxies to upstream, writes response
• file_server - Reads from filesystem, writes response
• respond - Writes static response

Control Flow Handlers:

• subroute - Executes nested routes
• error - Triggers error handling

Sources: File paths for various handlers can be found in the modules/caddyhttp/ directory.

Error Handling

Caddy provides a sophisticated error handling system that allows custom error routes to be executed when handlers return errors.

Error Flow

When a handler returns an error:

1. Error captured: Server.ServeHTTP() receives the error from serveHTTP()
2. Request restored: Original request values (method, URI, RemoteAddr) are restored from OriginalRequestCtxKey
3. Error context added: HTTPErrorConfig.WithError() adds error to request context and sets replacer placeholders
4. Error route executed: s.errorHandlerChain.ServeHTTP(w, r) is invoked
5. Fallback: If error route fails or no error routes configured, writes appropriate status code

Error Handling Flow

Sources: modules/caddyhttp/server.go382-458 modules/caddyhttp/server.go732-776

Error Placeholders

The HTTPErrorConfig.WithError() method sets the following placeholders for use in error routes:

Placeholder	Description
{http.error}	The full error value
{http.error.status_code}	HTTP status code from HandlerError
{http.error.status_text}	Status text for the status code
{http.error.message}	Error message string
{http.error.trace}	Stack trace or error origin
{http.error.id}	Unique identifier for this error occurrence

Sources: modules/caddyhttp/server.go754-776

HandlerError Type

Handlers should return HandlerError to provide structured error information:

This allows error routes to make decisions based on error properties (e.g., serve different error pages for 404 vs 500).

Sources: modules/caddyhttp/server.go754-776

Writing Custom Handlers

Custom handlers can be implemented as Caddy modules by implementing the MiddlewareHandler interface.

Handler Implementation Pattern

Handler Guidelines

Middleware Handlers should:

• Call next.ServeHTTP(w, r) to continue the chain
• Wrap the response writer to intercept writes if needed
• Return errors rather than writing status codes directly

Responder Handlers should:

• Generate or fetch the response content
• Write to the response writer
• Not call next.ServeHTTP()
• Return errors for error conditions

All Handlers should:

• Be stateless (configuration only, no request state)
• Be thread-safe (may be called concurrently)
• Use the request context for request-scoped values
• Return HandlerError for structured error information

Sources: modules/caddyhttp/caddyhttp.go59-92

Summary

Caddy's handler and middleware system provides a flexible, composable architecture for HTTP request processing:

• Two handler interfaces: Handler for simple handlers, MiddlewareHandler for handlers that delegate to next
• Functional composition: Handlers compile into a chain using the Middleware function type
• Route-based dispatch: Routes combine matchers with handler lists for conditional processing
• Bidirectional flow: Requests flow down the chain, responses flow back up
• Comprehensive error handling: Structured error types and dedicated error routes
• Extensible: Custom handlers integrate seamlessly via the module system

The architecture balances simplicity with power, enabling both straightforward configurations and complex request processing pipelines.

Sources: modules/caddyhttp/caddyhttp.go15-342 modules/caddyhttp/routes.go15-453 modules/caddyhttp/server.go15-1619 modules/caddyhttp/app.go15-1050