appendSubrouteToRouteList appends the routes in subroute to the routeList, optionally qualified by matchers.

References: caddyconfig.JSONModuleObject, caddyhttp.Route, json.RawMessage.

applyServerOptions sets the server options on the appropriate servers

References: caddyhttp.ServerLogConfig, fmt.Errorf, slices.Contains, slices.IndexFunc.

automationPolicyHasAllPublicNames returns true if all the names on the policy do NOT qualify for public certs OR are tailscale domains.

References: slices.ContainsFunc.

automationPolicyIsSubset returns true if a's subjects are a subset of b's subjects.

References: certmagic.MatchWildcard, slices.ContainsFunc.

automationPolicyShadows returns the index of a policy that aps[i] shadows; in other words, for all policies after position i, if that policy covers the same subjects but is less specific, that policy's position is returned, or -1 if no shadowing is found. For example, if policy i is for "foo.example.com" and policy i+2 is for "*.example.com", then i+2 will be returned, since that policy is shadowed by i, which is in front.

buildSubroute turns the config values, which are expected to be routes into a clean and orderly subroute that has all the routes within it.

References: caddyhttp.Route, caddyhttp.Subroute, fmt.Errorf, slices.Contains, sort.Strings.

consolidateAutomationPolicies combines automation policies that are the same, for a cleaner overall output.

References: bytes.Equal, caddytls.AutomationPolicy, reflect.DeepEqual, slices.Contains, slices.Delete, sort.SliceStable.

consolidateConnPolicies sorts any catch-all policy to the end, removes empty TLS connection policies, and combines equivalent ones for a cleaner overall output.

References: caddytls.MatchServerName, fmt.Errorf, json.Marshal, json.Unmarshal, reflect.DeepEqual, slices.Contains, slices.Delete, sort.SliceStable.

consolidateRoutes combines routes with the same properties (same matchers, same Terminal and Group settings) for a cleaner overall output.

References: reflect.DeepEqual.

References: caddyhttp.DefaultHTTPPort, caddyhttp.DefaultHTTPSPort, fmt.Errorf, strconv.Itoa.

References: fmt.Errorf, json.Marshal.

References: acme.EAB, caddyconfig.JSONModuleObject, caddytls.ChainPreference, caddytls.ChallengesConfig, caddytls.DNSChallengeConfig, caddytls.HTTPChallengeConfig, caddytls.TLSALPNChallengeConfig, slices.Contains.

References: certmagic.MatchWildcard, strings.HasPrefix.

References: strings.HasSuffix, strings.ToLower.

listenersUseAnyPortOtherThan returns true if there are any listeners in addresses that use a port which is not otherPort. Mostly borrowed from unexported method in caddyhttp package.

References: strconv.Atoi.

lowerExceptPlaceholders lowercases s except within placeholders (substrings in non-escaped '{ }' spans). See https://github.com/caddyserver/caddy/issues/3264

References: strings.Builder, unicode.ToLower.

References: caddyconfig.JSON, caddyhttp.MatchPath, fmt.Errorf, strings.HasPrefix.

newBaseAutomationPolicy returns a new TLS automation policy that gets its values from the global options map. It should be used as the base for any other automation policies. A nil policy (and no error) will be returned if there are no default/global options. However, if always is true, a non-nil value will always be returned (unless there is an error).

References: caddytls.AutomationPolicy, caddytls.InternalIssuer, certmagic.Issuer, certmagic.OCSPConfig, fmt.Errorf.

normalizeDirectiveName ensures directives that should be sorted at the same level are named the same before sorting happens.

parseAbort parses the abort directive.

References: caddyhttp.StaticResponse.

parseBind parses the bind directive. Syntax:

	bind <addresses...> [{
   protocols [h1|h2|h2c|h3] [...]
 }]

parseError parses the error directive.

References: caddyhttp.StaticError.

parseFilesystem parses the fs directive. Syntax:

fs <filesystem>

References: caddyhttp.VarsMiddleware.

References: caddyhttp.MatchExpression, caddyhttp.Subroute, fmt.Sprintf, strconv.Atoi, strings.HasSuffix, strings.Join.

parseInvoke parses the invoke directive.

References: caddyhttp.Invoke.

parseLog parses the log directive. Syntax:

log <logger_name> {
    hostnames <hostnames...>
    output <writer_module> ...
    core   <core_module> ...
    format <encoder_module> ...
    level  <level>
}

parseLogHelper is used both for the parseLog directive within Server Blocks, as well as the global "log" option for configuring loggers at the global level. The parseAsGlobalOption parameter is used to distinguish any differing logic between the two.

