Hickory DNS Server

https://docs.rs/hickory-server/latest/
Admin
Hickory DNS Server is a fully compliant domain name server and client library written in safe Rust...
Tokens:88,921
Snippets:516
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize and Configure DNS Server

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/mod.rs.html

Create a new DNS server instance with optional access control lists for network filtering.

```rust
pub fn new(handler: T) -> Self {
        Self::with_access(handler, [], [])
    }

    /// Creates a new ServerFuture with the specified Handler and denied/allowed networks
    pub fn with_access(
        handler: T,
        denied_networks: impl IntoIterator<Item = IpNet>,
        allowed_networks: impl IntoIterator<Item = IpNet>,
    ) -> Self {
        let mut access = AccessControl::default();
        access.insert_deny(denied_networks);
        access.insert_allow(allowed_networks);

        Self {
            context: Arc::new(ServerContext {
                handler,
                access,
                shutdown: CancellationToken::new(),
            }),
            join_set: JoinSet::new(),
        }
    }
```

--------------------------------

### Iterate Over Zone Records

Source: https://docs.rs/hickory-server/latest/hickory_server/zone_handler/struct.ZoneTransfer.html

Method to iterate over all records, including the start and end SOA records.

```rust
pub fn iter(&self) -> impl Iterator<Item = &Record>
```

--------------------------------

### Initialize and Query FileZoneHandler

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/file.rs.html

Demonstrates loading a zone file from a configuration path and performing A record lookups.

```rust
            zone_path: PathBuf::from("../../tests/test-data/test_configs/example.com.zone"),
        };
        let handler = FileZoneHandler::try_from_config(
            Name::from_str("example.com.").unwrap(),
            ZoneType::Primary,
            AxfrPolicy::Deny,
            None,
            &config,
            #[cfg(feature = "__dnssec")]
            Some(NxProofKind::Nsec),
        )
        .expect("failed to load file");

        let lookup = block_on(ZoneHandler::lookup(
            &handler,
            &LowerName::from_str("www.example.com.").unwrap(),
            RecordType::A,
            None,
            LookupOptions::default(),
        ))
        .expect("lookup failed");

        match lookup
            .into_iter()
            .next()
            .expect("A record not found in zone handler")
            .data
        {
            RData::A(ip) => assert_eq!(A::new(127, 0, 0, 1), ip),
            _ => panic!("wrong rdata type returned"),
        }

        let include_lookup = block_on(ZoneHandler::lookup(
            &handler,
            &LowerName::from_str("include.alias.example.com.").unwrap(),
            RecordType::A,
            None,
            LookupOptions::default(),
        ))
        .expect("INCLUDE lookup failed");

        match include_lookup
            .into_iter()
            .next()
            .expect("A record not found in zone handler")
            .data
        {
            RData::A(ip) => assert_eq!(A::new(127, 0, 0, 5), ip),
            _ => panic!("wrong rdata type returned"),
        }
    }
}
```

--------------------------------

### Get Zone TTL and Serial

Source: https://docs.rs/hickory-server/latest/hickory_server/store/sqlite/struct.SqliteZoneHandler.html

Retrieves the minimum TTL or the current serial number for the zone.

```rust
pub async fn minimum_ttl(&self) -> u32
```

```rust
pub async fn serial(&self) -> u32
```

--------------------------------

### Initialize and populate BlocklistZoneHandler

Source: https://docs.rs/hickory-server/latest/hickory_server/store/blocklist/struct.BlocklistZoneHandler.html

Demonstrates creating a handler from configuration and adding additional blocklist entries from a file.

```rust
use std::{fs::File, net::{Ipv4Addr, Ipv6Addr}, path::Path, str::FromStr, sync::Arc};
use hickory_proto::rr::{LowerName, RecordType, Name};
use hickory_server::{
    store::blocklist::*,
    zone_handler::{LookupControlFlow, LookupOptions, ZoneHandler, ZoneType},
};

#[tokio::main]
async fn main() {
    let config = BlocklistConfig {
        wildcard_match: true,
        min_wildcard_depth: 2,
        lists: vec!["default/blocklist.txt".to_string()],
        sinkhole_ipv4: None,
        sinkhole_ipv6: None,
        block_message: None,
        ttl: 86_400,
        consult_action: BlocklistConsultAction::Disabled,
        log_clients: true,
    };

    let mut blocklist = BlocklistZoneHandler::try_from_config(
        Name::root(),
        config,
        Some(Path::new("../../tests/test-data/test_configs")),
    ).unwrap();

    let handle = File::open("../../tests/test-data/test_configs/default/blocklist2.txt").unwrap();
    if let Err(e) = blocklist.add(handle) {
        panic!("error adding blocklist: {e:?}");
    }

    let origin = blocklist.origin().clone();
    let handler = Arc::new(blocklist) as Arc<dyn ZoneHandler>;

    // In this example, malc0de.com only exists in the blocklist2.txt file we added to the
    // zone handler after instantiating it.  The following simulates a lookup against the
    // blocklist zone handler, and checks for the expected response for a blocklist match.
    use LookupControlFlow::*;
    let Break(Ok(_res)) = handler.lookup(
                            &LowerName::from(Name::from_ascii("malc0de.com.").unwrap()),
                            RecordType::A,
                            None,
                            LookupOptions::default(),
                          ).await else {
        panic!("blocklist zone handler did not return expected match");
    };
}
```

--------------------------------

### Persist zone to journal

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/sqlite/mod.rs.html

Persists the current in-memory zone state to the associated journal, starting with an AXFR record.

```rust
pub async fn persist_to_journal(&self) -> Result<(), PersistenceError> {
        if let Some(journal) = self.journal.lock().await.as_ref() {
            let serial = self.in_memory.serial().await;

            info!("persisting zone to journal at SOA.serial: {serial}");

            // TODO: THIS NEEDS TO BE IN A TRANSACTION!!!
            journal.insert_record(
                serial,
                &Record::update0(Name::new(), 0, RecordType::AXFR).into_record_of_rdata(),
            )?;

            for rr_set in self.in_memory.records().await.values() {
                // TODO: should we preserve rr_sets or not?
```

