httpcaddyfile

Package: github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile.

The HTTP-app-specific Caddyfile adapter. This is what you actually invoke when you run caddy run --config Caddyfile (default file ext) or caddy adapt. It registers the caddyfile adapter and produces a full Config JSON document with http, tls, and pki apps as appropriate.

Purpose

• Translate a Caddyfile into Caddy's native JSON configuration for the HTTP app.
• Synthesize the matching tls and pki app configurations when needed.
• Apply directive ordering rules so users can write directives in any order.
• Expand shorthands (php_fastcgi, import, snippets, named matchers, …).

Directory layout

Path	Role
httpcaddyfile/httptype.go	The HTTP adapter's App type and main Setup (~61 KB)
httpcaddyfile/directives.go	Directive registry and ordering
httpcaddyfile/builtins.go	Adapters for bind, tls, log, route, handle, error, redir, respond, try_files, … (~35 KB)
httpcaddyfile/options.go	Global options like http_port, auto_https, storage, default_sni, log (~17 KB)
httpcaddyfile/serveroptions.go	Per-server options: protocols, metrics, trusted_proxies, client_ip_headers, …
httpcaddyfile/shorthands.go	Caddyfile shorthand expansion (@matchers, magic placeholders)
httpcaddyfile/addresses.go	Site-block address parsing (example.com, :8080, *.example.com, unix//tmp/x.sock)
httpcaddyfile/tlsapp.go	Builds the tls app JSON (~42 KB)
httpcaddyfile/pkiapp.go	Builds the pki app JSON when needed
httpcaddyfile/testdata/	Fixtures: input Caddyfile + expected JSON

Key abstractions

Type	Where	Description
App	httptype.go	The adapter type implementing caddyconfig.Adapter
Helper	httptype.go	Per-directive helper passed to directive parsers (placeholders, options, group ID, etc.)
ConfigValue	httptype.go	A directive's contribution to the eventual JSON: {Class, Value, directive name}
RegisterDirective / RegisterHandlerDirective	directives.go	Registers a parser function with priority
RegisterGlobalOption	options.go	Registers a global option parser

How it works

graph TD
    Caddyfile -->|caddyfile parser| Blocks[ServerBlocks]
    Blocks --> AddrParse[parse site-block addresses]
    AddrParse --> SiteGroups[group by listening address]
    SiteGroups --> DirParse[run each directive's parser]
    DirParse --> CV[ConfigValue list]
    CV -->|sort by priority| Sorted
    Sorted -->|build subroutes per site| Servers
    Servers --> HTTPApp[http app JSON]
    AddrParse --> TLS[tls app JSON]
    AddrParse --> PKI[pki app JSON]
    HTTPApp --> Final[Config JSON]
    TLS --> Final
    PKI --> Final

Directive registration

directives.go declares a slice of registered directives in priority order. Examples (priorities omitted; see the file for exact numbers):

tracing
map
vars
root
header
copy_response_headers
request_body
redir
rewrite
uri
try_files
handle_path
handle
route
basicauth
forward_auth
encode
push
file_server
reverse_proxy
acme_server
respond
metrics
abort
error

The order is what makes the Caddyfile feel forgiving: regardless of where you write header and reverse_proxy in your file, the adapter places header first in the route list.

Per-directive parsers

Each directive registered through RegisterHandlerDirective is a function:

func parseSomething(h Helper) ([]httpcaddyfile.ConfigValue, error)

The Helper exposes:

• A caddyfile.Dispenser for the directive's own tokens.
• The site block's address group ID.
• Hooks to register named matchers, errors, and snippets.
• Option(name) to consult global options.

Most directive parsers are tiny (10–30 lines) and live next to their handler module (modules/caddyhttp/<handler>/caddyfile.go).

Site-block address grouping

addresses.go parses addresses like example.com:443, *.example.com, :8080, unix//tmp/caddy.sock, and computes which address group a site belongs to. Sites that share the same listen address (modulo wildcards) end up in the same http server.

TLS app synthesis

tlsapp.go is large because it has to translate every TLS-relevant Caddyfile directive (tls, acme_dns, acme_eab, tls protocols, local_certs, key_type, client_auth block, …) into the tls app's JSON shape. It also builds default automation policies for site addresses that need certs.

PKI app synthesis

pkiapp.go only kicks in when the Caddyfile mentions pki { ca ... }. Otherwise, the default local CA is left implicit — caddytls's internal issuer creates it on demand.

Fixtures

testdata/ and caddytest/integration/caddyfile_adapt/ hold input/expected JSON pairs. Adding a directive or changing how one expands almost always requires a fixture update — that's the project's way of preventing silent JSON-shape regressions.

Integration points

• HTTP app: the consumer of the produced JSON.
• caddyfile parser: the upstream stage.
• Module directives: every Caddyfile-friendly handler/matcher under modules/ registers a directive here (or in its own package).

Entry points for modification

• Add a directive: register it in directives.go with a sensible priority, then implement parseFoo(h Helper).
• Add a global option: RegisterGlobalOption from options.go.
• Add a site-block address shape: addresses.go.
• Tweak TLS synthesis: tlsapp.go (security-critical; expect close review).

Related pages

• Caddyfile parser
• Caddyfile feature
• HTTP app
• TLS app