Hickory Client

https://docs.rs/hickory-client/latest/
Admin
Hickory Client is a Rust library for communicating with DNS servers and resolvers, enabling DNS...
Tokens:19,760
Snippets:135
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Test Module Setup

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Boilerplate for setting up unit tests for the client stream.

```rust
#[cfg(test)]
mod tests {
    use std::net::SocketAddr;

    use super::*;

    use ClientStreamXfrState::*;
    use futures_util::stream::iter;
    use hickory_proto::{
        rr::{
            RData,
```

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

### Client::new

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Initializes a new DNS client with a default 5-second timeout.

```APIDOC
## Client::new

### Description
Spawns a new Client Stream using a default timeout of 5 seconds for all requests.

### Arguments
- **stream** (Future) - A stream of bytes that can be used to send/receive DNS messages.
- **stream_handle** (BufDnsStreamHandle) - The handle for the stream on which bytes can be sent/received.
- **signer** (Option<Arc<dyn MessageFinalizer>>) - An optional signer for requests, needed for Updates with Sig0.
```

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

### Initialize Asynchronous TCP Client

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Demonstrates initializing a TCP-based DNS client, including background task spawning for request multiplexing.

```rust
#[tokio::test]
async fn async_client() {
    subscribe();
    use crate::client::{Client, ClientHandle};
    use hickory_proto::{
        rr::{DNSClass, Name, RData, RecordType},
        tcp::TcpClientStream,
    };
    use std::str::FromStr;

    // Since we used UDP in the previous examples, let's change things up a bit and use TCP here
    let addr = SocketAddr::from(([8, 8, 8, 8], 53));
    let (stream, sender) = TcpClientStream::new(addr, None, None, TokioRuntimeProvider::new());

    // Create a new client, the bg is a background future which handles
    //   the multiplexing of the DNS requests to the server.
    //   the client is a handle to an unbounded queue for sending requests via the
    //   background. The background must be scheduled to run before the client can
    //   send any dns requests
    let client = Client::new(stream, sender, None);

    // await the connection to be established
    let (mut client, bg) = client.await.expect("connection failed");

    // make sure to run the background task
    tokio::spawn(bg);

    // Create a query future
    let query = client.query(
        Name::from_str("www.example.com.").unwrap(),
        DNSClass::IN,
        RecordType::A,
    );

    // wait for its response
```

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

### Perform a DNS Query with TCP

Source: https://docs.rs/hickory-client/latest/hickory_client/index.html

Demonstrates setting up a TCP-based DNS client using the Tokio runtime to perform an A record query.

```rust
use std::net::Ipv4Addr;
use std::str::FromStr;
use tokio::net::TcpStream as TokioTcpStream;
use hickory_client::client::{Client, ClientHandle};
use hickory_client::proto::runtime::TokioRuntimeProvider;
use hickory_client::proto::rr::{DNSClass, Name, RData, RecordType};
use hickory_client::proto::rr::rdata::A;
use hickory_client::proto::tcp::TcpClientStream;

#[tokio::main]
async fn main() {
    // Since we used UDP in the previous examples, let's change things up a bit and use TCP here
    let (stream, sender) =
        TcpClientStream::new(([8, 8, 8, 8], 53).into(), None, None, TokioRuntimeProvider::new());

    // Create a new client, the bg is a background future which handles
    //   the multiplexing of the DNS requests to the server.
    //   the client is a handle to an unbounded queue for sending requests via the
    //   background. The background must be scheduled to run before the client can
    //   send any dns requests
    let client = Client::new(stream, sender, None);

    // await the connection to be established
    let (mut client, bg) = client.await.expect("connection failed");

    // make sure to run the background task
    tokio::spawn(bg);

    // Create a query future
    let query = client.query(
        Name::from_str("www.example.com.").unwrap(),
        DNSClass::IN,
        RecordType::A,
   );

    // wait for its response
    let response = query.await.unwrap();

    // validate it's what we expected
    if let RData::A(addr) = response.answers()[0].data() {
        assert_eq!(*addr, A::new(93, 184, 215, 14));
    }
}
```

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

### Initialize TCP Client with Tokio

Source: https://docs.rs/hickory-client/latest/src/hickory_client/lib.rs.html

Establish a TCP connection to a DNS server and initialize the client handle using the Tokio runtime.

```rust
use std::net::Ipv4Addr;
use std::str::FromStr;
use tokio::net::TcpStream as TokioTcpStream;
use hickory_client::client::{Client, ClientHandle};
use hickory_client::proto::runtime::TokioRuntimeProvider;
use hickory_client::proto::rr::{DNSClass, Name, RData, RecordType};
use hickory_client::proto::rr::rdata::A;
use hickory_client::proto::tcp::TcpClientStream;

#[tokio::main]
async fn main() {
    // Since we used UDP in the previous examples, let's change things up a bit and use TCP here
    let (stream, sender) =
        TcpClientStream::new(([8, 8, 8, 8], 53).into(), None, None, TokioRuntimeProvider::new());

    // Create a new client, the bg is a background future which handles
    //   the multiplexing of the DNS requests to the server.
    //   the client is a handle to an unbounded queue for sending requests via the
    //   background. The background must be scheduled to run before the client can
    //   send any dns requests
    let client = Client::new(stream, sender, None);

    // await the connection to be established
    let (mut client, bg) = client.await.expect("connection failed");

    // make sure to run the background task
    tokio::spawn(bg);

    // Create a query future
    let query = client.query(
```

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