--------------------------------

### Server Lifecycle Management

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/mod.rs.html

Demonstrates how to abort a running server and perform a graceful shutdown using tokio timeouts.

```rust
async fn abort() {
    subscribe();

    let endpoints = Endpoints::new().await;

    let endpoints2 = endpoints.clone();
    let (abortable, abort_handle) = future::abortable(async move {
        let mut server_future = Server::new(Catalog::new());
        endpoints2.register(&mut server_future).await;
        server_future.block_until_done().await
    });

    abort_handle.abort();
    abortable.await.expect_err("expected abort");

    endpoints.rebind_all().await;
}
```

```rust
#[tokio::test]
async fn graceful_shutdown() {
    subscribe();
    let mut server_future = Server::new(Catalog::new());
    let endpoints = Endpoints::new().await;
    endpoints.register(&mut server_future).await;

    timeout(Duration::from_secs(2), server_future.shutdown_gracefully())
        .await
        .expect("timed out waiting for the server to complete")
        .expect("error while awaiting tasks");

    endpoints.rebind_all().await;
}
```

--------------------------------

### Implement ZoneTransfer Iterator

Source: https://docs.rs/hickory-server/latest/src/hickory_server/zone_handler/auth_lookup.rs.html

Provides an iterator that chains the start SOA, zone records, and end SOA records.

```rust
impl ZoneTransfer {
    /// Iterate over all the records, starting and ending with the SOA record.
    pub fn iter(&self) -> impl Iterator<Item = &Record> {
        self.start_soa
            .iter()
            .chain(self.records.iter())
            .chain(self.end_soa.iter())
    }
}
```

--------------------------------

### Catalog Management Methods

Source: https://docs.rs/hickory-server/latest/src/hickory_server/zone_handler/catalog.rs.html

Methods for initializing the catalog and managing zone handlers.

```rust
impl Catalog {
    /// Constructs a new Catalog
    pub fn new() -> Self {
        Self {
            handlers: HashMap::new(),
            nsid_payload: None,
            #[cfg(feature = "metrics")]
            metrics: CatalogMetrics::default(),
        }
    }

    /// Insert or update the provided zone handlers
    ///
    /// # Arguments
    ///
    /// * `name` - zone name, e.g. example.com.
    /// * `handlers` - a vec of zone handler objects
    pub fn upsert(&mut self, name: LowerName, handlers: Vec<Arc<dyn ZoneHandler>>) {
        #[cfg(feature = "metrics")]
        for handler in handlers.iter() {
            self.metrics.add_handler(handler.as_ref())
        }

        self.handlers.insert(name, handlers);
    }

    /// Remove a zone from the catalog
    pub fn remove(&mut self, name: &LowerName) -> Option<Vec<Arc<dyn ZoneHandler>>> {
        // NOTE: metrics are not removed to avoid dropping counters that are potentially still
        // being used by other zone handlers having the same labels
        self.handlers.remove(name)
    }

    /// Set a specified name server identifier (NSID) in responses
    ///
    /// The provided `NSIDPayload` will be included in responses to requests that
    /// specify the NSID option in EDNS. Set to `None` to disable NSID.
    ///
    /// By default, no NSID is sent.
    pub fn set_nsid(&mut self, payload: Option<NSIDPayload>) {
        self.nsid_payload = payload
    }

    /// Return the name server identifier (NSID) that is used for responses (if enabled)
    ///
    /// See `set_nsid()` for more information.
    pub fn nsid(&self) -> Option<&NSIDPayload> {
        self.nsid_payload.as_ref()
    }
```

--------------------------------

### Implement Zone Transfer (AXFR)

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/in_memory/mod.rs.html

Handles AXFR requests by verifying policy and constructing a zone transfer response with start and end SOA records.

```rust
async fn zone_transfer(
        &self,
        request: &Request,
        lookup_options: LookupOptions,
        _now: u64,
    ) -> Option<(
        Result<ZoneTransfer, LookupError>,
        Option<TSigResponseContext>,
    )> {
        let request_info = match request.request_info() {
            Ok(info) => info,
            Err(e) => return Some((Err(e), None)),
        };

        if request_info.query.query_type() == RecordType::AXFR {
            // TODO: support more advanced AXFR options
            if !matches!(self.axfr_policy, AxfrPolicy::AllowAll) {
                return Some((Err(LookupError::from(ResponseCode::Refused)), None));
            }
        }

        let future = self.lookup(self.origin(), RecordType::SOA, None, lookup_options);
        let start_soa = if let LookupControlFlow::Continue(Ok(res)) = future.await {
            res.unwrap_records()
        } else {
            LookupRecords::Empty
        };

        let future = self.lookup(
            self.origin(),
            RecordType::SOA,
            None,
            LookupOptions::default(),
        );
        let end_soa = if let LookupControlFlow::Continue(Ok(res)) = future.await {
            res.unwrap_records()
        } else {
            LookupRecords::Empty
        };

        let records = AxfrRecords::new(
            lookup_options.dnssec_ok,
            self.inner.read().await.records.values().cloned().collect(),
        );

        Some((
            Ok(ZoneTransfer {
                start_soa,
                records,
                end_soa,
            }),
            None,
        ))
    }
```

--------------------------------

### Handle QUIC Connections

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/quic_handler.rs.html

Initializes and manages the QUIC server loop to process incoming connections and streams.

