Struct viaspf::Name

pub struct Name(_);

A name that can be used in DNS queries.

Name is a simplistic ad-hoc model for DNS names that should be sufficient for naming purposes as used in the SPF protocol. Name plays a part in the DNS name handling of the Lookup implementation and so the Name API is reduced and specific to its use in the evaluation logic.

The new and domain functions create a Name. Of these, Name::domain is designed for user-supplied inputs, as it will fully encode and validate the input to yield a well-formed ASCII-encoded domain name. Name::new is the hands-off variant, it only checks length limits and otherwise accepts all and any string input. This is intended for use with already validated inputs, or inputs that need to be passed along unchanged.

In the evaluation logic of evaluate_spf, Name::domain is used only on the domain name inputs. All further uses of Name are through Name::new and Name::as_str. Lookup implementations should treat Name as a transparent wrapper of a string.

A Name is always fully-qualified, relative to the root. When borrowing a Name with as_str, the string has a trailing dot:

let name = Name::new("my.org")?;
assert_eq!(name.as_str(), "my.org.");

In the Display presentation form the trailing dot is omitted:

let name = Name::new("my.org")?;
assert_eq!(name.to_string(), "my.org");

It needs to be stressed that Name is not a general-purpose domain name implementation. For example, escaping of special characters like . in labels has not been implemented. The implementation might be improved at a later time if it proves to be insufficient for the purposes of SPF.

Implementations

impl Name

pub fn new(s: &str) -> Result<Self, ParseNameError>

Constructs a syntactically valid DNS name from a string.

This only checks label length restrictions but does not apply any transformation to the given string (no case normalisation, Punycode encoding or similar).

Errors

If the given string is not a valid DNS name, an error is returned.

Examples

use viaspf::Name;

assert!(Name::new("example.org").is_ok());
assert!(Name::new("_spf.example.org").is_ok());

pub fn domain(s: &str) -> Result<Self, ParseNameError>

Constructs a syntactically valid, normalised domain name from a string.

In addition to checking label length restrictions and domain name syntax, this applies the IDNA algorithm with Punycode encoding to the given string. Unicode inputs are properly converted to ASCII format.

Errors

If the given string is not a valid domain name, an error is returned.

Examples

use viaspf::Name;

assert!(Name::domain("example.org").is_ok());
assert!(Name::domain("_spf.example.org").is_err());

assert_eq!(Name::domain("www.Bücher.de")?.to_string(), "www.xn--bcher-kva.de");

pub fn as_str(&self) -> &str

Returns a string slice of the fully-qualified name (including the trailing dot).

pub fn is_subdomain_of(&self, other: &Name) -> bool

Returns whether a name is a subdomain of another name.

Trait Implementations

impl AsRef<str> for Name

fn as_ref(&self) -> &str

Performs the conversion.

impl Clone for Name

fn clone(&self) -> Name

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Name

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Name

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for Name

type Err = ParseNameError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Name

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl PartialEq<Name> for Name

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Eq for Name