ingress

type ACMEEventsApp struct{}

type ACMEFailure struct {
	Identifier string
	Error      string
	Renewal    bool
	At         time.Time
}

type ACMEFailures struct {
	// contains filtered or unexported fields
}

type ACMEIssuer struct {
	Module string `json:"module"`
	// Email is the ACME account contact address, Caddy's own "email"
	// field verbatim. Not technically required by the ACME protocol
	// itself, but this codebase's own settings validation
	// (internal/api) requires a non-empty, syntactically valid address
	// whenever ACME is enabled: an unreachable ACME account is exactly
	// the kind of "renewal fails silently" risk this project treats as
	// its central one to catch before it bites a real user.
	Email string `json:"email,omitempty"`
	// CA is Caddy's own "ca" field: the ACME directory endpoint URL.
	// Empty leaves Caddy's compiled-in default in place, Let's Encrypt's
	// real production directory
	// (https://acme-v02.api.letsencrypt.org/directory, per
	// caddytls.ACMEIssuer's own doc comment). An operator who wants to
	// avoid Let's Encrypt's production rate limits while testing should
	// set this explicitly to Let's Encrypt's staging directory
	// (https://acme-staging-v02.api.letsencrypt.org/directory); this
	// package does not default to staging on its own, since silently
	// issuing a staging (browser-untrusted) certificate for what an
	// operator believes is a production toggle would be a worse
	// surprise than requiring them to opt in explicitly.
	CA string `json:"ca,omitempty"`
	// Challenges is non-nil for wildcard subjects (NewDNSACMEIssuer sets
	// DNS-01 here, RFC 8555 7.1.1 forbids HTTP-01 for a wildcard
	// identifier) or when a non-default HTTP-01 port is configured
	// (NewACMEIssuer's altHTTPPort parameter).
	Challenges *ChallengesConfig `json:"challenges,omitempty"`
}

type AbuseHandler struct {
	Handler string       `json:"handler"`
	App     string       `json:"app"`
	Policy  abuse.Policy `json:"policy"`
}

type AbusePolicy struct {
	App    string
	Policy abuse.Policy
}

type AccessFilter struct {
	MinMillis float64
	MinStatus int
	Since     time.Time
	Path      string
	Limit     int
}

type AccessLog struct {
	// contains filtered or unexported fields
}

type AccessRecord struct {
	Time      time.Time `json:"time"`
	Host      string    `json:"host"`
	Method    string    `json:"method"`
	Path      string    `json:"path"`
	Status    int       `json:"status"`
	Millis    float64   `json:"duration_ms"`
	BytesIn   int64     `json:"bytes_in"`
	BytesOut  int64     `json:"bytes_out"`
	RequestID string    `json:"request_id"`
	TraceID   string    `json:"trace_id,omitempty"`
	Upstream  bool      `json:"upstream_error,omitempty"`
	Cold      bool      `json:"cold_start,omitempty"`

	Identity *RequestIdentity `json:"-"`
	// Client and UserAgent stay in process memory for the abuse defense dry
	// run. They are never serialized, so no read API can return them.
	Client    netip.Addr `json:"-"`
	UserAgent string     `json:"-"`
	// Referrer is the Referer host only, kept in memory for the visitor summary and never serialized.
	Referrer string `json:"-"`
}

type ActiveHealthChecks struct {
	URI          string `json:"uri,omitempty"`
	Interval     string `json:"interval,omitempty"`
	Timeout      string `json:"timeout,omitempty"`
	Passes       int    `json:"passes,omitempty"`
	Fails        int    `json:"fails,omitempty"`
	ExpectStatus int    `json:"expect_status,omitempty"`
}

type ActiveSplit struct {
	TestID        string
	CookieName    string
	CookieTTL     time.Duration
	OverrideParam string
	Variants      []splittest.Variant
	VariantHosts  map[string]string
}

type AdminConfig struct {
	// Listen is the admin API bind address. Empty means Caddy's default,
	// localhost:2019.
	Listen string `json:"listen,omitempty"`
	// Disabled, if true, turns the admin listener off entirely. This
	// spike leaves it false (the real default) so the admin endpoint
	// actually comes up, since a production driver would want it
	// reachable for introspection even though this package itself talks
	// to Caddy via Go function calls (caddy.Load), not HTTP requests to
	// that listener.
	Disabled bool `json:"disabled,omitempty"`
	// Config holds admin-level config-management settings, notably
	// Persist. See AdminConfigSettings.
	Config *AdminConfigSettings `json:"config,omitempty"`
}

type AdminConfigSettings struct {
	// Persist controls whether Caddy keeps its own on-disk copy of
	// whatever config was last pushed to it (Caddy's default is true,
	// written to a fixed OS-level app-data path independent of the
	// storage module configured for certificates, see FileStorage's doc
	// comment). This spike found that surprising: it means an embedded
	// Caddy instance maintains a second, out-of-band record of its own
	// config on disk even when the storage module is pointed elsewhere,
	// which is exactly the "second config surface" ADR 005 argues
	// against embedding Caddy specifically to avoid. This spike's
	// builder pins it to false: the platform's own reconcile loop and
	// database are the single source of truth for desired ingress
	// state, not a file Caddy manages on its own.
	Persist *bool `json:"persist,omitempty"`
}

type Apps struct {
	HTTP *HTTPApp `json:"http,omitempty"`
	TLS  *TLSApp  `json:"tls,omitempty"`
	PKI  *PKIApp  `json:"pki,omitempty"`
	// Layer4 carries every raw TCP stream (internal/reconcile/ingress's
	// StreamRoute), applied in the exact same Config/caddy.Load call as
	// HTTP/TLS/PKI above: see layer4.go's own package doc comment for why
	// a stream can't be a second, independently-applied Caddy config.
	Layer4 *Layer4App `json:"layer4,omitempty"`
	// ACMEEvents feeds certificate success and failure events to DefaultACMEFailures.
	ACMEEvents *ACMEEventsApp `json:"acme_events,omitempty"`
}

type AuditRecorder interface {
	SaveAuditEntry(ctx context.Context, e store.AuditEntry) error
}

type AuthGate struct {
	URL         string
	CheckPath   string
	CopyHeaders []string
	Timeout     time.Duration
	// SetHeaders are set on the subrequest only, overwriting client values.
	// Internal use (built-in provider); values may hold Caddy placeholders.
	SetHeaders map[string]string
}