```rust
pub(super) async fn handle_quic(
    socket: net::UdpSocket,
    server_cert_resolver: Arc<dyn ResolvesServerCert>,
    cx: Arc<ServerContext<impl RequestHandler>>,
) -> Result<(), NetError> {
    debug!(?socket, "registered quic");
    handle_quic_with_server(QuicServer::with_socket(socket, server_cert_resolver)?, cx).await
}

pub(super) async fn handle_quic_with_server(
    mut server: QuicServer,
    cx: Arc<ServerContext<impl RequestHandler>>,
) -> Result<(), NetError> {
    let mut inner_join_set = JoinSet::new();
    loop {
        let shutdown = cx.shutdown.clone();
        let (streams, src_addr) = tokio::select! {
            result = server.next() => match result {
                Ok(Some(c)) => c,
                Ok(None) => continue,
                Err(error) => {
                    debug!(%error, "error receiving quic connection");
                    continue;
                }
            },
            _ = shutdown.cancelled() => {
                // A graceful shutdown was initiated. Break out of the loop.
                break;
            },
        };

        // verify that the src address is safe for responses
        // TODO: we're relying the quinn library to actually validate responses before we get here, but this check is still worth doing
        if let Err(error) = sanitize_src_address(src_addr) {
            warn!(
                %error, %src_addr,
                "address can not be responded to",
            );
            continue;
        }

        let cx = cx.clone();
        inner_join_set.spawn(async move {
            debug!("starting quic stream request from: {src_addr}");

            // TODO: need to consider timeout of total connect...
            let result = quic_handler(streams, src_addr, cx).await;

            if let Err(error) = result {
                warn!(%error, %src_addr, "quic stream processing failed")
            }
        });

        reap_tasks(&mut inner_join_set);
    }

    Ok(())
}
```

--------------------------------

### Initialize BlocklistZoneHandler from Configuration

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/blocklist.rs.html

Constructs a new handler instance from a provided configuration and base directory path.

```rust
pub fn try_from_config(
    origin: Name,
    config: BlocklistConfig,
    base_dir: Option<&Path>,
) -> Result<Self, String> {
    info!("loading blocklist config: {origin}");

    let mut handler = Self {
        origin: origin.into(),
        blocklist: HashMap::new(),
        wildcard_match: config.wildcard_match,
        min_wildcard_depth: config.min_wildcard_depth,
        sinkhole_ipv4: config.sinkhole_ipv4.unwrap_or(Ipv4Addr::UNSPECIFIED),
        sinkhole_ipv6: config.sinkhole_ipv6.unwrap_or(Ipv6Addr::UNSPECIFIED),
        ttl: config.ttl,
        block_message: config.block_message,
        consult_action: config.consult_action,
        log_clients: config.log_clients,
        #[cfg(feature = "metrics")]
        metrics: BlocklistMetrics::new(),
    };

    let base_dir = match base_dir {
        Some(dir) => dir.display(),
        None => {
            return Err(format!(
                "invalid blocklist (zone directory) base path specified: '{base_dir:?}'"
            ));
        }
    };

    // Load block lists into the block table cache for this zone handler.
    for bl in &config.lists {
        info!("adding blocklist {bl}");
```

--------------------------------

### Default OpCode Metrics Initialization

Source: https://docs.rs/hickory-server/latest/src/hickory_server/metrics.rs.html

Sets up the default opcode counters with descriptive metadata.

```rust
impl Default for OpCodeMetrics {
    fn default() -> Self {
        let key = "operation";
        Self {
            query: {
                let new = counter!(REQUEST_OPERATIONS_TOTAL, key => "query");
                describe_counter!(
                    REQUEST_OPERATIONS_TOTAL,
                    Unit::Count,
                    "Number of requests by opcode."
                );
                new
            },
            status: counter!(REQUEST_OPERATIONS_TOTAL, key => "status"),
            notify: counter!(REQUEST_OPERATIONS_TOTAL, key => "notify"),
            update: counter!(REQUEST_OPERATIONS_TOTAL, key => "update"),
            unknown: counter!(REQUEST_OPERATIONS_TOTAL, key => "unknown"),
        }
    }
}
```

--------------------------------

### Initialize Schema

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/sqlite/persistence.rs.html

Iteratively upgrades the database schema to the current version. Includes initial table creation for tracking.

```rust
pub fn schema_up(&mut self) -> Result<i64, PersistenceError> {
        while self.version < CURRENT_VERSION {
            match self.version + 1 {
                0 => self.version = self.init_up()?,
                1 => self.version = self.records_up()?,
                _ => panic!("incorrect version somewhere"), // valid panic, non-recoverable state
            }

            self.update_schema_version(self.version)?;
        }

        Ok(self.version)
    }
```

```rust
fn init_up(&self) -> Result<i64, PersistenceError> {
        let count = self.conn.lock().expect("conn poisoned").execute(
            "CREATE TABLE tdns_schema (
                                          \
                                            version INTEGER NOT NULL
                                        \
                                            )",
            [],
        )?;
        //
        assert_eq!(count, 0);

        let count = self
```

--------------------------------

### Default Protocol Metrics Initialization

Source: https://docs.rs/hickory-server/latest/src/hickory_server/metrics.rs.html

Sets up the default protocol counters with descriptive metadata.

```rust
impl Default for ProtocolMetrics {
    fn default() -> Self {
        let key = "protocol";
        Self {
            udp: {
                let new = counter!(REQUEST_PROTOCOLS_TOTAL, key => "udp");
                describe_counter!(
                    REQUEST_PROTOCOLS_TOTAL,
                    Unit::Count,
                    "Number of requests by transport protocol."
                );
                new
            },
            tcp: counter!(REQUEST_PROTOCOLS_TOTAL, key => "tcp"),
            #[cfg(feature = "__tls")]
            tls: counter!(REQUEST_PROTOCOLS_TOTAL, key => "tls"),
            #[cfg(feature = "__https")]
            https: counter!(REQUEST_PROTOCOLS_TOTAL, key => "https"),
            #[cfg(feature = "__quic")]
            quic: counter!(REQUEST_PROTOCOLS_TOTAL, key => "quic"),
            #[cfg(feature = "__h3")]
            h3: counter!(REQUEST_PROTOCOLS_TOTAL, key => "http3"),
        }
    }
}
```

