Hickory DNS Protocol

https://docs.rs/hickory-proto/latest/
Admin
Hickory DNS Protocol is a Rust library providing DNS protocol implementations with support for...
Tokens:973,113
Snippets:8,854
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### SOA Test Setup

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/soa.rs.html?search=std%3A%3Avec

Initial setup for testing SOA record functionality.

```rust
@test
fn test() {
    use core::str::FromStr;

    let rdata = SOA::new(
        Name::from_str("m.example.com.").unwrap(),
```

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

### TSIG Test Setup Helper

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/tsig.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Centralizes common setup code for TSIG rejection tests.

```rust
    fn get_message_and_signer() -> (Message, TSigner) {
        let time_begin = 1609459200u64;
        let fudge = 300u64;
        let origin: Name = Name::parse("example.com.", None).unwrap();
        let key_name: Name = Name::from_ascii("key_name.").unwrap();
        let mut question = Message::query();
```

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

### Example Searches

Source: https://docs.rs/hickory-proto/latest/hickory_proto/dnssec/type.DnsSecResult.html?search=

Common search patterns for the documentation tool.

```text
  * std::vec
  * u32 -> bool
  * Option<T>, (T -> U) -> Option<U>
```

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

### SOA Test Initialization

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/soa.rs.html?search=

Example of initializing an SOA record for testing purposes.

```rust
let rdata = SOA::new(
    Name::from_str("m.example.com.").unwrap(),
```

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

### SSHFP Presentation Format Example

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/sshfp/struct.SSHFP.html

Example of the SSHFP resource record presentation format as defined in RFC 4255.

```text
   host.example.  SSHFP 2 1 123456789abcdef67890123456789abcdef67890
```

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

### MX Record Configuration Examples

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/mx/struct.MX.html?search=

Examples of MX record syntax as defined in RFC 1033 for mail delivery routing.

```text
  MX (Mail Exchanger)  (See RFC-974 for more details.)

          <name>   [<ttl>] [<class>]   MX   <preference>   <host>

  MX records specify where mail for a domain name should be delivered.
  There may be multiple MX records for a particular name.  The
  preference value specifies the order a mailer should try multiple MX
  records when delivering mail.  Zero is the highest preference.
  Multiple records for the same name may have the same preference.

  A host BAR.FOO.COM may want its mail to be delivered to the host
  PO.FOO.COM and would then use the MX record:

          BAR.FOO.COM.    MX      10      PO.FOO.COM.

  A host BAZ.FOO.COM may want its mail to be delivered to one of three
  different machines, in the following order:

          BAZ.FOO.COM.    MX      10      PO1.FOO.COM.
                          MX      20      PO2.FOO.COM.
                          MX      30      PO3.FOO.COM.

  An entire domain of hosts not connected to the Internet may want
  their mail to go through a mail gateway that knows how to deliver
  mail to them.  If they would like mail addressed to any host in the
  domain FOO.COM to go through the mail gateway they might use:

          FOO.COM.        MX       10     RELAY.CS.NET.
          *.FOO.COM.      MX       20     RELAY.CS.NET.

  Note that you can specify a wildcard in the MX record to match on
  anything in FOO.COM, but that it won't match a plain FOO.COM.
```

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

### Example Search Queries

Source: https://docs.rs/hickory-proto/latest/hickory_proto/dnssec/enum.DnsSecError.html?search=

Common search patterns used for navigating Rust documentation.

```text
std::vec
u32 -> bool
Option<T>, (T -> U) -> Option<U>
```

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

### DNSKEY RR Presentation Format Example

Source: https://docs.rs/hickory-proto/latest/hickory_proto/dnssec/rdata/dnskey/struct.DNSKEY.html

Example of a DNSKEY resource record in presentation format as defined by RFC 4034.

```text
example.com. 86400 IN DNSKEY 256 3 5 ( AQPSKmynfzW4kyBv015MUG2DeIQ3
                                          Cbl+BBZH4b/0PY1kxkmvHjcZc8no
                                          kfzj31GajIQKY+5CptLr3buXA10h
                                          WqTkF7H6RfoRqXQeogmMHfpftf6z
                                          Mv1LyBUgia7za6ZEzOJBOztyvhjL
                                          742iU/TpPSEDhm2SNKLijfUppn1U
                                          aNvv4w==  )
```

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

### Usage Examples for parse_ttl

Source: https://docs.rs/hickory-proto/latest/hickory_proto/serialize/txt/fn.parse_ttl.html?search=

Examples demonstrating how to parse various TTL string formats including units like seconds, minutes, hours, days, and weeks.

