Extending Caddy

Caddy is easy to extend because of its modular architecture. Most kinds of Caddy extensions (or plugins) are known as modules if they extend or plug into Caddy’s configuration structure. To be clear, Caddy modules are distinct from Go modules (but they are also Go modules).

Prerequisites:

Quick Start

A Caddy module is any named type that registers itself as a Caddy module when its package is imported. Crucially, a module always implements the caddy.Module interface, which provides its name and a constructor function.

In a new Go module, paste the following template into a Go file and customize your package name, type name, and Caddy module ID:

  1. package mymodule
  3. import "github.com/caddyserver/caddy/v2"
  5. func init() {
  6.     caddy.RegisterModule(Gizmo{})
  7. }
  9. // Gizmo is an example; put your own type here.
  10. type Gizmo struct {
  11. }
  13. // CaddyModule returns the Caddy module information.
  14. func (Gizmo) CaddyModule() caddy.ModuleInfo {
  15.     return caddy.ModuleInfo{
  16.         ID:  "foo.gizmo",
  17.         New: func() caddy.Module { return new(Gizmo) },
  18.     }
  19. }

Then run this command from your project’s directory, and you should see your module in the list:

  1. xcaddy list-modules
  2. ...
  3. foo.gizmo
  4. ...

The xcaddy command is an important part of every module developer’s workflow. It compiles Caddy with your plugin, then runs it with the given arguments. It discards the temporary binary each time (similar to go run).

Congratulations, your module registers with Caddy and can be used in Caddy’s config document in whatever places use modules in the same namespace.

Under the hood, xcaddy is simply making a new Go module that requires both Caddy and your plugin (with an appropriate replace to use your local development version), then adds an import to ensure it is compiled in:

  1. import _ "github.com/example/mymodule"

Module Basics

Caddy modules:

  1. Implement the caddy.Module interface to provide an ID and constructor
  2. Have a unique name in the proper namespace
  3. Usually satisfy some interface(s) that are meaningful to the host module for that namespace

Host modules (or parent modules) are modules which load/initialize other modules. They typically define namespaces for guest modules.

Guest modules (or child modules) are modules which get loaded or initialized. All modules are guest modules.

Module IDs

Each Caddy module has a unique ID, consisting of a namespace and name:

  • A complete ID looks like foo.bar.module_name
  • The namespace would be foo.bar
  • The name would be module_name which must be unique in its namespace

Module IDs must use snake_case convention.

Namespaces

Namespaces are like classes, i.e. a namespace defines some functionality that is common among all modules within it. For example, we can expect that all modules within the http.handlers namespace are HTTP handlers. It follows that a host module may type-assert guest modules in that namespace from interface{} types into a more specific, useful type such as caddyhttp.MiddlewareHandler.

A guest module must be properly namespaced in order for it to be recognized by a host module because host modules will ask Caddy for modules within a certain namespace to provide the functionality desired by the host module. For example, if you were to write an HTTP handler module called gizmo, your module’s name would be http.handlers.gizmo, because the http app will look for handlers in the http.handlers namespace.

Put another way, Caddy modules are expected to implement certain interfaces depending on their module namespace. With this convention, module developers can say intuitive things such as, “All modules in the http.handlers namespace are HTTP handlers.” More technically, this usually means, “All modules in the http.handlers namespace implement the caddyhttp.MiddlewareHandler interface.” Because that method set is known, the more specific type can be asserted and used.

View a table mapping all the standard Caddy namespaces to their Go types.

The caddy and admin namespaces are reserved and cannot be app names.

To write modules which plug into 3rd-party host modules, consult those modules for their namespace documentation.

Names

The name within a namespace is significant and highly visible to users, but is not particularly important, as long as it is unique, concise, and makes sense for what it does.

App Modules

Apps are modules with an empty namespace, and which conventionally become their own top-level namespace. App modules implement the caddy.App interface.

These modules appear in the "apps" property of the top-level of Caddy’s config:

  1. {
  2.     "apps": {}
  3. }

Example apps are http and tls. Theirs is the empty namespace.

Guest modules written for these apps should be in a namespace derived from the app name. For example, HTTP handlers use the http.handlers namespace and TLS certificate loaders use the tls.certificates namespace.

Module Implementation

A module can be virtually any type, but structs are the most common because they can hold user configuration.

Configuration

Most modules require some configuration. Caddy takes care of this automatically, as long as your type is compatible with JSON. Thus, if a module is a struct type, it will need struct tags on its fields, which should use snake_casing according to Caddy convention:

  1. type Gizmo struct {
  2.     MyField string `json:"my_field,omitempty"`
  3.     Number  int    `json:"number,omitempty"`
  4. }

Using struct tags in this way will ensure that config properties are consisently named across all of Caddy.

When a module is initialized, it will already have its configuration filled out. It is also possible to perform additional provisioning and validation steps after a module is initialized.

Module Lifecycle