### build

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.AsyncSecureClientBuilder.html

Constructs the DnssecClient and the associated background exchange task.

```APIDOC
## pub async fn build(self) -> Result<(DnssecClient, DnsExchangeBackground<S, TokioTime>), ProtoError>

### Description
Finalizes the configuration and constructs the new DnssecClient along with its background exchange handler.

### Response
- **Result** (Tuple) - Returns a tuple containing the DnssecClient and DnsExchangeBackground on success, or a ProtoError on failure.
```

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

### Client Implementation and Initialization

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

The Client struct is initialized using either new or with_timeout, which require a stream, a stream handle, and an optional signer. The connect method is used to establish the exchange and return the client alongside a background task.

```rust
pub async fn new<F, S>(
        stream: F,
        stream_handle: BufDnsStreamHandle,
        signer: Option<Arc<dyn MessageFinalizer>>,
    ) -> Result<(Self, DnsExchangeBackground<DnsMultiplexer<S>, TokioTime>), ProtoError>
    where
        F: Future<Output = Result<S, ProtoError>> + Send + Unpin + 'static,
        S: DnsClientStream + 'static + Unpin,
    {
        Self::with_timeout(stream, stream_handle, Duration::from_secs(5), signer).await
    }
```

```rust
pub async fn with_timeout<F, S>(
        stream: F,
        stream_handle: BufDnsStreamHandle,
        timeout_duration: Duration,
        signer: Option<Arc<dyn MessageFinalizer>>,
    ) -> Result<(Self, DnsExchangeBackground<DnsMultiplexer<S>, TokioTime>), ProtoError>
    where
        F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
        S: DnsClientStream + 'static + Unpin,
    {
        let mp = DnsMultiplexer::with_timeout(stream, stream_handle, timeout_duration, signer);
        Self::connect(mp).await
    }
```

```rust
pub async fn connect<F, S>(
        connect_future: F,
    ) -> Result<(Self, DnsExchangeBackground<S, TokioTime>), ProtoError>
    where
        S: DnsRequestSender,
        F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
    {
        let result = DnsExchange::connect(connect_future).await;
        let use_edns = true;
        result.map(|(exchange, bg)| (Self { exchange, use_edns }, bg))
    }
```

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

### Client::new

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.Client.html

Spawns a new Client Stream with a default timeout of 5 seconds.

```APIDOC
## pub async fn new<F, S>(stream: F, stream_handle: BufDnsStreamHandle, signer: Option<Arc<dyn MessageFinalizer>>) -> Result<(Self, DnsExchangeBackground<DnsMultiplexer<S>, TokioTime>), ProtoError>

### Description
Spawns a new Client Stream. This uses a default timeout of 5 seconds for all requests.

### Parameters
- **stream** (F) - A stream of bytes that can be used to send/receive DNS messages.
- **stream_handle** (BufDnsStreamHandle) - The handle for the stream on which bytes can be sent/received.
- **signer** (Option<Arc<dyn MessageFinalizer>>) - An optional signer for requests, needed for Updates with Sig0.
```

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

### DnssecClient Connect Method

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.DnssecClient.html

Establishes a connection to return a DNSSEC-verifying client using the default TrustAnchor.

```rust
pub async fn connect<F, S>( connect_future: F, ) -> Result<(Self, DnsExchangeBackground<S, TokioTime>), ProtoError>
where S: DnsRequestSender, F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
```

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

### Client::with_timeout

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Initializes a new DNS client with a custom request timeout.

```APIDOC
## Client::with_timeout

### Description
Spawns a new Client Stream with a specified timeout duration for requests.

### Arguments
- **stream** (Future) - A stream of bytes that can be used to send/receive DNS messages.
- **stream_handle** (BufDnsStreamHandle) - The handle for the stream on which bytes can be sent/received.
- **timeout_duration** (Duration) - The time to wait for a response before canceling the request.
- **signer** (Option<Arc<dyn MessageFinalizer>>) - An optional signer for requests.
```

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

### DnssecClient::connect

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/dnssec_client.rs.html

Establishes a connection and returns a new DnssecClient instance with default trust anchors.

```APIDOC
## DnssecClient::connect

### Description
Returns a DNSSEC verifying client with the default TrustAnchor.

### Signature
`pub async fn connect<F, S>(connect_future: F) -> Result<(Self, DnsExchangeBackground<S, TokioTime>), ProtoError>`

### Parameters
- **connect_future** (Future) - A future that resolves to a DnsRequestSender.
```

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

### Helper functions for DNS record generation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Utility functions to create SOA and A records for testing purposes.

