Command represents a subcommand. Name, Func, and Short are required.

type Command struct {
	// The name of the subcommand. Must conform to the
	// format described by the RegisterCommand() godoc.
	// Required.
	Name	string

	// Usage is a brief message describing the syntax of
	// the subcommand's flags and args. Use [] to indicate
	// optional parameters and <> to enclose literal values
	// intended to be replaced by the user. Do not prefix
	// the string with "caddy" or the name of the command
	// since these will be prepended for you; only include
	// the actual parameters for this command.
	Usage	string

	// Short is a one-line message explaining what the
	// command does. Should not end with punctuation.
	// Required.
	Short	string

	// Long is the full help text shown to the user.
	// Will be trimmed of whitespace on both ends before
	// being printed.
	Long	string

	// Flags is the flagset for command.
	// This is ignored if CobraFunc is set.
	Flags	*flag.FlagSet

	// Func is a function that executes a subcommand using
	// the parsed flags. It returns an exit code and any
	// associated error.
	// Required if CobraFunc is not set.
	Func	CommandFunc

	// CobraFunc allows further configuration of the command
	// via cobra's APIs. If this is set, then Func and Flags
	// are ignored, with the assumption that they are set in
	// this function. A caddycmd.WrapCommandFuncForCobra helper
	// exists to simplify porting CommandFunc to Cobra's RunE.
	CobraFunc	func(*cobra.Command)
}

CommandFunc is a command's function. It runs the command and returns the proper exit code along with any error that occurred.

type CommandFunc func(Flags) (int, error)

Flags wraps a FlagSet so that typed values from flags can be easily retrieved.

type Flags struct {
	*pflag.FlagSet
}

StringSlice is a flag.Value that enables repeated use of a string flag.

type StringSlice []string

exitError carries the exit code from CommandFunc to Main()

type exitError struct {
	ExitCode	int
	Err		error
}

This type doesn't have documentation.

type moduleInfo struct {
	caddyModuleID	string
	goModule	*debug.Module
	err		error
}

This type doesn't have documentation.

type pluginPackage struct {
	Version	string
	Path	string
}

This type doesn't have documentation.

type rootCommandFactory struct {
	constructor	func() *cobra.Command
	options		[]func(*cobra.Command)
}

This type doesn't have documentation.

type storVal struct {
	StorageRaw json.RawMessage `json:"storage,omitempty" caddy:"namespace=caddy.storage inline_key=module"`
}

AdminAPIRequest makes an API request according to the CLI flags given, with the given HTTP method and request URI. If body is non-nil, it will be assumed to be Content-Type application/json. The caller should close the response body. Should only be used by Caddy CLI commands which need to interact with a running instance of Caddy via the admin API.

func AdminAPIRequest(adminAddr, method, uri string, headers http.Header, body io.Reader) (*http.Response, error) {
	parsedAddr, err := caddy.ParseNetworkAddress(adminAddr)
	if err != nil || parsedAddr.PortRangeSize() > 1 {
		return nil, fmt.Errorf("invalid admin address %s: %v", adminAddr, err)
	}
	origin := "http://" + parsedAddr.JoinHostPort(0)
	if parsedAddr.IsUnixNetwork() {
		origin = "http://127.0.0.1"	// bogus host is a hack so that http.NewRequest() is happy

		// the unix address at this point might still contain the optional
		// unix socket permissions, which are part of the address/host.
		// those need to be removed first, as they aren't part of the
		// resulting unix file path
		addr, _, err := internal.SplitUnixSocketPermissionsBits(parsedAddr.Host)
		if err != nil {
			return nil, err
		}
		parsedAddr.Host = addr
	} else if parsedAddr.IsFdNetwork() {
		origin = "http://127.0.0.1"
	}

	// form the request
	req, err := http.NewRequest(method, origin+uri, body)
	if err != nil {
		return nil, fmt.Errorf("making request: %v", err)
	}
	if parsedAddr.IsUnixNetwork() || parsedAddr.IsFdNetwork() {
		// We used to conform to RFC 2616 Section 14.26 which requires
		// an empty host header when there is no host, as is the case
		// with unix sockets and socket fds. However, Go required a
		// Host value so we used a hack of a space character as the host
		// (it would see the Host was non-empty, then trim the space later).
		// As of Go 1.20.6 (July 2023), this hack no longer works. See:
		// https://github.com/golang/go/issues/60374
		// See also the discussion here:
		// https://github.com/golang/go/issues/61431
		//
		// After that, we now require a Host value of either 127.0.0.1
		// or ::1 if one is set. Above I choose to use 127.0.0.1. Even
		// though the value should be completely irrelevant (it could be
		// "srldkjfsd"), if for some reason the Host *is* used, at least
		// we can have some reasonable assurance it will stay on the local
		// machine and that browsers, if they ever allow access to unix
		// sockets, can still enforce CORS, ensuring it is still coming
		// from the local machine.
	} else {
		req.Header.Set("Origin", origin)
	}
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	for k, v := range headers {
		req.Header[k] = v
	}

	// make an HTTP client that dials our network type, since admin
	// endpoints aren't always TCP, which is what the default transport
	// expects; reuse is not of particular concern here
	client := http.Client{
		Transport: &http.Transport{
			DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
				return net.Dial(parsedAddr.Network, parsedAddr.JoinHostPort(0))
			},
		},
	}

	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("performing request: %v", err)
	}

	// if it didn't work, let the user know
	if resp.StatusCode >= 400 {
		respBody, err := io.ReadAll(io.LimitReader(resp.Body, 1024*1024*2))
		if err != nil {
			return nil, fmt.Errorf("HTTP %d: reading error message: %v", resp.StatusCode, err)
		}
		return nil, fmt.Errorf("caddy responded with error: HTTP %d: %s", resp.StatusCode, respBody)
	}

	return resp, nil
}