A module’s life begins when it is loaded by a host module. The following happens:

  1. New() is called to get an instance of the module’s value.
  2. The module’s configuration is unmarshaled into that instance.
  3. If the module is a caddy.Provisioner, the Provision() method is called.
  4. If the module is a caddy.Validator, the Validate() method is called.
  5. At this point, the host module is given the loaded guest module as an interface{} value, so the host module will usually type-assert the guest module into a more useful type. Check the documentation for the host module to know what is required of a guest module in its namespace, e.g. what methods need to be implemented.
  6. When a module is no longer needed, and if it is a caddy.CleanerUpper, the Cleanup() method is called.

Note that multiple loaded instances of your module may overlap at a given time! During config changes, new modules are started before the old ones are stopped. Be sure to use global state carefully. Use the caddy.UsagePool type to help manage global state across module loads.

Provisioning

A module’s configuration will be unmarshaled into its value automatically. This means, for example, that struct fields will be filled out for you.

However, if your module requires additional provisioning steps, you can implement the (optional) caddy.Provisioner interface:

  1. // Provision sets up the module.
  2. func (g *Gizmo) Provision(ctx caddy.Context) error {
  3.     // TODO: set up the module
  4.     return nil
  5. }

This is typically where host modules will load their guest/child modules, but it can be used for pretty much anything. Module provisioning is done in an arbitrary order.

A module may access other apps by calling ctx.App(), but modules must not have circular dependencies. In other words, a module loaded by the http app cannot depend on the tls app if a module loaded by the tls app depends on the http app. (Very similar to rules forbidding import cycles in Go.)

Additionally, you should avoid performing expensive operations in Provision, since provisioning is performed even if a config is only being validated. When in the provisioning phase, do not expect that the module will actually be used.

Logs

If your module needs logging, do not use log.Print*() from the Go standard library. In other words, do not use Go’s global logger. Caddy uses high-performance, highly flexible, structured logging with zap.

To emit logs, get a logger in your module’s Provision method:

  1. func (g *Gizmo) Provision(ctx caddy.Context) error {
  2.     g.logger = ctx.Logger(g) // g.logger is a *zap.Logger
  3. }

Then you can emit structured, leveled logs using g.logger. See zap’s godoc for details.

Validating

Modules which would like to validate their configuration may do so by satisfying the (optional) caddy.Validator interface:

  1. // Validate validates that the module has a usable config.
  2. func (g Gizmo) Validate() error {
  3.     // TODO: validate the module's setup
  4.     return nil
  5. }

Validate should be a read-only function. It is run after the Provision() method.

Interface guards

Caddy module behavior is implicit because Go interfaces are satisfied implicitly. Simply adding the right methods to your module’s type is all it takes to make or break your module’s correctness. Thus, making a typo or getting the method signature wrong can lead to unexpected (lack of) behavior.

Fortunately, there is an easy, no-overhead, compile-time check you can add to your code to ensure you’ve added the right methods. These are called interface guards:

  1. var _ InterfaceName = (*YourType)(nil)

Replace InterfaceName with the interface you intend to satisfy, and YourType with the name of your module’s type.

For example, an HTTP handler such as the static file server might satisfy multiple interfaces:

  1. // Interface guards
  2. var (
  3.     _ caddy.Provisioner           = (*FileServer)(nil)
  4.     _ caddyhttp.MiddlewareHandler = (*FileServer)(nil)
  5. )

This prevents the program from compiling if *FileServer does not satisfy those interfaces.

Without interface guards, confusing bugs can slip in. For example, if your module must provision itself before being used but your Provision() method has a mistake (e.g. misspelled or wrong signature), provisioning will never happen, leading to head-scratching. Interface guards are super easy and can prevent that. They usually go at the bottom of the file.

Host Modules

A module becomes a host module when it loads its own guest modules. This is useful if a piece of the module’s functionality can be implemented in different ways.

A host module is almost always a struct. Normally, supporting a guest module requires two struct fields: one to hold its raw JSON, and another to hold its decoded value:

  1. type Gizmo struct {
  2.     GadgetRaw json.RawMessage `json:"gadget,omitempty" caddy:"namespace=foo.gizmo.gadgets inline_key=gadgeter"`
  4.     Gadget Gadgeter `json:"-"`
  5. }

The first field (GadgetRaw in this example) is where the raw, unprovisioned JSON form of the guest module can be found.

The second field (Gadget) is where the final, provisioned value will eventually be stored. Since the second field is not user-facing, we exclude it from JSON with a struct tag. (You could also unexport it if it is not needed by other packages, and then no struct tag is needed.)

Caddy struct tags

The caddy struct tag on the raw module field helps Caddy to know the namespace and name (comprising the complete ID) of the module to load. It is also used for generating documentation.

The struct tag has a very simple format: key1=val1 key2=val2 ...

For module fields, the struct tag will look like:

  1. `caddy:"namespace=foo.bar inline_key=baz"`

The namespace= part is required. It defines the namespace in which to look for the module.

The inline_key= part is only used if the module’s name will be found inline with the module itself; this implies that the value is an object where one of the keys is the inline key, and its value is the name of the module. If omitted, then the field type must be a caddy.ModuleMap or []caddy.ModuleMap, where the map key is the module name.