```rust
fn soa_record(serial: u32) -> Record {
    let soa = RData::SOA(SOA::new(
        Name::from_ascii("example.com.").unwrap(),
        Name::from_ascii("admin.example.com.").unwrap(),
        serial,
        60,
        60,
        60,
        60,
    ));
    Record::from_rdata(Name::from_ascii("example.com.").unwrap(), 600, soa)
}

fn a_record(ip: u8) -> Record {
    let a = RData::A(A::new(0, 0, 0, ip));
    Record::from_rdata(Name::from_ascii("www.example.com.").unwrap(), 600, a)
}
```

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

### version()

Source: https://docs.rs/hickory-client/latest/hickory_client/fn.version.html

Returns the version string of the hickory_client crate as specified in Cargo.toml.

```APIDOC
## Function: version()

### Description
Returns the version of the crate as specified in Cargo.toml.

### Signature
`pub fn version() -> &'static str`

### Returns
- **&'static str** - The version string of the crate.
```

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

### Initialize and test MemoizeClientHandle

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/memoize_client_handle.rs.html

Initializes a MemoizeClientHandle with a test client and verifies that subsequent identical queries return the same cached response ID.

```rust
use futures::executor::block_on;

subscribe();

let client = MemoizeClientHandle::new(TestClient {
    i: Arc::new(Mutex::new(0)),
});

let mut test1 = Message::new();
test1.add_query(Query::new().set_query_type(RecordType::A).clone());

let mut test2 = Message::new();
test2.add_query(Query::new().set_query_type(RecordType::AAAA).clone());

let result = block_on(client.send(test1.clone()).first_answer())
    .ok()
    .unwrap();
assert_eq!(result.id(), 0);

let result = block_on(client.send(test2.clone()).first_answer())
    .ok()
    .unwrap();
assert_eq!(result.id(), 1);

// should get the same result for each...
let result = block_on(client.send(test1).first_answer()).ok().unwrap();
assert_eq!(result.id(), 0);

let result = block_on(client.send(test2).first_answer()).ok().unwrap();
assert_eq!(result.id(), 1);
}
}
```

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

### version()

Source: https://docs.rs/hickory-client/latest/src/hickory_client/lib.rs.html

Returns the current version of the library as specified in Cargo.toml.

```APIDOC
### version()

#### Description
Returns the current version of the library as a string slice.

#### Signature
`pub fn version() -> &'static str`
```

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

### TestClient Implementation for Memoization

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/memoize_client_handle.rs.html

A mock client used for testing the memoization logic, tracking request IDs and simulating network responses.

```rust
94#[cfg(test)]
95mod test {
96    #![allow(clippy::dbg_macro, clippy::print_stdout)]
97
98    use std::pin::Pin;
99    use std::sync::Arc;
100
101    use futures::lock::Mutex;
102    use futures::*;
103    use hickory_proto::{
104        ProtoError,
105        op::{Message, Query},
106        rr::RecordType,
107        xfer::{DnsHandle, DnsRequest, DnsResponse},
108    };
109    use test_support::subscribe;
110
111    use crate::client::*;
112    use hickory_proto::xfer::FirstAnswer;
113
114    #[derive(Clone)]
115    struct TestClient {
116        i: Arc<Mutex<u16>>,
117    }
118
119    impl DnsHandle for TestClient {
120        type Response = Pin<Box<dyn Stream<Item = Result<DnsResponse, ProtoError>> + Send>>;
121
122        fn send<R: Into<DnsRequest> + Send + 'static>(&self, request: R) -> Self::Response {
123            let i = Arc::clone(&self.i);
124            let future = async {
125                let i = i;
126                let request = request;
127                let mut message = Message::new();
128
129                let mut i = i.lock().await;
130
131                message.set_id(*i);
132                println!(
133                    "sending {}: {}",
134                    *i,
135                    request.into().queries().first().expect("no query!").clone()
136                );
137
138                *i += 1;
139
140                Ok(DnsResponse::from_message(message).unwrap())
141            };
142
143            Box::pin(stream::once(future))
144        }
145    }
146
147    #[test]
148    fn test_memoized() {
```

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

### Client Streaming Response Implementation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

A wrapper for streaming DNS responses that maps protocol errors to client errors.

```rust
pub struct ClientStreamingResponse<R>(pub(crate) R)
where
    R: Stream<Item = Result<DnsResponse, ProtoError>> + Send + Unpin + 'static;

impl<R> Stream for ClientStreamingResponse<R>
where
    R: Stream<Item = Result<DnsResponse, ProtoError>> + Send + Unpin + 'static,
{
    type Item = Result<DnsResponse, ClientError>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        Poll::Ready(ready!(self.0.poll_next_unpin(cx)).map(|r| r.map_err(ClientError::from)))
    }
}
```

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

### Client::connect

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.Client.html

Returns a future that awaits a connection for the DNS client.

```APIDOC
## pub async fn connect<F, S>(connect_future: F) -> Result<(Self, DnsExchangeBackground<S, TokioTime>), ProtoError>

### Description
Returns a future, which itself wraps a future which is awaiting connection. The connect_future should be lazy.

### Returns
Returns a tuple of Self and a handle to send DNS messages, along with an optional background task that must be run on an executor.
```

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

### create

Source: https://docs.rs/hickory-client/latest/hickory_client/client/trait.ClientHandle.html

Sends a record to create on the server as per RFC 2136.

```APIDOC
## fn create<R>(&mut self, rrset: R, zone_origin: Name) -> ClientResponse

