caddyserver/caddy
Glossary
Caddy-specific terms used throughout the codebase and the wiki. Where a concept lives in code, the path is given.
| Term | Meaning |
|---|---|
| App | A top-level module that implements Start()/Stop(). Caddy core loads apps from Config.AppsRaw. The standard build ships http, tls, pki, and events (caddy.go). |
| Module | Anything registered through caddy.RegisterModule(). Modules have a dotted ID, an empty constructor, and may implement lifecycle interfaces (modules.go). |
| Module ID | Dot-separated lowercase string. Apps have a single label (http); other modules use <namespace>.<category>.<name> (http.handlers.file_server, caddy.logging.encoders.json). |
| Namespace | All but the last label of a module ID. Host modules use caddy:"namespace=…" struct tags to pick which modules can fill a json.RawMessage field. |
| Provisioner | Optional interface; Provision(caddy.Context) error runs after JSON unmarshal and before Validate/Start (caddy.go). |
| Validator | Optional interface; Validate() error checks that a provisioned module is internally consistent. |
| CleanerUpper | Optional interface; Cleanup() error runs when the module's parent context is canceled (during reload or shutdown). |
| Caddy Context | A wrapper around context.Context with extra accessors for sibling apps, sub-module loading, the configured filesystem, and a scoped zap logger (context.go). |
| Replacer | Caddy's placeholder engine; resolves things like {http.request.uri.path} or {env.FOO} to runtime values. Implemented in replacer.go; HTTP-specific placeholders live in modules/caddyhttp/replacer.go. |
| Storage | Persistence layer for TLS state (certs, OCSP staples, ACME locks). Implements certmagic.Storage. The default is a file-system backend at modules/filestorage/. |
| Adapter | Module that converts a non-JSON config (Caddyfile, NGINX, JSON 5, …) into Caddy's JSON. Registered with caddyconfig.RegisterAdapter (caddyconfig/configadapters.go). |
| Caddyfile | Caddy's human-friendly config language. Parsed by caddyconfig/caddyfile/ and converted to JSON for the HTTP app by caddyconfig/httpcaddyfile/. |
| Directive | A Caddyfile keyword like respond, reverse_proxy, tls, file_server. Each directive is registered by an HTTP module's init() function in modules/caddyhttp/... and ordered in caddyconfig/httpcaddyfile/directives.go. |
| Matcher | A predicate over an HTTP request. Lives in the http.matchers.* namespace (e.g. http.matchers.path, http.matchers.header, http.matchers.expression for CEL). Defined in modules/caddyhttp/matchers.go. |
| Route | A list of matchers plus a list of handlers. Compiled into a middleware chain at provision time (modules/caddyhttp/routes.go). |
| Handler | A module that implements the Handler or MiddlewareHandler interface from modules/caddyhttp/caddyhttp.go. Registered under http.handlers.*. |
| Issuer | A TLS certificate issuer module under tls.issuance.*. The standard build ships acme, zerossl, and internal (modules/caddytls/). |
| Connection policy | A tls.ConnectionPolicy that picks the right cert and TLS settings during the handshake (modules/caddytls/connpolicy.go). |
| CertMagic | The certificate-management library Caddy delegates to (github.com/caddyserver/certmagic). |
| Automatic HTTPS | The process of inferring which hostnames need certificates from HTTP routes, then telling the tls app to manage them (modules/caddyhttp/autohttps.go). |
| Admin API | Internal HTTP server (default localhost:2019) for live config edits, cert inspection, metrics, and module-defined endpoints. Defined in admin.go; routes registered with caddy.AdminRouter. |
| AdminRouter | Optional module interface; modules implement it to expose admin endpoints under /<id>/. Used by modules/caddyhttp/reverseproxy/admin.go, modules/metrics/, modules/caddypki/adminapi.go, etc. |
| Listener wrapper | A caddy.ListenerWrapper that decorates a net.Listener (e.g. PROXY-protocol parsing, HTTP→HTTPS redirect). Lives in caddy.listeners.* (listeners.go). |
| Standard build | The default binary; everything imported by modules/standard/imports.go and modules/caddyhttp/standard/imports.go. |
| xcaddy | External tool for compiling Caddy with extra plugin imports. Lives in a sibling repo at caddyserver/xcaddy. |
| Encoder / Writer (logging) | Zap-based output formatting (encoder, e.g. caddy.logging.encoders.json) and destination (writer, e.g. caddy.logging.writers.file). Defined in modules/logging/. |
| Event | A typed message dispatched by the events app. Modules emit and subscribe to events for cert renewal, config reload notifications, and similar hooks (modules/caddyevents/app.go). |
| Pingback | Mechanism caddy start uses to confirm the spawned process is alive: parent and child exchange random bytes over a localhost socket (cmd/main.go handlePingbackConn). |
Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.