Loading guest modules

To load a guest module, call ctx.LoadModule() during the provision phase:

  1. // Provision sets up g and loads its gadget.
  2. func (g *Gizmo) Provision(ctx caddy.Context) error {
  3.     if g.GadgetRaw != nil {
  4.         val, err := ctx.LoadModule(g, "GadgetRaw")
  5.         if err != nil {
  6.             return fmt.Errorf("loading gadget module: %v", err)
  7.         }
  8.         g.Gadget = val.(Gadgeter)
  9.     }
  10.     return nil
  11. }

Note that the LoadModule() call takes a pointer to the struct and the field name as a string. Weird, right? Why not just pass the struct field directly? It’s because there are a few different ways to load modules depending on the layout of the config. This method signature allows Caddy to use reflection to figure out the best way to load the module and, most importantly, read its struct tags.

If a guest module must explicitly be set by the user, you should return an error if the Raw field is nil or empty before trying to load it.

Notice how the loaded module is type-asserted: g.Gadget = val.(Gadgeter) - this is because the returned val is a interface{} type which is not very useful. However, we expect that all modules in the declared namespace (foo.gizmo.gadgets from the struct tag in our example) implement the Gadgeter interface, so this type assertion is safe, and then we can use it!

If your host module defines a new namespace, be sure to document both that namespace and its Go type(s) for developers like we have done here.

Complete Example

Let’s suppose we want to write an HTTP handler module. This will be a contrived middleware for demonstration purposes which prints the visitor’s IP address to a stream on every HTTP request.

We also want it to be configurable via the Caddyfile, because most people prefer to use the Caddyfile in non-automated situations. We do this by registering a Caddyfile handler directive, which is a kind of directive that can add a handler to the HTTP route. We also implement the caddyfile.Unmarshaler interface. By adding these few lines of code, this module can be configured with the Caddyfile! For example: visitor_ip stdout.

Here is the code for such a module, with explanatory comments:

  1. package visitorip
  3. import (
  4.     "fmt"
  5.     "io"
  6.     "net/http"
  7.     "os"
  9.     "github.com/caddyserver/caddy/v2"
  10.     "github.com/caddyserver/caddy/v2/caddyconfig/caddyfile"
  11.     "github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile"
  12.     "github.com/caddyserver/caddy/v2/modules/caddyhttp"
  13. )
  15. func init() {
  16.     caddy.RegisterModule(Middleware{})
  17.     httpcaddyfile.RegisterHandlerDirective("visitor_ip", parseCaddyfile)
  18. }
  20. // Middleware implements an HTTP handler that writes the
  21. // visitor's IP address to a file or stream.
  22. type Middleware struct {
  23.     // The file or stream to write to. Can be "stdout"
  24.     // or "stderr".
  25.     Output string `json:"output,omitempty"`
  27.     w io.Writer
  28. }
  30. // CaddyModule returns the Caddy module information.
  31. func (Middleware) CaddyModule() caddy.ModuleInfo {
  32.     return caddy.ModuleInfo{
  33.         ID:  "http.handlers.visitor_ip",
  34.         New: func() caddy.Module { return new(Middleware) },
  35.     }
  36. }
  38. // Provision implements caddy.Provisioner.
  39. func (m *Middleware) Provision(ctx caddy.Context) error {
  40.     switch m.Output {
  41.     case "stdout":
  42.         m.w = os.Stdout
  43.     case "stderr":
  44.         m.w = os.Stderr
  45.     default:
  46.         return fmt.Errorf("an output stream is required")
  47.     }
  48.     return nil
  49. }
  51. // Validate implements caddy.Validator.
  52. func (m *Middleware) Validate() error {
  53.     if m.w == nil {
  54.         return fmt.Errorf("no writer")
  55.     }
  56.     return nil
  57. }
  59. // ServeHTTP implements caddyhttp.MiddlewareHandler.
  60. func (m Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
  61.     m.w.Write([]byte(r.RemoteAddr))
  62.     return next.ServeHTTP(w, r)
  63. }
  65. // UnmarshalCaddyfile implements caddyfile.Unmarshaler.
  66. func (m *Middleware) UnmarshalCaddyfile(d *caddyfile.Dispenser) error {
  67.     for d.Next() {
  68.         if !d.Args(&m.Output) {
  69.             return d.ArgErr()
  70.         }
  71.     }
  72.     return nil
  73. }
  75. // parseCaddyfile unmarshals tokens from h into a new Middleware.
  76. func parseCaddyfile(h httpcaddyfile.Helper) (caddyhttp.MiddlewareHandler, error) {
  77.     var m Middleware
  78.     err := m.UnmarshalCaddyfile(h.Dispenser)
  79.     return m, err
  80. }
  82. // Interface guards
  83. var (
  84.     _ caddy.Provisioner           = (*Middleware)(nil)
  85.     _ caddy.Validator             = (*Middleware)(nil)
  86.     _ caddyhttp.MiddlewareHandler = (*Middleware)(nil)
  87.     _ caddyfile.Unmarshaler       = (*Middleware)(nil)
  88. )