### Description
Sends a record to create on the server. This will fail if the record exists (atomicity depends on the server).

### Parameters
- **rrset** (R) - The record(s) to create
- **zone_origin** (Name) - The zone name to update, i.e. SOA name
```

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

### MemoizeClientHandle::new

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.MemoizeClientHandle.html

Creates a new instance of MemoizeClientHandle by wrapping an existing ClientHandle.

```APIDOC
## pub fn new(client: H) -> Self

### Description
Returns a new handle wrapping the specified client to enable memoization of DNS responses.

### Parameters
- **client** (H: ClientHandle) - Required - The underlying client handle to wrap.
```

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

### Implement DnsHandle for Client

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Provides the core DNS exchange functionality and EDNS status checking for the Client.

```rust
pub fn disable_edns(&mut self) {
        self.use_edns = false;
    }
}

impl DnsHandle for Client {
    type Response = DnsExchangeSend;

    fn send<R: Into<DnsRequest> + Unpin + Send + 'static>(&self, request: R) -> Self::Response {
        self.exchange.send(request)
    }

    fn is_using_edns(&self) -> bool {
        self.use_edns
    }
}
```

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

### MemoizeClientHandle Implementation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/memoize_client_handle.rs.html

The core structure and logic for memoizing DNS queries, including the inner_send method that manages the query cache.

```rust
1// Copyright 2015-2016 Benjamin Fry <benjaminfry@me.com>
2//
3// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
4// https://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// https://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7use std::collections::HashMap;
8use std::pin::Pin;
9use std::sync::Arc;
10
11use futures_util::future::FutureExt;
12use futures_util::lock::Mutex;
13use futures_util::stream::Stream;
14use hickory_proto::{
15    ProtoError,
16    op::Query,
17    xfer::{DnsHandle, DnsRequest, DnsResponse},
18};
19
20use crate::client::ClientHandle;
21use crate::client::rc_stream::{RcStream, rc_stream};
22
23// TODO: move to proto
24/// A ClientHandle for memoized (cached) responses to queries.
25///
26/// This wraps a ClientHandle, changing the implementation `send()` to store the response against
27///  the Message.Query that was sent. This should reduce network traffic especially during things
28///  like DNSSEC validation. *Warning* this will currently cache for the life of the Client.
29#[derive(Clone)]
30#[must_use = "queries can only be sent through a ClientHandle"]
31pub struct MemoizeClientHandle<H: ClientHandle> {
32    client: H,
33    active_queries: Arc<Mutex<HashMap<Query, RcStream<<H as DnsHandle>::Response>>>>,
34}
35
36impl<H> MemoizeClientHandle<H>
37where
38    H: ClientHandle,
39{
40    /// Returns a new handle wrapping the specified client
41    pub fn new(client: H) -> Self {
42        Self {
43            client,
44            active_queries: Arc::new(Mutex::new(HashMap::new())),
45        }
46    }
47
48    async fn inner_send(
49        request: DnsRequest,
50        active_queries: Arc<Mutex<HashMap<Query, RcStream<<H as DnsHandle>::Response>>>>,
51        client: H,
52    ) -> impl Stream<Item = Result<DnsResponse, ProtoError>> {
53        // TODO: what if we want to support multiple queries (non-standard)?
54        let query = request.queries().first().expect("no query!").clone();
55
56        // lock all the currently running queries
57        let mut active_queries = active_queries.lock().await;
58
59        // TODO: we need to consider TTL on the records here at some point
60        // If the query is running, grab that existing one...
61        if let Some(rc_stream) = active_queries.get(&query) {
62            return rc_stream.clone();
63        };
64
65        // Otherwise issue a new query and store in the map
66        active_queries
67            .entry(query)
68            .or_insert_with(|| rc_stream(client.send(request)))
69            .clone()
70    }
71}
72
73impl<H> DnsHandle for MemoizeClientHandle<H>
74where
75    H: ClientHandle,
76{
77    type Response = Pin<Box<dyn Stream<Item = Result<DnsResponse, ProtoError>> + Send>>;
78
79    fn send<R: Into<DnsRequest>>(&self, request: R) -> Self::Response {
80        let request = request.into();
81
82        Box::pin(
83            Self::inner_send(
84                request,
85                Arc::clone(&self.active_queries),
86                self.client.clone(),
87            )
88            .flatten_stream(),
89        )
90    }
91}
```

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

### Querying a DNS A record

Source: https://docs.rs/hickory-client/latest/src/hickory_client/lib.rs.html

Demonstrates performing a DNS query for an A record and validating the response data.

```rust
        Name::from_str("www.example.com.").unwrap(),
        DNSClass::IN,
        RecordType::A,
    );

    // wait for its response
    let response = query.await.unwrap();

    // validate it's what we expected
    if let RData::A(addr) = response.answers()[0].data() {
        assert_eq!(*addr, A::new(93, 184, 215, 14));
    }
}
```

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

### Create a new MemoizeClientHandle

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.MemoizeClientHandle.html

Constructor for creating a new handle that wraps an existing client.

```rust
pub fn new(client: H) -> Self
```

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

### create

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Sends a record to create on the server. This operation will fail if the record already exists.

```APIDOC
## Method: create