--------------------------------

### Loading SqliteZoneHandler from Configuration

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/sqlite/mod.rs.html

The try_from_config method initializes a zone handler from a configuration object, handling path resolution and journal recovery.

```rust
    pub async fn try_from_config(
        origin: Name,
        zone_type: ZoneType,
        axfr_policy: AxfrPolicy,
        enable_dnssec: bool,
        root_dir: Option<&Path>,
        config: &SqliteConfig,
        #[cfg(feature = "__dnssec")] nx_proof_kind: Option<NxProofKind>,
    ) -> Result<Self, String> {
        let zone_name = origin;

        // to be compatible with previous versions, the extension might be zone, not jrnl
        let zone_path = rooted(&config.zone_path, root_dir);
        let journal_path = rooted(&config.journal_path, root_dir);

        #[cfg_attr(not(feature = "__dnssec"), allow(unused_mut))]
        let mut handler = if journal_path.exists() {
            // load the zone
            info!("recovering zone from journal: {journal_path:?}",);
            let journal = Journal::from_file(&journal_path)
                .map_err(|e| format!("error opening journal: {journal_path:?}: {e}"))?;
```

--------------------------------

### TLS Request Handling Initialization

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/mod.rs.html

Initializes TLS acceptor and begins the connection loop.

```rust
#[cfg(feature = "__tls")]
async fn handle_tls(
    listener: net::TcpListener,
    tls_config: Arc<ServerConfig>,
    handshake_timeout: Duration,
    cx: Arc<ServerContext<impl RequestHandler>>,
) -> Result<(), NetError> {
    debug!(?listener, "registered tls");
    let tls_acceptor = TlsAcceptor::from(tls_config);

    let mut inner_join_set = JoinSet::new();
    loop {
        let (tcp_stream, src_addr) = tokio::select! {
            tcp_stream = listener.accept() => match tcp_stream {
```

--------------------------------

### FileZoneHandler Initialization

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/file.rs.html

Methods for creating a new FileZoneHandler instance, either directly or from a configuration file path.

```rust
    pub async fn new(in_memory: InMemoryZoneHandler) -> Self {
        Self {
            #[cfg(feature = "metrics")]
            metrics: {
                let new = PersistentStoreMetrics::new("file");
                let records = in_memory.records().await;
                new.zone_records.increment(records.len() as f64);
                new
            },
            in_memory,
        }
    }

    /// Read the ZoneHandler for the origin from the specified configuration
    pub fn try_from_config(
        origin: Name,
        zone_type: ZoneType,
        axfr_policy: AxfrPolicy,
        root_dir: Option<&Path>,
        config: &FileConfig,
        #[cfg(feature = "__dnssec")] nx_proof_kind: Option<NxProofKind>,
    ) -> Result<Self, String> {
        let zone_path = rooted(&config.zone_path, root_dir);
        let records = zone_from_path(&zone_path, origin.clone())
            .map_err(|e| format!("failed to load zone file: {e}"))?;

        // Don't call `new()`, since it needs to be async to get the number of records to initialize metrics
        Ok(Self {
            #[cfg(feature = "metrics")]
            metrics: {
                let new = PersistentStoreMetrics::new("file");
                new.zone_records.increment(records.len() as f64);
                new
            },
            in_memory: InMemoryZoneHandler::new(
                origin,
                records,
                zone_type,
                axfr_policy,
                #[cfg(feature = "__dnssec")]
                nx_proof_kind,
            )?,
        })
    }
```

--------------------------------

### Implement Forwarder Search and DNSSEC Methods

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/forwarder.rs.html

Asynchronous methods for handling DNS lookups and NSEC/NSEC3 record queries within the forwarder store.

```rust
async fn search(
        &self,
        request: &Request,
        lookup_options: LookupOptions,
    ) -> (LookupControlFlow<AuthLookup>, Option<TSigResponseContext>) {
        let request_info = match request.request_info() {
            Ok(info) => info,
            Err(e) => return (LookupControlFlow::Break(Err(e)), None),
        };
        (
            self.lookup(
                request_info.query.name(),
                request_info.query.query_type(),
                Some(&request_info),
                lookup_options,
            )
            .await,
            None,
        )
    }

    async fn nsec_records(
        &self,
        _name: &LowerName,
        _lookup_options: LookupOptions,
    ) -> LookupControlFlow<AuthLookup> {
        LookupControlFlow::Continue(Err(LookupError::from(io::Error::other(
            "Getting NSEC records is unimplemented for the forwarder",
        ))))
    }

    #[cfg(feature = "__dnssec")]
    async fn nsec3_records(
        &self,
        _info: Nsec3QueryInfo<'_>,
        _lookup_options: LookupOptions,
    ) -> LookupControlFlow<AuthLookup> {
        LookupControlFlow::Continue(Err(LookupError::from(io::Error::other(
            "getting NSEC3 records is unimplemented for the forwarder",
        ))))
    }

    #[cfg(feature = "__dnssec")]
    fn nx_proof_kind(&self) -> Option<&NxProofKind> {
        None
    }

    #[cfg(feature = "metrics")]
    fn metrics_label(&self) -> &'static str {
        "forwarder"
    }
}
```

--------------------------------

### Constructing a MessageResponse from a Request

Source: https://docs.rs/hickory-server/latest/hickory_server/zone_handler/struct.MessageResponseBuilder.html

Demonstrates initializing a builder from a request and generating an error response.