type AutoHTTPSConfig struct {
	Disabled     bool `json:"disable,omitempty"`
	DisableRedir bool `json:"disable_redirects,omitempty"`
}

type AutoHostOptOutSource interface {
	ListAppAutoHostOptOuts(ctx context.Context) (map[string]bool, error)
}

type Automation struct {
	Policies []AutomationPolicy `json:"policies,omitempty"`
}

type AutomationPolicy struct {
	Subjects []string `json:"subjects,omitempty"`
	Issuers  []any    `json:"issuers,omitempty"`
	// OnDemand defers issuance to the first TLS handshake for a subject. Subjects here are exact hosts, which is the allowlist.
	OnDemand bool `json:"on_demand,omitempty"`
}

type BasicAuthAccount struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

type BasicAuthHandler struct {
	Handler   string             `json:"handler"`
	Providers BasicAuthProviders `json:"providers"`
}

type BasicAuthHash struct {
	Algorithm string `json:"algorithm"`
}

type BasicAuthProviders struct {
	HTTPBasic *HTTPBasicAuthProvider `json:"http_basic"`
}

type CA struct {
	// InstallTrust controls whether Caddy attempts to install this CA's
	// root certificate into the local OS/browser trust store on first
	// use. Caddy's own default is true, which on this spike's dev
	// machine meant an unprompted `sudo` invocation that failed
	// noisily (no interactive terminal, no `certutil`) but did not
	// block certificate issuance. That's tolerable on a developer
	// laptop; it is the wrong default for a headless server process,
	// which has no desktop trust store to install into and should
	// never attempt an interactive sudo prompt at startup. This spike's
	// TLS builder pins it to false explicitly rather than relying on
	// Caddy's default.
	InstallTrust *bool `json:"install_trust,omitempty"`
}

type CARetryBackoff func(ctx context.Context) (base, ceiling time.Duration)

type CacheBucket struct {
	Minute    int64  `json:"minute"`
	Hits      uint64 `json:"hits"`
	Misses    uint64 `json:"misses"`
	HitBytes  uint64 `json:"hit_bytes"`
	MissBytes uint64 `json:"miss_bytes"`
}

type CacheHandler struct {
	Handler        string                    `json:"handler"`
	Key            string                    `json:"key"`
	Rules          []trafficpolicy.CacheRule `json:"rules"`
	MaxObjectBytes int64                     `json:"max_object_bytes"`
	MaxTTLSeconds  int                       `json:"max_ttl_seconds"`
}

type CacheReason struct {
	Code   string `json:"code"`
	Detail string `json:"detail,omitempty"`
	Count  uint64 `json:"count"`
}

type CacheStats struct {
	Hits     uint64 `json:"hits"`
	Misses   uint64 `json:"misses"`
	Bypasses uint64 `json:"bypasses"`
	Stale    uint64 `json:"stale"`
	// HitBytes were served from the cache; OriginBytes were fetched from the
	// app on cacheable paths. HitBytes is the bandwidth the app was spared.
	HitBytes    uint64        `json:"hit_bytes"`
	OriginBytes uint64        `json:"origin_bytes"`
	Entries     int           `json:"entries"`
	Bytes       int64         `json:"bytes"`
	Series      []CacheBucket `json:"series"`
	// Reasons counts responses and requests left out of the cache, most
	// common first.
	Reasons []CacheReason `json:"reasons"`
}

type CertKeyPEMPair struct {
	CertificatePEM string   `json:"certificate"`
	KeyPEM         string   `json:"key"`
	Tags           []string `json:"tags,omitempty"`
}

type CertPurgeMarkerStore interface {
	CertPurgeStore
	GetCertStorageValue(ctx context.Context, key string) (*store.CertStorageValue, error)
	SaveCertStorageValue(ctx context.Context, key string, value []byte) error
}

type CertPurgeStore interface {
	ListCertStorageKeys(ctx context.Context, prefix string, recursive bool) ([]string, error)
	DeleteCertStorageValue(ctx context.Context, key string) error
}

type CertStore interface {
	SaveCertStorageValue(ctx context.Context, key string, value []byte) error
	GetCertStorageValue(ctx context.Context, key string) (*store.CertStorageValue, error)
	DeleteCertStorageValue(ctx context.Context, key string) error
	ExistsCertStorageValue(ctx context.Context, key string) (bool, error)
	ListCertStorageKeys(ctx context.Context, prefix string, recursive bool) ([]string, error)
	StatCertStorageValue(ctx context.Context, key string) (*store.CertStorageKeyInfo, error)
	AcquireCertStorageLock(ctx context.Context, name string, staleAfter time.Duration) (bool, error)
	TouchCertStorageLock(ctx context.Context, name string) error
	ReleaseCertStorageLock(ctx context.Context, name string) error
}

type CertificatesConfig map[string]any

type ChallengesConfig struct {
	DNS  *DNSChallengeConfig  `json:"dns,omitempty"`
	HTTP *HTTPChallengeConfig `json:"http,omitempty"`
}

type ClientIPMatcher struct {
	Ranges []string `json:"ranges"`
}

type CloudflareDNSProvider struct {
	Name     string `json:"name"`
	APIToken string `json:"api_token"`
}

type Config struct {
	Admin *AdminConfig `json:"admin,omitempty"`
	// Storage selects the Caddy storage module certificates, ACME
	// account state, and the internal issuer's local CA are persisted
	// through. Typed any rather than a single concrete struct for the
	// same reason Route.Handle and AutomationPolicy.Issuers already are
	// in this file: it is a Caddy module reference, and Caddy's module
	// system is inherently polymorphic (any value marshaling to
	// {"module": "<id>", ...} is valid here). *FileStorage (the local
	// filesystem, via NewFileStorage) and SQLiteStorageRef
	// (internal/store's SQLite, via NewSQLiteStorageRef)
	// are this package's two concrete options as of this writing; a nil
	// Storage leaves Caddy's own OS-specific default in place.
	Storage any  `json:"storage,omitempty"`
	Apps    Apps `json:"apps"`
	// Logging taps certificate-issuance errors; see newACMELogTap.
	Logging *LoggingConfig `json:"logging,omitempty"`
	// contains filtered or unexported fields
}