### Description
Sends a record to create on the server. This operation will fail if the record already exists, with atomicity depending on the server implementation.

### Arguments
- **rrset** (R: Into<RecordSet>) - The record(s) to create.
- **zone_origin** (Name) - The zone name to update (e.g., SOA name).

### Returns
- **ClientResponse** - A response object containing the result of the DNS update operation.
```

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

### AsyncSecureClientBuilder

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/dnssec_client.rs.html

A builder pattern for configuring and constructing a DnssecClient with custom trust anchors.

```APIDOC
## AsyncSecureClientBuilder

### Description
A builder to allow a custom trust anchor to be used for validating all signed records.

### Methods
- **trust_anchor(trust_anchor: TrustAnchors) -> Self**: Sets the trust anchor for the client.
- **build() -> Result<(DnssecClient, DnsExchangeBackground<S, TokioTime>), ProtoError>**: Constructs the new client.
```

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

### DnssecClient Builder Method

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.DnssecClient.html

Creates a builder for a DNSSEC-verifying client with a replaceable TrustAnchor.

```rust
pub fn builder<F, S>(connect_future: F) -> AsyncSecureClientBuilder<F, S>
where F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin, S: DnsRequestSender + 'static,
```

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

### DNS Create Record Operation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Sends a request to create a record on the server, failing if the record already exists.

```rust
fn create<R>(
        &mut self,
        rrset: R,
        zone_origin: Name,
    ) -> ClientResponse<<Self as DnsHandle>::Response>
    where
        R: Into<RecordSet>,
    {
        let rrset = rrset.into();
        let message = update_message::create(rrset, zone_origin, self.is_using_edns());

        ClientResponse(self.send(message))
    }
```

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

### Retrieve library version

Source: https://docs.rs/hickory-client/latest/src/hickory_client/lib.rs.html

Returns the current version of the library as defined in Cargo.toml.

```rust
pub fn version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}
```

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

### Retrieve crate version

Source: https://docs.rs/hickory-client/latest/hickory_client/fn.version.html

Returns the version string as specified in the project's Cargo.toml file.

```rust
pub fn version() -> &'static str
```

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

### DNS Notify Implementation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Constructs and sends a DNS NOTIFY message to a secondary server.

```rust
) -> ClientResponse<<Self as DnsHandle>::Response>
    where
        R: Into<RecordSet>,
    {
        debug!("notifying: {} {:?}", name, query_type);

        // build the message
        let mut message: Message = Message::new();
        let id: u16 = rand::random();
        message
            .set_id(id)
            // 3.3. NOTIFY is similar to QUERY in that it has a request message with
            // the header QR flag "clear" and a response message with QR "set".  The
            // response message contains no useful information, but its reception by
            // the Primary is an indication that the Secondary has received the NOTIFY
            // and that the Primary Zone Server can remove the Secondary from any retry queue for
            // this NOTIFY event.
            .set_message_type(MessageType::Query)
            .set_op_code(OpCode::Notify);

        // Extended dns
        if self.is_using_edns() {
            message
                .extensions_mut()
                .get_or_insert_with(Edns::new)
                .set_max_payload(update_message::MAX_PAYLOAD_LEN)
                .set_version(0);
        }

        // add the query
        let mut query: Query = Query::new();
        query
            .set_name(name)
            .set_query_class(query_class)
            .set_query_type(query_type);
        message.add_query(query);

        // add the notify message, see https://tools.ietf.org/html/rfc1996, section 3.7
        if let Some(rrset) = rrset {
            message.add_answers(rrset.into());
        }

        ClientResponse(self.send(message))
    }
```

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

### Add Dependency to Cargo.toml

Source: https://docs.rs/hickory-client/latest/hickory_client/index.html

Include the hickory-client crate in your project dependencies.

```toml
[dependencies]
hickory-client = "*"
```

```toml
[dependencies]
hickory-client = { version = "*", default-features = false }
```

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

### query

Source: https://docs.rs/hickory-client/latest/hickory_client/client/trait.ClientHandle.html

Performs a classic DNS query. Note that this does not recurse on PTR or CNAME record responses.

```APIDOC
## fn query(&mut self, name: Name, query_class: DNSClass, query_type: RecordType) -> ClientResponse

### Description
A classic DNS query. Note: This will not recurse on PTR or CNAME record responses; that is up to the caller.