```rust
use hickory_proto::{op::ResponseCode, rr::Record};
use hickory_server::{
    server::Request,
    zone_handler::{MessageResponse, MessageResponseBuilder},
};

fn handle_request<'q>(request: &'q Request) -> MessageResponse<
    'q,
    'static,
    impl Iterator<Item = &'static Record> + Send + 'static,
    impl Iterator<Item = &'static Record> + Send + 'static,
    impl Iterator<Item = &'static Record> + Send + 'static,
    impl Iterator<Item = &'static Record> + Send + 'static,
> {
    MessageResponseBuilder::from_message_request(request)
        .error_msg(&request.metadata, ResponseCode::ServFail)
}
```

--------------------------------

### Implementing the Search Method

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/in_memory/mod.rs.html

The entry point for searching the in-memory zone, handling specific record types like SOA and AXFR.

```rust
async fn search(
    &self,
    request: &Request,
    lookup_options: LookupOptions,
) -> (LookupControlFlow<AuthLookup>, Option<TSigResponseContext>) {
    let request_info = match request.request_info() {
        Ok(info) => info,
        Err(e) => return (LookupControlFlow::Break(Err(e)), None),
    };
    debug!("searching InMemoryZoneHandler for: {}", request_info.query);

    let lookup_name = request_info.query.name();
    let record_type: RecordType = request_info.query.query_type();

    match record_type {
        RecordType::SOA => (
            self.lookup(
                self.origin(),
                record_type,
                Some(&request_info),
                lookup_options,
            )
            .await,
            None,
        ),
        RecordType::AXFR => (
            LookupControlFlow::Break(Err(LookupError::NetError(
                "AXFR must be handled with ZoneHandler::zone_transfer()".into(),
            ))),
            None,
        ),
        _ => (
```

--------------------------------

### Initialize SQLite Schema

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/sqlite/persistence.rs.html

Executes SQL commands to initialize the schema version and create the records table for zone history tracking.

```rust
            .conn
            .lock()
            .expect("conn poisoned")
            .execute("INSERT INTO tdns_schema (version) VALUES (0)", [])?;
```

```rust
    fn records_up(&self) -> Result<i64, PersistenceError> {
        // we'll be using rowid for our primary key, basically: `rowid INTEGER PRIMARY KEY ASC`
        let count = self.conn.lock().expect("conn poisoned").execute(
            "CREATE TABLE records (
                                          \
                                            client_id      INTEGER NOT NULL,
                                          \
                                            soa_serial     INTEGER NOT NULL,
                                          \
                                            timestamp      TEXT NOT NULL,
                                          \
                                            record         BLOB NOT NULL
                                        \
                                            )",
            [],
        )?;
        //
        assert_eq!(count, 1);

        Ok(1)
    }
```

--------------------------------

### Handle HTTP/3 Connections

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/h3_handler.rs.html

Initializes and manages the HTTP/3 server loop, accepting connections and spawning tasks for individual stream handling.

```rust
pub(super) async fn handle_h3(
    socket: net::UdpSocket,
    server_cert_resolver: Arc<dyn ResolvesServerCert>,
    dns_hostname: Option<String>,
    cx: Arc<ServerContext<impl RequestHandler>>,
) -> Result<(), NetError> {
    debug!("registered h3: {:?}", socket);
    handle_h3_with_server(
        H3Server::with_socket(socket, server_cert_resolver)?,
        dns_hostname,
        cx,
    )
    .await
}
```

```rust
pub(super) async fn handle_h3_with_server(
    mut server: H3Server,
    dns_hostname: Option<String>,
    cx: Arc<ServerContext<impl RequestHandler>>,
) -> Result<(), NetError> {
    let dns_hostname = dns_hostname.map(|n| n.into());

    let mut inner_join_set = JoinSet::new();
    loop {
        let shutdown = cx.shutdown.clone();
        let (streams, src_addr) = tokio::select! {
            result = server.accept() => match result {
                Ok(Some(c)) => c,
                Ok(None) => continue,
                Err(error) => {
                    debug!(%error, "error receiving h3 connection");
                    continue;
                }
            },
            _ = shutdown.cancelled() => {
                // A graceful shutdown was initiated. Break out of the loop.
                break;
            },
        };

        // verify that the src address is safe for responses
        // TODO: we're relying the quinn library to actually validate responses before we get here, but this check is still worth doing
        if let Err(error) = sanitize_src_address(src_addr) {
            warn!(
                %error, %src_addr,
                "address can not be responded to",
            );
            continue;
        }

        let cx = cx.clone();
        let dns_hostname = dns_hostname.clone();
        inner_join_set.spawn(async move {
            debug!("starting h3 stream request from: {src_addr}");

            // TODO: need to consider timeout of total connect...
            let result = h3_handler(streams, src_addr, dns_hostname, cx).await;

            if let Err(error) = result {
                warn!(%error, %src_addr, "h3 stream processing failed")
            }
        });

        reap_tasks(&mut inner_join_set);
    }

    Ok(())
}
```

--------------------------------

### Handle Raw DNS Requests

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/mod.rs.html

Entry point for processing raw messages, converting them into parts and initializing a response handler.

```rust
impl<T: RequestHandler> ServerContext<T> {
    async fn handle_raw_request(
        &self,
        message: SerialMessage,
        protocol: Protocol,
        response_handler: BufDnsStreamHandle,
    ) {
        let (message, src_addr) = message.into_parts();
        let response_handler = ResponseHandle::new(src_addr, response_handler, protocol);

        self.handle_request(Bytes::from(message), src_addr, protocol, response_handler)
            .await;
    }
```

--------------------------------

### Create a new ResponseHandle

Source: https://docs.rs/hickory-server/latest/hickory_server/server/struct.ResponseHandle.html

Constructor for initializing a new ResponseHandle with a destination address, stream handle, and protocol.

```rust
pub fn new( dst: SocketAddr, stream_handle: BufDnsStreamHandle, protocol: Protocol, ) -> Self
```

--------------------------------

### RecursiveZoneHandler::try_from_config

Source: https://docs.rs/hickory-server/latest/hickory_server/store/recursor/struct.RecursiveZoneHandler.html