type CorazaWAFHandler struct {
	Handler string `json:"handler"`
	// Directives is a ModSecurity/Coraza directives block, evaluated
	// verbatim. NewCorazaWAFHandler always sets SecRuleEngine plus the
	// three @-prefixed OWASP CRS includes LoadOWASPCRS makes resolvable.
	Directives string `json:"directives"`
	// LoadOWASPCRS makes the coraza-coreruleset ruleset (compiled into
	// this binary via the blank import in driver.go) resolvable from
	// Directives' @-prefixed Include paths. NewCorazaWAFHandler always
	// sets this true; there is no per-domain custom-ruleset authoring in
	// this package, only the stock OWASP CRS.
	LoadOWASPCRS bool `json:"load_owasp_crs"`
}

type CountedItem struct {
	Label string `json:"label"`
	Count int    `json:"count"`
}

type DNS01Provider interface {
	// contains filtered or unexported methods
}

type DNSChallengeConfig struct {
	// Provider is a dns.providers.* module reference, typed any like
	// Route.Handle. Its inline_key is "name", not "module" (per
	// caddytls.DNSChallengeConfig.ProviderRaw's struct tag).
	Provider any `json:"provider"`
}

type DNSProvider struct {
	ID       string   `json:"id"`
	Name     string   `json:"name"`
	Suffix   string   `json:"suffix"`
	IPFormat IPFormat `json:"ip_format"`
	// IPv4Only providers have no known IPv6 mapping, so an IPv6 public address yields no hostname.
	IPv4Only bool   `json:"ipv4_only"`
	Note     string `json:"note"`
}

type DomainVisitors struct {
	Domain   string `json:"domain"`
	Requests int    `json:"requests"`
	Visitors int    `json:"visitors"`
}

type Driver struct {
	// contains filtered or unexported fields
}

type EdgeOverrides struct {
	TrustedProxies        string
	MaxHeaderBytes        *int64
	MaxBodyBytes          *int64
	ReadHeaderTimeoutSecs *int64
	IdleTimeoutSecs       *int64
}

type EncodeHandler struct {
	Handler   string              `json:"handler"`
	Encodings map[string]struct{} `json:"encodings"`
	Prefer    []string            `json:"prefer"`
	MinLength int                 `json:"minimum_length"`
}

type ErrorPage struct {
	StatusCode int
	Body       string
}

type ErrorsConfig struct {
	Routes []Route `json:"routes,omitempty"`
}

type ExpressionMatcher struct {
	Expr string `json:"expr"`
	// Name is always emitted: Caddy 2.11's MatchExpression.UnmarshalJSON
	// type-asserts it and panics the whole process when it is absent.
	Name string `json:"name"`
}

type FallbackResolver struct {
	// contains filtered or unexported fields
}

type FileServerHandler struct {
	Handler string `json:"handler"`
	// Root is the local filesystem directory to serve, e.g.
	// "/var/lib/levelrail-data/static/docs/abc1234". Caddy resolves
	// requests underneath it directly; there is no upstream to dial and
	// nothing here to route through Docker.
	Root string `json:"root,omitempty"`
}

type FileStorage struct {
	Module string `json:"module"`
	Root   string `json:"root,omitempty"`
}

type FirewallHandler struct {
	Handler string `json:"handler"`
}

type GeoHandler struct {
	Handler string            `json:"handler"`
	Rule    trafficpolicy.Geo `json:"rule"`
}

type GeoResolver struct {
	// contains filtered or unexported fields
}

type GeoStatus struct {
	Active       bool     `json:"active"`
	Sources      []string `json:"sources"`
	Header       string   `json:"header,omitempty"`
	HeaderNeeds  string   `json:"header_needs,omitempty"`
	DBPath       string   `json:"db_path,omitempty"`
	DBType       string   `json:"db_type,omitempty"`
	DBBuildEpoch uint     `json:"db_build_epoch,omitempty"`
	Error        string   `json:"error,omitempty"`
}

type GoogleCloudDNSModule struct {
	ServiceAccountJSON string `json:"service_account_json,omitempty"`
	// contains filtered or unexported fields
}

type GoogleCloudDNSProvider struct {
	Name               string `json:"name"`
	ServiceAccountJSON string `json:"service_account_json"`
}

type HTTPApp struct {
	Servers map[string]*Server `json:"servers,omitempty"`
	// HTTPPort mirrors Caddy's own top-level "http_port" field: the port
	// automatic-HTTPS features (an enabled redirect, or an ACME HTTP-01
	// challenge with no AlternatePort set) fall back to. 0 (omitempty)
	// keeps Caddy's compiled-in default, port 80.
	HTTPPort int `json:"http_port,omitempty"`
	// GracePeriod mirrors Caddy's grace_period: how long in-flight requests
	// get to finish on shutdown or config replacement.
	GracePeriod string `json:"grace_period,omitempty"`
}

type HTTPBasicAuthProvider struct {
	Accounts []BasicAuthAccount `json:"accounts"`
	Hash     BasicAuthHash      `json:"hash"`
}

type HTTPChallengeConfig struct {
	AlternatePort int  `json:"alternate_port,omitempty"`
	Disabled      bool `json:"disabled,omitempty"`
}

type HTTPTransport struct {
	Protocol              string             `json:"protocol"`
	TLS                   *UpstreamTLSConfig `json:"tls,omitempty"`
	DialTimeout           string             `json:"dial_timeout,omitempty"`
	ResponseHeaderTimeout string             `json:"response_header_timeout,omitempty"`
}

type Hardening struct {
	ReadHeaderTimeout time.Duration
	ReadTimeout       time.Duration
	WriteTimeout      time.Duration
	IdleTimeout       time.Duration
	MaxHeaderBytes    int
	MaxBodyBytes      int64
	Protocols         []string
	TrustedProxies    []string
	ClientIPHeaders   []string
	RetryWindow       time.Duration
	RetryInterval     time.Duration
	DialTimeout       time.Duration
	FailDuration      time.Duration
	RetryAfterSeconds int
	// GracePeriod lets in-flight requests finish when the config is replaced or
	// the process stops. Zero closes them at once.
	GracePeriod time.Duration
	// BrandName and DocsURL label the diagnostic page for unmatched hosts and
	// backendless apps; both come from the brand layer.
	BrandName string
	DocsURL   string
}

