Hickory Recursor

https://docs.rs/hickory-recursor/latest/
Admin
Hickory Recursor is a recursive DNS resolver based on the Hickory DNS (stub) resolver, designed for...
Tokens:85,316
Snippets:429
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Rust Slice binary_search Examples

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Provides examples of using the `binary_search` method in Rust. It illustrates finding elements, handling cases where elements are not found, and managing multiple occurrences of an element.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

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

### Rust Vec push Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

A basic example demonstrating the `push` method to append a single element to the end of a vector. It shows the vector's state before and after the operation.

```Rust
let mut vec = vec![1, 2];
vec.push(3);
assert_eq!(vec, [1, 2, 3]);
```

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

### Rust Vec as_ptr Examples

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Illustrates the usage of `as_ptr` to get a raw pointer to the vector's buffer. Includes examples of iterating through the buffer using the pointer and demonstrating aliasing guarantees.

```rust
let x = vec![1, 2, 4];
let x_ptr = x.as_ptr();

unsafe {
    for i in 0..x.len() {
        assert_eq!(*x_ptr.add(i), 1 << i);
    }
}
```

```rust
unsafe {
    let mut v = vec![0, 1, 2];
    let ptr1 = v.as_ptr();
    let _ = ptr1.read();
    let ptr2 = v.as_mut_ptr().offset(2);
    ptr2.write(2);
    let _ = ptr1.read();
}
```

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

### Hickory Recursor Resolve Method Example

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor

Demonstrates the usage of the `resolve` method within the Hickory Recursor, including error handling and assertions.

```Rust
let res = recursor.resolve(query, Instant::now(), false).await.unwrap_err();
assert!(res.to_string().contains("fully qualified"));
```

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

### Rust partition_point Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the usage of the `partition_point` method on Rust slices. This method returns the index of the first element that does not satisfy the predicate, effectively partitioning the slice.

```rust
let v = [1, 2, 3, 3, 5, 6, 7];
let i = v.partition_point(|&x| x < 5);

assert_eq!(i, 4);
assert!(v[..i].iter().all(|&x| x < 5));
assert!(v[i..].iter().all(|&x| !(x < 5)));
```

```rust
let a = [2, 4, 8];
assert_eq!(a.partition_point(|x| x < &100), a.len());
let a: [i32; 0] = [];
assert_eq!(a.partition_point(|x| x < &100), 0);
```

```rust
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.partition_point(|&x| x <= num);
s.insert(idx, num);
assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);
```

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

### DNS Resolution Scenario Example

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor

Presents a scenario for domain space administration, illustrating how name servers might be allocated for zones like root, MIL, EDU, MIT.EDU, and ISI.EDU.

```rust
/// 6. A SCENARIO
///
/// In our sample domain space, suppose we wanted separate administrative
/// control for the root, MIL, EDU, MIT.EDU and ISI.EDU zones.  We might
/// allocate name servers as follows:
///
///                                    |(C.ISI.EDU,SRI-NIC.ARPA
///                                    | A.ISI.EDU)
///              +---------------------+------------------+
///              |                     |                  |
///             MIL                   EDU                ARPA
```

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

### Rust Slice SIMD Splitting Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates how to split a slice into a prefix, a middle section of SIMD types, and a suffix using the `as_simd` method. Includes a function for calculating SIMD sums.

```Rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);

```

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

### Rust Slice Len Method

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Shows a basic example of using the `len` method to get the number of elements in a slice.

```Rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

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

### Rust slice strip_suffix examples

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Provides examples for the `strip_suffix` method in Rust slices. It illustrates removing a suffix from a slice and the results based on whether the suffix is present, absent, or matches the entire slice.

```Rust
let v = &[10, 40, 30];
assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_suffix(&[50]), None);
assert_eq!(v.strip_suffix(&[50, 30]), None);
```

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

### Rust Vec Truncate Examples

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates how to truncate a Rust Vec to a specified length. Includes examples for truncating to a smaller size, a size larger than the current length, and to zero length.

```rust
let mut vec = vec![1, 2, 3, 4, 5];
vec.truncate(2);
assert_eq!(vec, [1, 2]);
```

```rust
let mut vec = vec![1, 2, 3];
vec.truncate(8);
assert_eq!(vec, [1, 2, 3]);
```

```rust
let mut vec = vec![1, 2, 3];
vec.truncate(0);
assert_eq!(vec, []);
```

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

### Rust slice strip_prefix examples

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the usage of the `strip_prefix` method on Rust slices. It shows how to remove a prefix from a slice and the expected output when the prefix matches, partially matches, or does not match.

```Rust
let v = &[10, 40, 30];
assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
assert_eq!(v.strip_prefix(&[50]), None);
assert_eq!(v.strip_prefix(&[10, 50]), None);

let prefix : &str = "he";
assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
           Some(b"llo".as_ref()));
```

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

### Rust slice trim_prefix examples (Nightly)

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the experimental `trim_prefix` method for Rust slices. This method removes a prefix if present, otherwise returns the original slice. Examples cover cases with and without the prefix.

```Rust
#![feature(trim_prefix_suffix)]

let v = &[10, 40, 30];

// Prefix present - removes it
assert_eq!(v.trim_prefix(&[10]), &[40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 40]), &[30][..]);
assert_eq!(v.trim_prefix(&[10, 40, 30]), &[][..]);

// Prefix absent - returns original slice
assert_eq!(v.trim_prefix(&[50]), &[10, 40, 30][..]);
assert_eq!(v.trim_prefix(&[10, 50]), &[10, 40, 30][..]);

let prefix : &str = "he";
assert_eq!(b"hello".trim_prefix(prefix.as_bytes()), b"llo".as_ref());
```

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

### Rust rsplitn Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates splitting a slice from the end into at most 2 subslices, using a predicate to determine split points. The split element is not included in the subslices.

```rust
let v = [10, 40, 30, 20, 60, 50];

for group in v.rsplitn(2, |num| *num % 3 == 0) {
    println!("{group:?}");
}
```

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

### Hickory-recursor DNS Handle - Get Resolver Options

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

Retrieves the resolver options for the Hickory-recursor, encapsulating configuration for DNS resolution.

```rust
fn recursor_opts(&self) -> ResolverOpts {
recursor_opts(self.avoid_local_udp_ports.clone(), self.case_randomization)
}
```

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

### Rust: partition_dedup_by Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Illustrates using the unstable `partition_dedup_by` method with a custom equality function (case-insensitive string comparison). It partitions the slice based on the provided `same_bucket` closure.

```Rust
#![feature(slice_partition_dedup)]

let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"];

let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b));

assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]);
assert_eq!(duplicates, ["bar", "Foo", "BAZ"]);
```

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

### Check if slice starts with a prefix

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

The `starts_with` method determines if a slice begins with a specified prefix. It returns true if the prefix matches the beginning of the slice or if the prefix is empty.

```rust
pub fn starts_with<T: PartialEq>(&self, needle: &[T]) -> bool

// Example:
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));

// Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
```

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

### Rust Slice windows() Iterator

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the `windows()` iterator for creating sliding windows of a specified size over a slice. Includes examples for slices of sufficient length and slices shorter than the window size, showing that `next()` returns `None` when no full window can be formed.

```rust
let slice = ['l', 'o', 'r', 'e', 'm'];
let mut iter = slice.windows(3);
assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
assert!(iter.next().is_none());
```

```rust
let slice = ['f', 'o', 'o'];
let mut iter = slice.windows(4);
assert!(iter.next().is_none());
```

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

### Rust Vec Splice Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates using the `splice` method to replace a range of elements in a vector with new elements and collecting the removed elements.

```Rust
let mut v = vec![1, 2, 3, 4];
let new = [7, 8, 9];
let u: Vec<_> = v.splice(1..3, new).collect();
assert_eq!(v, [1, 7, 8, 9, 4]);
assert_eq!(u, [2, 3]);
```

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

### Rust split_once Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Illustrates splitting a slice into two parts based on the first element that satisfies a given predicate. Returns None if no element matches the predicate. This is a nightly-only experimental API.

```rust
#![feature(slice_split_once)]
let s = [1, 2, 3, 2, 4];
assert_eq!(s.split_once(|&x| x == 2), Some((
    &[1][..],
    &[3, 2, 4][..]
)));
assert_eq!(s.split_once(|&x| x == 0), None);
```

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

### Rust rsplit_once Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates splitting a slice into two parts based on the last element that satisfies a given predicate. Returns None if no element matches the predicate. This is a nightly-only experimental API.

```rust
#![feature(slice_split_once)]
let s = [1, 2, 3, 2, 4];
assert_eq!(s.rsplit_once(|&x| x == 2), Some((
    &[1, 2, 3][..],
    &[4][..]
)));
assert_eq!(s.rsplit_once(|&x| x == 0), None);
```

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

### Rust Vec as_slice Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Shows how to use the `as_slice` method to get an immutable slice of the entire vector's contents. This is equivalent to `&s[..]`.

```rust
use std::io::{self, Write};
let buffer = vec![1, 2, 3, 5, 8];
io::sink().write(buffer.as_slice()).unwrap();
```

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

### Handling Second-Level Domain Queries and Potential Issues

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

This documentation describes the behavior when a user directly queries a second-level domain (e.g., example.com). It highlights the potential for superfluous NS queries to parent zones (e.g., com.) and the resulting empty answers or SOA records returned by non-authoritative servers.

```rust
// If the user is directly querying the second-level domain (e.g., an A query for example.com),
// the following behavior will occur:
//
// query NS . for com. -> NS list + glue for com.
//
// ns_pool_for_zone would return that as the NS pool to use for the query 'example.com'.
// The subsequent lookup request for then ask the com. servers to resolve A example.com, which
// they are not authoritative for. In that case, those servers will return an empty answer
```

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

### Rust: split_at_mut_checked Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Shows how to use `split_at_mut_checked` to get mutable references to two subslices. It returns `None` if the index is out of bounds, ensuring safe mutable splitting.

```rust
let mut v = [1, 0, 3, 0, 5, 6];

if let Some((left, right)) = v.split_at_mut_checked(2) {
    assert_eq!(left, [1, 0]);
    assert_eq!(right, [3, 0, 5, 6]);
    left[1] = 2;
    right[1] = 4;
}
assert_eq!(v, [1, 2, 3, 4, 5, 6]);

assert_eq!(None, v.split_at_mut_checked(7));
```

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

### Hickory Recursor Files

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

Lists the source files for the hickory-recursor crate, including error handling, core logic, DNS handle, and pool management.

```Rust
error.rs
lib.rs
recursor.rs
recursor_dns_handle.rs
recursor_pool.rs
```

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

### Get Element Offset (Rust)

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Returns the index of an element reference within a slice. This method uses pointer arithmetic and does not compare elements. It returns None if the element reference does not point to the start of an element. This is a nightly-only experimental API.

```rust
pub fn element_offset(&self, element: [&T]) -> Option<usize>
// ... implementation details ...