### Parameters
- **name** (Name) - The label to lookup
- **query_class** (DNSClass) - Most likely this should always be DNSClass::IN
- **query_type** (RecordType) - Record type to lookup
```

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

### DnssecClient Implementation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/dnssec_client.rs.html

The core DnssecClient struct and its associated builder for managing DNSSEC-verified connections.

```rust
1// Copyright 2015-2019 Benjamin Fry <benjaminfry@me.com>
2//
3// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
4// https://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// https://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7
8use std::future::Future;
9use std::pin::Pin;
10use std::sync::Arc;
11
12use futures_util::stream::Stream;
13
14use crate::client::Client;
15use crate::proto::ProtoError;
16use crate::proto::dnssec::DnssecDnsHandle;
17use crate::proto::dnssec::TrustAnchors;
18use crate::proto::runtime::TokioTime;
19use crate::proto::xfer::{
20    DnsExchangeBackground, DnsHandle, DnsRequest, DnsRequestSender, DnsResponse,
21};
22
23/// A DNSSEC Client implemented over futures-rs.
24///
25/// This Client is generic and capable of wrapping UDP, TCP, and other underlying DNS protocol
26///  implementations.
27pub struct DnssecClient {
28    client: DnssecDnsHandle<Client>,
29}
30
31impl DnssecClient {
32    /// Returns a DNSSEC verifying client with a TrustAnchor that can be replaced
33    pub fn builder<F, S>(connect_future: F) -> AsyncSecureClientBuilder<F, S>
34    where
35        F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
36        S: DnsRequestSender + 'static,
37    {
38        AsyncSecureClientBuilder {
39            connect_future,
40            trust_anchor: None,
41        }
42    }
43
44    /// Returns a DNSSEC verifying client with the default TrustAnchor
45    pub async fn connect<F, S>(
46        connect_future: F,
47    ) -> Result<(Self, DnsExchangeBackground<S, TokioTime>), ProtoError>
48    where
49        S: DnsRequestSender,
50        F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
51    {
52        Self::builder(connect_future).build().await
53    }
54
55    fn from_client(client: Client, trust_anchor: Arc<TrustAnchors>) -> Self {
56        Self {
57            client: DnssecDnsHandle::with_trust_anchor(client, trust_anchor),
58        }
59    }
60}
61
62impl Clone for DnssecClient {
63    fn clone(&self) -> Self {
64        Self {
65            client: self.client.clone(),
66        }
67    }
68}
69
70impl DnsHandle for DnssecClient {
71    type Response = Pin<Box<(dyn Stream<Item = Result<DnsResponse, ProtoError>> + Send + 'static)>>;
72
73    fn send<R: Into<DnsRequest> + Unpin + Send + 'static>(&self, request: R) -> Self::Response {
74        self.client.send(request)
75    }
76}
77
78/// A builder to allow a custom trust to be used for validating all signed records
79pub struct AsyncSecureClientBuilder<F, S>
80where
81    F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
82    S: DnsRequestSender + 'static,
83{
84    connect_future: F,
85    trust_anchor: Option<TrustAnchors>,
86}
87
88impl<F, S> AsyncSecureClientBuilder<F, S>
89where
90    F: Future<Output = Result<S, ProtoError>> + 'static + Send + Unpin,
91    S: DnsRequestSender + 'static,
92{
93    /// This variant allows for the trust_anchor to be replaced
94    ///
95    /// # Arguments
96    ///
97    /// * `trust_anchor` - the set of trusted DNSKEY public_keys, by default this only contains the
98    ///   root public_key.
99    pub fn trust_anchor(mut self, trust_anchor: TrustAnchors) -> Self {
100        self.trust_anchor = Some(trust_anchor);
101        self
102    }
103
104    /// Construct the new client
105    pub async fn build(
106        mut self,
107    ) -> Result<(DnssecClient, DnsExchangeBackground<S, TokioTime>), ProtoError> {
108        let trust_anchor = Arc::new(self.trust_anchor.take().unwrap_or_default());
109        let result = Client::connect(self.connect_future).await;
110
111        result.map(|(client, bg)| (DnssecClient::from_client(client, trust_anchor), bg))
112    }
113}
```

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

### ClientHandle Blanket Implementation Methods

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.Client.html

Methods provided by the ClientHandle trait for DNS record management and zone transfers.

```rust
fn query( &mut self, name: Name, query_class: DNSClass, query_type: RecordType, ) -> ClientResponse<<Self as DnsHandle>::Response>
```

```rust
fn notify<R>( &mut self, name: Name, query_class: DNSClass, query_type: RecordType, rrset: Option<R>, ) -> ClientResponse<<Self as DnsHandle>::Response>
where R: Into<RecordSet>,
```

```rust
fn create<R>( &mut self, rrset: R, zone_origin: Name, ) -> ClientResponse<<Self as DnsHandle>::Response>
where R: Into<RecordSet>,
```

```rust
fn append<R>( &mut self, rrset: R, zone_origin: Name, must_exist: bool, ) -> ClientResponse<<Self as DnsHandle>::Response>
where R: Into<RecordSet>,
```

```rust
fn compare_and_swap<C, N>( &mut self, current: C, new: N, zone_origin: Name, ) -> ClientResponse<<Self as DnsHandle>::Response>
where C: Into<RecordSet>, N: Into<RecordSet>,
```

```rust
fn delete_by_rdata<R>( &mut self, rrset: R, zone_origin: Name, ) -> ClientResponse<<Self as DnsHandle>::Response>
where R: Into<RecordSet>,
```

```rust
fn delete_rrset( &mut self, record: Record, zone_origin: Name, ) -> ClientResponse<<Self as DnsHandle>::Response>
```

```rust
fn delete_all( &mut self, name_of_records: Name, zone_origin: Name, dns_class: DNSClass, ) -> ClientResponse<<Self as DnsHandle>::Response>
```

```rust
fn zone_transfer( &mut self, zone_origin: Name, last_soa: Option<SOA>, ) -> ClientStreamXfr<<Self as DnsHandle>::Response>
```

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

### Client Response Future Implementation

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

A future that resolves to a single DNS response, converting protocol errors to client errors.

```rust
pub struct ClientResponse<R>(pub(crate) R)
where
    R: Stream<Item = Result<DnsResponse, ProtoError>> + Send + Unpin + 'static;