type HeaderOps struct {
	Set    map[string][]string `json:"set,omitempty"`
	Delete []string            `json:"delete,omitempty"`
}

type HeaderResponse struct {
	Set      map[string][]string `json:"set,omitempty"`
	Deferred bool                `json:"deferred,omitempty"`
}

type HeadersHandler struct {
	Handler  string          `json:"handler"`
	Request  *HeaderOps      `json:"request,omitempty"`
	Response *HeaderResponse `json:"response,omitempty"`
}

type HealthChecks struct {
	Active  *ActiveHealthChecks  `json:"active,omitempty"`
	Passive *PassiveHealthChecks `json:"passive,omitempty"`
}

type HoldRoute struct {
	Hosts []string
}

type HoldTracker struct {
	// contains filtered or unexported fields
}

type IPFormat string

type InheritedSockets struct {
	HTTPS     int
	HTTP      int
	HTTPSPort int
	HTTPPort  int
}

type InternalIssuer struct {
	Module string `json:"module"`
	// Lifetime bounds the certificate it signs, so a fallback certificate
	// is replaced (and the public issuer retried) soon after it is issued.
	Lifetime string `json:"lifetime,omitempty"`
}

type LBRoute struct {
	Upstreams []string
	// Weights aligns with Upstreams and is only emitted for the weighted policy.
	Weights []int
	Policy  string
	// CookieName is the sticky-session cookie for the cookie policy.
	CookieName            string
	Retries               int
	TryDuration           string
	TryInterval           string
	ActiveHealth          *ActiveHealthChecks
	PassiveHealth         *PassiveHealthChecks
	StreamCloseDelay      string
	DialTimeout           string
	ResponseHeaderTimeout string
	UpstreamTLS           *UpstreamTLSConfig
	RateLimitRPS          int
	RateLimitBurst        int
}

type Layer4App struct {
	Servers map[string]*Layer4Server `json:"servers,omitempty"`
}

type Layer4ProxyHandler struct {
	Handler   string               `json:"handler"`
	Upstreams []Layer4UpstreamDial `json:"upstreams,omitempty"`
}

type Layer4Route struct {
	Handle []any `json:"handle"`
}

type Layer4Server struct {
	Listen []string      `json:"listen,omitempty"`
	Routes []Layer4Route `json:"routes,omitempty"`
}

type Layer4UpstreamDial struct {
	Dial []string `json:"dial,omitempty"`
}

type LoadBalancing struct {
	SelectionPolicy *SelectionPolicy `json:"selection_policy,omitempty"`
	Retries         int              `json:"retries,omitempty"`
	TryDuration     string           `json:"try_duration,omitempty"`
	TryInterval     string           `json:"try_interval,omitempty"`
}

type LogConfig struct {
	Writer  map[string]string `json:"writer"`
	Encoder map[string]string `json:"encoder"`
	Level   string            `json:"level,omitempty"`
	Include []string          `json:"include"`
}

type LoggingConfig struct {
	Logs map[string]*LogConfig `json:"logs"`
}

type MaintenanceGate struct {
	Page        MaintenancePage
	BypassCIDRs []string
	BypassPaths []string
}

type MaintenancePage struct {
	Title             string
	Message           string
	RetryAfterSeconds int
}

type MaintenanceRoute struct {
	// Hosts are the Host header values that get the fixed maintenance
	// response. Also contributes to the Subjects list used for TLS
	// automation when RoutesOptions.TLS is true, the same as Hosts on
	// ProxyRoute/StaticRoute: a domain in maintenance mode still needs
	// a valid certificate, an operator flips this on and off far more
	// often than they'd want to also manage TLS for.
	Hosts []string
	Page  MaintenancePage
}

type Matcher struct {
	Host       []string            `json:"host,omitempty"`
	Path       []string            `json:"path,omitempty"`
	Expression *ExpressionMatcher  `json:"expression,omitempty"`
	Not        []Matcher           `json:"not,omitempty"`
	Vars       map[string][]string `json:"vars,omitempty"`
	Header     map[string][]string `json:"header,omitempty"`
	ClientIP   *ClientIPMatcher    `json:"client_ip,omitempty"`
}

type PKIApp struct {
	CertificateAuthorities map[string]*CA `json:"certificate_authorities,omitempty"`
}

type PassiveHealthChecks struct {
	FailDuration    string `json:"fail_duration,omitempty"`
	MaxFails        int    `json:"max_fails,omitempty"`
	UnhealthyStatus []int  `json:"unhealthy_status,omitempty"`
}

type ProviderChoice struct {
	Provider   string `json:"provider"`
	CustomBase string `json:"custom_base_domain,omitempty"`
}

type ProviderSource interface {
	GetDNSProviderDefault(ctx context.Context) (store.DNSProviderChoice, error)
	ListAppDNSProviders(ctx context.Context) (map[string]store.DNSProviderChoice, error)
}

type ProxyHeaders struct {
	Request *HeaderOps `json:"request,omitempty"`
}

type ProxyOptions struct {
	// ServerName keys the server within apps.http.servers. Arbitrary,
	// used only for logging/introspection.
	ServerName string
	// ListenAddr is a Caddy network address, e.g. ":8080" or
	// "127.0.0.1:8443".
	ListenAddr string
	// BackendDial is the reverse-proxy target, e.g. "127.0.0.1:9090".
	BackendDial string
	// Hosts, if non-empty, restricts the route to these Host header
	// values and is also the Subjects list used for TLS automation when
	// TLS is enabled. Empty means "match every request on this
	// listener", which is only valid for the plain-HTTP case: Caddy's
	// automatic HTTPS needs at least one qualifying hostname to know
	// what to issue a certificate for.
	Hosts []string
	// TLS, if true, adds a tls app automation policy scoping the
	// internal issuer to Hosts, and disables the HTTP->HTTPS redirect
	// (see Server.AutomaticHTTPS).
	TLS bool
	// AdminListen overrides Caddy's admin API bind address. Empty keeps
	// Caddy's own default (localhost:2019).
	AdminListen string
	// StorageDir overrides Caddy's storage root (certificates, ACME
	// account state, the internal issuer's local CA). Empty keeps
	// Caddy's own OS-specific default. See FileStorage's doc comment for
	// why Phase 1 should always set this rather than rely on the
	// default.
	StorageDir string
}

