caddyconfig

Documentation

Index

• func JSON(val any, warnings *[]Warning) json.RawMessage
• func JSONModuleObject(val any, fieldName, fieldVal string, warnings *[]Warning) json.RawMessage
• func RegisterAdapter(name string, adapter Adapter)
• type Adapter
  • func GetAdapter(name string) Adapter
• type HTTPLoader
  • func (HTTPLoader) CaddyModule() caddy.ModuleInfo
  • func (hl HTTPLoader) LoadConfig(ctx caddy.Context) ([]byte, error)
• type Warning
  • func (w Warning) String() string

Functions

func JSON

func JSON(val any, warnings *[]Warning) json.RawMessage

JSON encodes val as JSON, returning it as a json.RawMessage. Any marshaling errors (which are highly unlikely with correct code) are converted to warnings. This is convenient when filling config structs that require a json.RawMessage, without having to worry about errors.

func JSONModuleObject

func JSONModuleObject(val any, fieldName, fieldVal string, warnings *[]Warning) json.RawMessage

JSONModuleObject is like JSON(), except it marshals val into a JSON object with an added key named fieldName with the value fieldVal. This is useful for encoding module values where the module name has to be described within the object by a certain key; for example, `"handler": "file_server"` for a file server HTTP handler (fieldName="handler" and fieldVal="file_server"). The val parameter must encode into a map[string]any (i.e. it must be a struct or map). Any errors are converted into warnings.

func RegisterAdapter

func RegisterAdapter(name string, adapter Adapter)

RegisterAdapter registers a config adapter with the given name. This should usually be done at init-time. It panics if the adapter cannot be registered successfully.

Types

type Adapter

type Adapter interface {
	Adapt(body []byte, options map[string]any) ([]byte, []Warning, error)
}

Adapter is a type which can adapt a configuration to Caddy JSON. It returns the results and any warnings, or an error.

func GetAdapter

func GetAdapter(name string) Adapter

GetAdapter returns the adapter with the given name, or nil if one with that name is not registered.

type HTTPLoader

type HTTPLoader struct {
	// The method for the request. Default: GET
	Method string `json:"method,omitempty"`

	// The URL of the request.
	URL string `json:"url,omitempty"`

	// HTTP headers to add to the request.
	Headers http.Header `json:"header,omitempty"`

	// Maximum time allowed for a complete connection and request.
	Timeout caddy.Duration `json:"timeout,omitempty"`

	// The name of the config adapter to use, if any. Only needed
	// if the HTTP response is not a JSON config and if the server's
	// Content-Type header is missing or incorrect.
	Adapter string `json:"adapter,omitempty"`

	TLS *struct {
		// Present this instance's managed remote identity credentials to the server.
		UseServerIdentity bool `json:"use_server_identity,omitempty"`

		// PEM-encoded client certificate filename to present to the server.
		ClientCertificateFile string `json:"client_certificate_file,omitempty"`

		// PEM-encoded key to use with the client certificate.
		ClientCertificateKeyFile string `json:"client_certificate_key_file,omitempty"`

		// List of PEM-encoded CA certificate files to add to the same trust
		// store as RootCAPool (or root_ca_pool in the JSON).
		RootCAPEMFiles []string `json:"root_ca_pem_files,omitempty"`
	} `json:"tls,omitempty"`
}

HTTPLoader can load Caddy configs over HTTP(S).

If the response is not a JSON config, a config adapter must be specified either in the loader config (`adapter`), or in the Content-Type HTTP header returned in the HTTP response from the server. The Content-Type header is read just like the admin API's `/load` endpoint. Uf you don't have control over the HTTP server (but can still trust its response), you can override the Content-Type header by setting the `adapter` property in this config.

func (HTTPLoader) CaddyModule

func (HTTPLoader) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (HTTPLoader) LoadConfig

func (hl HTTPLoader) LoadConfig(ctx caddy.Context) ([]byte, error)

LoadConfig loads a Caddy config.

type Warning

type Warning struct {
	File      string `json:"file,omitempty"`
	Line      int    `json:"line,omitempty"`
	Directive string `json:"directive,omitempty"`
	Message   string `json:"message,omitempty"`
}

Warning represents a warning or notice related to conversion.

func (Warning) String

func (w Warning) String() string