Module domain::bits

DNS data.

This module provides types and traits for working with DNS data as well as parsing and composing wire-format DNS messages.

Working with DNS Data

The module contains abstractions for two concepts used in DNS data: domain names and character strings. In both cases, the supplied types internally contain the binary data and work directly on it. Similar to raw bytes slices, there types for borrowed and owned domain names and character strings where the owned type derefs to the borrowed one. For domain names, these types are DNameSlice and DNameBuf; for character strings CharStr and CharStrBuf.

For domain names there is a third variant, ParsedDName. This type is necessary to represent compressed names where the remainder of a name is to be found elsewhere in the message. It avoids allocations when access to the entire name isn’t necessary.

Traits are used when constructing composite types to allow them to work on borrowed and owned data as well as on parsed domain names. For character strings and raw bytes data, AsRef<CharStr> and AsRef<[u8]> are being used. For domain names, there is a separate trait, DName with the same purpose. However, its functionality is limited to the what parsed domain names can provide.

A number of composite types are already defined: Question for the questions of a query, Record for resource records.

Instead of having one big enum, the data of resource records is kept generic through two traits: RecordData provides functions common to all variants of record data types while ParsedRecordData adds the ability to construct a value from a wire-format message for those variants that can use borrowed data and parsed domain names. The actual types implementing these traits can by found in the crate’s rdata module.

Parsing and Composing Messages

In order to easily distinguish the process of creating and disecting wire-format messages from working with master files, we use the term parsing and composing for reading from and writing to wire-format data.

Both parsing and composing happen on bytes buffers. This seems to be a reasonably good choice given the relatively small size of DNS messages and the complexities introduced by name compression. The details are explained in the parse and compose sub-modules. Unless you are implementing your own resource record types, you are unlikely to ever having to deal with parsing and composing directly.

Instead, the types Message and MessageBuilder are there to make parsing and constructing DNS messages easy. A Message takes the binary data of a DNS message and allows iterating over its four sections to look at the questions and resource records. Similarly, a MessageBuilder takes a bytes vector (or creates one for you) and has functionality to build the sections of the message step-by-step.

Re-exports

pub use self::charstr::CharStr;

pub use self::charstr::CharStrBuf;

pub use self::compose::Composable;

pub use self::compose::Composer;

pub use self::compose::ComposeError;

pub use self::compose::ComposeMode;

pub use self::compose::ComposeResult;

pub use self::compose::ComposeSnapshot;

pub use self::header::Header;

pub use self::header::HeaderCounts;

pub use self::header::HeaderSection;

pub use self::message::Message;

pub use self::message::MessageBuf;

pub use self::message_builder::MessageBuilder;

pub use self::message_builder::AnswerBuilder;

pub use self::message_builder::AuthorityBuilder;

pub use self::message_builder::AdditionalBuilder;

pub use self::parse::Parser;

pub use self::parse::ParseError;

pub use self::parse::ParseResult;

pub use self::question::Question;

pub use self::rdata::GenericRecordData;

pub use self::rdata::ParsedRecordData;

pub use self::rdata::RecordData;

pub use self::record::GenericRecord;

pub use self::record::Record;

Modules

charstr	Character strings.
compose	Assembling wire-format DNS data.
header	The header of a DNS message.
message	Accessing exisiting DNS messages.
message_builder	Building a new message.
name	Domain names.
opt	Record data for OPT records.
parse	Parsing of DNS wire-format data.
question	A single question of a DNS message.
rdata	Basic resource data handling.
record	Resource Records

Structs

DNameBuf	An owned complete domain name.
DNameSlice	A slice of a domain name.
ParsedDName	A domain name parsed from a DNS message.

Traits

DName

A trait implemented by all domain name types.