type ProxyRewrite struct {
	Method string `json:"method,omitempty"`
	URI    string `json:"uri,omitempty"`
}

type ProxyRoute struct {
	// Hosts are the Host header values routed to BackendDial. Also
	// contributes to the Subjects list used for TLS automation when
	// RoutesOptions.TLS is true.
	Hosts []string
	// BackendDial is the reverse-proxy target, e.g. "127.0.0.1:9090".
	BackendDial string
	// BasicAuth, if non-nil, adds a BasicAuthHandler ahead of the
	// reverse-proxy handler so every host in this route requires HTTP
	// Basic Auth. Nil (the default) reproduces this package's prior
	// behavior exactly: a plain reverse-proxy route with no
	// authentication handler.
	BasicAuth *BasicAuthAccount
	// WAF, if non-nil, adds a WAF and/or rate-limit handler ahead of
	// BasicAuth and the reverse-proxy handler. Nil (the default)
	// reproduces this package's prior behavior exactly: no such handler
	// at all.
	WAF *WAFConfig
	// AuthGate, if non-nil, sends every request to an auth service first.
	AuthGate *AuthGate
	// ErrorPages, if non-empty, replaces the response for each listed
	// status code with the operator's own HTML, covering both a status
	// the backend itself returns (via ReverseProxyHandler.HandleResponse)
	// and a real proxy failure Caddy generates on this route's behalf
	// (via a wrapping SubrouteHandler.Errors). Empty (the default)
	// reproduces this package's prior behavior exactly.
	ErrorPages []ErrorPage
	// Hidden asks search engines to stay away: X-Robots-Tag on every
	// response and an ingress-served /robots.txt that disallows everything.
	Hidden bool
	// MaxBodyBytes, when positive, replaces the instance request body cap for these hosts.
	MaxBodyBytes int64
	// LB, if non-nil, replaces BackendDial with a multi-upstream pool.
	LB *LBRoute
	// Policy, if non-nil, adds the domain's traffic controls (policy_*.go).
	Policy *RoutePolicy
	// Abuse, if non-nil and active, puts the owning app's abuse defense in
	// front of every other control on the route.
	Abuse *AbusePolicy
	// Upstream, if non-nil, shapes a standalone domain's single backend.
	// Ignored when LB is set.
	Upstream *UpstreamOptions
	// Maintenance, if non-nil, serves the maintenance page to every request
	// outside its bypass list, ahead of every other control.
	Maintenance *MaintenanceGate
}

type RateLimitHandler struct {
	Handler    string                   `json:"handler"`
	RateLimits map[string]RateLimitZone `json:"rate_limits,omitempty"`
}

type RateLimitZone struct {
	Key       string `json:"key,omitempty"`
	MaxEvents int    `json:"max_events,omitempty"`
	Window    string `json:"window,omitempty"`
}

type RedirectRoute struct {
	// Hosts are the Host header values that get redirected to TargetURL.
	// Also contributes to the Subjects list used for TLS automation when
	// RoutesOptions.TLS is true, the same as MaintenanceRoute.Hosts: a
	// redirected domain still needs a valid certificate to redirect a
	// browser that arrives over HTTPS in the first place.
	Hosts []string
	// TargetURL is the absolute URL every matched request is redirected
	// to, e.g. "https://example.com" or "https://newapp.example.com/promo".
	// Validated by the caller (internal/api); this package performs no
	// validation of its own.
	TargetURL string
	// StatusCode is the redirect's HTTP status: store.DomainRedirectPermanent
	// (301, the default) or store.DomainRedirectTemporary (302).
	StatusCode int
}

type RedirectsHandler struct {
	Handler string `json:"handler"`
	// contains filtered or unexported fields
}

type RequestBodyHandler struct {
	Handler string `json:"handler"`
	MaxSize int64  `json:"max_size"`
}

type RequestIdentity struct {
	ClientIP     string
	UserAgent    string
	ReferrerHost string
}

type RequestObservation struct {
	Method      string
	Path        string
	Status      int
	Duration    time.Duration
	BytesIn     int64
	BytesOut    int64
	UpstreamErr bool
	Upstream    string
	RequestID   string
	At          time.Time
	// Referrer is the Referer header's host only; Country an ISO code.
	Referrer string
	Country  string
}

type RequestStats struct {
	// contains filtered or unexported fields
}

type RequestStatsHandler struct {
	Handler string `json:"handler"`
	Key     string `json:"key"`
}

type ResponseCache struct {
	// contains filtered or unexported fields
}

type ResponseHandler struct {
	Match  *ResponseMatcher `json:"match,omitempty"`
	Routes []Route          `json:"routes,omitempty"`
}

type ResponseMatcher struct {
	StatusCode []int `json:"status_code,omitempty"`
}

type ReverseProxyHandler struct {
	Handler   string     `json:"handler"`
	Upstreams []Upstream `json:"upstreams"`
	// HandleResponse mirrors reverse_proxy's own handle_response field:
	// routes evaluated against the backend's actual response, ahead of
	// it being written to the client. Used by error-page routes to
	// replace a backend-returned status like 404 or 500 with a custom
	// body while keeping the same status code.
	HandleResponse []ResponseHandler `json:"handle_response,omitempty"`

	LoadBalancing    *LoadBalancing `json:"load_balancing,omitempty"`
	HealthChecks     *HealthChecks  `json:"health_checks,omitempty"`
	Transport        *HTTPTransport `json:"transport,omitempty"`
	StreamCloseDelay string         `json:"stream_close_delay,omitempty"`
	Headers          *ProxyHeaders  `json:"headers,omitempty"`
	Rewrite          *ProxyRewrite  `json:"rewrite,omitempty"`
}

type RewriteHandler struct {
	Handler string `json:"handler"`
	URI     string `json:"uri"`
	Method  string `json:"method,omitempty"`
}

type Route struct {
	Match  []Matcher `json:"match,omitempty"`
	Handle []any     `json:"handle"`
}

type Route53DNSProvider struct {
	Name            string `json:"name"`
	AccessKeyID     string `json:"access_key_id,omitempty"`
	SecretAccessKey string `json:"secret_access_key,omitempty"`
	Region          string `json:"region,omitempty"`
	HostedZoneID    string `json:"hosted_zone_id,omitempty"`
}

