engine

Documentation

Index

• Constants
• func Register(engineType EngineType, factory EngineFactory)
• func ValidateTemplateConfig(config EngineConfig) error
• type CacheConfig
• type DNSSECConfig
• type DNSSECMode
• type DomainFilterAction
• type DomainFilterConfig
• type Engine
  • func New(engineType EngineType, configDir string) (Engine, error)
• type EngineCapabilities
• type EngineConfig
• type EngineFactory
• type EngineHealthStatus
• type EngineType
  • func AvailableEngines() []EngineType
• type TemplateData
  • func NewTemplateData(config EngineConfig) TemplateData
• type UpstreamConfig
• type UpstreamTransport

Constants

const BindConfigTemplate = `` /* 577-byte string literal not displayed */

BindConfigTemplate is the text/template string for generating ISC BIND named.conf.

const CorefileTemplate = `` /* 521-byte string literal not displayed */

CorefileTemplate is the text/template string for generating a CoreDNS Corefile.

const RecursorConfTemplate = `` /* 500-byte string literal not displayed */

RecursorConfTemplate is the text/template string for generating PowerDNS recursor.conf.

const UnboundConfigTemplate = `` /* 1035-byte string literal not displayed */

UnboundConfigTemplate is the text/template string for generating unbound.conf.

Functions

func Register

func Register(engineType EngineType, factory EngineFactory)

Register adds an engine factory to the registry. Called by each engine package's init() function.

func ValidateTemplateConfig

func ValidateTemplateConfig(config EngineConfig) error

ValidateTemplateConfig validates addresses before rendering configuration templates.

Types

type CacheConfig

type CacheConfig struct {
	// MaxEntries is the maximum number of cache entries.
	MaxEntries int32 `json:"maxEntries"`
	// PositiveTtlMin is the minimum TTL for positive responses in seconds.
	PositiveTtlMin int32 `json:"positiveTtlMin"`
	// PositiveTtlMax is the maximum TTL for positive responses in seconds.
	PositiveTtlMax int32 `json:"positiveTtlMax"`
	// NegativeTtl is the TTL for negative responses in seconds.
	NegativeTtl int32 `json:"negativeTtl"`
	// PrefetchEnabled enables cache prefetching.
	PrefetchEnabled bool `json:"prefetchEnabled"`
	// PrefetchThreshold is the number of lookups before prefetching.
	PrefetchThreshold int32 `json:"prefetchThreshold"`
}

CacheConfig holds cache tuning parameters.

type DNSSECConfig

type DNSSECConfig struct {
	// Mode controls resolver DNSSEC behavior.
	Mode DNSSECMode `json:"mode,omitempty"`
}

DNSSECConfig holds DNSSEC processing settings.

type DNSSECMode

type DNSSECMode string

DNSSECMode identifies DNSSEC processing behavior.

const (
	// DNSSECModeOff disables DNSSEC processing.
	DNSSECModeOff DNSSECMode = "off"
	// DNSSECModeProcess enables DNSSEC-aware processing without strict validation.
	DNSSECModeProcess DNSSECMode = "process"
	// DNSSECModeValidate enables strict DNSSEC validation.
	DNSSECModeValidate DNSSECMode = "validate"
)

type DomainFilterAction

type DomainFilterAction string

DomainFilterAction determines how denied queries are answered.

const (
	// DomainFilterActionRefused responds with REFUSED to denied queries.
	DomainFilterActionRefused DomainFilterAction = "refused"
	// DomainFilterActionNXDomain responds with NXDOMAIN to denied queries.
	DomainFilterActionNXDomain DomainFilterAction = "nxdomain"
)

type DomainFilterConfig

type DomainFilterConfig struct {
	// Allow is a list of domain patterns that are permitted. If non-empty,
	// only domains matching at least one pattern are allowed. Patterns support
	// wildcards: "*.example.com" matches any subdomain of example.com.
	Allow []string `json:"allow,omitempty"`
	// Deny is a list of domain patterns that are blocked. Deny rules are
	// evaluated after allow rules. A domain matching both allow and deny is denied.
	Deny []string `json:"deny,omitempty"`
	// Action determines the DNS response code for denied queries.
	// Defaults to "refused".
	Action DomainFilterAction `json:"action,omitempty"`
}

DomainFilterConfig controls proxy-level domain allow/deny filtering.

type Engine

type Engine interface {
	// Configure generates engine-specific config from the abstract EngineConfig.
	// Returns the path to the generated config file.
	Configure(ctx context.Context, config EngineConfig) (string, error)

	// Start launches the engine subprocess.
	Start(ctx context.Context) error

	// Reload triggers a graceful config reload without dropping queries.
	Reload(ctx context.Context) error

	// Stop gracefully shuts down the engine.
	Stop(ctx context.Context) error

	// Capabilities describes the feature surface supported by the engine implementation.
	Capabilities() EngineCapabilities

	// HealthStatus returns a detailed health snapshot for the running engine.
	HealthStatus(ctx context.Context) (EngineHealthStatus, error)

	// HealthCheck returns true if the engine is responding to DNS queries.
	// Prefer HealthStatus when callers need latency and failure reason details.
	HealthCheck(ctx context.Context) (bool, error)

	// Name returns the engine identifier.
	Name() EngineType
}