References: caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, fmt.Sprintf, reflect.DeepEqual, strconv.Atoi, time.ParseDuration, zapcore.Core, zapcore.Encoder.

parseLogName parses the log_name directive. Syntax:

log_name <names...>

References: caddyhttp.AccessLoggerNameVarKey, caddyhttp.VarsMiddleware.

parseLogOptions parses the global log option. Syntax:

log [name] {
    output  <writer_module> ...
    format  <encoder_module> ...
    level   <level>
    include <namespaces...>
    exclude <namespaces...>
}

When the name argument is unspecified, this directive modifies the default logger.

References: caddyconfig.Warning.

parseLogSkip parses the log_skip directive. Syntax:

log_skip [<matcher>]

References: caddyhttp.VarsMiddleware.

References: caddyconfig.JSON, caddyfile.MatcherNameCtxKey, caddyfile.NewDispenser, caddyfile.Token, caddyfile.Unmarshaler, caddyhttp.RequestMatcher, caddyhttp.RequestMatcherWithError, fmt.Errorf.

References: certmagic.OCSPConfig.

References: acme.EAB.

References: caddyfile.UnmarshalModule, certmagic.Issuer.

References: caddyfile.UnmarshalModule, libdns.RecordAppender, libdns.RecordDeleter, libdns.RecordGetter, libdns.RecordSetter.

References: caddyconfig.JSON, caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, caddytls.ECH, caddytls.ECHConfiguration, caddytls.ECHDNSPublisher, caddytls.ECHPublication.

References: strconv.Atoi.

References: strconv.Atoi.

References: caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, caddytls.OnDemandConfig, caddytls.OnDemandPermission, caddytls.PermissionByHTTP.

References: slices.DeleteFunc, slices.Index, slices.Insert.

References: caddytls.ParseCaddyfilePreferredChainsOptions.

References: caddyfile.UnmarshalModule.

parsePKIApp parses the global log option. Syntax:

pki {
    ca [<id>] {
        name                  <name>
        root_cn               <name>
        intermediate_cn       <name>
        intermediate_lifetime <duration>
        root {
            cert   <path>
            key    <path>
            format <format>
        }
        intermediate {
            cert   <path>
            key    <path>
            format <format>
        }
    }
}

When the CA ID is unspecified, 'local' is assumed.

References: caddypki.CA, caddypki.DefaultCAID, caddypki.KeyPair, caddypki.PKI.

parseRedir parses the redir directive. Syntax:

redir [<matcher>] <to> [<code>]

<code> can be "permanent" for 301, "temporary" for 302 (default), a placeholder, or any number in the 3xx range or 401. The special code "html" can be used to redirect only browser clients (will respond with HTTP 200 and no Location header; redirect is performed with JS and a meta tag).

References: caddyhttp.StaticResponse, caddyhttp.WeakString, fmt.Sprintf, html.EscapeString, http.Header, strconv.Atoi, strings.HasPrefix.

parseRespond parses the respond directive.

References: caddyhttp.StaticResponse.

parseRoot parses the root directive. Syntax:

root [<matcher>] <path>

References: caddyhttp.VarsMiddleware.

parseRoute parses the route directive.

References: caddyhttp.Route, caddyhttp.Subroute.

parseSegmentAsConfig parses the segment such that its subdirectives are themselves treated as directives, including named matcher definitions, and the raw Config structs are returned.

References: caddyfile.NewDispenser, caddyfile.Segment, maps.Copy, strings.HasPrefix.

parseTLS parses the tls directive. Syntax:

tls [<email>|internal|force_automate]|[<cert_file> <key_file>] {
    protocols <min> [<max>]
    ciphers   <cipher_suites...>
    curves    <curves...>
    client_auth {
        mode                   [request|require|verify_if_given|require_and_verify]
        trust_pool			   <module_name> [...]
        trusted_leaf_cert      <base64_der>
        trusted_leaf_cert_file <filename>
    }
    alpn                          <values...>
    load                          <paths...>
    ca                            <acme_ca_endpoint>
    ca_root                       <pem_file>
    key_type                      [ed25519|p256|p384|rsa2048|rsa4096]
    dns                           [<provider_name> [...]]    (required, though, if DNS is not configured as global option)
    propagation_delay             <duration>
    propagation_timeout           <duration>
    resolvers                     <dns_servers...>
    dns_ttl                       <duration>
    dns_challenge_override_domain <domain>
    on_demand
    reuse_private_keys
    force_automate
    eab                           <key_id> <mac_key>
    issuer                        <module_name> [...]
    get_certificate               <module_name> [...]
    insecure_secrets_log          <log_file>
}

