Struct Resolver 

pub struct Resolver { /* private fields */ }

An in-process DNS query orchestrator.

Construct it from a split-DNS policy and one or more upstream backends per group, then resolve decoded queries against it. It owns policy selection, caching, and upstream failover, but not server lifecycle or transport protocol implementation; see the module documentation.

Lifecycle

Construct via Resolver::builder, call Resolver::resolve as many times as needed, then drop. This stage holds no background threads, so there is no explicit shutdown method — Rust’s ordinary drop semantics fully release any resources the resolver owns (including any sockets a registered crate::upstream::UdpBackend/crate::upstream::TcpBackend opens per call).

Implementations

impl Resolver

pub fn builder(policy: SplitDnsPolicy) -> ResolverBuilder

Starts building a resolver from a split-DNS policy.

pub async fn resolve(&self, query: &Message) -> Result<Message>

Resolves one query.

Extracts the queried name from query’s first question. Locally handled Fake IP questions return before the hook, cache, and upstream stages. For every other question, static SplitDnsPolicy routing supplies a tentative group and an optional crate::hooks::RouteHook can authoritatively replace it. The selected registered group scopes the in-memory answer cache; on a miss its backends are tried in registration order: the first backend to return Ok wins and its answer is cached (per the existing TTL rules) and returned immediately. A backend failing with Error::Timeout, Error::Transport, or Error::Tls is treated as retryable — resolution moves on to the next backend in the group rather than failing the whole call. Once every backend in the group has been tried and failed, the last attempted backend’s error is propagated as-is; this exhausted-group failure is never cached. A group with exactly one backend behaves exactly as before: success or that one backend’s own error.

Errors

Returns Error::NoRoute when no split-DNS rule matches the queried name and no default upstream group is configured, when no question is present in query, or when the selected group has no backend registered. A hook-selected unknown or empty group never falls back to static policy. A hook failure returns Error::Hook and is neither retried nor cached. Returns the last attempted backend’s error, propagated as-is (not cached), once every backend in the matched group has failed.

Runtime requirement

Must be called from inside a tokio runtime context if the selected backend performs real socket I/O (e.g. crate::upstream::UdpBackend/ crate::upstream::TcpBackend) — see crate::upstream’s module-level docs.