type RouteCheck struct {
	Token string
	Reply string
}

type RoutePolicy struct {
	Policy trafficpolicy.Policy
	// AppDials maps an app name to its reverse proxy dial address.
	AppDials map[string]string
	// AppWake maps a sleeping app to its wake route, so a forwarder that
	// targets it starts it instead of answering "not running".
	AppWake map[string]WakeRoute
	// Targets maps an external forwarder URL to its checked address. A URL
	// missing here (blocked or unresolvable) compiles to a 502 response.
	Targets map[string]trafficpolicy.ResolvedTarget
	// TLSTerminatedUpstream means a proxy in front terminates TLS.
	TLSTerminatedUpstream bool
	// TLSReal means visitors see a publicly trusted certificate.
	TLSReal bool
	// HTTPSPort is the public HTTPS port for force HTTPS redirects.
	HTTPSPort int
	// GeoActive is false when no country source is configured; geo rules
	// are then skipped and reported as disabled.
	GeoActive bool
	Limits    trafficpolicy.Limits
}

type RoutesOptions struct {
	// ServerName keys the server within apps.http.servers. Arbitrary,
	// used only for logging/introspection.
	ServerName string
	// ListenAddr is a Caddy network address shared by every route, e.g.
	// ":443".
	ListenAddr string
	// HTTPPort is this control plane's own configured HTTP/port-80
	// equivalent (see internal/reconcile/ingress.WithHTTPListenAddr).
	// Threaded to HTTPApp.HTTPPort and, when ACME is enabled for a
	// non-wildcard host, to the ACME issuer's Challenges.HTTP.
	// AlternatePort (see NewACMEIssuer), so an instance running its
	// ingress on non-default ports never reaches for a literal port 80.
	// 0 keeps Caddy's own default (80) in both places.
	HTTPPort int
	// HTTPRedirect, when true, lets Caddy bind the HTTP port and 308
	// redirect every routed host to https. Off keeps the port unbound
	// outside ACME challenges (non-root dev runs cannot bind port 80).
	HTTPRedirect bool
	// FallbackCertLifetime is how long the internal fallback certificate
	// served while public ACME issuance fails lives, so the public CA is
	// retried on that cadence. Empty keeps Caddy's default (12h).
	FallbackCertLifetime string
	// LazyCertHosts get their certificate on the first TLS handshake instead of when the config loads.
	LazyCertHosts []string
	// PlainHTTP serves the same routes over unencrypted HTTP on HTTPPort,
	// for a proxy in front that terminates TLS and dials this port.
	PlainHTTP bool
	// HTTPBindHost is the interface the PlainHTTP listener binds; empty means every interface.
	HTTPBindHost string
	// Routes is every reverse-proxy backend to route on this listener.
	// Empty is valid: it produces a listener with no routes and no TLS
	// automation policy, the normal shape for a reconcile pass over zero
	// currently-routable services, not an error condition.
	Routes []ProxyRoute
	// StaticRoutes is every static site to serve directly on this same
	// listener, alongside Routes: one shared Caddy server can carry both
	// reverse-proxy and file_server routes, disambiguated by Host the
	// same way two ProxyRoutes already are. Empty (the default) is valid
	// for exactly the same reason an empty Routes is.
	StaticRoutes []StaticRoute
	// MaintenanceRoutes is every domain currently in maintenance mode,
	// sharing this same listener the same way StaticRoutes does. A
	// caller must never put the same host in both Routes/StaticRoutes
	// and MaintenanceRoutes in one call: BuildRoutesConfig builds
	// whatever it's given, it does not itself resolve that conflict
	// (the ingress reconciler's job, splitting a service's hosts before
	// ever calling this function).
	MaintenanceRoutes []MaintenanceRoute
	// RedirectRoutes is every domain currently configured to redirect to
	// a target URL, sharing this same listener the same way
	// MaintenanceRoutes does. A caller must never put the same host in
	// both another route kind and RedirectRoutes in one call, the same
	// caller-resolves-conflicts contract MaintenanceRoutes documents:
	// internal/reconcile/ingress resolves maintenance mode ahead of a
	// redirect for any host with both configured (a domain deliberately
	// taken down for maintenance stays down, even if it also has a
	// stale redirect configured from an earlier migration), so a host
	// never reaches this field and MaintenanceRoutes at once.
	RedirectRoutes []RedirectRoute

	// RouteCheck, when set, answers a verifier's marker request on every
	// host, ahead of every other route.
	RouteCheck *RouteCheck
	// TLS, if true, adds a tls app automation policy scoped to every
	// route's Hosts, both Routes and StaticRoutes (skipped if both are
	// empty, since automatic HTTPS needs at least one subject to issue a
	// certificate for), and disables the HTTP->HTTPS redirect (see
	// Server.AutomaticHTTPS).
	TLS bool
	// ACMEEnabled, if true (and TLS is true and there's at least one
	// host), scopes every routed host's single automation policy to a
	// real ACME issuer (NewACMEIssuer) instead of Caddy's offline
	// internal issuer. This is the operator-facing toggle
	// internal/store.IngressSettings.ACMEEnabled drives
	// (internal/reconcile/ingress reads that row fresh every reconcile
	// pass and threads it straight through). False, the default,
	// reproduces this package's original, ADR-005-verified behavior
	// exactly: every route gets the internal issuer, byte-identical to
	// before this field existed. There is deliberately no per-host mix
	// of ACME and internal issuers in this pass: every currently-routed
	// host shares one automation policy, either all-internal or
	// all-ACME. Real per-domain granularity is genuine, existing Caddy
	// capability (AutomationPolicy already supports an ordered list of
	// policies, "the first policy whose Subjects match a given hostname
	// wins," see that type's own doc comment) but is an explicit,
	// deliberately out-of-scope v1 gap, not something this field's
	// absence of a per-route override quietly forecloses.
	ACMEEnabled bool
	// ACMEEmail is the ACME account contact address, passed straight
	// through to NewACMEIssuer when ACMEEnabled is true. This package
	// performs no validation on it (empty is accepted structurally);
	// internal/api's PUT /api/v1/settings/ingress is where "required and
	// syntactically valid whenever ACME is enabled" is actually
	// enforced, before a value ever reaches this builder.
	ACMEEmail string
	// ACMEDirectoryURL overrides the ACME CA's directory endpoint,
	// passed straight through to NewACMEIssuer when ACMEEnabled is true.
	// Empty keeps Caddy's own compiled-in default (Let's Encrypt
	// production). See ACMEIssuer.CA's own doc comment for why this
	// package never silently substitutes Let's Encrypt's staging
	// directory on an operator's behalf.
	ACMEDirectoryURL string
	// DNSProvider, if non-nil (and ACMEEnabled is true and at least one
	// route's host is a wildcard, see IsWildcardDomain), scopes every
	// wildcard subject to a separate automation policy using DNS-01 via
	// this provider (NewDNSACMEIssuer) instead of the plain ACME policy
	// every non-wildcard host still gets: HTTP-01 cannot solve a
	// wildcard identifier. Nil reproduces this package's prior behavior
	// exactly, wildcard hosts included, byte-identical to before this
	// field existed. Exactly one provider is ever active per reconcile
	// pass; internal/reconcile/ingress resolves which one (and its
	// credentials) from the operator-facing settings and internal/secrets.
	DNSProvider DNS01Provider
	// DNS01AllHosts makes DNS-01 the challenge for every host, not only
	// wildcards, so servers behind CGNAT or a closed port 80 can still
	// issue. It needs DNSProvider; without one the build fails closed.
	DNS01AllHosts bool
	// DNS01Hosts are single hosts that use DNS-01 while every other host
	// keeps its own challenge. Ignored when no DNSProvider is set.
	DNS01Hosts []string
	// AdminListen overrides Caddy's admin API bind address. Empty keeps
	// Caddy's own default (localhost:2019).
	AdminListen string
	// StorageDir overrides Caddy's storage root. Empty keeps Caddy's own
	// OS-specific default. See FileStorage's doc comment. Ignored when
	// CertStorage is set.
	StorageDir string
	// TLSCertificates is every domain currently configured with a BYO TLS
	// certificate (internal/store.DomainTLSCert), sourced fresh from the
	// store and internal/secrets every reconcile pass by the caller (no
	// caching here, matching every other RoutesOptions field). Each
	// entry's Host must already be present in Routes/StaticRoutes/
	// MaintenanceRoutes' combined host list for Caddy to ever select the
	// loaded certificate for a real connection; a host with no route at
	// all still loads harmlessly, it's just never selected. Empty (the
	// default) reproduces this package's prior behavior exactly: every
	// host gets Caddy's automatic ACME/internal issuance as before this
	// field existed.
	TLSCertificates []TLSCertificateOverride
	// CertStorage, if non-nil, overrides StorageDir with an arbitrary
	// Caddy storage module reference (e.g. NewSQLiteStorageRef()),
	// letting the caller point Caddy's certificate/ACME-account storage
	// at internal/store's SQLite instead of the local
	// filesystem, so certificate storage lives in the database and
	// multi-node deployments can share cert state. Takes precedence over
	// StorageDir when both are set, rather than being an error, so a
	// caller migrating from one to the other doesn't need a separate
	// code path just to clear the old field.
	CertStorage any
	// RequestStats, if true, wraps every proxy and static route in the
	// request_stats handler (per-app request rate, errors, latency).
	RequestStats bool
	// Firewall puts the instance firewall handler in front of every host route.
	Firewall bool
	// Hardening, if non-nil, applies server limits, failover defaults and the
	// friendly 503 page. Nil keeps the legacy bare config.
	Hardening *Hardening
	// Inherited, when active, replaces the listen addresses with systemd
	// passed sockets and serves the HTTP to HTTPS redirect from its own server.
	Inherited *InheritedSockets
	// HoldRoutes answer 503 for hosts whose backend is momentarily absent.
	HoldRoutes []HoldRoute
	// WakeRoutes serve a "waking up" page for sleeping apps and ask the
	// control plane to start them.
	WakeRoutes []WakeRoute
	// Streams is every raw TCP port forward to proxy, each on its own
	// dedicated listener (apps.layer4.servers), applied in this same
	// Config/caddy.Load call: see layer4.go's package doc comment for
	// why this can't be a second, independently-applied Caddy config.
	// Empty (the default) adds no layer4 app at all, reproducing this
	// package's behavior before this field existed exactly.
	Streams []StreamRoute
}

