caddy

Documentation

Overview

Package caddy implements the Caddy web server as a service in your own Go programs.

To use this package, follow a few simple steps:

1. Set the AppName and AppVersion variables.
2. Call LoadCaddyfile() to get the Caddyfile (it might have been piped in as part of a restart). You should pass in your own Caddyfile loader.
3. Call caddy.Start() to start Caddy, caddy.Stop() to stop it, or caddy.Restart() to restart it.

You should use caddy.Wait() to wait for all Caddy servers to quit before your process exits.

Index

• Constants
• Variables
• func IsRestart() bool
• func Restart(newCaddyfile Input) error
• func Start(cdyfile Input) (err error)
• func Stop() error
• func TrapSignals()
• func Wait()
• type CaddyfileInput
  • func DefaultInput() CaddyfileInput
  • func (c CaddyfileInput) Body() []byte
  • func (c CaddyfileInput) IsFile() bool
  • func (c CaddyfileInput) Path() string
• type Input
  • func Caddyfile() Input
  • func CaddyfileFromPipe(f *os.File) (Input, error)
  • func LoadCaddyfile(loader func() (Input, error)) (cdyfile Input, err error)
• type SetupFunc

Constants

const (
	// DefaultHost is the default host.
	DefaultHost = ""
	// DefaultPort is the default port.
	DefaultPort = "2015"
	// DefaultRoot is the default root folder.
	DefaultRoot = "."
)

const (
	// DefaultConfigFile is the name of the configuration file that is loaded
	// by default if no other file is specified.
	DefaultConfigFile = "Caddyfile"
)

Variables

var (
	// AppName is the name of the application.
	AppName string

	// AppVersion is the version of the application.
	AppVersion string

	// Quiet when set to true, will not show any informative output on initialization.
	Quiet bool

	// HTTP2 indicates whether HTTP2 is enabled or not.
	HTTP2 bool // TODO: temporary flag until http2 is standard

	// PidFile is the path to the pidfile to create.
	PidFile string

	// GracefulTimeout is the maximum duration of a graceful shutdown.
	GracefulTimeout time.Duration
)

Configurable application parameters

var (
	// Root is the site root
	Root = DefaultRoot

	// Host is the site host
	Host = DefaultHost

	// Port is the site port
	Port = DefaultPort
)

These defaults are configurable through the command line

Functions

func IsRestart

func IsRestart() bool

IsRestart returns whether this process is, according to env variables, a fork as part of a graceful restart.

func Restart

func Restart(newCaddyfile Input) error

Restart restarts the entire application; gracefully with zero downtime if on a POSIX-compatible system, or forcefully if on Windows but with imperceptibly-short downtime.

The restarted application will use newCaddyfile as its input configuration. If newCaddyfile is nil, the current (existing) Caddyfile configuration will be used.

Note: The process must exist in the same place on the disk in order for this to work. Thus, multiple graceful restarts don't work if executing with `go run`, since the binary is cleaned up when `go run` sees the initial parent process exit.

func Start

func Start(cdyfile Input) (err error)

Start starts Caddy with the given Caddyfile. If cdyfile is nil, the LoadCaddyfile function will be called to get one.

This function blocks until all the servers are listening.

Note (POSIX): If Start is called in the child process of a restart more than once within the duration of the graceful cutoff (i.e. the child process called Start a first time, then called Stop, then Start again within the first 5 seconds or however long GracefulTimeout is) and the Caddyfiles have at least one listener address in common, the second Start may fail with "address already in use" as there's no guarantee that the parent process has relinquished the address before the grace period ends.

func Stop

func Stop() error

Stop stops all servers. It blocks until they are all stopped. It does NOT execute shutdown callbacks that may have been configured by middleware (they must be executed separately).

func TrapSignals

func TrapSignals()

TrapSignals create signal handlers for all applicable signals for this system. If your Go program uses signals, this is a rather invasive function; best to implement them yourself in that case. Signals are not required for the caddy package to function properly, but this is a convenient way to allow the user to control this package of your program.

func Wait

func Wait()

Wait blocks until all servers are stopped.

Types

type CaddyfileInput

type CaddyfileInput struct {
	Filepath string
	Contents []byte
	RealFile bool
}

CaddyfileInput represents a Caddyfile as input and is simply a convenient way to implement the Input interface.

func DefaultInput

func DefaultInput() CaddyfileInput

DefaultInput returns the default Caddyfile input to use when it is otherwise empty or missing. It uses the default host and port (depends on host, e.g. localhost is 2015, otherwise 443) and root.

func (CaddyfileInput) Body

func (c CaddyfileInput) Body() []byte

Body returns c.Contents.

func (CaddyfileInput) IsFile

func (c CaddyfileInput) IsFile() bool

IsFile returns true if the original input was a real file on the file system.

func (CaddyfileInput) Path

func (c CaddyfileInput) Path() string

Path returns c.Filepath.

type Input

type Input interface {
	// Gets the Caddyfile contents
	Body() []byte

	// Gets the path to the origin file
	Path() string

	// IsFile returns true if the original input was a file on the file system
	// that could be loaded again later if requested.
	IsFile() bool
}

Input represents a Caddyfile; its contents and file path (which should include the file name at the end of the path). If path does not apply (e.g. piped input) you may use any understandable value. The path is mainly used for logging, error messages, and debugging.

func Caddyfile

func Caddyfile() Input

Caddyfile returns the current Caddyfile

func CaddyfileFromPipe

func CaddyfileFromPipe(f *os.File) (Input, error)

CaddyfileFromPipe loads the Caddyfile input from f if f is not interactive input. f is assumed to be a pipe or stream, such as os.Stdin. If f is not a pipe, no error is returned but the Input value will be nil. An error is only returned if there was an error reading the pipe, even if the length of what was read is 0.

func LoadCaddyfile

func LoadCaddyfile(loader func() (Input, error)) (cdyfile Input, err error)

LoadCaddyfile loads a Caddyfile, prioritizing a Caddyfile piped from stdin as part of a restart (only happens on first call to LoadCaddyfile). If it is not a restart, this function tries calling the user's loader function, and if that returns nil, then this function resorts to the default configuration. Thus, if there are no other errors, this function always returns at least the default Caddyfile.

type SetupFunc

type SetupFunc func(c *setup.Controller) (middleware.Middleware, error)

SetupFunc takes a controller and may optionally return a middleware. If the resulting middleware is not nil, it will be chained into the HTTP handlers in the order specified in this package.