ingress

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 only for wildcard subjects: RFC 8555 7.1.1
	// restricts HTTP-01 to non-wildcard identifiers, so
	// NewCloudflareDNSACMEIssuer sets DNS-01 here instead.
	Challenges *ChallengesConfig `json:"challenges,omitempty"`
}

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. See docs-local/research/caddy-spike.md for what
	// happened when this collided with an already-bound port.
	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. See
	// docs-local/research/caddy-spike.md.
	Persist *bool `json:"persist,omitempty"`
}

type Apps struct {
	HTTP *HTTPApp `json:"http,omitempty"`
	TLS  *TLSApp  `json:"tls,omitempty"`
	PKI  *PKIApp  `json:"pki,omitempty"`
}

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

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

type AutomationPolicy struct {
	Subjects []string `json:"subjects,omitempty"`
	Issuers  []any    `json:"issuers,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. See docs-local/research/caddy-spike.md.
	InstallTrust *bool `json:"install_trust,omitempty"`
}

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

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"`
}

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, TASKS.md 3.6)
	// 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"`
}

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 Driver 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 HTTPApp struct {
	Servers map[string]*Server `json:"servers,omitempty"`
}

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

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

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
}

type Matcher struct {
	Host []string `json:"host,omitempty"`
}

type PKIApp struct {
	CertificateAuthorities map[string]*CA `json:"certificate_authorities,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 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
}

type ReverseProxyHandler struct {
	Handler   string     `json:"handler"`
	Upstreams []Upstream `json:"upstreams"`
}

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

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
	// 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
	// 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
	// CloudflareDNSAPIToken, if non-empty (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 Cloudflare (NewCloudflareDNSACMEIssuer) instead
	// of the plain ACME policy every non-wildcard host still gets:
	// HTTP-01 cannot solve a wildcard identifier. Empty reproduces this
	// package's prior behavior exactly, wildcard hosts included, byte-
	// identical to before this field existed; internal/store.
	// CloudflareDNSSettings.Enabled plus internal/secrets' stored token
	// is what an operator-facing settings flow resolves this from.
	CloudflareDNSAPIToken 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 (TASKS.md 3.6) 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
}

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

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

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"`
}

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
}

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 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"`
}