type SQLiteStorage struct {
	// contains filtered or unexported fields
}

type SQLiteStorageRef struct {
	Module string `json:"module"`
}

type SelectionPolicy struct {
	Policy   string           `json:"policy"`
	Weights  []int            `json:"weights,omitempty"`
	Name     string           `json:"name,omitempty"`
	MaxAge   string           `json:"max_age,omitempty"`
	Fallback *SelectionPolicy `json:"fallback,omitempty"`
}

type Server struct {
	Listen []string `json:"listen,omitempty"`
	Routes []Route  `json:"routes,omitempty"`

	// AutomaticHTTPS controls Caddy's automatic-HTTPS behavior for this
	// server specifically. This spike disables the HTTP->HTTPS redirect
	// (DisableRedir) for the TLS server: automatic redirects bind Caddy's
	// default HTTP port (80), which needs root and would surprise a local
	// spike run under a normal user, so the standalone TLS demo makes
	// that trade-off explicit instead of silently trying to grab port 80.
	AutomaticHTTPS *AutoHTTPSConfig `json:"automatic_https,omitempty"`

	ReadHeaderTimeout    string                `json:"read_header_timeout,omitempty"`
	ReadTimeout          string                `json:"read_timeout,omitempty"`
	WriteTimeout         string                `json:"write_timeout,omitempty"`
	IdleTimeout          string                `json:"idle_timeout,omitempty"`
	MaxHeaderBytes       int                   `json:"max_header_bytes,omitempty"`
	Protocols            []string              `json:"protocols,omitempty"`
	TrustedProxies       *TrustedProxiesConfig `json:"trusted_proxies,omitempty"`
	TrustedProxiesStrict int                   `json:"trusted_proxies_strict,omitempty"`
	ClientIPHeaders      []string              `json:"client_ip_headers,omitempty"`
	Errors               *ErrorsConfig         `json:"errors,omitempty"`
}

