Expand description
Domain names.
This module provides various types for working with domain names.
Main types: Dname, RelativeDname, ParsedDname,
UncertainDname, DnameBuilder.
Main traits: ToDname, ToRelativeDname.
Domain names are a sequence of labels which are in turn a sequence of up to 63 octets. While they are limited to a subset of ASCII by convention, all octet values are allowed. In their wire-format representation labels are prefixed with an octet containing the the number of octets in the label. The labels in a domain name are nominally arranged backwards. That is, the ‘most significant’ label is the last one. In an absolute domain name, this last label is an empty label, called the root label and indicating the root of the domain name tree. Only absolute names can appear inside DNS messages.
In order to save space in DNS messages (which were originally limited to 512 bytes for most cases), a name can end in a pointer to another name stored elsewhere in the message. This makes lazy message parsing somewhat difficult since you need to carry around a reference to the original message until actual parsing happens.
As a consequence, this module provides three different basic types for
domain names: A self-contained, absolute domain name is represented by
Dname, a self-contained, relative domain is RelativeDname. These
are generic over an underlying octets sequence. Additionally, a possibly
compressed absolute domain name taken from a message becomes a
ParsedDname. This type is generic over an octets reference which makes
it a little more unwieldy.
Sometimes, it isn’t quite clear if a domain name is absolute or relative.
This often happens because in a name’s string representation, which
contains each label’s content separated by dots, the final dot before the
empty root label is omitted. For instance, instead of the strictly
correct www.example.com. the slightly shorter www.example.com is
accepted as an absolute name if it is clear from context that the name
is absolute. The UncertainDname type provides a means to keep such
a name that may be absolute or relative.
In order to make it cheap to combine names, a mechanism exists to chain
names together and treat them as a single name. The two traits ToDname
and ToRelativeDname allow writing code that is generic over any kind
of either absolute or relative domain name.
Alternatively, you can use DnameBuilder to construct a name manually
from individual labels.
Structs
Two domain names chained together.
The label iterator for chained domain names.
An uncompressed, absolute domain name.
Builds a domain name step by step by appending data.
An iterator over the labels in an uncompressed name.
An octets slice with the content of a domain name label.
Chaining domain names would exceed the size limit.
A label was longer than the allowed 63 octets.
An owned label.
A domain name parsed from a DNS message.
An iterator over the labels in a parsed domain name.
An iterator over ever shorter suffixes of a parsed domain name.
An uncompressed, relative domain name.
An iterator over the labels in an octets slice.
An attempt was made to strip a suffix that wasn’t actually a suffix.
Enums
A domain name wasn’t encoded correctly.
A bad label type was encountered.
An error happened while trying to push data to a domain name builder.
An error happened while trying to push a name to a domain name builder.
An error happened while creating a domain name from octets.
An error happened while splitting a label from an octets slice.
The label iterator for domain name chains with uncertain domain names.
A domain name that may be absolute or relative.
Traits
A type that represents an absolute domain name.
A name that is either absolute or relative.
A type that can produce an iterator over its labels.
A type that represents a relative domain name.