impl<R> Future for ClientResponse<R>
where
    R: Stream<Item = Result<DnsResponse, ProtoError>> + Send + Unpin + 'static,
{
    type Output = Result<DnsResponse, ClientError>;

    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        Poll::Ready(
            match ready!(self.0.poll_next_unpin(cx)) {
                Some(r) => r,
                None => Err(ProtoError::from(ProtoErrorKind::Timeout)),
            }
            .map_err(ClientError::from),
        )
    }
}
```

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

### DnsHandle::lookup

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.MemoizeClientHandle.html

Performs a classic DNS query using the memoized handle.

```APIDOC
## fn lookup(&self, query: Query, options: DnsRequestOptions) -> Self::Response

### Description
Performs a classic DNS query, returning a cached response if available.

### Parameters
- **query** (Query) - Required - The DNS query to perform.
- **options** (DnsRequestOptions) - Required - Options for the DNS request.
```

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

### DnsHandle Trait Implementation for Client

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.Client.html

Core methods for performing DNS operations and checking handle status.

```rust
type Response = DnsExchangeSend
```

```rust
fn send<R: Into<DnsRequest> + Unpin + Send + 'static>( &self, request: R, ) -> Self::Response
```

```rust
fn is_using_edns(&self) -> bool
```

```rust
fn is_verifying_dnssec(&self) -> bool
```

```rust
fn lookup(&self, query: Query, options: DnsRequestOptions) -> Self::Response
```

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

### Process Zone Transfer State Transitions

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Handles the logic for AXFR and IXFR state transitions based on DNS answers.

```rust
                maybe_incr,
                expected_serial,
            } => {
                if let Some(serial) = get_serial(&answers[0]) {
                    // maybe IXFR, or empty AXFR
                    if serial == expected_serial {
                        // empty AXFR
                        *self = Ended;
                        if answers.len() == 1 {
                            Ok(())
                        } else {
                            // invalid answer : trailing records
                            Err(ClientErrorKind::Message(
                                "invalid zone transfer, contains trailing records",
                            )
                            .into())
                        }
                    } else if maybe_incr {
                        *self = Ixfr {
                            inner,
                            expected_serial,
                            even: true,
                        };
                        self.process(&answers[1..])
                    } else {
                        *self = Ended;
                        Err(ClientErrorKind::Message(
                            "invalid zone transfer, expected AXFR, got IXFR",
                        )
                        .into())
                    }
                } else {
                    // standard AXFR
                    *self = Axfr {
                        inner,
                        expected_serial,
                    };
                    self.process(&answers[1..])
                }
            }
            Axfr {
                inner,
                expected_serial,
            } => {
                let soa_count = answers
                    .iter()
                    .filter(|a| a.record_type() == RecordType::SOA)
                    .count();
                match soa_count {
                    0 => {
                        *self = Axfr {
                            inner,
                            expected_serial,
                        };
                        Ok(())
                    }
                    1 => {
                        *self = Ended;
                        match answers.last().map(|r| r.record_type()) {
                            Some(RecordType::SOA) => Ok(()),
                            _ => Err(ClientErrorKind::Message(
                                "invalid zone transfer, contains trailing records",
                            )
                            .into()),
                        }
                    }
                    _ => {
                        *self = Ended;
                        Err(ClientErrorKind::Message(
                            "invalid zone transfer, contains trailing records",
                        )
                        .into())
                    }
                }
            }
            Ixfr {
                inner,
                even,
                expected_serial,
            } => {
                let even = answers
                    .iter()
                    .fold(even, |even, a| even ^ (a.record_type() == RecordType::SOA));
                if even {
                    if let Some(serial) = get_serial(answers.last().unwrap()) {
                        if serial == expected_serial {
                            *self = Ended;
                            return Ok(());
                        }
                    }
                }
                *self = Ixfr {
                    inner,
                    even,
                    expected_serial,
                };
                Ok(())
            }
            Ended | Invalid => {
                unreachable!();
            }
        }
    }
}
```

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

### DnssecClient::lookup

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.DnssecClient.html

Performs a classic DNS query.

```APIDOC
## fn lookup(&self, query: Query, options: DnsRequestOptions) -> Self::Response

### Description
Executes a standard DNS lookup query using the provided options.

### Parameters
- **query** (Query) - The DNS query to perform.
- **options** (DnsRequestOptions) - Configuration options for the request.
```

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

### Stream testcase generator

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Creates a stream of DNS responses from a vector of record vectors.

```rust
fn get_stream_testcase(
    records: Vec<Vec<Record>>,
) -> impl Stream<Item = Result<DnsResponse, ProtoError>> + Send + Unpin + 'static {
    let stream = records.into_iter().map(|r| {
        Ok({
            let mut m = Message::new();
            m.insert_answers(r);
            DnsResponse::from_message(m).unwrap()
        })
    });
    iter(stream)
}
```

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

### DnssecClient::builder

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.DnssecClient.html

Creates a builder for a DNSSEC verifying client with a configurable TrustAnchor.

```APIDOC
## pub fn builder<F, S>(connect_future: F) -> AsyncSecureClientBuilder<F, S>