Initializes a new RecursiveZoneHandler from the provided configuration.

```APIDOC
## pub async fn try_from_config

### Description
Reads the ZoneHandler for the specified origin from the provided configuration.

### Signature
`pub async fn try_from_config(origin: Name, _zone_type: ZoneType, config: RecursiveConfig, root_dir: Option<&Path>, conn_provider: P) -> Result<Self, String>`

### Parameters
- **origin** (Name) - The origin name for the zone.
- **_zone_type** (ZoneType) - The type of the zone.
- **config** (RecursiveConfig) - The configuration for the recursive handler.
- **root_dir** (Option<&Path>) - Optional root directory path.
- **conn_provider** (P) - The connection provider implementation.

### Returns
- **Result<Self, String>** - Returns the initialized RecursiveZoneHandler or an error string if initialization fails.
```

--------------------------------

### Zone Handler Factory Helper

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/blocklist.rs.html

Creates a BlocklistZoneHandler from a configuration, panicking if initialization fails.

```rust
fn handler(config: BlocklistConfig) -> Arc<dyn ZoneHandler> {
        let handler = BlocklistZoneHandler::try_from_config(
            Name::root(),
            config,
            Some(Path::new("../../tests/test-data/test_configs/")),
        );

        // Test: verify the blocklist zone handler was successfully created.
        match handler {
            Ok(handler) => Arc::new(handler),
            Err(error) => panic!("error creating blocklist zone handler: {error}"),
        }
    }
```

--------------------------------

### Manage DNSSEC Keys and Signing

Source: https://docs.rs/hickory-server/latest/hickory_server/store/sqlite/struct.SqliteZoneHandler.html

Methods for adding signing keys and securing the zone. Requires the '__dnssec' feature.

```rust
pub fn add_zone_signing_key_mut( &mut self, signer: DnssecSigner, ) -> DnsSecResult<()>
```

```rust
pub fn secure_zone_mut(&mut self) -> DnsSecResult<()>
```

--------------------------------

### Implement DNS Class Metrics

Source: https://docs.rs/hickory-server/latest/src/hickory_server/metrics.rs.html

Handles initialization and incrementing of DNS class counters.

```rust
struct DNSClassMetrics {
    r#in: Counter,
    ch: Counter,
    hs: Counter,
    none: Counter,
    any: Counter,
    unknown: Counter,
}

impl DNSClassMetrics {
    fn new(direction: Direction) -> Self {
        let dns_class_name = match direction {
            Direction::Request => REQUEST_DNS_CLASSES_TOTAL,
            Direction::Response => RESPONSE_DNS_CLASSES_TOTAL,
        };
        let key = "class";
        Self {
            r#in: {
                let new = counter!(dns_class_name, key => "in");
                let description = match direction {
                    Direction::Request => "Number of requests by DNS class.",
                    Direction::Response => {
                        "Total number of resource records in responses by DNS class."
                    }
                };
                describe_counter!(dns_class_name, Unit::Count, description);
                new
            },
            ch: counter!(dns_class_name, key => "ch"),
            hs: counter!(dns_class_name, key => "hs"),
            none: counter!(dns_class_name, key => "none"),
            any: counter!(dns_class_name, key => "any"),
            unknown: counter!(dns_class_name, key => "unknown"),
        }
    }

    fn increment(&self, dns_class: DNSClass) {
        match dns_class {
            DNSClass::IN => self.r#in.increment(1),
            DNSClass::CH => self.ch.increment(1),
            DNSClass::HS => self.hs.increment(1),
            DNSClass::NONE => self.none.increment(1),
            DNSClass::ANY => self.any.increment(1),
            DNSClass::Unknown(_) => self.unknown.increment(1),
            DNSClass::OPT(_) => { /* skip OPT class type */ }
        }
    }
}
```

--------------------------------

### Flag Metrics Structure and Initialization

Source: https://docs.rs/hickory-server/latest/src/hickory_server/metrics.rs.html

Defines the structure for tracking DNS flags and provides a constructor for initializing metrics based on direction.

```rust
#[derive(Clone)]
pub(super) struct FlagMetrics {
    authoritative: Counter,
    authentic_data: Counter,
    checking_disabled: Counter,
    recursion_available: Counter,
    recursion_desired: Counter,
    truncation: Counter,
}

impl FlagMetrics {
    fn new(direction: Direction) -> Self {
        let flags_name = match direction {
            Direction::Request => REQUEST_FLAGS_TOTAL,
```

--------------------------------

### Initialize and Manage Journal

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/sqlite/persistence.rs.html

Constructs a new Journal instance from an existing connection or a file path, and provides access to the underlying SQLite connection and schema version.

```rust
impl Journal {
    /// Constructs a new Journal, attaching to the specified Sqlite Connection
    pub fn new(conn: Connection) -> Result<Self, PersistenceError> {
        let version = Self::select_schema_version(&conn)?;
        Ok(Self {
            conn: Mutex::new(conn),
            version,
        })
    }

    /// Constructs a new Journal opening a Sqlite connection to the file at the specified path
    pub fn from_file(journal_file: &Path) -> Result<Self, PersistenceError> {
        let result = Self::new(Connection::open(journal_file)?);
        let mut journal = result?;
        journal.schema_up()?;
        Ok(journal)
    }

    /// Returns a reference to the Sqlite Connection
    pub fn conn(&self) -> MutexGuard<'_, Connection> {
        self.conn.lock().expect("conn poisoned")
    }

    /// Returns the current schema version of the journal
    pub fn schema_version(&self) -> i64 {
        self.version
    }
```

--------------------------------

### Sqlite and TSIG Configuration Structures

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/sqlite/mod.rs.html

Configuration structs for defining Sqlite zone storage and TSIG authentication parameters.