```rust
use hickory_proto::serialize::txt::parse_ttl;

assert_eq!(parse_ttl("0").unwrap(),  0);
assert!(parse_ttl("s").is_err());
assert!(parse_ttl("").is_err());
assert_eq!(parse_ttl("0s").unwrap(), 0);
assert_eq!(parse_ttl("1").unwrap(),  1);
assert_eq!(parse_ttl("1S").unwrap(), 1);
assert_eq!(parse_ttl("1s").unwrap(), 1);
assert_eq!(parse_ttl("1M").unwrap(), 60);
assert_eq!(parse_ttl("1m").unwrap(), 60);
assert_eq!(parse_ttl("1H").unwrap(), 3600);
assert_eq!(parse_ttl("1h").unwrap(), 3600);
assert_eq!(parse_ttl("1D").unwrap(), 86400);
assert_eq!(parse_ttl("1d").unwrap(), 86400);
assert_eq!(parse_ttl("1W").unwrap(), 604800);
assert_eq!(parse_ttl("1w").unwrap(), 604800);
assert_eq!(parse_ttl("1s2d3w4h2m").unwrap(), 1+2*86400+3*604800+4*3600+2*60);
assert_eq!(parse_ttl("3w3w").unwrap(), 3*604800+3*604800);
assert!(parse_ttl("7102w").is_err());
```

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

### Get Slice from Specific Position

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/binary/decoder.rs.html

Retrieves a slice of data from the binary decoder starting from a given offset. This is useful for accessing data without consuming it from the decoder's current position. An error occurs if the offset is out of bounds.

```rust
let deadbeef = b"deadbeef";
let mut decoder = BinDecoder::new(deadbeef);

decoder.read_slice(4).expect("failed to read dead");
let read = decoder.slice_from(0).expect("failed to get slice");
assert_eq!(&read, b"dead");

decoder.read_slice(2).expect("failed to read be");
let read = decoder.slice_from(4).expect("failed to get slice");
assert_eq!(&read, b"be");

decoder.read_slice(0).expect("failed to read nothing");
let read = decoder.slice_from(4).expect("failed to get slice");
assert_eq!(&read, b"be");

// this should fail
assert!(decoder.slice_from(10).is_err());
```

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

### Initialize and Compare OPT Options

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/opt.rs.html?search=u32+-%3E+bool

Demonstrates creating OPT instances with unknown EDNS options and verifying equality and hash consistency.

```rust
        // Leading byte changed in the vec
        let options_3 = OPT::new(vec![
            (
                EdnsCode::Unknown(15u16),
                EdnsOption::Unknown(
                    15u16,
                    vec![
                        0xff, 0x09, 0x55, 0x6E, 0x6B, 0x6E, 0x6F, 0x77, 0x6E, 0x20, 0x65, 0x72,
                        0x72, 0x6F, 0x72,
                    ],
                ),
            ),
            (
                EdnsCode::Unknown(15u16),
                EdnsOption::Unknown(15u16, vec![0x00, 0x06]),
            ),
        ]);

        let mut hasher_1 = DefaultHasher::new();
        options_1.hash(&mut hasher_1);
        let hash_1 = hasher_1.finish();

        let mut hasher_2 = DefaultHasher::new();
        options_2.hash(&mut hasher_2);
        let hash_2 = hasher_2.finish();

        let mut hasher_3 = DefaultHasher::new();
        options_3.hash(&mut hasher_3);
        let hash_3 = hasher_3.finish();

        assert_eq!(options_1, options_2);
        assert_eq!(hash_1, hash_2);

        assert!(options_1 != options_3);
        assert!(hash_1 != hash_3);
    }
}
```

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

### Initialize DnssecSigner and Calculate Key Tag

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/dnssec/signer.rs.html?search=

Demonstrates creating a DnssecSigner instance from an RSA signing key and calculating the associated key tag.

```rust
        let pub_key = key.to_public_key().unwrap();
        let dnskey = DNSKEY::from_key(&pub_key);
        let signer = DnssecSigner::new(
            dnskey,
            Box::new(key),
            Name::root(),
            Duration::from_secs(300),
        );
        let key_tag = signer.calculate_key_tag().unwrap();

        assert_eq!(key_tag, 3257);
    }
```

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

### HINFO Record Format Example

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/hinfo/struct.HINFO.html

Example of HINFO record format as described in RFC 1033.

```text
HINFO (Host Info)

           <host>   [<ttl>] [<class>]   HINFO   <hardware>   <software>

   The HINFO record gives information about a particular host.  The data
   is two strings separated by whitespace.  The first string is a
   hardware description and the second is software.  The hardware is
   usually a manufacturer name followed by a dash and model designation.
   The software string is usually the name of the operating system.

   Official HINFO types can be found in the latest Assigned Numbers RFC,
   the latest of which is RFC-1010.  The Hardware type is called the
   Machine name and the Software type is called the System name.

   Some sample HINFO records:

           SRI-NIC.ARPA.           HINFO   DEC-2060 TOPS20
           UCBARPA.Berkeley.EDU.   HINFO   VAX-11/780 UNIX
```

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

### Create and Initialize DnssecSigner

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/dnssec/signer.rs.html

Demonstrates the creation of a DnssecSigner instance with a private key and root name.