Cognitive complexity: 6, Cyclomatic complexity: 5

Commands returns a list of commands initialised by RegisterCommand

func Commands() map[string]Command {
	return commands
}

Cognitive complexity: 0, Cyclomatic complexity: 1

DetermineAdminAPIAddress determines which admin API endpoint address should be used based on the inputs. By priority: if address is specified, then it is returned; if config is specified, then that config will be used for finding the admin address; if configFile (and configAdapter) are specified, then that config will be loaded to find the admin address; otherwise, the default admin listen address will be returned.

func DetermineAdminAPIAddress(address string, config []byte, configFile, configAdapter string) (string, error) {
	// Prefer the address if specified and non-empty
	if address != "" {
		return address, nil
	}

	// Try to load the config from file if specified, with the given adapter name
	if configFile != "" {
		var loadedConfigFile string
		var err error

		// use the provided loaded config if non-empty
		// otherwise, load it from the specified file/adapter
		loadedConfig := config
		if len(loadedConfig) == 0 {
			// get the config in caddy's native format
			loadedConfig, loadedConfigFile, err = LoadConfig(configFile, configAdapter)
			if err != nil {
				return "", err
			}
			if loadedConfigFile == "" {
				return "", fmt.Errorf("no config file to load; either use --config flag or ensure Caddyfile exists in current directory")
			}
		}

		// get the address of the admin listener from the config
		if len(loadedConfig) > 0 {
			var tmpStruct struct {
				Admin caddy.AdminConfig `json:"admin"`
			}
			err := json.Unmarshal(loadedConfig, &tmpStruct)
			if err != nil {
				return "", fmt.Errorf("unmarshaling admin listener address from config: %v", err)
			}
			if tmpStruct.Admin.Listen != "" {
				return tmpStruct.Admin.Listen, nil
			}
		}
	}

	// Fallback to the default listen address otherwise
	return caddy.DefaultAdminListen, nil
}

Cognitive complexity: 17, Cyclomatic complexity: 9

LoadConfig loads the config from configFile and adapts it using adapterName. If adapterName is specified, configFile must be also. If no configFile is specified, it tries loading a default config file. The lack of a config file is not treated as an error, but false will be returned if there is no config available. It prints any warnings to stderr, and returns the resulting JSON config bytes along with the name of the loaded config file (if any).

func LoadConfig(configFile, adapterName string) ([]byte, string, error) {
	return loadConfigWithLogger(caddy.Log(), configFile, adapterName)
}

Cognitive complexity: 0, Cyclomatic complexity: 1

Main implements the main function of the caddy command. Call this if Caddy is to be the main() of your program.