```rust
/// Configuration for zone file for sqlite based zones
#[derive(Deserialize, PartialEq, Eq, Debug)]
#[serde(deny_unknown_fields)]
pub struct SqliteConfig {
    /// path to initial zone file
    pub zone_path: PathBuf,
    /// path to the sqlite journal file
    pub journal_path: PathBuf,
    /// Are updates allowed to this zone
    #[serde(default)]
    pub allow_update: bool,
    /// TSIG keys allowed to authenticate updates if `allow_update` is true
    #[cfg(feature = "__dnssec")]
    #[serde(default)]
    pub tsig_keys: Vec<TsigKeyConfig>,
}
```

```rust
/// Configuration for a TSIG authentication signer key
#[derive(Deserialize, PartialEq, Eq, Debug)]
#[serde(deny_unknown_fields)]
#[cfg(feature = "__dnssec")]
pub struct TsigKeyConfig {
    /// The key name
    pub name: String,
    /// A path to the unencoded symmetric HMAC key data
    pub key_file: PathBuf,
    /// The key algorithm
    pub algorithm: TsigAlgorithm,
    /// Allowed +/- difference (in seconds) between the time a TSIG request was signed
    /// and when it is verified.
    ///
    /// A fudge value that is too large may leave the server open to replay attacks.
    /// A fudge value that is too small may cause failures from latency and clock
    /// desynchronization.
    ///
    /// RFC 8945 recommends a fudge value of 300 seconds (the default if not specified).
    #[serde(default = "default_fudge")]
    pub fudge: u16,
}
```

```rust
#[cfg(feature = "__dnssec")]
impl TsigKeyConfig {
    fn to_signer(&self, zone_name: &Name, root_dir: Option<&Path>) -> Result<TSigner, String> {
        let key_file = rooted(&self.key_file, root_dir);
        let key_data = fs::read(&key_file)
            .map_err(|e| format!("error reading TSIG key file: {}: {e}", key_file.display()))?;
        let signer_name = Name::from_str(&self.name).unwrap_or_else(|_| zone_name.clone());

        TSigner::new(key_data, self.algorithm.clone(), signer_name, self.fudge)
            .map_err(|e| format!("invalid TSIG key configuration: {e}"))
    }
}
```

--------------------------------

### Blocklist Configuration Structure

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/blocklist.rs.html

Defines the configuration parameters for the blocklist, including wildcard settings, sinkhole IPs, and consult actions.

```rust
pub struct BlocklistConfig {
    /// Support wildcards?  Defaults to true. If set to true, block list entries containing
    /// asterisks will be expanded to match queries.
    pub wildcard_match: bool,

    /// Minimum wildcard depth.  Defaults to 2.  Any wildcard entries without at least this many
    /// static elements will not be expanded (e.g., *.com has a depth of 1; *.example.com has a
    /// depth of two.) This is meant as a safeguard against an errant block list entry, such as *
    /// or *.com that might block many more hosts than intended.
    pub min_wildcard_depth: u8,

    /// Block lists to load.  These should be specified as relative (to the server zone directory)
    /// paths in the config file.
    pub lists: Vec<String>,

    /// IPv4 sinkhole IP. This is the IP that is returned when a blocklist entry is matched for an
    /// A query. If unspecified, an implementation-provided default will be used.
    pub sinkhole_ipv4: Option<Ipv4Addr>,

    /// IPv6 sinkhole IP.  This is the IP that is returned when a blocklist entry is matched for a
    /// AAAA query. If unspecified, an implementation-provided default will be used.
    pub sinkhole_ipv6: Option<Ipv6Addr>,

    /// Block TTL. This is the length of time a block response should be stored in the requesting
    /// resolvers cache, in seconds.  Defaults to 86,400 seconds.
    pub ttl: u32,

    /// Block message to return to the user.  This is an optional message that, if configured, will
    /// be returned as a TXT record in the additionals section when a blocklist entry is matched for
    /// a query.
    pub block_message: Option<String>,

    /// The consult action controls how the blocklist handles queries where another zone handler has
    /// already provided an answer.  By default, it ignores any such queries ("Disabled",) however
    /// it can be configured to log blocklist matches for those queries ("Log",) or can be
    /// configured to overwrite the previous responses ("Enforce".)
    pub consult_action: BlocklistConsultAction,

    /// Controls client IP logging for blocklist matches
    pub log_clients: bool,
}
```

--------------------------------

### RequestInfo Constructor

Source: https://docs.rs/hickory-server/latest/hickory_server/server/struct.RequestInfo.html

The constructor method for creating a new RequestInfo instance.

```rust
pub fn new( src: SocketAddr, protocol: Protocol, metadata: &'a Metadata, query: &'a LowerQuery, ) -> Self
```

--------------------------------

### Zone Loading Test

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/file.rs.html

A test case for loading a zone configuration, demonstrating conditional configuration based on the __dnssec feature.

```rust
#[test]
    fn test_load_zone() {
        subscribe();

        #[cfg(feature = "__dnssec")]
        let config = FileConfig {
            zone_path: PathBuf::from("../../tests/test-data/test_configs/dnssec/example.com.zone"),
        };
        #[cfg(not(feature = "__dnssec"))]
        let config = FileConfig {
```

--------------------------------

### Construct a mock Queries object

Source: https://docs.rs/hickory-server/latest/hickory_server/zone_handler/struct.Queries.html

Creates a new Queries instance for testing purposes. Requires the 'testing' crate feature.

```rust
pub fn new(query: Vec<LowerQuery>) -> Self
```

--------------------------------

### FileZoneHandler Lookup and Search Methods

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/file.rs.html

Asynchronous methods for performing DNS lookups, searches, and zone transfers against an in-memory zone representation.

```rust
async fn lookup(
        &self,
        name: &LowerName,
        rtype: RecordType,
        request_info: Option<&RequestInfo<'_>>,
        lookup_options: LookupOptions,
    ) -> LookupControlFlow<AuthLookup> {
        self.in_memory
            .lookup(name, rtype, request_info, lookup_options)
            .await
    }
```