```rust
let key = RsaSigningKey::from_pkcs8(&PrivatePkcs8KeyDer::from(RSA_KEY), Algorithm::RSASHA256).unwrap();
let pub_key = key.to_public_key().unwrap();
let dnskey = DNSKEY::from_key(&pub_key);
let signer = DnssecSigner::new(
    dnskey,
    Box::new(key),
    Name::root(),
    Duration::from_secs(300),
);
```

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

### ZoneUsage::example

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/domain/usage.rs.html

Creates a ZoneUsage configuration for the .example. zone, applying default restrictions suitable for documentation and examples.

```APIDOC
## ZoneUsage::example

### Description
Creates a ZoneUsage configuration for the .example. zone, applying default restrictions suitable for documentation and examples.

### Signature
```rust
pub fn example(name: Name) -> Self
```

### Parameters
* **name**: Name - The name of the .example. zone.
```

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

### SVCB Record Examples

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/svcb/struct.SVCB.html

Examples of SVCB and HTTPS resource record formats as defined in RFC 9460.

```text
simple.example. 7200 IN HTTPS 1 . alpn=h3
pool  7200 IN HTTPS 1 h3pool alpn=h2,h3 ech="123..."
              HTTPS 2 .      alpn=h2 ech="abc..."
@     7200 IN HTTPS 0 www
_8765._baz.api.example.com. 7200 IN SVCB 0 svc4-baz.example.net.
```

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

### TLSA Record Presentation Format Examples

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/tlsa.rs.html?search=

Examples of TLSA record presentation formats as defined in RFC 6698.

```text
_443._tcp.www.example.com. IN TLSA (
   0 0 1 d2abde240d7cd3ee6b4b28c54df034b9
         7983a1d16e8a410e4561cb106618e971 )
```

```text
_443._tcp.www.example.com. IN TLSA (
   1 1 2 92003ba34942dc74152e2f2c408d29ec
         a5a520e7f2e06bb944f4dca346baf63c
         1b177615d466f6c4b71c216a50292bd5
         8c9ebdd2f74e38fe51ffd48c43326cbc )
```

```text
_443._tcp.www.example.com. IN TLSA (
   3 0 0 30820307308201efa003020102020... )
```

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

### TXT Record Creation and Binary Encoding/Decoding

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/txt.rs.html

Shows how to create a TXT record from string data, encode it into a binary format using BinEncoder, and then decode it back into a TXT record using BinDecoder. Asserts that the decoded record matches the original.

```rust
let rdata = TXT::new(vec!["Test me some".to_string(), "more please".to_string()]);

let mut bytes = Vec::new();
let mut encoder: BinEncoder<'_> = BinEncoder::new(&mut bytes);
assert!(rdata.emit(&mut encoder).is_ok());
let bytes = encoder.into_bytes();

#[cfg(feature = "std")]
println!("bytes: {:?}", bytes);

let mut decoder: BinDecoder<'_> = BinDecoder::new(bytes);
let restrict = Restrict::new(bytes.len() as u16);
let read_rdata = TXT::read_data(&mut decoder, restrict).expect("Decoding error");
assert_eq!(rdata, read_rdata);
```

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

### Iterating Through All Supported Algorithms

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/dnssec/supported_algorithm.rs.html

Shows how to iterate through all available DNSSEC algorithms using `SupportedAlgorithms::all()` and verify the count and order of algorithms returned by the iterator. Also demonstrates iterating over a custom set of algorithms.

```rust
let supported = SupportedAlgorithms::all();
assert_eq!(supported.iter().count(), 7);

// it just so happens that the iterator has a fixed order...
let supported = SupportedAlgorithms::all();
let mut iter = supported.iter();
assert_eq!(iter.next(), Some(Algorithm::RSASHA1));
assert_eq!(iter.next(), Some(Algorithm::RSASHA256));
assert_eq!(iter.next(), Some(Algorithm::RSASHA1NSEC3SHA1));
assert_eq!(iter.next(), Some(Algorithm::RSASHA512));
assert_eq!(iter.next(), Some(Algorithm::ECDSAP256SHA256));
assert_eq!(iter.next(), Some(Algorithm::ECDSAP384SHA384));
assert_eq!(iter.next(), Some(Algorithm::ED25519));

let mut supported = SupportedAlgorithms::new();
supported.set(Algorithm::RSASHA256);
supported.set(Algorithm::RSASHA512);

let mut iter = supported.iter();
assert_eq!(iter.next(), Some(Algorithm::RSASHA256));
assert_eq!(iter.next(), Some(Algorithm::RSASHA512));
```

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

### mDNS Unicast Response Bit Test Setup

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/op/query.rs.html?search=std%3A%3Avec

Test setup for verifying mDNS unicast response bit handling.