References: acme.EAB, caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, caddytls.ACMEIssuer, caddytls.CertKeyFilePair, caddytls.ChallengesConfig, caddytls.CipherSuiteNameSupported, caddytls.ClientAuthentication, caddytls.ConnectionPolicy, caddytls.CustomCertSelectionPolicy, caddytls.DNSChallengeConfig, caddytls.DefaultIssuers, caddytls.FileLoader, caddytls.FolderLoader, caddytls.InternalIssuer, caddytls.SupportedCurves, caddytls.SupportedProtocols, certmagic.Issuer, certmagic.Manager, fmt.Sprintf, strings.Contains, time.Duration.

parseVars parses the vars directive. See its UnmarshalCaddyfile method for syntax.

References: caddyhttp.VarsMiddleware.

placeholderShorthands returns a slice of old-new string pairs, where the left of the pair is a placeholder shorthand that may be used in the Caddyfile, and the right is the replacement.

References: caddyhttp.MatchPath, caddyhttp.Route, json.Unmarshal, sort.SliceStable, strings.TrimSuffix.

specificity returns len(s) minus any wildcards () and placeholders ({...}). Basically, it's a length count that penalizes the use of wildcards and placeholders. This is useful for comparing hostnames and paths. However, wildcards in paths are not a sure answer to the question of specificity. For example, '.example.com' is clearly less specific than 'a.example.com', but is '/a' more or less specific than '/a*'?

References: strings.Count, strings.Index.

subjectQualifiesForPublicCert is like certmagic.SubjectQualifiesForPublicCert() except that this allows domains with multiple wildcard levels like '..example.com' to qualify if the automation policy has OnDemand enabled (i.e. this function is more lenient).

IP subjects are considered as non-qualifying for public certs. Technically, there are now public ACME CAs as well as non-ACME CAs that issue IP certificates. But this function is used solely for implicit automation (defaults), where it gets really complicated to keep track of which issuers support IP certificates in which circumstances. Currently, issuers that support IP certificates are very few, and all require some sort of config from the user anyway (such as an account credential). Since we cannot implicitly and automatically get public IP certs without configuration from the user, we treat IPs as not qualifying for public certificates. Users should expressly configure an issuer that supports IP certs for that purpose.

References: certmagic.SubjectIsIP, certmagic.SubjectIsInternal, strings.Count.

References: caddyconfig.Warning.

tryInt tries to convert val to an integer. If it fails, it downgrades the error to a warning and returns 0.

References: caddyconfig.Warning.

References: caddyconfig.Warning.

References: caddyhttp.Metrics.

References: caddyconfig.JSONModuleObject, caddyfile.UnmarshalModule, caddyhttp.IPRangeSource, caddyhttp.Metrics, fmt.Errorf, humanize.ParseBytes, slices.Contains.

References: caddyhttp.MatchHost, caddyhttp.MatchPath, caddyhttp.RequestMatcherWithError, fmt.Errorf, slices.Contains.

consolidateAddrMappings eliminates repetition of identical server blocks in a mapping of single listener addresses to protocols to lists of server blocks. Since multiple addresses may serve multiple protocols to identical sites (server block contents), this function turns a 1:many mapping into a many:many mapping. Server block contents (tokens) must be exactly identical so that reflect.DeepEqual returns true in order for the addresses to be combined. Identical entries are deleted from the addrToServerBlocks map. Essentially, each pairing (each association from multiple addresses to multiple server blocks; i.e. each element of the returned slice) becomes a server definition in the output JSON.

References: reflect.DeepEqual, sort.Strings.

listenersForServerBlockAddress essentially converts the Caddyfile site addresses to a map from Caddy listener addresses and the protocols to serve them with to the parsed address for each server block.

References: caddyhttp.DefaultHTTPPort, caddyhttp.DefaultHTTPSPort, fmt.Errorf, strconv.Itoa.

mapAddressToProtocolToServerBlocks returns a map of listener address to list of server blocks that will be served on that address. To do this, each server block is expanded so that each one is considered individually, although keys of a server block that share the same address stay grouped together so the config isn't repeated unnecessarily. For example, this Caddyfile:

example.com {
	bind 127.0.0.1
}
www.example.com, example.net/path, localhost:9999 {
	bind 127.0.0.1 1.2.3.4
}

