caddyconfig

Package import path: github.com/caddyserver/caddyserver/caddy/v2/caddyconfig (in code: github.com/caddyserver/caddy/v2/caddyconfig).

This package is the registry and helper layer for "config adapters" — anything that converts a non-JSON config (Caddyfile, NGINX, JSON 5, YAML, TOML) into Caddy's JSON.

Purpose

• Define the Adapter interface every adapter implements.
• Provide RegisterAdapter / GetAdapter for plugin integration.
• Offer JSON and JSONModuleObject helpers that the rest of the codebase uses to build json.RawMessage values without sprinkling json.Marshal everywhere.

Directory layout

Path	Role
caddyconfig/configadapters.go	Adapter, Warning, JSON, JSONModuleObject, registry
caddyconfig/load.go	The "auto-detect adapter and apply" path used by caddy run --config
caddyconfig/httploader.go	The caddy.config_loaders.http module that fetches configs over HTTP
caddyconfig/caddyfile/	The generic Caddyfile parser (see caddyfile parser)
caddyconfig/httpcaddyfile/	The HTTP-app Caddyfile adapter (see httpcaddyfile)

Key abstractions

Type	Where	Description
Adapter	configadapters.go	Adapt(body []byte, options map[string]any) ([]byte, []Warning, error)
Warning	configadapters.go	{File, Line, Directive, Message} — non-fatal diagnostic
RegisterAdapter / GetAdapter	configadapters.go	Singleton registry; also wraps the adapter as a Caddy module under caddy.adapters.<name>
JSON	configadapters.go	JSON(val any, warnings *[]Warning) json.RawMessage — marshal with warning collection
JSONModuleObject	configadapters.go	Same, but stamps a <fieldName>: <fieldVal> key into the result; used to encode module values

How it works

graph LR
    Plugin[adapter package init] -->|RegisterAdapter| Registry
    CLI[caddy run --config] -->|caddyconfig.LoadConfig| Detect
    Detect -->|by file ext| Lookup[GetAdapter]
    Lookup --> Registry
    Registry --> Adapter
    Source[config source bytes] --> Adapter
    Adapter --> JSON[adapted JSON]
    JSON --> Runtime[caddy.Load]

load.go: LoadConfig is the routine cmd/commandfuncs.go uses for caddy run --config. It:

1. Reads the file bytes.
2. Picks an adapter by the --adapter flag, by the caddy.adapters.* module name, or by file extension fallback.
3. Calls Adapter.Adapt.
4. Prints any warnings to stderr.
5. Returns the resulting JSON.

httploader.go registers caddy.config_loaders.http — a config loader that fetches JSON from a URL on a recurring schedule. Useful for centralized config distribution.

JSON and JSONModuleObject

These helpers exist because the codebase needs to produce json.RawMessage values constantly (every adapter is essentially building JSON in pieces). They:

• Marshal the value.
• Push errors into a passed-in *[]Warning slice instead of returning them, so adapter code stays readable.
• For module values, JSONModuleObject(val, "handler", "file_server", warnings) produces {"handler":"file_server", ...} — exactly the shape Caddy modules expect when their inline-key tag is handler.

You'll see these used heavily in caddyconfig/httpcaddyfile/.

Integration points

• Caddyfile parser: caddyconfig/caddyfile/adapter.go is itself an Adapter registered under caddyfile.
• HTTP-Caddyfile adapter: wraps the Caddyfile parser plus directive ordering; registered under caddyfile.
• External adapters: community modules register NGINX, JSON 5, YAML, TOML, etc.

Entry points for modification

• New built-in helper? configadapters.go is small enough that adding a sibling helper to JSON is straightforward.
• New loader (e.g. fetch from S3)? Implement caddy.ConfigLoader and register caddy.config_loaders.<name>. httploader.go is the smallest worked example.

Related pages

• Caddyfile parser
• HTTP Caddyfile adapter
• Caddyfile feature