```rust
#[cfg(feature = "mdns")]
#[test]
fn test_mdns_unicast_response_bit_handling() {
    const QCLASS_OFFSET: usize = 1 /* empty name */ +
        size_of::<u16>() /* query_type */;

    let mut query = Query::new();
    query.set_mdns_unicast_response(true);
```

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

### DS RR Presentation Format Example

Source: https://docs.rs/hickory-proto/latest/hickory_proto/dnssec/rdata/ds/struct.DS.html

Example of a DNSKEY RR and its corresponding DS RR as defined in RFC 4034.

```text
dskey.example.com. 86400 IN DNSKEY 256 3 5 ( AQOeiiR0GOMYkDshWoSKz9Xz
                                             fwJr1AYtsmx3TGkJaNXVbfi/
                                             2pHm822aJ5iI9BMzNXxeYCmZ
                                             DRD99WYwYqUSdjMmmAphXdvx
                                             egXd/M5+X7OrzKBaMbCVdFLU
                                             Uh6DhweJBjEVv5f2wwjM9Xzc
                                             nOf+EPbtG9DMBmADjFDc2w/r
                                             ljwvFw==
                                             ) ;  key id = 60485

   dskey.example.com. 86400 IN DS 60485 5 1 ( 2BB183AF5F22588179A53B0A
                                              98631FAD1A292118 )
```

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

### SVCB Zone File Presentation Format Example

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/svcb.rs.html

Illustrates how SVCB records are represented in a zone file, showing the service priority, target name, and service parameters like port.

```dns
example.com.      7200  IN HTTPS 0 svc.example.net.
svc.example.net.  7200  IN CNAME svc2.example.net.
svc2.example.net. 7200  IN HTTPS 1 . port=8002
svc2.example.net. 300   IN A     192.0.2.2
svc2.example.net. 300   IN AAAA  2001:db8::2
```

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

### Getting the Base Name of a LowerName

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/lower_name.rs.html

Trims the first label from a LowerName to get its base name. This is useful for hierarchical lookups.

```rust
pub fn base_name(&self) -> Self {
        Self(self.0.base_name())
    }
```

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

### Create and Validate OPENPGPKEY Records

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/openpgpkey.rs.html?search=

Demonstrates creating OPENPGPKEY instances from raw bytes and base64-encoded tokens.

```rust
                .map(|rd| rd == OPENPGPKEY::new(b"trust_dns is awesome".to_vec()))
                .unwrap_or(false)
        );
        assert!(
            OPENPGPKEY::from_tokens(vec!["c2VsZi1wcmFpc2Ugc3Rpbmtz"].into_iter())
                .map(|rd| rd == OPENPGPKEY::new(b"self-praise stinks".to_vec()))
                .unwrap_or(false)
        );
    }
}
```

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

### Canonical DNS Name Order Example

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/domain/struct.Name.html?search=

Example of names sorted in canonical DNS name order as defined by RFC 4034.

```text
           example
           a.example
           yljkjljk.a.example
           Z.a.example
           zABC.a.EXAMPLE
           z.example
           \001.z.example
           *.z.example
           \200.z.example
```

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

### Create DnsResponse from Message

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/op/dns_response.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates initializing a DnsResponse from a DNS message and verifying the presence of answers.

```rust
message.add_query(Query::query(Name::root(), RecordType::A));
        message.add_answer(Record::from_rdata(
            Name::root(),
            88640,
            RData::A(A::new(127, 0, 0, 2)),
        ));

        let response = DnsResponse::from_message(message.into_response()).unwrap();

        assert!(response.contains_answer())
```

```rust
let mut message = Message::query();
        message.metadata.response_code = ResponseCode::NoError;
        message.add_query(Query::query(an_example(), RecordType::SOA));
        message.add_authority(soa());

        let response = DnsResponse::from_message(message.into_response()).unwrap();

        assert!(response.contains_answer());
```

```rust
let mut message = Message::query();
        message.metadata.response_code = ResponseCode::NoError;
        message.add_query(Query::query(xx(), RecordType::ANY));
        message.add_authority(ns1_record());
        message.add_additional(ns1_a());

        let response = DnsResponse::from_message(message.into_response()).unwrap();

        assert!(response.contains_answer());
```

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

### NAPTR Master File Format Example

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/naptr/struct.NAPTR.html

Example of NAPTR records as they appear in a DNS master file, following RFC 2915 specifications.

```text
;;      order pflags service           regexp replacement
IN NAPTR 100  50  "a"    "z3950+N2L+N2C"     ""   cidserver.example.com.
IN NAPTR 100  50  "a"    "rcds+N2C"          ""   cidserver.example.com.
IN NAPTR 100  50  "s"    "http+N2L+N2C+N2R"  ""   www.example.com.
```

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

### DNS Header Encoding Example

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/op/header.rs.html

Demonstrates encoding a DNS header structure into a byte vector using BinEncoder. Verifies the output against an expected byte sequence.