### Description
Returns a DNSSEC verifying client builder that allows for a replaceable TrustAnchor.

### Parameters
- **connect_future** (F) - A future that resolves to a DnsRequestSender.
```

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

### Clone Trait Implementation for Client

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.Client.html

Methods for duplicating the Client instance.

```rust
fn clone(&self) -> Client
```

```rust
fn clone_from(&mut self, source: &Self)
```

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

### DnssecClient Definition

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.DnssecClient.html

The internal structure definition for DnssecClient.

```rust
pub struct DnssecClient { /* private fields */ }
```

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

### Client::with_timeout

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.Client.html

Spawns a new Client Stream with a custom timeout duration.

```APIDOC
## pub async fn with_timeout<F, S>(stream: F, stream_handle: BufDnsStreamHandle, timeout_duration: Duration, signer: Option<Arc<dyn MessageFinalizer>>) -> Result<(Self, DnsExchangeBackground<DnsMultiplexer<S>, TokioTime>), ProtoError>

### Description
Spawns a new Client Stream with a specified timeout duration for requests.

### Parameters
- **stream** (F) - A stream of bytes that can be used to send/receive DNS messages.
- **stream_handle** (BufDnsStreamHandle) - The handle for the stream on which bytes can be sent/received.
- **timeout_duration** (Duration) - The time to wait for a response before canceling the request.
- **signer** (Option<Arc<dyn MessageFinalizer>>) - An optional signer for requests.
```

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

### trust_anchor

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.AsyncSecureClientBuilder.html

Configures the trust anchor for the builder, allowing the replacement of the default root public key with a custom set of trusted DNSKEY public keys.

```APIDOC
## pub fn trust_anchor(self, trust_anchor: TrustAnchors) -> Self

### Description
Replaces the default trust anchor with a custom set of trusted DNSKEY public keys.

### Parameters
- **trust_anchor** (TrustAnchors) - Required - The set of trusted DNSKEY public keys.
```

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

### DnsHandle::send

Source: https://docs.rs/hickory-client/latest/hickory_client/client/struct.MemoizeClientHandle.html

Sends a DNS request through the memoized client handle.

```APIDOC
## fn send<R: Into<DnsRequest>>(&self, request: R) -> Self::Response

### Description
Sends a message via the channel in the client, utilizing the cache if the query has been previously resolved.

### Parameters
- **request** (R: Into<DnsRequest>) - Required - The DNS request to be sent.
```

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

### Implement Stream for ClientStreamXfr

Source: https://docs.rs/hickory-client/latest/src/hickory_client/client/client.rs.html

Polls the underlying stream and processes DNS responses through the state machine.

```rust
impl<R> Stream for ClientStreamXfr<R>
where
    R: Stream<Item = Result<DnsResponse, ProtoError>> + Send + Unpin + 'static,
{
    type Item = Result<DnsResponse, ClientError>;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        use ClientStreamXfrState::*;

        if matches!(self.state, Ended) {
            return Poll::Ready(None);
        }

        let message = ready!(self.state.inner().poll_next_unpin(cx)).map(|response| {
            let ok = response?;
            self.state.process(ok.answers())?;
            Ok(ok)
        });
        Poll::Ready(message)
    }
}
```

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

### ClientHandle Trait Methods

Source: https://docs.rs/hickory-client/latest/hickory_client/client/trait.ClientHandle.html

The ClientHandle trait provides methods for performing DNS queries and managing DNS records.

```APIDOC
## ClientHandle Methods

### query
Performs a DNS query for a specific name, class, and type.

### notify
Sends a DNS notify message.

### create
Creates a new record set in a zone.

### append
Appends records to an existing record set.

### compare_and_swap
Performs an atomic compare-and-swap operation on a record set.

### delete_by_rdata
Deletes records matching specific RData.

### delete_rrset
Deletes an entire record set.

### delete_all
Deletes all records for a given name in a zone.

### zone_transfer
Initiates a zone transfer (AXFR/IXFR).
```

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

### compare_and_swap

Source: https://docs.rs/hickory-client/latest/hickory_client/client/trait.ClientHandle.html

Compares an existing RRset with a provided current value and, if it matches, swaps it for a new value.

```APIDOC
## fn compare_and_swap<C, N>( &mut self, current: C, new: N, zone_origin: Name, ) -> ClientResponse<<Self as DnsHandle>::Response>

### Description
Compares the current RRset and, if it matches, swaps it for the new value. Atomicity depends on the server.

### Arguments
- **current** (C: Into<RecordSet>) - The current RRset which must exist for the swap to complete.
- **new** (N: Into<RecordSet>) - The new RRset with which to replace the current RRset.
- **zone_origin** (Name) - The zone name to update, i.e. SOA name.
```
Tokens:
Raw