cli

type APIConfig struct {
	// Addr is where the management API listens. Empty disables it entirely.
	//
	// The example configuration binds loopback. Putting this on an address the
	// rest of the network can reach means every device on it can try the token,
	// which is a different security posture and should be a decision rather
	// than a default.
	Addr string `json:"addr"`

	// Token authenticates every request. There is no way to disable
	// authentication; see the api package.
	Token string `json:"token"`

	// TokenFile reads the token from a file instead, which is how a token
	// avoids being in a configuration file that gets copied into a support
	// ticket or committed to a repository.
	TokenFile string `json:"token_file"`

	// AllowedOrigins enables CORS for exactly these origins. Empty refuses
	// every cross-origin request.
	AllowedOrigins []string `json:"allowed_origins"`

	// ExposeLog enables the query-log endpoints, which read a browsing history.
	// It is separate from the rest of the API for that reason.
	ExposeLog bool `json:"expose_log"`

	// ReadOnly refuses every mutating request.
	ReadOnly bool `json:"read_only"`

	// MaxPageSize bounds how many query-log rows one request may read. Zero
	// takes the API's own default. It is the only thing standing between an
	// authenticated-but-restricted client and the whole retained history, one
	// page at a time.
	MaxPageSize int `json:"max_page_size"`

	// LogRetention bounds the query log: entries older than MaxAge and beyond
	// MaxEntries are discarded. Zero takes the storage default of a week or a
	// million entries.
	//
	// It is configuration rather than a constant because the log is a record of
	// what everyone on the network looked up, and how long that is kept is the
	// operator's decision, not this daemon's.
	LogRetention RetentionConfig `json:"log_retention"`
}

type CacheConfig struct {
	Enabled    *bool    `json:"enabled,omitempty"`
	MaxEntries int      `json:"max_entries"`
	MinTTL     Duration `json:"min_ttl"`
	MaxTTL     Duration `json:"max_ttl"`
	// ServeStale keeps answering from expired entries for this long when the
	// upstream cannot be reached (RFC 8767). Zero disables it. It is a
	// deliberate correctness trade and so is off unless asked for.
	ServeStale Duration `json:"serve_stale"`
}

type Config struct {
	Version int `json:"version"`

	Listen   ListenConfig   `json:"listen"`
	Upstream UpstreamConfig `json:"upstream"`
	Cache    CacheConfig    `json:"cache"`
	Policy   PolicyConfig   `json:"policy"`
	Logging  LoggingConfig  `json:"logging"`
	API      APIConfig      `json:"api"`
}

type Duration time.Duration

type ListenConfig struct {
	// Addr is the address to bind, "host:port". Port 53 is privileged on every
	// Unix, so a daemon binding it either starts as root and drops privileges
	// or is granted CAP_NET_BIND_SERVICE.
	Addr string `json:"addr"`
	// UDP and TCP each default to true. Both are wanted in almost every
	// deployment: a client that receives a truncated UDP answer retries over
	// TCP, and disabling TCP makes every large answer unresolvable.
	UDP *bool `json:"udp,omitempty"`
	TCP *bool `json:"tcp,omitempty"`

	MaxInFlight  int      `json:"max_in_flight"`
	MaxTCPConns  int      `json:"max_tcp_conns"`
	QueryTimeout Duration `json:"query_timeout"`
}

type LoggingConfig struct {
	Level  string `json:"level"`
	Format string `json:"format"`
}

type PolicyConfig struct {
	// Blocklists and Allowlists are paths to list files. Remote URLs are not
	// fetched by the daemon: downloading, verifying and refreshing them is a
	// separate concern with its own failure modes, and a resolver that cannot
	// start because a list server is down is worse than one with a stale list.
	Blocklists []string `json:"blocklists"`
	Allowlists []string `json:"allowlists"`
	// Block is "nxdomain", "refused" or "nodata".
	Block string `json:"block"`
}

type RetentionConfig struct {
	MaxAge     Duration `json:"max_age"`
	MaxEntries int      `json:"max_entries"`
}

type UpstreamConfig struct {
	// Servers are endpoints, each "scheme://address": udp, tcp, tls or https.
	// A preset name may be used instead of a URL.
	Servers []string `json:"servers"`
	// Strategy is "sequential", "race", "round-robin" or "random".
	Strategy string `json:"strategy"`
	// Randomize enables DNS-0x20 case randomisation against upstreams that
	// tolerate it. It is off by default because a small number of servers
	// normalise case in replies, and against one of those it breaks every query
	// rather than degrading.
	Randomize bool     `json:"randomize"`
	Timeout   Duration `json:"timeout"`
}