```rust
let mut header = Header {
            id: 0x1234,
            flags: Flags {
                qr: false,
                opcode: OpCode::Query,
                aa: false,
                tc: false,
                rd: true,
                ra: false,
                z: 0,
                rcode: ResponseCode::NoError,
            },
            counts: HeaderCounts {
                queries: 0x0001,
                answers: 0x0000,
                authorities: 0x0000,
                additionals: 0x0000,
            },
        };

        let expect = vec![
            0x12, 0x34, 0x00, 0x00, // Flags: QR=0, OpCode=0, AA=0, TC=0, RD=1, RA=0, Z=0, RCODE=0
            0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        ];

        let mut bytes = Vec::with_capacity(512);
        {
            let mut encoder = BinEncoder::new(&mut bytes);
            header.emit(&mut encoder).unwrap();
        }

        assert_eq!(bytes, expect);
```

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

### store_label_pointer

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/binary/encoder.rs.html

Stores a pointer to a label that has already been written into the buffer. The location of this pointer is the current position in the buffer, and it refers to a label starting at the specified `start` index.

```APIDOC
## store_label_pointer

### Description
Records a reference to a previously encoded label within the buffer. This is used for name compression, allowing subsequent references to the same label to point back to its first occurrence.

### Method
`&mut self`

### Parameters
* `start` (usize) - The starting index of the label in the buffer.
* `end` (usize) - The ending index of the label in the buffer.
```

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

### OPENPGPKEY::new

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/openpgpkey/struct.OPENPGPKEY.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new instance of the OPENPGPKEY record data.

```APIDOC
## pub fn new(public_key: Vec<u8>) -> Self

### Description
Creates a new OPENPGPKEY record data instance.

### Parameters
- **public_key** (Vec<u8>) - Required - An OpenPGP Transferable Public Key.
```

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

### Get Records with or without RRSIGs

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rr_set.rs.html

Retrieves all records within an RRset. Use `records_with_rrsigs` to include DNSSEC RRSIG records if they exist, or `records_without_rrsigs` to get only the primary records.

```rust
pub fn records(&self, and_rrsigs: bool) -> RrsetRecords<'_> {
        if and_rrsigs {
            self.records_with_rrsigs()
        } else {
            self.records_without_rrsigs()
        }
    }
```

```rust
pub fn records_with_rrsigs(&self) -> RrsetRecords<'_> {
        if self.records.is_empty() {
            RrsetRecords::Empty
        } else {
            RrsetRecords::RecordsAndRrsigs(RecordsAndRrsigsIter(
                self.records.iter().chain(self.rrsigs.iter()),
            ))
        }
    }
```

```rust
pub fn records_without_rrsigs(&self) -> RrsetRecords<'_> {
        if self.records.is_empty() {
            RrsetRecords::Empty
        } else {
            RrsetRecords::RecordsOnly(self.records.iter())
        }
    }
```

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

### Name::new

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/domain/name.rs.html

Creates a new, empty domain name. This is the default constructor.

```APIDOC
## Name::new

### Description
Creates a new, empty domain name. This is the default constructor.

### Method
`Name::new()`

### Returns
A new `Name` instance.

### Example
```rust
use hickory_proto::rr::domain::Name;

let name = Name::new();
```
```

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

### Initialize and use Parser

Source: https://docs.rs/hickory-proto/latest/hickory_proto/serialize/txt/trust_anchor/struct.Parser.html?search=

Methods for creating a new parser instance and executing the parsing process.

```rust
pub fn new(input: impl Into<Cow<'a, str>>) -> Self
```

```rust
pub fn parse(self) -> ParseResult<Vec<Entry>>
```

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

### Get Iterator Size Hint

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/domain/name.rs.html

Illustrates how to use `size_hint()` on a domain name iterator to get an estimate of the number of remaining elements. Shows the hint before and after consuming one element.

```rust
fn test_size_hint() {
        let name = Name::from_ascii("www.example.com").unwrap();
        let mut iter = name.iter();

        assert_eq!(iter.size_hint().0, 3);
        assert_eq!(iter.next().unwrap(), b"www");
        assert_eq!(iter.size_hint().0, 2);
    }
```

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

### Store Label Pointer

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/binary/encoder.rs.html

Stores a pointer to a label within the buffer. The pointer consists of a start and end index. Asserts that indices are within u16::MAX and that start is less than or equal to end.

```rust
pub fn store_label_pointer(&mut self, start: usize, end: usize) {
        assert!(start <= (u16::MAX as usize));
        assert!(end <= (u16::MAX as usize));
        assert!(start <= end);
    }
```

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

### Creating and Checking a DNS Response with an Answer

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/op/dns_response.rs.html

Demonstrates how to construct a DNS message, add an A record as an answer, convert it to a DnsResponse, and assert that it contains an answer.

```rust
    #[test]
    fn contains_answer() {
        let mut message = Message::query();
        message.add_answer(Record::from_rdata(
            Name::root(),
            88640,
            RData::A(A::new(127, 0, 0, 2)),
        ));

        let response = DnsResponse::from_message(message.into_response()).unwrap();

        assert!(response.contains_answer())
    }
```

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