func Main() {
	if len(os.Args) == 0 {
		fmt.Printf("[FATAL] no arguments provided by OS; args[0] must be command\n")
		os.Exit(caddy.ExitCodeFailedStartup)
	}

	undo, err := maxprocs.Set()
	defer undo()
	if err != nil {
		caddy.Log().Warn("failed to set GOMAXPROCS", zap.Error(err))
	}

	if err := defaultFactory.Build().Execute(); err != nil {
		var exitError *exitError
		if errors.As(err, &exitError) {
			os.Exit(exitError.ExitCode)
		}
		os.Exit(1)
	}
}

Cognitive complexity: 8, Cyclomatic complexity: 5

RegisterCommand registers the command cmd. cmd.Name must be unique and conform to the following format:

• lowercase
• alphanumeric and hyphen characters only
• cannot start or end with a hyphen
• hyphen cannot be adjacent to another hyphen

This function panics if the name is already registered, if the name does not meet the described format, or if any of the fields are missing from cmd.

This function should be used in init().

func RegisterCommand(cmd Command) {
	if cmd.Name == "" {
		panic("command name is required")
	}
	if cmd.Func == nil && cmd.CobraFunc == nil {
		panic("command function missing")
	}
	if cmd.Short == "" {
		panic("command short string is required")
	}
	if _, exists := commands[cmd.Name]; exists {
		panic("command already registered: " + cmd.Name)
	}
	if !commandNameRegex.MatchString(cmd.Name) {
		panic("invalid command name")
	}
	defaultFactory.Use(func(rootCmd *cobra.Command) {
		rootCmd.AddCommand(caddyCmdToCobra(cmd))
	})
}

Cognitive complexity: 11, Cyclomatic complexity: 7

WrapCommandFuncForCobra wraps a Caddy CommandFunc for use in a cobra command's RunE field.

func WrapCommandFuncForCobra(f CommandFunc) func(cmd *cobra.Command, _ []string) error {
	return func(cmd *cobra.Command, _ []string) error {
		status, err := f(Flags{cmd.Flags()})
		if status > 1 {
			cmd.SilenceErrors = true
			return &exitError{ExitCode: status, Err: err}
		}
		return err
	}
}

Cognitive complexity: 5, Cyclomatic complexity: 2

func (ss *StringSlice) Set(value string) error {
	*ss = append(*ss, value)
	return nil
}

Cognitive complexity: 0, Cyclomatic complexity: 1

func (e *exitError) Error() string {
	if e.Err == nil {
		return fmt.Sprintf("exiting with status %d", e.ExitCode)
	}
	return e.Err.Error()
}

Cognitive complexity: 2, Cyclomatic complexity: 2

func (f *rootCommandFactory) Build() *cobra.Command {
	o := f.constructor()
	for _, v := range f.options {
		v(o)
	}
	return o
}

Cognitive complexity: 3, Cyclomatic complexity: 2

func (f *rootCommandFactory) Use(fn func(cmd *cobra.Command)) {
	f.options = append(f.options, fn)
}

Cognitive complexity: 0, Cyclomatic complexity: 1

Bool returns the boolean representation of the flag given by name. It returns false if the flag is not a boolean type. It panics if the flag is not in the flag set.

func (f Flags) Bool(name string) bool {
	val, _ := strconv.ParseBool(f.String(name))
	return val
}

Cognitive complexity: 0, Cyclomatic complexity: 1

Duration returns the duration representation of the flag given by name. It returns false if the flag is not a duration type. It panics if the flag is not in the flag set.

func (f Flags) Duration(name string) time.Duration {
	val, _ := caddy.ParseDuration(f.String(name))
	return val
}

Cognitive complexity: 0, Cyclomatic complexity: 1

Float64 returns the float64 representation of the flag given by name. It returns false if the flag is not a float64 type. It panics if the flag is not in the flag set.

func (f Flags) Float64(name string) float64 {
	val, _ := strconv.ParseFloat(f.String(name), 64)
	return val
}

Cognitive complexity: 0, Cyclomatic complexity: 1

Int returns the integer representation of the flag given by name. It returns 0 if the flag is not an integer type. It panics if the flag is not in the flag set.

func (f Flags) Int(name string) int {
	val, _ := strconv.ParseInt(f.String(name), 0, strconv.IntSize)
	return int(val)
}

Cognitive complexity: 0, Cyclomatic complexity: 1

String returns the string representation of the flag given by name. It panics if the flag is not in the flag set.

func (f Flags) String(name string) string {
	return f.FlagSet.Lookup(name).Value.String()
}

Cognitive complexity: 0, Cyclomatic complexity: 1