github.com/caddyserver/caddy/v2/caddyconfig

No package summary is available.

Package

Files: 3. Third party imports: 0. Imports from organisation: 0. Tests: 0. Benchmarks: 0.

Vars

Types

Adapter

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

Field name	Field type	Comment
type	`any`	No comment on field.

HTTPLoader

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. If 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.

Field name	Field type	Comment
Method	`string`	The method for the request. Default: GET
URL	`string`	The URL of the request.
Headers	`http.Header`	HTTP headers to add to the request.
Timeout	`caddy.Duration`	Maximum time allowed for a complete connection and request.
Adapter	`string`	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.
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"` }	No comment on field.

Warning

Warning represents a warning or notice related to conversion.

Field name	Field type	Comment
File	`string`	No comment on field.
Line	`int`	No comment on field.
Directive	`string`	No comment on field.
Message	`string`	No comment on field.

adapterModule

adapterModule is a wrapper type that can turn any config adapter into a Caddy module, which has the benefit of being counted with other modules, even though they do not technically extend the Caddy configuration structure. See caddyserver/caddy#3132.

Field name	Field type	Comment
name	`string`	No comment on field.
	`Adapter`	No comment on field.

adminLoad

adminLoad is a module that provides the /load endpoint for the Caddy admin API. The only reason it's not baked into the caddy package directly is because of the import of the caddyconfig package for its GetAdapter function. If the caddy package depends on the caddyconfig package, then the caddyconfig package will not be able to import the caddy package, and it can more easily cause backward edges in the dependency tree (i.e. import cycle). Fortunately, the admin API has first-class support for adding endpoints from modules.

Functions

func GetAdapter

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

func JSON

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.

Uses: json.Marshal.

func JSONModuleObject

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.

Uses: json.Marshal, json.Unmarshal.

func RegisterAdapter

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.

Uses: fmt.Errorf.

func (HTTPLoader) CaddyModule

CaddyModule returns the Caddy module information.

func (HTTPLoader) LoadConfig

LoadConfig loads a Caddy config.

Uses: fmt.Errorf, http.MethodGet, http.NewRequest, io.ReadAll.

func (Warning) String

Uses: fmt.Sprintf.

func (adapterModule) CaddyModule

func (adminLoad) CaddyModule

CaddyModule returns the Caddy module information.

func (adminLoad) Routes

Routes returns a route for the /load endpoint.

Private functions

func adaptByContentType

adaptByContentType adapts body to Caddy JSON using the adapter specified by contentType. If contentType is empty or ends with "/json", the input will be returned, as a no-op.

References: fmt.Errorf, http.StatusBadRequest, mime.ParseMediaType, strings.Cut, strings.HasSuffix.

func attemptHttpCall

References: fmt.Errorf.

func doHttpCallWithRetries

References: http.Response, time.After, time.Millisecond.

func init

func makeClient

References: fmt.Errorf, http.Client, http.Transport, os.ReadFile, time.Duration, tls.Certificate, tls.Config, tls.LoadX509KeyPair, x509.NewCertPool.

func handleAdapt

handleAdapt adapts the given Caddy config to JSON and responds with the result.

References: bytes.Buffer, fmt.Errorf, http.MethodPost, http.StatusBadRequest, http.StatusMethodNotAllowed, io.Copy, json.NewEncoder, json.RawMessage.

func handleLoad

handleLoad replaces the entire current configuration with a new one provided in the response body. It supports config adapters through the use of the Content-Type header. A config that is identical to the currently-running config will be a no-op unless Cache-Control: must-revalidate is set.

References: bytes.Buffer, fmt.Errorf, http.MethodPost, http.StatusBadRequest, http.StatusMethodNotAllowed, io.Copy, json.Marshal.