### Borrow Slice from Buffer

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/binary/encoder.rs.html

Returns a slice of the buffer from a start index to an end index. Asserts that the start index is less than the current offset and the end index is within the buffer's bounds.

```rust
pub fn slice_of(&self, start: usize, end: usize) -> &[u8] {
        assert!(start < self.offset);
        assert!(end <= self.buffer.len());
        &self.buffer.buffer()[start..end]
    }
```

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

### OPT::new

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/opt/struct.OPT.html?search=u32+-%3E+bool

Creates a new OPT record data instance.

```APIDOC
### pub fn new(options: Vec<(EdnsCode, EdnsOption)>) -> Self

Creates a new OPT record data.

#### Arguments
- **options** (Vec<(EdnsCode, EdnsOption)>) - List of code and record type tuples

#### Return value
- **Self** - The newly created OPT data
```

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

### TLSA RR Examples

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/tlsa.rs.html

Provides examples of TLSA RDATA for different certificate association scenarios, including hashed PKIX CA certificates and subject public keys, as well as full certificate associations.

```text
2.3.  TLSA RR Examples

    In the following examples, the domain name is formed using the rules
    in Section 3.

    An example of a hashed (SHA-256) association of a PKIX CA
    certificate:

    _443._tcp.www.example.com. IN TLSA (
       0 0 1 d2abde240d7cd3ee6b4b28c54df034b9
             7983a1d16e8a410e4561cb106618e971 )

    An example of a hashed (SHA-512) subject public key association of a
    PKIX end entity certificate:

    _443._tcp.www.example.com. IN TLSA (
       1 1 2 92003ba34942dc74152e2f2c408d29ec
             a5a520e7f2e06bb944f4dca346baf63c
             1b177615d466f6c4b71c216a50292bd5
             8c9ebdd2f74e38fe51ffd48c43326cbc )

    An example of a full certificate association of a PKIX end entity
    certificate:

    _443._tcp.www.example.com. IN TLSA (
       3 0 0 30820307308201efa003020102020... )
```

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

### ClientSubnet::new

Source: https://docs.rs/hickory-proto/latest/hickory_proto/rr/rdata/opt/struct.ClientSubnet.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructs a new ClientSubnet instance with the specified IP address, source prefix, and scope prefix.

```APIDOC
### pub fn new(address: IpAddr, source_prefix: u8, scope_prefix: u8) -> Self

Construct a new EcsOption with the address, source_prefix and scope_prefix.
```

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

### ClientSubnet Constructor

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/opt.rs.html

Provides a constructor function `new` for creating a `ClientSubnet` instance. It takes the IP address, source prefix length, and scope prefix length as arguments.

```rust
impl ClientSubnet {
    /// Construct a new EcsOption with the address, source_prefix and scope_prefix.
    pub fn new(address: IpAddr, source_prefix: u8, scope_prefix: u8) -> Self {
        Self {
            address,
            source_prefix,
            scope_prefix,
        }
    }
// ...
```

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

### CAA Issue Property Examples

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/caa.rs.html

Illustrates the usage of the CAA 'issue' property tag for restricting certificate issuance. Includes examples for specifying authorized issuers, forbidding all issuance, and handling malformed values.

```text
certs.example.com         CAA 0 issue "ca1.example.net"
certs.example.com         CAA 0 issue "ca2.example.org"
```

```text
nocerts.example.com       CAA 0 issue ";"
```

```text
malformed.example.com     CAA 0 issue "%%%%%"
```

```text
account.example.com   CAA 0 issue "ca1.example.net; account=230123"
```

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

### RFC 4034 NSEC Record Example

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/dnssec/rdata/nsec.rs.html

Implements and verifies an NSEC record based on the example provided in section 4.3 of RFC 4034. This snippet ensures correct encoding and decoding of a specific NSEC record structure with various record types.

```rust
use std::println;

use alloc::vec::Vec;

use super::*

#[test]
fn rfc4034_example_rdata() {
    // From section 4.3 of RFC 4034
    let bytes = b"\x04host\
        \x07example\
        \x03com\x00\
        \x00\x06\x40\x01\x00\x00\x00\x03\
        \x04\x1b\x00\x00\x00\x00\x00\x00\
        \x00\x00\x00\x00\x00\x00\x00\x00\
        \x00\x00\x00\x00\x00\x00\x00\x00\
        \x00\x00\x00\x00\x20";
    let rdata = NSEC::new(
        Name::parse("host.example.com.", None).unwrap(),
        [
            RecordType::A,
            RecordType::MX,
            RecordType::RRSIG,
            RecordType::NSEC,
            RecordType::Unknown(1234),
        ],
    );

    let mut buffer = Vec::new();
    let mut encoder = BinEncoder::new(&mut buffer);
    rdata.emit(&mut encoder).expect("Encoding error");
    assert_eq!(encoder.into_bytes(), bytes);

    let mut decoder = BinDecoder::new(bytes);
    let decoded = NSEC::read_data(&mut decoder, Restrict::new(bytes.len() as u16))
        .expect("Decoding error");
    assert_eq!(decoded, rdata);
}
```

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

