Module domain::base::name

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

Chain	Two domain names chained together.
ChainIter	The label iterator for chained domain names.
Dname	An uncompressed, absolute domain name.
DnameBuilder	Builds a domain name step by step by appending data.
DnameIter	An iterator over the labels in an uncompressed name.
Label	An octets slice with the content of a domain name label.
LongChainError	Chaining domain names would exceed the size limit.
LongLabelError	A label was longer than the allowed 63 octets.
OwnedLabel	An owned label.
ParsedDname	A domain name parsed from a DNS message.
ParsedDnameIter	An iterator over the labels in a parsed domain name.
ParsedSuffixIter	An iterator over ever shorter suffixes of a parsed domain name.
RelativeDname	An uncompressed, relative domain name.
SliceLabelsIter	An iterator over the labels in an octets slice.
StripSuffixError	An attempt was made to strip a suffix that wasn’t actually a suffix.

Enums

DnameError	A domain name wasn’t encoded correctly.
FromStrError
LabelTypeError	A bad label type was encountered.
PushError	An error happened while trying to push data to a domain name builder.
PushNameError	An error happened while trying to push a name to a domain name builder.
RelativeDnameError	An error happened while creating a domain name from octets.
SplitLabelError	An error happened while splitting a label from an octets slice.
UncertainChainIter	The label iterator for domain name chains with uncertain domain names.
UncertainDname	A domain name that may be absolute or relative.

Traits

ToDname	A type that represents an absolute domain name.
ToEitherDname	A name that is either absolute or relative.
ToLabelIter	A type that can produce an iterator over its labels.
ToRelativeDname	A type that represents a relative domain name.