Engine manages the lifecycle of a DNS resolver engine.

func New

func New(engineType EngineType, configDir string) (Engine, error)

New creates a new Engine instance for the given type.

type EngineCapabilities

type EngineCapabilities struct {
	SupportsHotReload         bool
	SupportedTransports       []UpstreamTransport
	SupportedDNSSECModes      []DNSSECMode
	SupportsTLSServerName     bool
	SupportsWeightedUpstreams bool
	SupportsPriorityUpstreams bool
}

EngineCapabilities describes supported behavior for an engine implementation.

type EngineConfig

type EngineConfig struct {
	// Upstreams is the list of upstream resolvers to forward to.
	Upstreams []UpstreamConfig `json:"upstreams"`

	// Cache holds cache tuning parameters.
	Cache CacheConfig `json:"cache"`

	// DomainFilter holds optional proxy-level domain allow/deny rules.
	DomainFilter DomainFilterConfig `json:"domainFilter,omitempty"`

	// ListenAddr is the address the engine should listen on (e.g., "127.0.0.1").
	ListenAddr string `json:"listenAddr"`

	// ListenPort is the port the engine should listen on (e.g., 5354).
	ListenPort int32 `json:"listenPort"`

	// WorkerThreads is the number of engine worker threads.
	WorkerThreads int32 `json:"workerThreads,omitempty"`

	// DNSSEC holds DNSSEC processing settings.
	DNSSEC DNSSECConfig `json:"dnssec,omitempty"`
}

EngineConfig is the engine-agnostic configuration derived from CRDs.

type EngineFactory

type EngineFactory func(configDir string) Engine

EngineFactory is a function that creates a new Engine instance.

type EngineHealthStatus

type EngineHealthStatus struct {
	Healthy bool
	Latency time.Duration
	Reason  string
}

EngineHealthStatus reports liveness plus diagnostic context.

type EngineType

type EngineType string

EngineType identifies which DNS engine to use.

const (
	// EngineUnbound is the Unbound DNS resolver.
	EngineUnbound EngineType = "unbound"
	// EngineCoreDNS is the CoreDNS resolver.
	EngineCoreDNS EngineType = "coredns"
	// EnginePowerDNS is the PowerDNS Recursor.
	EnginePowerDNS EngineType = "powerdns"
	// EngineBIND is the ISC BIND resolver.
	EngineBIND EngineType = "bind"
)

func AvailableEngines

func AvailableEngines() []EngineType

AvailableEngines returns all registered engine types.

type TemplateData

type TemplateData struct {
	EngineConfig

	// MsgCacheSize is the Unbound msg-cache-size derived from MaxEntries.
	MsgCacheSize string
	// RrsetCacheSize is the Unbound rrset-cache-size (2x msg-cache-size).
	RrsetCacheSize string
	// ForwardAddresses is the PowerDNS semicolon-separated upstream list (e.g., "1.1.1.1:53;8.8.8.8:53").
	ForwardAddresses string
	// CoreDNSUpstreams is the ordered upstream target list for CoreDNS forward.
	CoreDNSUpstreams []string
	// CoreDNSTLSServerName is an optional tls_servername for CoreDNS forward.
	CoreDNSTLSServerName string
	// UnboundForwardTLSUpstream toggles forward-tls-upstream in Unbound.
	UnboundForwardTLSUpstream bool
	// BindMaxCacheSize is the BIND max-cache-size value (e.g., "100m").
	BindMaxCacheSize string
	// BindDNSSECValidation is the BIND dnssec-validation value (auto or no).
	BindDNSSECValidation string
}

TemplateData extends EngineConfig with computed fields for template rendering.

func NewTemplateData

func NewTemplateData(config EngineConfig) TemplateData

NewTemplateData creates a TemplateData from an EngineConfig with computed fields.

type UpstreamConfig

type UpstreamConfig struct {
	// Address is the IP or hostname of the upstream.
	Address string `json:"address"`
	// Port is the port of the upstream.
	Port int32 `json:"port"`
	// Transport selects upstream protocol transport.
	Transport UpstreamTransport `json:"transport,omitempty"`
	// TLSServerName overrides SNI/hostname verification for TLS-based transports.
	TLSServerName string `json:"tlsServerName,omitempty"`
	// Weight is the relative upstream weight.
	Weight int32 `json:"weight,omitempty"`
	// Preference is the priority hint for ordering upstreams.
	Preference int32 `json:"preference,omitempty"`
}

UpstreamConfig represents a single upstream resolver.

type UpstreamTransport

type UpstreamTransport string

UpstreamTransport identifies how upstream DNS queries are transported.

const (
	// UpstreamTransportDNS uses plain DNS over UDP/TCP.
	UpstreamTransportDNS UpstreamTransport = "dns"
	// UpstreamTransportDoT uses DNS-over-TLS.
	UpstreamTransportDoT UpstreamTransport = "dot"
	// UpstreamTransportDoH uses DNS-over-HTTPS.
	UpstreamTransportDoH UpstreamTransport = "doh"
)