### Compare Domain Names

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/domain/name.rs.html?search=

Demonstrates partial and full ordering comparisons between domain names.

```rust
    #[test]
    fn test_partial_cmp_eq() {
        let root = Some(Name::from_labels(Vec::<&str>::new()).unwrap());
        let comparisons: Vec<(Name, Name)> = vec![
            (root.clone().unwrap(), root.clone().unwrap()),
            (
                Name::parse("example.", root.as_ref()).unwrap(),
                Name::parse("example", root.as_ref()).unwrap(),
            ),
        ];

        for (left, right) in comparisons {
            #[cfg(feature = "std")]
            println!("left: {left}, right: {right}");
            assert_eq!(left.partial_cmp(&right), Some(Ordering::Equal));
        }
    }
```

```rust
    #[test]
    fn test_partial_cmp() {
        let comparisons: Vec<(Name, Name)> = vec![
            (
                Name::from_str("example.").unwrap(),
                Name::from_str("a.example.").unwrap(),
            ),
            (
                Name::from_str("a.example.").unwrap(),
                Name::from_str("yljkjljk.a.example.").unwrap(),
            ),
            (
                Name::from_str("yljkjljk.a.example.").unwrap(),
                Name::from_ascii("Z.a.example.").unwrap(),
            ),
            (
                Name::from_ascii("Z.a.example").unwrap(),
                Name::from_ascii("zABC.a.EXAMPLE.").unwrap(),
            ),
            (
                Name::from_ascii("zABC.a.EXAMPLE.").unwrap(),
                Name::from_str("z.example.").unwrap(),
            ),
            (
                Name::from_str("z.example").unwrap(),
                Name::from_labels(vec![&[1u8] as &[u8], b"z", b"example."]).unwrap(),
            ),
            (
                Name::from_labels(vec![&[1u8] as &[u8], b"z", b"example"]).unwrap(),
                Name::from_str("*.z.example.").unwrap(),
            ),
            (
                Name::from_str("*.z.example").unwrap(),
                Name::from_labels(vec![&[200u8] as &[u8], b"z", b"example."]).unwrap(),
            ),
        ];

        for (left, right) in comparisons {
            #[cfg(feature = "std")]
            println!("left: {left}, right: {right}");
            assert_eq!(left.cmp(&right), Ordering::Less);
        }
    }
```

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

### Initialize a new Parser

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/txt/zone.rs.html?search=

Creates a new Parser instance. The path argument is used to resolve relative $INCLUDE paths.

```rust
impl<'a> Parser<'a> {
    /// Returns a new Zone file parser
    ///
    /// The `path` argument's parent directory is used to resolve relative `$INCLUDE` paths.
    /// Relative `$INCLUDE` paths will yield an error if `path` is `None`.
    pub fn new(
        input: impl Into<Cow<'a, str>>,
        path: Option<PathBuf>,
        mut origin: Option<Name>,
    ) -> Self {
        if let Some(origin) = &mut origin {
            origin.set_fqdn(true);
        }
        Self {
            lexers: vec![(Lexer::new(input), path)],
            origin,
        }
    }
```

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

### OPENPGPKEY Constructor and Token Parsing

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/openpgpkey.rs.html?search=std%3A%3Avec

Methods to initialize a new record and parse it from string tokens, expecting a base64-encoded public key.

