Writing a Plugin: Server Type

Join the Caddy Community Forum to chat with other Caddy developers!

Caddy ships with an HTTP server, but you can implement other server types and plug them into Caddy. Other server types could be mail, DNS, TCP, something else used internally, etc.

To Caddy, the notion of a server is anything that can Listen() and Serve(). What that means and how that works is up to you. Feel free to be creative and liberal with this idea.

At a high level, plugging in a server type is very easy, using the caddy.RegisterServerType() function. You pass in the name of the server type and a caddy.ServerType struct describing it.

Here's a (somewhat simplified) example of how the HTTP server does it:

import "github.com/mholt/caddy"

func init() {
	caddy.RegisterServerType("http", caddy.ServerType{
		Directives: directives,
		DefaultInput: func() caddy.Input {
			return caddy.CaddyfileInput{
				Contents:       []byte(fmt.Sprintf("%s:%s\nroot %s", Host, Port, Root)),
				ServerTypeName: "http",
			}
		},
		NewContext: newContext,
	})
}

As you can see, server types consist of a name ("http"), a list of directives, a default Caddyfile input (optional, but recommended), and a context. We'll talk about each of these now.

Directives

Each server type gets to define which directives it recognizes and in what order they should be executed. This is simply a list of strings, where each string is the name of a directive:

var directives = []string{
	"dir1",
	"dir2",
	"etc",
}

In most server types, the execution order matters significantly, so directives will not be executed if they are not in this list.

Default Caddyfile Input

This is optional, but highly recommended in case you would rather not default to a blank Caddyfile. What this means for your server type is up to you. But you can return an instance of caddy.CaddyfileInput to satisfy this function. Caddy will call your function only if it is needed.

Context

Caddy tries to avoid as much global state as possible. When Caddy loads, parses, and executes a Caddyfile, it does so in a scope called an Instance so that a group of servers can be managed individually and multiple server types can be started in the same process.

Each time Caddy goes through this startup phase, it will create a new caddy.Instance and Caddy will ask your server type for a new caddy.Context value so that it can execute your server's directives without sharing global state. Read the godoc for caddy.Context for more information.

You should not store a a list of contexts with your server type; they will be stored with the Instance and are accessible from Controllers. Keeping references to contexts lying around will prevent them from being garbage collected if the server is stopped later, which is likely a memory leak.

Ultimately, your goal is to make it so that MakeServers() returns a list of caddy.Server values that Caddy can use. How you do that is entirely up to you.

For example: the HTTP server uses its context type to keep a map of site configs. The package also has an exported function, GetConfig(c Controller) that gets a config for a certain site, designated by the caddy.Controller that is passed in. The config, in turn, stores the list of middleware, etc -- all the information needed to set up a site. Each directive's action calls the GetConfig function so they can help set up the site properly. By the time MakeServers() is called, all it has to do is combine those site configs into server instances and return them. (Server instances implement caddy.Server.)

The caddy.Server interface has four methods; two are for TCP, two are for UDP or other:

type Server interface {
    // Required if using TCP
    Listen() (net.Listener, error)
    Serve(net.Listener) error

    // Required if using UDP or other
    ListenPacket() (net.PacketConn, error)
    ServePacket(net.PacketConn) error
}

If your server only uses TCP, the *Packet() methods may be no-ops (i.e. they return nil). The inverse is true for non-TCP servers. A server may also use both TCP and UDP, and implement all four methods.

Once this interface is implemented and configuration is properly applied from Caddyfile directives, your server type is ready to roll. Put it under test and add it to the Caddy download page!