type ShieldHandler struct {
	Handler string               `json:"handler"`
	Key     string               `json:"key"`
	Rule    trafficpolicy.Shield `json:"rule"`
}

type SnapshotCheck struct {
	SavedAt     time.Time
	ConfigBytes int
}

type SnapshotData struct {
	SavedAt     time.Time       `json:"saved_at"`
	Fingerprint string          `json:"fingerprint"`
	Ports       []int           `json:"ports"`
	Config      json.RawMessage `json:"config"`
}

type SnapshotStatus struct {
	Enabled bool
	// SavedAt is the last successful write or the age of the restored file.
	SavedAt time.Time
	// Restored is true when this process started serving from the snapshot.
	Restored bool
	// RestoreError is why a present snapshot was not used; empty when it was
	// used or there was none.
	RestoreError string
	// SaveError is the last write failure, cleared by the next success.
	SaveError string
}

type SnapshotStore struct {
	// contains filtered or unexported fields
}

type SplitTestingHandler struct {
	Handler string `json:"handler"`
}

type Splits struct {
	// contains filtered or unexported fields
}

type StaticResponseHandler struct {
	Handler string `json:"handler"`
	// StatusCode is an int, not caddyhttp.WeakString's own
	// string-or-number wire shape: Caddy accepts a plain JSON number
	// here for a fixed, non-placeholder status code, which is all this
	// package ever needs.
	StatusCode int                 `json:"status_code,omitempty"`
	Body       string              `json:"body,omitempty"`
	Headers    map[string][]string `json:"headers,omitempty"`
}

type StaticRoute struct {
	// Hosts are the Host header values served from RootDir. Also
	// contributes to the Subjects list used for TLS automation when
	// RoutesOptions.TLS is true.
	Hosts []string
	// RootDir is the local filesystem directory to serve.
	RootDir string
	// Rules, when set, serves the tree through the routing rules compiled
	// at deploy time instead of the plain file server.
	Rules *staticroutes.Ruleset
}

type StaticSiteHandler struct {
	Handler string `json:"handler"`
	// contains filtered or unexported fields
}

type StreamRoute struct {
	// ListenAddr is a Caddy network address, e.g. ":9000". Always a
	// single stream's own dedicated port; never shared with HTTP's
	// listener or another stream's.
	ListenAddr string
	// BackendDial is the TCP proxy target, e.g. "127.0.0.1:5432".
	BackendDial string
}

type SubrouteHandler struct {
	Handler string        `json:"handler"`
	Routes  []Route       `json:"routes,omitempty"`
	Errors  *ErrorsConfig `json:"errors,omitempty"`
}

type TLSApp struct {
	Automation *Automation `json:"automation,omitempty"`
	// Certificates mirrors Caddy's tls.certificates field (a
	// caddy.ModuleMap keyed by loader module name within the
	// tls.certificates namespace). This package only ever sets the
	// "load_pem" key (see CertKeyPEMPair), for BYO TLS certificates.
	Certificates CertificatesConfig `json:"certificates,omitempty"`
}

type TLSCertificateOverride struct {
	Host    string
	CertPEM string
	KeyPEM  string
}

type TrustedProxiesConfig struct {
	Source string   `json:"source"`
	Ranges []string `json:"ranges"`
}

type Upstream struct {
	// Dial is a host:port address, e.g. "127.0.0.1:8080". Caddy's own
	// docs note this must resolve to exactly one socket, no port ranges.
	Dial string `json:"dial"`
}

type UpstreamOptions struct {
	TLS                bool
	InsecureSkipVerify bool
	ServerName         string
	// HostHeader is a literal Host value, escaped before use; empty keeps
	// the client's Host. HostFromUpstream wins over it.
	HostHeader            string
	HostFromUpstream      bool
	DisableWebSocket      bool
	DialTimeout           time.Duration
	ResponseHeaderTimeout time.Duration
	StripPrefix           string
	// BasePath is prepended to every forwarded path (a URL target's path).
	BasePath string
}

type UpstreamTLSConfig struct {
	InsecureSkipVerify bool   `json:"insecure_skip_verify,omitempty"`
	ServerName         string `json:"server_name,omitempty"`
}

type VarsHandler struct {
	Handler string `json:"handler"`
}

type VisitorBucket struct {
	Start    time.Time `json:"start"`
	Requests int       `json:"requests"`
	Visitors int       `json:"visitors"`
}

type VisitorHistoryStore interface {
	UpsertVisitorRollups(ctx context.Context, rows []store.VisitorRollup) error
	ListVisitorRollups(ctx context.Context, app, domain string, since, until time.Time) ([]store.VisitorRollup, error)
	PruneVisitorRollups(ctx context.Context, cutoff time.Time) (int64, error)
}

type VisitorSummary struct {
	Requests   int              `json:"requests"`
	Visitors   int              `json:"visitors"`
	Status     map[string]int   `json:"status"`
	TopPaths   []CountedItem    `json:"top_paths"`
	TopRefs    []CountedItem    `json:"top_referrers"`
	Series     []VisitorBucket  `json:"series"`
	Domains    []DomainVisitors `json:"domains"`
	OldestKept time.Time        `json:"oldest_record,omitempty"`
	SaltPeriod string           `json:"salt_period"`
}

type VisitorSummaryOptions struct {
	Domain string
	Since  time.Time
	Until  time.Time
	TopN   int
}

type WAFConfig struct {
	// Enabled turns on the OWASP Coraza handler (NewCorazaWAFHandler).
	Enabled bool
	// Blocking selects Coraza's SecRuleEngine mode: true is "On" (CRS
	// matches reject the request), false is "DetectionOnly" (CRS runs
	// and logs but never rejects). Only meaningful when Enabled is true.
	Blocking bool
	// RateLimitRPS, if greater than zero, adds a rate-limit handler
	// (NewRateLimitHandler) independent of Enabled: an operator can rate
	// limit a domain without also enabling the WAF, or vice versa.
	RateLimitRPS int
	// RateLimitBurst is the short-window (1s) cap; values at or below
	// RateLimitRPS are treated as "no extra burst allowance" by
	// NewRateLimitHandler.
	RateLimitBurst int
}

type WakeRoute struct {
	Hosts []string
	// Dial is the control plane's own listener, Token its shared wake secret.
	Dial  string
	Token string
	App   string
}