```rust
impl OPENPGPKEY {
    /// Creates a new OPENPGPKEY record data.
    ///
    /// # Arguments
    ///
    /// * `public_key` - an OpenPGP Transferable Public Key. This will NOT
    ///   be checked.
    pub fn new(public_key: Vec<u8>) -> Self {
        Self { public_key }
    }

    /// Parse the RData from a set of tokens.
    ///
    /// [RFC 7929](https://tools.ietf.org/html/rfc7929#section-2.3)
    ///
    /// ```text
    /// 2.3.  The OPENPGPKEY RDATA Presentation Format
    ///
    ///    The RDATA Presentation Format, as visible in Zone Files [RFC1035],
    ///    consists of a single OpenPGP Transferable Public Key as defined in
    ///    Section 11.1 of [RFC4880] encoded in base64 as defined in Section 4
    ///    of [RFC4648].
    /// ```
    pub(crate) fn from_tokens<'i, I: Iterator<Item = &'i str>>(
        mut tokens: I,
    ) -> Result<Self, ParseError> {
        let encoded_public_key = tokens.next().ok_or(ParseError::Message(
            "OPENPGPKEY public key field is missing",
        ))?;
        let public_key = data_encoding::BASE64.decode(encoded_public_key.as_bytes())?;
        Some(Self::new(public_key))
            .filter(|_| tokens.next().is_none())
            .ok_or(ParseError::Message("too many fields for OPENPGPKEY"))
    }
}
```

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

### Result::is_err Implementation

Source: https://docs.rs/hickory-proto/latest/hickory_proto/dnssec/type.DnsSecResult.html?search=

Example of checking if a result is Err.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

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

### Result::is_ok Implementation

Source: https://docs.rs/hickory-proto/latest/hickory_proto/dnssec/type.DnsSecResult.html?search=

Example of checking if a result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

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

### Create CERT Struct Instance

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/rdata/cert.rs.html?search=std%3A%3Avec

Demonstrates the manual instantiation of a CERT struct and verification of its fields.

```rust
// Sample values
        let cert_type = CertType::PKIX;
        let key_tag = 12345;
        let algorithm = Algorithm::RSASHA256; // Replace with an actual variant from Algorithm
        let cert_data = [1, 2, 3, 4, 5];

        // Create an instance of the CERT struct
        let cert = CERT {
            cert_type,
            key_tag,
            algorithm,
            cert_data: cert_data.to_vec(),
        };

        // Assert that the fields are correctly set
        assert_eq!(cert.cert_type, cert_type);
        assert_eq!(cert.key_tag, key_tag);
        assert_eq!(cert.algorithm, algorithm);
```

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

### Get Current Offset

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/binary/encoder.rs.html

Returns the current offset into the buffer.

```rust
pub fn offset(&self) -> usize {
        self.offset
    }
```

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

### Initialize Parser

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/txt/zone.rs.html?search=u32+-%3E+bool

Creates a new Parser instance with an input string, optional path for relative includes, and an optional origin.

```rust
pub fn new(
        input: impl Into<Cow<'a, str>>,
        path: Option<PathBuf>,
        mut origin: Option<Name>,
    ) -> Self {
        if let Some(origin) = &mut origin {
            origin.set_fqdn(true);
        }
        Self {
            lexers: vec![(Lexer::new(input), path)],
            origin,
        }
    }
```

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

### Parse Domain Names

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/domain/name.rs.html?search=

Demonstrates creating domain names from strings and labels.

```rust
    #[test]
    fn test_from_str() {
        assert_eq!(
            Name::from_str("www.example.com.").unwrap(),
            Name::from_labels(vec![b"www" as &[u8], b"example", b"com"]).unwrap()
        );
        assert_eq!(
            Name::from_str(".").unwrap(),
            Name::from_labels(Vec::<&str>::new()).unwrap()
        );
    }
```

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

### Get Buffer Length

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/binary/encoder.rs.html

Returns the current length of the buffer.

```rust
pub fn len(&self) -> usize {
        self.buffer.len()
    }
```

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

### Get Label Length

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/rr/domain/label.rs.html

Returns the length of the label in bytes.

```rust
pub fn len(&self) -> usize {
    self.0.len()
}
```

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

### Zone Lexer Tokenization Examples

Source: https://docs.rs/hickory-proto/latest/src/hickory_proto/serialize/txt/zone_lex.rs.html

Demonstrates the tokenization of various zone file elements including blank tokens, character data, IP addresses, end-of-line markers, include directives, and subsystem references.

```rust
assert_eq!(next_token(&mut lexer).unwrap(), Token::Blank);
        assert_eq!(
            next_token(&mut lexer).unwrap(),
            Token::CharData("A".to_string())
        );
        assert_eq!(
            next_token(&mut lexer).unwrap(),
            Token::CharData("128.9.0.32".to_string())
        );
        assert_eq!(next_token(&mut lexer).unwrap(), Token::EOL);
        assert_eq!(next_token(&mut lexer).unwrap(), Token::EOL);
        assert_eq!(next_token(&mut lexer).unwrap(), Token::Include);
        assert_eq!(
            next_token(&mut lexer).unwrap(),
            Token::CharData("<SUBSYS>ISI-MAILBOXES.TXT".to_string())
        );
        assert!(next_token(&mut lexer).is_none());
```

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

### BinEncodable Implementations

Source: https://docs.rs/hickory-proto/latest/hickory_proto/serialize/binary/trait.BinEncodable.html?search=u32+-%3E+bool

Examples of implementing the BinEncodable trait for various types.

```rust
impl BinEncodable for Vec<u8>
fn emit(&self, encoder: &mut BinEncoder<'_>) -> Result<(), ProtoError>
```

```rust
impl BinEncodable for i32
fn emit(&self, encoder: &mut BinEncoder<'_>) -> Result<(), ProtoError>
```

```rust
impl BinEncodable for u16
fn emit(&self, encoder: &mut BinEncoder<'_>) -> Result<(), ProtoError>
```

```rust
impl BinEncodable for u32
fn emit(&self, encoder: &mut BinEncoder<'_>) -> Result<(), ProtoError>
```
Tokens:
Raw