```rust
async fn search(
        &self,
        request: &Request,
        lookup_options: LookupOptions,
    ) -> (LookupControlFlow<AuthLookup>, Option<TSigResponseContext>) {
        self.in_memory.search(request, lookup_options).await
    }
```

```rust
async fn zone_transfer(
        &self,
        request: &Request,
        lookup_options: LookupOptions,
        now: u64,
    ) -> Option<(
        Result<ZoneTransfer, LookupError>,
        Option<TSigResponseContext>,
    )> {
        self.in_memory
            .zone_transfer(request, lookup_options, now)
            .await
    }
```

--------------------------------

### Register QUIC Listener

Source: https://docs.rs/hickory-server/latest/src/hickory_server/server/mod.rs.html

Registers a UDP socket for DNS-over-QUIC (DoQ) support using a certificate resolver.

```rust
#[cfg(feature = "__quic")]
    pub fn register_quic_listener(
        &mut self,
        socket: net::UdpSocket,
        // TODO: need to set a timeout between requests.
        _timeout: Duration,
        server_cert_resolver: Arc<dyn ResolvesServerCert>,
    ) -> io::Result<()> {
        let cx = self.context.clone();
        self.join_set
            .spawn(quic_handler::handle_quic(socket, server_cert_resolver, cx));
        Ok(())
    }
```

--------------------------------

### Queries Structure and Lifecycle Management

Source: https://docs.rs/hickory-server/latest/src/hickory_server/zone_handler/message_request.rs.html

Core implementation for managing a collection of DNS queries, including construction, reading from decoders, and serialization.

```rust
#[cfg(any(test, feature = "testing"))]
    pub fn new(query: Vec<LowerQuery>) -> Self {
        let mut encoded = Vec::new();
        let mut encoder = BinEncoder::new(&mut encoded);
        for q in query.iter() {
            q.emit(&mut encoder).unwrap();
        }
        Self {
            queries: query,
            original: encoded.into_boxed_slice(),
        }
    }

    /// Read queries from a decoder
    pub fn read(decoder: &mut BinDecoder<'_>, num_queries: usize) -> Result<Self, DecodeError> {
        let queries_start = decoder.index();
        let mut queries = Vec::with_capacity(num_queries);
        for _ in 0..num_queries {
            queries.push(LowerQuery::read(decoder)?);
        }

        let original = decoder
            .slice_from(queries_start)?
            .to_vec()
            .into_boxed_slice();

        Ok(Self { queries, original })
    }
```

--------------------------------

### register_quic_listener_and_tls_config

Source: https://docs.rs/hickory-server/latest/hickory_server/server/struct.Server.html

Registers a UDP socket for DNS-over-QUIC (DoQ) using a provided TLS configuration.

```APIDOC
## register_quic_listener_and_tls_config

### Description
Register a UdpSocket for supporting DoQ (DNS-over-QUIC) with the provided TLS config. The socket should be bound to an IPv4 or IPv6 address.

### Signature
`pub fn register_quic_listener_and_tls_config(&mut self, socket: UdpSocket, _timeout: Duration, tls_config: Arc<ServerConfig>) -> Result<(), NetError>`

### Arguments
- **socket** (UdpSocket) - A bound UDP socket.
- **_timeout** (Duration) - Timeout duration for incoming requests.
- **tls_config** (Arc<ServerConfig>) - Customized TLS configuration with TLS 1.3 and DoQ ALPN support.
```

--------------------------------

### DnssecZoneHandler Implementation

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/file.rs.html

Implementation of DnssecZoneHandler for FileZoneHandler, providing methods to add signing keys and secure the zone.

```rust
#[cfg(feature = "__dnssec")]
#[async_trait::async_trait]
impl DnssecZoneHandler for FileZoneHandler {
    /// Add Signer
    async fn add_zone_signing_key(&self, signer: DnssecSigner) -> DnsSecResult<()> {
        self.in_memory.add_zone_signing_key(signer).await
    }

    /// Sign the zone for DNSSEC
    async fn secure_zone(&self) -> DnsSecResult<()> {
        DnssecZoneHandler::secure_zone(&self.in_memory).await
    }
}
```

--------------------------------

### RecursiveZoneHandler Configuration Loading

Source: https://docs.rs/hickory-server/latest/src/hickory_server/store/recursor.rs.html

Initializes a RecursiveZoneHandler from configuration, including setting up persistence tasks if enabled.

```rust
    pub async fn try_from_config(
        origin: Name,
        _zone_type: ZoneType,
        config: RecursiveConfig,
        root_dir: Option<&Path>,
        conn_provider: P,
    ) -> Result<Self, String> {
        info!("loading recursor config: {}", origin);

        #[cfg(all(feature = "toml", any(feature = "__tls", feature = "__quic")))]
        let persistence_config = match &config.options.opportunistic_encryption {
            OpportunisticEncryption::Enabled { config } => config.persistence.clone(),
            _ => None,
        };

        let recursor = Recursor::from_config(config, root_dir, conn_provider.clone())
            .map_err(|e| format!("failed to build recursor: {e}"))?;

        Ok(Self {
            origin: origin.into(),
            // Once the recursor is built, potentially use the recursor's pool context to spawn a
            // background save task, holding the task handle (if created) so it drops with the zone handler.
            #[cfg(all(feature = "toml", any(feature = "__tls", feature = "__quic")))]
            opportunistic_encryption_persistence_task: match persistence_config {
                Some(config) => {
                    OpportunisticEncryptionStatePersistTask::<P::Timer>::start(
                        config,
                        recursor.pool_context(),
                        conn_provider.clone(),
                    )
                    .await?
                }
                _ => None,
            },
            #[cfg(not(all(feature = "toml", any(feature = "__tls", feature = "__quic"))))]
            opportunistic_encryption_persistence_task: None,
            recursor,
        })
    }
```
Tokens:
Raw