domain/base/
mod.rs

1//! Handling of DNS data.
2//!
3//! This module provides types and traits for working with DNS data. The types
4//! allow creating such data from scratch and processing it. Crucially, the
5//! module provides means to extract the data from wire-format DNS messages
6//! and assemble such messages.
7//!
8//!
9//! ## Representation of Variable-length Data and DNS Messages
10//!
11//! Various types have to deal with data of variable length. For instance, a
12//! domain name can be anywhere between one and 255 bytes long. Since there
13//! is no single best type to deal with such data – slices, vecs, or even
14//! byte arrays may all be prefered in certain cases –, the crate uses a set
15//! of traits to be able to be generic over bytes sequences. We call types
16//! that provide these traits ‘octet sequences’ or simply ‘octets.’
17//!
18//! Different traits exist for octet references, owned octets, and octet
19//! builder, that is types that allow constructing an octet stequence from
20//! indidivual bytes or slice. The [`octseq`] crate contains all traits and
21//! trait implementations. It also contains a detailed descriptions of the
22//! traits, their purpose, and how it all fits together.
23//!
24//!
25//! ## Parsing and Composing Messages
26//!
27//! In order to easily distinguish the process of creating and disecting
28//! wire-format messages other forms of representation conversion such as
29//! reading from a zone file, we use the term *parsing* for extracting data
30//! from a wire-format representation and *composing* for producing such a
31//! representation.
32//!
33//! Both parsing and composing happen on buffers holding a complete DNS
34//! message. This seems to be a reasonable choice given the limited
35//! size of DNS messages and the complexities introduced by compressing
36//! domain names in message by referencing other parts of the message.
37//! The fundamental types for parsing and composing are also part of the
38//! [`octseq`] module. But unless you are implementing your own resource record
39//! types, you are unlikely to ever having to deal with parsing and composing
40//! directly.
41//!
42//! Instead, the types [`Message`] and [`MessageBuilder`] are there to make
43//! parsing and constructing DNS messages easy. A [`Message`] takes the
44//! binary data of a DNS message and allows iterating over its four
45//! sections to look at the questions and resource records. Similarly,
46//! a [`MessageBuilder`] takes a bytes vector (or creates one for you) and
47//! has functionality to build the sections of the message step-by-step.
48//!
49//!
50//! # Types for DNS Data
51//!
52//! The module contains a number of types for DNS data, both fundamental
53//! and composed. Because they often come with a number of support types,
54//! they are arranged in submodules. You will find detailed explanations for
55//! all of them in their module. These are:
56//!
57//! * [charstr] for DNS character strings,
58//! * [header] for the header of DNS messages,
59//! * [name] for domain names,
60//! * [opt] for the record data of OPT records used in EDNS,
61//! * [question] for questions,
62//! * [serial] for serial numbers of zones, and
63//! * [record] for DNS resource records including record
64//!   data,
65//! * [rdata] for all the individual record types.
66//!
67//!
68//! # Zone File Processing
69//!
70//! Handling for the text format for DNS data from zone files is available
71//! via the crate’s
72#![cfg_attr(feature = "zonefile", doc = "[zonefile][crate::zonefile]")]
73#![cfg_attr(not(feature = "zonefile"), doc = "zonefile")]
74//!  module. See there for more information.
75//!
76//!
77//! # Support for `no_std`
78//!
79//! The crate is capable of operating without the `std` crate. Obviously, the
80//! set of features is somewhat limited. Specifically, most owned octet
81//! sequence types require an allocator. The [`octseq`] crate thus defines a
82//! set of types atop fixed size byte arrays that can be kept on the stack.
83//! Additional types can be created via the `octets_array` macro.
84//!
85//! Use of the `std` crate is selected via the `std` feature. This is part of
86//! the default set, so you will have to disable the default features.
87
88//--- Re-exports
89
90pub use self::charstr::CharStr;
91pub use self::cmp::CanonicalOrd;
92pub use self::header::{Header, HeaderCounts, HeaderSection};
93pub use self::iana::Rtype;
94pub use self::message::{Message, QuestionSection, RecordSection};
95#[cfg(feature = "std")]
96pub use self::message_builder::{HashCompressor, TreeCompressor};
97pub use self::message_builder::{
98    MessageBuilder, RecordSectionBuilder, StaticCompressor, StreamTarget,
99};
100pub use self::name::{
101    Name, NameBuilder, ParsedName, RelativeName, ToName, ToRelativeName,
102};
103pub use self::question::Question;
104pub use self::rdata::{ParseRecordData, RecordData, UnknownRecordData};
105pub use self::record::{ParsedRecord, Record, RecordHeader, Ttl};
106pub use self::serial::Serial;
107
108//--- Modules
109
110pub mod charstr;
111pub mod cmp;
112mod dig_printer;
113pub mod header;
114pub mod iana;
115pub mod message;
116pub mod message_builder;
117pub mod name;
118pub mod net;
119pub mod opt;
120pub mod question;
121pub mod rdata;
122pub mod record;
123pub mod scan;
124pub mod serial;
125pub mod zonefile_fmt;
126//pub mod str;
127pub mod wire;
128
129//--- Private Helper Modules
130
131mod serde;