// Example Usage:
// let slice = [10, 20, 30];
// let element_ref = &slice[1..2]; // This would be a slice reference
// let offset = slice.element_offset(element_ref);
// assert_eq!(offset, Some(1));
```

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

### Rust Slice rchunks Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the usage of the `rchunks` method on a slice, which returns an iterator over chunks of a specified size starting from the end of the slice. The last chunk may be smaller if the slice length is not divisible by the chunk size.

```Rust
#![feature(array_windows)]
let slice = [0, 1, 2, 3];
let mut iter = slice.array_windows();
assert_eq!(iter.next().unwrap(), &[0, 1]);
assert_eq!(iter.next().unwrap(), &[1, 2]);
assert_eq!(iter.next().unwrap(), &[2, 3]);
assert!(iter.next().is_none());
```

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

### RecursorDnsHandle Constructor

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

Initializes a new RecursorDnsHandle with specified DNS resolution and caching configurations. It takes various parameters to set up root servers, cache sizes, recursion limits, security settings, and network access policies.

```rust
pub(crate) fn new(
        roots: impl Into<NameServerConfigGroup>,
        ns_cache_size: usize,
        record_cache_size: usize,
        recursion_limit: Option<u8>,
        ns_recursion_limit: Option<u8>,
        security_aware: bool,
        allow_server: Vec<IpNet>,
        deny_server: Vec<IpNet>,
        avoid_local_udp_ports: Arc<HashSet<u16>>,
        ttl_config: TtlConfig,
        case_randomization: bool,
    ) -> Self {
        // configure the hickory-resolver
        let roots: NameServerConfigGroup = roots.into();

        assert!(!roots.is_empty(), "roots must not be empty");
        // ... (rest of the implementation)
```

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

### Rust: Get First Chunk Mutably

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

The `first_chunk_mut` method returns a mutable reference to the first `N` items in a slice as an array. If the slice is shorter than `N`, it returns `None`. This enables in-place modification of fixed-size blocks at the start of a slice.

```rust
pub fn first_chunk_mut<const N: usize>(&mut self) -> Option<&mut [T; N]>

// Example:
let x = &mut [0, 1, 2];

if let Some(first) = x.first_chunk_mut::<2>() {
    first[0] = 5;
    first[1] = 4;
}
assert_eq!(x, &[5, 4, 2]);

assert_eq!(None, x.first_chunk_mut::<4>());
```

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

### NameServerConfigGroup Methods

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Provides a collection of methods for creating and manipulating NameServerConfigGroup configurations, including setting up DNS servers like Cloudflare, Google, and Quad9 with various protocols (HTTPS, TLS, QUIC, H3).

```APIDOC
NameServerConfigGroup:
  append_ips(ips: Vec<IpAddr>)
    Appends a list of IP addresses to the existing name server configurations.

  cloudflare()
    Creates a NameServerConfigGroup with Cloudflare's DNS servers.

  cloudflare_https()
    Creates a NameServerConfigGroup with Cloudflare's DNS servers using HTTPS.

  cloudflare_tls()
    Creates a NameServerConfigGroup with Cloudflare's DNS servers using TLS.

  from_ips_clear(ips: Vec<IpAddr>)
    Creates a NameServerConfigGroup from a list of IP addresses, clearing any existing configurations.

  from_ips_h3(ips: Vec<IpAddr>)
    Creates a NameServerConfigGroup from a list of IP addresses using the H3 protocol.

  from_ips_https(ips: Vec<IpAddr>)
    Creates a NameServerConfigGroup from a list of IP addresses using HTTPS.

  from_ips_quic(ips: Vec<IpAddr>)
    Creates a NameServerConfigGroup from a list of IP addresses using QUIC.

  from_ips_tls(ips: Vec<IpAddr>)
    Creates a NameServerConfigGroup from a list of IP addresses using TLS.

  google()
    Creates a NameServerConfigGroup with Google's DNS servers.

  google_h3()
    Creates a NameServerConfigGroup with Google's DNS servers using H3.

  google_https()
    Creates a NameServerConfigGroup with Google's DNS servers using HTTPS.

  google_tls()
    Creates a NameServerConfigGroup with Google's DNS servers using TLS.

  into_inner()
    Consumes the NameServerConfigGroup and returns the inner configuration.

  merge(other: NameServerConfigGroup)
    Merges another NameServerConfigGroup into this one.

  new()
    Creates a new, empty NameServerConfigGroup.

  quad9()
    Creates a NameServerConfigGroup with Quad9's DNS servers.

  quad9_https()
    Creates a NameServerConfigGroup with Quad9's DNS servers using HTTPS.

  quad9_tls()
    Creates a NameServerConfigGroup with Quad9's DNS servers using TLS.

  with_bind_addr(addr: SocketAddr)
    Sets the bind address for the name server.

  with_capacity(capacity: usize)
    Sets the initial capacity for the internal storage.
```

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

### Rust Vec dedup_by Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Illustrates the `dedup_by` method, which removes consecutive elements that are considered equal by a provided closure. This example uses `eq_ignore_ascii_case` to remove case-insensitive duplicates.

```Rust
let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
assert_eq!(vec, ["foo", "bar", "baz", "bar"]);
```

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

### Hickory DNS Recursor Library Overview

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/error

Provides an overview of the Hickory DNS Recursor library, highlighting its features such as DNSSEC support and its foundation on Tokio and Futures. It also lists the library's dependencies and licensing information.

```Rust
/// Hickory DNS Recursor is a safe and secure DNS recursive resolver with DNSSEC support.
/// Hickory DNS is based on the Tokio and Futures libraries, which means
/// it should be easily integrated into other software that also use those
/// libraries. This library can be used as in the server and binary for performing recursive lookups.
```

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

### Rust Vec dedup_by_key Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Shows how `dedup_by_key` removes consecutive duplicate elements from a vector based on a key extracted from each element. In this example, elements are grouped by their value divided by 10.

```Rust
let mut vec = vec![10, 20, 21, 30, 20];
vec.dedup_by_key(|i| *i / 10);
assert_eq!(vec, [10, 20, 30, 20]);
```

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

### Initialize DNS Handle and Caches

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

Initializes the DNS handle with specified cache sizes and configures the name server pool. It also sets up deny and allow lists for DNS servers based on IP networks.

```rust
let opts = recursor_opts(avoid_local_udp_ports.clone(), case_randomization);
let roots = GenericNameServerPool::from_config(roots, opts, TokioConnectionProvider::default());
let roots = RecursorPool::from(Name::root(), roots);
let name_server_cache = Arc::new(Mutex::new(LruCache::new(ns_cache_size)));
let record_cache = DnsLru::new(record_cache_size, ttl_config);
```

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

### Hickory Recursor Dependencies

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/lib

Lists the dependencies for the hickory-recursor crate, including asynchronous programming utilities, DNS protocol handling, and caching mechanisms.

```Rust
# Dependencies
# async-recursion ^1.0.0
# async-trait ^0.1.43
# backtrace ^0.3.50 _optional_
# bytes ^1
# cfg-if ^1
# enum-as-inner ^0.6
# futures-util ^0.3.5
# hickory-proto ^0.25
# hickory-resolver ^0.25
# ipnet ^2.3.0
# lru-cache ^0.1.2
# parking_lot ^0.12
# prefix-trie ^0.7
# serde ^1.0 _optional_
# thiserror ^2
# tokio ^1.21
# tracing ^0.1.30
```

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

### NameServerConfigGroup Creation

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Provides methods to create new NameServerConfigGroup instances. `new()` creates a group with default capacity, while `with_capacity()` allows specifying the initial capacity.

```rust
impl NameServerConfigGroup {
    /// Creates a new `NameServerConfigGroup` with a default size of 2
    pub fn new() -> NameServerConfigGroup;

    /// Creates a new `NameServiceConfigGroup` with the specified capacity
    pub fn with_capacity(capacity: usize) -> NameServerConfigGroup;
}
```

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

### Recursor Configuration and Instantiation

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor

This snippet demonstrates how to configure and instantiate a DNS recursor. It shows the use of a builder pattern to set various options like server allowances, caching sizes, recursion limits, and DNSSEC policies. The code then creates a `RecursorDnsHandle` and determines the `RecursorMode` based on the DNSSEC policy, including handling validation with static keys.

```Rust
let handle = RecursorDnsHandle::new(
            roots,
            ns_cache_size,
            record_cache_size,
            recursion_limit,
            ns_recursion_limit,
            dnssec_policy.is_security_aware(),
            allow_servers,
            deny_servers,
            Arc::new(avoid_local_udp_ports),
            ttl_config,
            case_randomization,
        );

        let mode = match dnssec_policy {
            DnssecPolicy::SecurityUnaware => RecursorMode::NonValidating { handle },

            #[cfg(feature = "__dnssec")]
            DnssecPolicy::ValidationDisabled => RecursorMode::NonValidating { handle },

            #[cfg(feature = "__dnssec")]
            DnssecPolicy::ValidateWithStaticKey { trust_anchor } => {
                let record_cache = handle.record_cache().clone();
                let trust_anchor = match trust_anchor {
                    Some(anchor) if anchor.is_empty() => {
                        return Err(Error::from("trust anchor must not be empty"));
                    }
                    Some(anchor) => anchor,
                    None => Arc::new(TrustAnchors::default()),
                };

                RecursorMode::Validating {
                    record_cache,
                    
```

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

### Rust slice trim_suffix examples (Nightly)

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Showcases the experimental `trim_suffix` method for Rust slices. This function removes a suffix if it exists, otherwise returning the original slice. Examples illustrate its behavior with and without a matching suffix.

```Rust
let v = &[10, 40, 30];

// Suffix present - removes it
assert_eq!(v.trim_suffix(&[30]), &[10, 40][..]);
assert_eq!(v.trim_suffix(&[40, 30]), &[10][..]);
assert_eq!(v.trim_suffix(&[10, 40, 30]), &[][..]);

// Suffix absent - returns original slice
assert_eq!(v.trim_suffix(&[50]), &[10, 40, 30][..]);
assert_eq!(v.trim_suffix(&[50, 30]), &[10, 40, 30][..]);
```

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

### NameServerConfigGroup Windowing Method

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Provides a method for creating sliding windows over the NameServerConfigGroup.

```APIDOC
NameServerConfigGroup::windows
  - Returns an iterator over the sliding windows of the NameServerConfigGroup.
```

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

### Rust Slice split_at_unchecked Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the usage of the unsafe `split_at_unchecked` method on a Rust slice. This method divides a slice into two at a specified index without performing bounds checking. The examples show splitting at index 0, 2, and the length of the slice.

```rust
let v = ['a', 'b', 'c'];

unsafe {
   let (left, right) = v.split_at_unchecked(0);
   assert_eq!(left, []);
   assert_eq!(right, ['a', 'b', 'c']);
}

unsafe {
    let (left, right) = v.split_at_unchecked(2);
    assert_eq!(left, ['a', 'b']);
    assert_eq!(right, ['c']);
}

unsafe {
    let (left, right) = v.split_at_unchecked(3);
    assert_eq!(left, ['a', 'b', 'c']);
    assert_eq!(right, []);
}
```

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

### Recursive Name Server Discovery for Zone NS Pool

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

This section explains the recursive search for authoritative name servers to build an NS pool for a given zone. It details the queries made for parent zones (e.g., com.) and how the NS pool is constructed from the results, including glue records.

```rust
// Recursively search for authoritative name servers for the queried record to build an NS
// pool to use for queries for a given zone. By searching for zone.base_name() (e.g.,
// example.com if the query is 'www.example.com'), we should end up with the following set
// of queries:
//
// query NS . for com. -> NS list + glue for com.
// query NS com. for example.com. -> NS list + glue for example.com.
//
// ns_pool_for_zone would then return an NS pool based the results of the last query, plus
// any additional glue records that needed to be resolved, and the authoritative name servers
// for example.com can be queried directly for 'www.example.com'.
```

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

### Rust Slice split_at_mut_unchecked Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Illustrates the use of the unsafe `split_at_mut_unchecked` method for mutable slices in Rust. This method splits a mutable slice into two mutable subslices without bounds checking. The example shows how to modify elements in the subslices and observe the changes in the original slice.

```rust
let mut v = [1, 0, 3, 0, 5, 6];
// scoped to restrict the lifetime of the borrows
unsafe {
    let (left, right) = v.split_at_mut_unchecked(2);
    assert_eq!(left, [1, 0]);
    assert_eq!(right, [3, 0, 5, 6]);
    left[1] = 2;
    right[1] = 4;
}
assert_eq!(v, [1, 2, 3, 4, 5, 6]);
```

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

### Get Error Kind

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/error

A method to retrieve the specific kind of error from an `Error` instance.

```rust
impl Error {
    pub fn kind(&self) -> &ErrorKind {
        &self.kind
    }
}
```

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

### Hickory Recursor Core Files

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/error

Lists the core Rust source files for the hickory-recursor library, including error handling, main library logic, and pool management.

```Rust
error.rs
lib.rs
recursor.rs
ecursor_dns_handle.rs
ecursor_pool.rs
```

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

### Get Allocator Reference (Rust)

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Returns a reference to the underlying allocator. This is a nightly-only experimental API.

```rust
pub fn allocator(&self) -> &A
```

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

### Rustdoc Settings

Source: https://docs.rs/hickory-recursor/latest/settings

Configuration options for the Rustdoc documentation generator, allowing customization of themes, layout, and behavior for displaying documentation.

```Rust
Theme:
light dark ayu system preference
Preferred light theme
light dark ayu
Preferred dark theme
light dark ayu
Auto-hide item contents for large items
Auto-hide item methods' documentation
Auto-hide trait implementation documentation
Directly go to item in search if there is only one result
Show line numbers on code examples
Hide persistent navigation bar
Hide table of contents
Hide module navigation
Disable keyboard shortcuts
Use sans serif fonts
Word wrap source code
```

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

### Get Record Cache (Rust)

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

Provides access to the DNS record cache, which is conditionally compiled based on the '__dnssec' feature flag.

```rust
#[cfg(feature = "__dnssec")]
pub(crate) fn record_cache(&self) -> &DnsLru {
    &self.record_cache
}
```

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

### DNS Name Server Pool Construction

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor_dns_handle

This code snippet demonstrates the process of constructing a DNS name server pool for a given query name. It involves collecting missing IP addresses, potentially performing lookups for glue records, and then initializing a `RecursorPool` with the resolved name servers and configuration.

```rust
        // collect missing IP addresses
        if config_group.is_empty() && !need_ips_for_names.is_empty() {
            debug!("ns_pool_for_referral need glue for {query_name}");

            let (new_depth, nameserver_pool) = self
                .ns_pool_for_zone(query_name.clone(), request_time, depth)
                .await?;

            depth = new_depth;

            depth = self
                .append_ips_from_lookup(
                    &query_name,
                    depth,
                    request_time,
                    nameserver_pool,
                    need_ips_for_names.iter().filter_map(|x| x.data().as_ns()),
                    &mut config_group,
                )
                .await?;
        }

        debug!("ns_pool_for_referral found nameservers for {query_name}: {config_group:?}");

        // now construct a namesever pool based off the NS and glue records
        let ns = GenericNameServerPool::from_config(
            config_group,
            self.recursor_opts(),
            TokioConnectionProvider::default(),
        );
        let ns = RecursorPool::from(query_name.clone(), ns);

        // store in cache for future usage
        self.name_server_cache.lock().insert(query_name, ns.clone());

        Ok((depth, ns))
```

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

### Rust Slice get

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Returns a reference to an element or subslice based on the index type. Returns None if the index is out of bounds.

```rust
pub fn get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>
where I: SliceIndex<[T]> 

// Example:
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```

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

### Build Recursor with Root Servers

Source: https://docs.rs/hickory-recursor/latest/src/hickory_recursor/recursor

Constructs a new `Recursor` instance using a provided list of `NameServerConfigGroup` for the root nodes. This method panics if the roots list is empty.

```rust
/// Construct a new recursor using the list of NameServerConfigs for the root node list
///
/// # Panics
///
/// This will panic if the roots are empty.
pub fn build(self, roots: impl Into<NameServerConfigGroup>) -> Result<Recursor, Error> {
    Recursor::build(roots, self)
}
```

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

### Rust: split_at_checked Example

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates the usage of `split_at_checked` to divide a slice into two at a given index. It returns `None` if the index is out of bounds.

```rust
let v = [1, -2, 3, -4, 5, -6];

{
   let (left, right) = v.split_at_checked(0).unwrap();
   assert_eq!(left, []);
   assert_eq!(right, [1, -2, 3, -4, 5, -6]);
}

{
    let (left, right) = v.split_at_checked(2).unwrap();
    assert_eq!(left, [1, -2]);
    assert_eq!(right, [3, -4, 5, -6]);
}

{
    let (left, right) = v.split_at_checked(6).unwrap();
    assert_eq!(left, [1, -2, 3, -4, 5, -6]);
    assert_eq!(right, []);
}

assert_eq!(None, v.split_at_checked(7));
```

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

### NameServerConfigGroup Swapping Methods

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Methods for swapping elements within the NameServerConfigGroup.

```APIDOC
NameServerConfigGroup::swap
  - Swaps two elements in the NameServerConfigGroup.

NameServerConfigGroup::swap_unchecked
  - Swaps two elements in the NameServerConfigGroup without bounds checking.

NameServerConfigGroup::swap_with_slice
  - Swaps a portion of the NameServerConfigGroup with another slice.
```

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

### Rust: Get vector length with len

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Returns the number of elements currently in the vector, also known as its length, using the `len` method.

```rust
pub fn len(&self) -> usize
Returns the number of elements in the vector, also referred to as its ‘length’.

Examples:
let a = vec![1, 2, 3];
assert_eq!(a.len(), 3);
```

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

### Create Quad9 DNS Configurations

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Offers methods to create NameServerConfigGroup configurations using Quad9's secure public DNS servers. Options include standard DNS, DNS over TLS (TLS), and DNS over HTTPS (HTTPS).

```rust
pub fn quad9() -> NameServerConfigGroup
// Creates a configuration, using `9.9.9.9`, `149.112.112.112` and `2620:fe::fe`, `2620:fe::fe:9`, the “secure” variants of the quad9 settings (thank you, Quad9).
```

```rust
pub fn quad9_tls() -> NameServerConfigGroup
// Creates a configuration, using `9.9.9.9`, `149.112.112.112` and `2620:fe::fe`, `2620:fe::fe:9`, the “secure” variants of the quad9 settings. This limits the registered connections to just TLS lookups
```

```rust
pub fn quad9_https() -> NameServerConfigGroup
// Creates a configuration, using `9.9.9.9`, `149.112.112.112` and `2620:fe::fe`, `2620:fe::fe:9`, the “secure” variants of the quad9 settings. This limits the registered connections to just HTTPS lookups
```

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

### Rust Slice iter

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Returns an iterator over the elements of a slice, yielding items from start to end. The iterator provides immutable references to the elements.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

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

### Rust: split_mut Example with Predicate

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Demonstrates `split_mut`, which yields mutable subslices separated by elements matching a predicate. This allows in-place modification of the subslices.

```rust
let mut v = [10, 40, 30, 20, 60, 50];

for group in v.split_mut(|num| *num % 3 == 0) {
    group[0] = 1;
}
assert_eq!(v, [1, 40, 30, 1, 60, 1]);
```

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

### NameServerConfigGroup API (Rust)

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Documentation for the NameServerConfigGroup struct in the hickory-recursor crate. Includes methods for cloning and debugging.

```APIDOC
pub fn connect<Separator>(&self, sep: Separator) -> <[[T]] as Join<Separator>>::Output [ⓘ]
where [[T]]: Join<Separator>,
Deprecated since 1.3.0: renamed to join
Flattens a slice of `T` into a single value `Self::Output`, placing a given separator between each.

clone(&self) -> NameServerConfigGroup
Returns a duplicate of the value.

clone_from(&mut self, source: &Self)
Performs copy-assignment from `source`.

fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>
Formats the value using the given formatter.
```

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

### Configure DNS-over-QUIC

Source: https://docs.rs/hickory-recursor/latest/hickory_recursor/struct

Configures a NameServer address and port for DNS-over-QUIC. This method creates QUIC connections to the specified IP addresses and port, using the provided TLS DNS name and a flag to trust negative responses.

```APIDOC
pub fn from_ips_quic(
    ips: &[[IpAddr]],
    port: u16,
    tls_dns_name: String,
    trust_negative_responses: bool,
) -> NameServerConfigGroup

Configure a NameServer address and port for DNS-over-QUIC.
This will create a QUIC connections.
```
Tokens:
Raw