has two server blocks to start with. But expressed in this Caddyfile are actually 4 listener addresses: 127.0.0.1:443, 1.2.3.4:443, 127.0.0.1:9999, and 127.0.0.1:9999. This is because the bind directive is applied to each key of its server block (specifying the host part), and each key may have a different port. And we definitely need to be sure that a site which is bound to be served on a specific interface is not served on others just because that is more convenient: it would be a potential security risk if the difference between interfaces means private vs. public.

So what this function does for the example above is iterate each server block, and for each server block, iterate its keys. For the first, it finds one key (example.com) and determines its listener address (127.0.0.1:443 - because of 'bind' and automatic HTTPS). It then adds the listener address to the map value returned by this function, with the first server block as one of its associations.

It then iterates each key on the second server block and associates them with one or more listener addresses. Indeed, each key in this block has two listener addresses because of the 'bind' directive. Once we know which addresses serve which keys, we can create a new server block for each address containing the contents of the server block and only those specific keys of the server block which use that address.

It is possible and even likely that some keys in the returned map have the exact same list of server blocks (i.e. they are identical). This happens when multiple hosts are declared with a 'bind' directive and the resulting listener addresses are not shared by any other server block (or the other server blocks are exactly identical in their token contents). This happens with our example above because 1.2.3.4:443 and 1.2.3.4:9999 are used exclusively with the second server block. This repetition may be undesirable, so call consolidateAddrMappings() to map multiple addresses to the same lists of server blocks (a many:many mapping). (Doing this is essentially a map-reduce technique.)

References: caddyfile.ServerBlock, caddyfile.Token, fmt.Errorf, sort.Strings.

serversFromPairings creates the servers for each pairing of addresses to server blocks. Each pairing is essentially a server definition.

References: caddyconfig.JSON, caddyconfig.JSONModuleObject, caddyhttp.AutoHTTPSConfig, caddyhttp.DefaultHTTPPort, caddyhttp.DefaultHTTPSPort, caddyhttp.HTTPErrorConfig, caddyhttp.Route, caddyhttp.Server, caddyhttp.ServerLogConfig, caddyhttp.StringArray, caddyhttp.Subroute, caddytls.ConnectionPolicy, fmt.Errorf, fmt.Sprintf, net.SplitHostPort, slices.Contains, slices.Sort, sort.SliceStable, strconv.Itoa, strings.Contains, zap.String.

References: caddypki.CA, caddypki.DefaultCAID, caddypki.PKI.

References: caddyconfig.JSON, caddyconfig.JSONModuleObject, caddyhttp.DefaultHTTPPort, caddytls.ACMEIssuer, caddytls.AutomateLoader, caddytls.AutomationConfig, caddytls.AutomationPolicy, caddytls.CertificateLoader, caddytls.ChallengesConfig, caddytls.DefaultIssuers, caddytls.ECH, caddytls.InternalIssuer, caddytls.OnDemandConfig, caddytls.TLS, certmagic.Issuer, certmagic.OCSPConfig, certmagic.SubjectQualifiesForCert, certmagic.SubjectQualifiesForPublicCert, fmt.Errorf, json.RawMessage, reflect.Append, reflect.DeepEqual, reflect.New, reflect.Slice, reflect.TypeOf, reflect.ValueOf, slices.Contains, slices.Sort, sort.Strings, strconv.Itoa, strings.HasPrefix.

evaluateGlobalOptionsBlock evaluates the global options block, which is expected to be the first server block if it has zero keys. It returns the updated list of server blocks with the global options block removed, and updates options accordingly.

References: caddyfile.NewDispenser, fmt.Errorf, sort.Slice.

extractNamedRoutes pulls out any named route server blocks so they don't get parsed as sites, and stores them in options for later.

References: caddyconfig.JSONModuleObject, caddyfile.NewDispenser, caddyfile.Segment, caddyhttp.Route, caddyhttp.Subroute, json.RawMessage.

References: fmt.Sprintf.

hasHostCatchAllKey returns true if sb has a key that omits a host portion, i.e. it "catches all" hosts.

References: slices.ContainsFunc.

hostsFromKeys returns a list of all the non-empty hostnames found in the keys of the server block sb. If logger mode is false, a key with an empty hostname portion will return an empty slice, since that server block is interpreted to effectively match all hosts. An empty string is never added to the slice.

If loggerMode is true, then the non-standard ports of keys will be joined to the hostnames. This is to effectively match the Host header of requests that come in for that key.

The resulting slice is not sorted but will never have duplicates.

References: caddyhttp.DefaultHTTPPort, caddyhttp.DefaultHTTPSPort, net.JoinHostPort, strconv.Itoa.

isAllHTTP returns true if all sb keys explicitly specify the http:// scheme

References: slices.ContainsFunc.