Module domain::bits::name [−][src]
Domain names.
This module contains various types for working with domain names.
Domain names are a sequence of labels. For the most part, labels are in turn a sequence of up to 63 octets. While they are limited to ASCII by convention, all 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, often called the root label. Only absolute names can appear inside DNS messages.
There are two twists to this: One are binary labels which essentially encode a sequence of one-bit labels, are somewhat esoteric, and have been declared historic. The other is name compression. 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.
This is why there are three types for domain names in this module. Two
types represent uncompressed domain names encoded in their wire format
atop a bytes sequence. The DNameSlice
type is a slice of a domain
name akin to a [u8]
. It is an unsized type and will have to be used
behind a pointer, typically a reference. The DNameBuf
type acts as
its owned companion. Similar to the relationship between [u8]
and a
Vec<u8>
it derefs to a DNameSlice
and provides facilities to
manipulate domain names. Both types can contain either absolute or
relative domain names.
A compressed domain name can only occur in a parsed DNS message.
Accordingly, its type is called ParsedDName
. It internally holds a
reference to the message it was parsed from. There’s only two things you
can do with a parsed domain name: convert it into a regular domain name
and iterate over its labels. Luckily, though, the latter is good enough
for comparing them to other domain names.
Creating data structures that can use both DNameSlice
and DNameBuf
can be achieved by being generic over AsRef<DNameSlice>
as AsRef
is
implemented both for &DNameSlice
and DNameBuf
. In order to allow
types that allow ParsedDName
as well, there is an additional trait
DName
. Naturally, the functionality provided by it is limited to
what ParsedDName
can do: conversion into a regular domain name and
iteration over labels.
TODO
- Implement an optimization where there is an optional first byte with the unallocated label type 0b10 that indicates whether the name is absolute or relative (ie., 0x80 means absolute and 0x81 relative and everything else means this really is the first byte of the domain name).
Structs
DNameBuf |
An owned complete domain name. |
DNameBuildInto |
A type for iteratively pushing a domain name into a bytes vec. |
DNameBuilder |
Builds an owned domain step by step from bytes. |
DNameSlice |
A slice of a domain name. |
Label |
An uncompressed domain name label. |
LabelBuf |
An owned domain name label. |
LabelIter |
An iterator over the labelettes in a label. |
NameLabelettes |
An iterator over the labelettes of a domain name. |
NameLabels |
An iterator over the labels in a domain name. |
ParsedDName |
A domain name parsed from a DNS message. |
PushError |
An error happened while trying to append content to an owned domain name. |
StripSuffixError |
An attempt was made to strip a suffix that wasn’t actually a suffix. |
Enums
FromStrError | |
LabelContent |
The contents of a label. |
Labelette |
A labelette is an atomic label. |
Traits
DName |
A trait implemented by all domain name types. |